Installing Containerized Windows Agents

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

Important!

  • Windows agents require a ServiceManager to run with the permissions of the System user to execute jobs and file transfers. Make sure you use the ServiceManager that is installed with the System account.

  • It is not possible to use the Centralized Agent Upgrade (CAU) (CAU) to upgrade agents in a container because, after restarting a container, the agent uses the agent image again, thus rendering a CAU irrelevant.

The Enterprise 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

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

Dockerfile example 

FROM mcr.microsoft.com/windows/server:ltsc2022

RUN echo on && \
    mkdir C:\\agent-windows  && \
    winrm set winrm/config/service/auth @{Basic="true"} && \
    winrm set winrm/config/service @{AllowUnencrypted="true"} && \
    net user Administrator Passw0rd /active:yes && \
    powershell -Command (New-ItemProperty 'HKLM:\\SYSTEM\\CurrentControlSet\\Services\\Tcpip6\\Parameters\\' -Name  'DisabledComponents' -Value '0xffffffff' -PropertyType 'DWord')

RUN powershell -Command \
		$ErrorActionPreference = 'Stop'; \
		$ProgressPreference = 'SilentlyContinue'; \
		[Net.ServicePointManager]::SecurityProtocol = [Net.SecurityProtocolType]::Tls, [Net.SecurityProtocolType]::Tls12, [Net.SecurityProtocolType]::Ssl3; \
		Invoke-WebRequest -UseBasicParsing -Uri "https://aka.ms/vs/15/release/vc_redist.x64.exe" -OutFile vc_redist.x64.exe; \
		Start-Process ./vc_redist.x64.exe -ArgumentList '/quiet' -Wait; \
		Remove-Item ./vc_redist.x64.exe -force

WORKDIR "C:\\agent-windows"

COPY Automation.Engine_Agent_Windows.zip .
COPY Automation.Engine_ServiceManager.zip .
COPY run.ps1 .

ENTRYPOINT [ "powershell.exe" ]
CMD [ "C:\\agent-windows\\run.ps1" ]

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.

Note: The TLS/SSL implementation does not apply to the HP-UX Agent, as it is no longer supported in this version.

You can use the trustedCertFolder=, agentSecurityFolder=, and keyPassword= parameters in the respective INI file to point to the relevant certificates. If the trustedCertFolder= parameter is not set, the certificates should be installed in the respective store; that is the Java trust store for Java Agents, the Windows OS store for Windows Agents, or the TLS/SSL store for UNIX Agents. For more information, see Securing Connections to the AE (TLS/SSL).

For more information about the different certificate types and for detailed instructions on how to create and use them, see What Kind of Certificates Should I Use for Automic Automation v21.

Important! When you install or upgrade containerized Agents for an Automic Automation Kubernetes Edition system, you have to make sure that you configure your Agents to reach the TCP or HTTPS load balancer and not the JCP directly. Also, make sure that your HTTPS load balancer has the required certificates in place. For more information, see Connecting to the AAKE Cluster.

Configuring Containers

You customize the container configuration for a specific container (instance of an image) at runtime.

Starting the Image

You can use a plain docker script to start the image.

Example - _start.bat

Make sure that the definition of the -v "%cd%\trustedcert": and -v "%cd%\security": variables point to the relevant certificates.

docker run -it ^
  --env-file env.file ^
  -p 21000:2300 ^
  -v "%cd%\trustedcert":"c:\agent-windows\trustedcert" ^
  -v "%cd%\security":"c:\agent-windows\security" ^
  agent-windows:21.0

The env.file comprises the following information:

automic_global_name=Linux-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

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. 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 Preparing TLS/SSL Certificates.

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

  1. Configure the INI file.

    It is recommended using environment variables to configure the INI file. You can do so by defining the parameters that correspond to the INI file settings in the run.ps1 file. For more information see, Agent Windows 64-bit INI file.

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

    Example run.ps1 file 

    function unpackZipFile($sourceArchive, $destinationFolder, $subFolder) {
	Expand-Archive -path $sourceArchive -destinationPath TMP_FOLD
	New-Item $destinationFolder -itemType "directory"
	Move-Item .\TMP_FOLD\$subFolder\* $destinationFolder
	Remove-Item .\TMP_FOLD\ -recurse
}

function replaceInFile($filePath, $replacements) {
	$result = Get-Content $filePath
	foreach ($replacement in $replacements.getEnumerator()) {
		$result = $result -replace $replacement.Name, $replacement.Value
	}
	Set-Content -Path $filePath -Value $result 
}

function prepareAgent {
	$agentBasePath = ".\Automic\Agent\windows"
	Write-Output "Unpacking Agent"
	unpackZipFile -sourceArchive .\Automation.Engine_Agent_Windows.zip -destinationFolder "$agentBasePath\bin" -subFolder Agents\windows\x64
	
	New-Item "$agentBasePath\temp" -ItemType "directory"
	
	Write-Output "Adapting Agent's ini file"
	replaceInFile -filePath "$agentBasePath\bin\UCXJWX6.ini" -replacements @{
		"^NAME=.*" 			= "NAME=$env:automic_global_name";
		"^SYSTEM=.*" 			= "SYSTEM=$env:automic_global_system";
		"^connection=.*" 		= "connection=$env:automic_tcpip_connection";
		"^trustedCertFolder=.*" 	= "trustedCertFolder=..\..\..\..\trustedcert";
		"^agentSecurityFolder=.*" 	= "agentSecurityFolder=..\..\..\..\security";
		"^InitialPackage=.*" 	  	= "InitialPackage=package";
		"^;UC_EX_IP_ADDR=.*" 		= "UC_EX_IP_ADDR=$env:automic_variables_uc_ex_ip_addr";
		"^;UC_EX_IP_PORT=.*" 		= "UC_EX_IP_PORT=$env:automic_variables_uc_ex_ip_port";
		"^;UC_EX_JOB_MD_IP_ADDR=.*"	= "UC_EX_JOB_MD_IP_ADDR=$env:automic_variables_uc_ex_job_md_ip_addr";
	}
}

function installAndStartServiceManager {
	$smgrBasePath = ".\Automic\ServiceManager"
	$smgrWorkdir = "$smgrBasePath\bin"

	Write-Output "Unpacking Service Manager"
	unpackZipFile -sourceArchive .\Automation.Engine_ServiceManager.zip -destinationFolder "$smgrWorkdir" -subFolder ServiceManager\windows\x64\
	New-Item "$smgrBasePath\temp" -ItemType "directory"
	
	Write-Output "Create smc and smd file"
	Set-Content -path "$smgrWorkdir\AUTOMIC.smd" -value "DEFINE Agent;*OWN\..\..\Agent\windows\bin\UCXJWX6.exe;*OWN\..\..\Agent\windows\bin"
	Set-Content -path "$smgrWorkdir\AUTOMIC.smc" -value "WAIT 0`nCREATE Agent"  

	Write-Output "Adapting Service Manager's ini file"
	replaceInFile -filePath "$smgrWorkdir\ucybsmgr.ini" -replacements @{
		"^\[Destination.*" 	= "[Destination AUTOMIC]";
		"^cmdfile.*" 		= "cmdfile=*OWN\AUTOMIC.smc";
		"^deffile.*" 		= "deffile=*OWN\AUTOMIC.smd";
	}

	Write-Output "Installing Service Manager"
	$smgrExe = "$smgrWorkdir\ucybsmgr.exe"
	Start-Process -FilePath $smgrExe -ArgumentList "-install AUTOMIC" -WorkingDirectory $smgrWorkdir -Wait -Verb RunAs

	$serviceName = "UC4.ServiceManager.AUTOMIC"

	Write-Output "Starting Service Manager"
	Restart-Service -Name $serviceName -Force
	Start-Sleep -Milliseconds 15000
	$agentProcess = (get-process | Where-Object {$_.ProcessName -eq 'ucxjwx6'} | Select-Object Id, ProcessName)

	if ($null -ne $agentProcess) {
		Write-Output "Agent started:  $agentProcess"
		$agentPID = $agentProcess.id
		do {
			$processStillActive = get-process | Where-Object {$_.ID -eq $agentPID}
			Start-Sleep -Seconds $env:agent_liveness_check_intervall
		} while ($null -ne $processStillActive)
		Write-Output "Agent process shut down"
	} else {
		Write-Output "Failed to start agent - check log files for more information"
	}
}

#### Main ####
prepareAgent
installAndStartServiceManager

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.

Resetting the Agent Key

If, for any reason, you do not want to store the public/private key in a volume, you can reset the agent key in the Automation Engine before the agent can connect again. You can do so using the REST API before starting the agent.

Example 

curl -f --request POST -u "$CLIENT0_USER/$CLIENT0_DEPARTMENT:$CLIENT0_PASSWORD" \
    "http://$REST_CONNECTION/ae/api/v1/0/system/agents/$AGENT_NAME/resetpublickey" -v

See also: