Installing Containerized UNIX Agents

As an administrator, you set up your system to run a UNIX Agent in a container by building and running a Docker image hosting a UNIX Agent.

The Broadcom Software Academy provides examples on how to deploy an Automic Automation Java, Windows or UNIX agent in a container. To access this additional information please select the relevant link:

This page includes the following:

Prerequisites

Make sure that you have all the resources required by the agents at build time in place. These are the following:

  • Base image

  • Agent binaries

  • INI files

Note: The image should be generic so that it can be reused for several instances. Therefore, it is recommended adding only resources that do no change for several instances. Make sure not to add any instance-specific configuration.

Connecting to the Automation Engine

The Automation Engine and the Windows, UNIX, and Java Agents communicate using TLS/SSL. These agents establish a connection with the Java communication process (JCP), which uses trusted certificates to prove their identity to other communication partners.

Important! Make sure you are familiar with the TLS/SSL and certificate implementation before installing and/or upgrading the respective component. For more information, see:

When you used certificates signed by a CA, the certificates are stored in the respective Java or OS store by default; that is the Java trust store for Java components and Java Agents, the Windows OS store for Windows Agents, or the TLS/SSL store for UNIX Agents. In this case, you only have to check that the root certificates already are in the respective store.

If the relevant certificates are not there and you want to import them, you can use OS or Java specific tools for that purpose, such as Keytool, cert-manager, OpenSSL and such. For more information on how to use those tools, please refer to the respective product documentation.

If you do not want to use the default locations for the components and Agents listed above, make sure you use the trustedCertFolder=, agentSecurityFolder=, and keyPassword= parameters (if applicable) in the respective configuration (INI) file to define the path to the folder where the trusted certificates are stored.

Important! TLS/SSL Agents (in containers and on-premises) as well as the TLS Gateway, when used for the Automic Automation Kubernetes Edition, establish a connection to an ingress / HTTPS load balancer, which requires a certificate for authentication.

Make sure that address of the load balancer is defined on both sides: the Automation Engine and the Agent / TLS Gateway and that your HTTPS load balancer has the required certificates in place. For more information, see Connecting to AWI, the JCP and REST Processes Using an Ingress.

Configuring Containers

You customize the container configuration for a specific container (instance of an image) at runtime. You can run the agent either in privileged (root) and unprivileged mode.

Running Containerized Agents in Privileged (root) Mode and Starting the Image

Follow the instructions below to run the Agent in privileged (root) mode.

  1. Create the docker file and run script.

    Dockerfile example - privileged (root) mode 

    FROM ubuntu:20.04

RUN mkdir /opt/agent-unix
COPY ucxjlx6.tar.gz /opt/agent-unix

WORKDIR /opt/agent-unix
RUN tar -xzf ucxjlx6.tar.gz

WORKDIR /opt/agent-unix/bin
COPY --chmod=0755 run.sh .

ENTRYPOINT [ "/opt/agent-unix/bin/run.sh" ]

    run.sh script example - privileged (root) mode 

    #!/bin/bash

terminate() {
	echo $0: trapped signal
	if [ ! -z "$PID" ]; then
		echo $0: will kill agent
		kill $PID
	fi
	echo $0: exiting
	exit 0
}

echo $0: will trap SIGINT and SIGTERM
trap 'kill ${!}; terminate' INT TERM

echo "1. adopt agent configuration"
mv ucxjxxx.ori.ini ucxjlx6.ini 
sed -i "s/^name.*=.*/name=$automic_global_name/g" ucxjlx6.ini
sed -i "s/^system.*=.*/system=$automic_global_system/g" ucxjlx6.ini
sed -i "s/^MsgToStdout.*=.*/MsgToStdout=$automic_misc_msgtostdout/g" ucxjlx6.ini
sed -i "s/^connection.*=.*/connection=$automic_tcpip_connection/g" ucxjlx6.ini
sed -i "s/^keyPassword.*=.*/keyPassword=$automic_authorization_keypassword/g" ucxjlx6.ini

sed -i "s#^trustedCertFolder.*=.*#trustedCertFolder=../trustedcert#g" ucxjlx6.ini
sed -i "s#^initialPackage.*=.*#initialPackage=./package#g" ucxjlx6.ini

sed -i "/^\[VARIABLES\].*/a UC_EX_IP_ADDR=$automic_variables_uc_ex_ip_addr" ucxjlx6.ini
sed -i "/^\[VARIABLES\].*/a UC_EX_IP_PORT=$automic_variables_uc_ex_ip_port" ucxjlx6.ini
sed -i "/^\[VARIABLES\].*/a UC_EX_JOB_MD_IP_ADDR=$automic_variables_uc_ex_job_md_ip_addr" ucxjlx6.ini

echo "2. create user"
useradd -m execuser
echo execuser:agentpw | chpasswd

echo "3. start agent"
./ucxjlx6 &
PID=$!
wait $PID

  2. Start the image. To do so, you can use a plain docker script.

    Example - _start.sh

    Make sure that the definition of the -v ${PWD}/security: and -v ${PWD}/trustedcert: variables point to the relevant certificates.

    #!/bin/sh

# add '--entrypoint bash' for debugging
docker run -it \
    --env-file env.file \
    -p 21000:2300 \
    -v ${PWD}/security:/opt/agent-unix/bin/security \
    -v ${PWD}/trustedcert:/opt/agent-unix/trustedcert \
    -v ${PWD}/package:/opt/agent-unix/bin/package \
    agent-unix:24.0

    The env.file comprises the following information:

    automic_global_name=Agent-Docker-V210
automic_global_system=AUTOMIC
automic_global_logging=CON:
automic_tcpip_connection_DNS=myAEServer.local:8443
automic_tcpip_connection=1.2.3.4:8443
automic_variables_uc_ex_ip_addr=192.168.1.2
automic_variables_uc_ex_ip_port=12300
automic_variables_uc_ex_job_md_ip_addr=localhost
not_used_automic_misc_msgtostdout=yes
automic_keypass=changeit

    You can also build the image and publish it to the image repository.

    If your Agent runs in a Kubernetes cluster, you can also use k8s scripts to start the image.

    Example k8s deployment.yaml

    Make sure that the definition of the - name: security-volume and - name: trustedcert-volume parameters in the config map point to the relevant certificates.

    Note: This example uses PVCs to mount the certificates and so on. In this case, you have to create the PV and PVCs before deploying the agents and configure them accordingly.

    apiVersion: apps/v1
kind: Deployment
metadata:
  name: docker-linux
  labels:
    app: agent-unix
spec:
  replicas: 1
  selector:
    matchLabels:
      app: agent-unix
  template:
    metadata:
      labels:
        app: agent-unix
    spec:
      containers:
      - name: agent-unix
        image: agent-unix:24.0
        imagePullPolicy: Never
        ports:
        - containerPort: 2300
          hostPort: 21000
        envFrom:
          - configMapRef:
              name: docker-linux-config
        volumeMounts:
          - name: security-volume
            mountPath: /opt/agent-unix/bin/security
          - name: trustedcert-volume
            mountPath: /opt/agent-unix/trustedcert
      volumes:
      - name: security-volume
        persistentVolumeClaim:
          claimName: pvc-securityfolder
      - name: trustedcert-volume
        persistentVolumeClaim:
          claimName: pvc-trustedcertfolder

    The configmap comprises the following information:

    TheapiVersion: v1
kind: ConfigMap
metadata:
  name: k8s-linux-config
data:
  automic_global_name: linux-k8s-v240
  automic_global_system: AUTOMIC
  automic_tcpip_connection_DNS: myAEServer.local:8443
  automic_tcpip_connection: 1.2.3.4:8443
  automic_authorization_keypassword: changeit
  automic_misc_msgtostdout: "yes"
  automic_variables_uc_ex_ip_addr: 192.168.1.2
  automic_variables_uc_ex_ip_port: "22300"
  automic_variables_uc_ex_job_md_ip_addr: localhost

Running Containerized Agents in Unprivileged Mode and Starting the Image

Follow the instructions below to run the Agent in unprivileged mode.

  1. Create the docker file and run script.

    Dockerfile example - unprivileged mode

    FROM ubuntu:20.04

RUN mkdir /opt/agent-unix
COPY ucxjlx6.tar.gz /opt/agent-unix

WORKDIR /opt/agent-unix
RUN tar -xzf ucxjlx6.tar.gz

# create agentuser with id 1001
RUN useradd -m agentuser -u 1001 
RUN echo agentuser:agentpw | chpasswd
RUN chown -R 1001:0 /opt/agent-unix && chmod -R g=u /opt/agent-unix
# change to user 1001 aka agentuser
USER 1001

WORKDIR /opt/agent-unix/bin
COPY --chmod=0755 run.sh .

    run.sh script example - unprivileged mode 

    #!/bin/bash

terminate() {
	echo $0: trapped signal
	if [ ! -z "$PID" ]; then
		echo $0: will kill agent
		kill $PID
	fi
	echo $0: exiting
	exit 0
}

echo $0: will trap SIGINT and SIGTERM
trap 'kill ${!}; terminate' INT TERM

echo "1. adopt agent configuration"
mv ucxjxxx.ori.ini ucxjlx6.ini 
sed -i "s/^name.*=.*/name=$automic_global_name/g" ucxjlx6.ini
sed -i "s/^system.*=.*/system=$automic_global_system/g" ucxjlx6.ini
sed -i "s/^MsgToStdout.*=.*/MsgToStdout=$automic_misc_msgtostdout/g" ucxjlx6.ini
sed -i "s/^connection.*=.*/connection=$automic_tcpip_connection/g" ucxjlx6.ini
sed -i "s/^keyPassword.*=.*/keyPassword=$automic_authorization_keypassword/g" ucxjlx6.ini

sed -i "s#^trustedCertFolder.*=.*#trustedCertFolder=../trustedcert#g" ucxjlx6.ini
sed -i "s#^initialPackage.*=.*#initialPackage=./package#g" ucxjlx6.ini

sed -i "/^\[VARIABLES\].*/a UC_EX_IP_ADDR=$automic_variables_uc_ex_ip_addr" ucxjlx6.ini
sed -i "/^\[VARIABLES\].*/a UC_EX_IP_PORT=$automic_variables_uc_ex_ip_port" ucxjlx6.ini
sed -i "/^\[VARIABLES\].*/a UC_EX_JOB_MD_IP_ADDR=$automic_variables_uc_ex_job_md_ip_addr" ucxjlx6.ini

echo "2. start agent"
./ucxjlx6 &
PID=$!
wait $PID

  2. Start the image. To do so, you can use a plain docker script.

    Example - _start.sh

    Make sure that the definition of the -v ${PWD}/security: and -v ${PWD}/trustedcert: variables point to the relevant certificates.

    #!/bin/sh

# add '--entrypoint bash' for debugging
docker run -it \
    --env-file env.file \
    -p 21000:2300 \
    -v ${PWD}/security:/opt/agent-unix/bin/security \
    -v ${PWD}/trustedcert:/opt/agent-unix/trustedcert \
    -v ${PWD}/package:/opt/agent-unix/bin/package \
    agent-unix:24.0

    The env.file comprises the following information:

    automic_global_name=Agent-Docker-V210
automic_global_system=AUTOMIC
automic_global_logging=CON:
automic_tcpip_connection_DNS=myAEServer.local:8443
automic_tcpip_connection=1.2.3.4:8443
automic_variables_uc_ex_ip_addr=192.168.1.2
automic_variables_uc_ex_ip_port=12300
automic_variables_uc_ex_job_md_ip_addr=localhost
not_used_automic_misc_msgtostdout=yes
automic_keypass=changeit

    You can also build the image and publish it to the image repository.

    If your Agent runs in a Kubernetes cluster, you can also use k8s scripts to start the image.

    Make sure that the definition of the - name: security-volume and - name: trustedcert-volume parameters in the config map point to the relevant certificates.

    Notes:

    • This example uses PVCs to mount the certificates and so on. In this case, you have to create the PV and PVCs before deploying the agents and configure them accordingly.

    • To use the Agent in unprivileged mode with the security folder in a PVC, the deployment file must have a security context set to use a fsgroup that is not root (0).

    apiVersion: apps/v1
kind: Deployment
metadata:
  name: docker-linux
  labels:
    app: agent-unix
spec:
  replicas: 1
  selector:
    matchLabels:
      app: agent-unix
  template:
    metadata:
      labels:
        app: agent-unix
    spec:
      containers:
      - name: agent-unix
        image: agent-unix:24.0
        imagePullPolicy: Never
        ports:
        - containerPort: 2300
          hostPort: 21000
        envFrom:
          - configMapRef:
              name: docker-linux-config
        volumeMounts:
          - name: security-volume
            mountPath: /opt/agent-unix/bin/security
          - name: trustedcert-volume
            mountPath: /opt/agent-unix/trustedcert
      securityContext:
         fsGroup: 2000
      volumes:
      - name: security-volume
        persistentVolumeClaim:
          claimName: pvc-securityfolder
      - name: trustedcert-volume
        persistentVolumeClaim:
          claimName: pvc-trustedcertfolder
           mountPath: /opt/agent-linux/bin/security

    The configmap comprises the following information:

    TheapiVersion: v1
kind: ConfigMap
metadata:
  name: k8s-linux-config
data:
  automic_global_name: linux-k8s-v240
  automic_global_system: AUTOMIC
  automic_tcpip_connection_DNS: myAEServer.local:8443
  automic_tcpip_connection: 1.2.3.4:8443
  automic_authorization_keypassword: changeit
  automic_misc_msgtostdout: "yes"
  automic_variables_uc_ex_ip_addr: 192.168.1.2
  automic_variables_uc_ex_ip_port: "22300"
  automic_variables_uc_ex_job_md_ip_addr: localhost

Configuring the Agent

There are several areas that are relevant to successfully configure the agents:

  1. If you have not done so yet, configure the JCP certificate.

    Make sure the agent trusts the JCP. If you do not use a public trusted certificate, make sure to add the relevant certificate to the trustedCertFolder. For more information, see Securing Connections to the AE (TLS/SSL).

  2. If you have not done so yet, configure the Agent certificate.

    The Agent uses the files (private keys, signed certificates and root certificates) stored in its security folder to authenticate against the Automation Engine. You have to preserve this folder in a volume. Otherwise, the certificate (and private key) is lost and the Automation Engine does not recognize the agent and rejects it. For more information, see TLS/SSL Certificate Considerations.

  3. Authenticate the Agent.

    If you use the authentication methods LOCAL or LOCAL_REMOTE, you require an authentication package for the initial start. For more information, see Agent Authentication and Changing the Authentication Method.

    The easiest way to mount the authentication package for the initial start is setting a volume and defining it in the InitialPackage= parameter of the INI file.

  4. Configure the INI file.

    Make sure that you configure the docker file or, if you are using K8s, the configmap to be able to define the relevant INI file parameters using environment variables

    You can also provide the INI file with a volume which is passed at the start of an agent.

    For more information, see Agents INI Files.

Configuring the Network

The listening port of the Agent must be available for other agents to enable file transfers. Therefore, the port must be available with the capabilities of Docker or Kubernetes. The job messenger must still connect directly to the agent within the container.

The following settings must be defined in the INI file:

  • UC_EX_IP_ADDR must be set to the external ip or hostname

  • UC_EX_IP_PORT must be set to the external port

  • UC_EX_JOB_MD_IP_ADDR must be set to localhost

Important! Make sure that the hostnames required are resolvable inside the cluster either by configuring a DNS or services with ExternalName.

See also: