Configuring environment variables for agents

Edit online

Each agent requires its own environment values. Refer to the agent-specific .env.agent.<agent-name>.example file and update the values for your target environment.

Deploy agent services

Agent services are deployed separately from the core services. Ensure that the core services are running successfully before deploying the agents.
  1. Create the environment file in the respective agent folder:
    agents/<agent-name>/.env.agent.<agent-name>

    Each agent requires a separate environment file.
    Example for the Automation Insight agent:
    cp agents/automation-insight-agent/.env.agent.automation-insight.example \
   agents/automation-insight-agent/.env.agent.automation-insight
  2. Edit the file on Linux (AMD64 system):
    vi agents/automation-insight-agent/.env.agent.automation-insight

  3. If you are using zCX, create or update the file using a supported editor.

    For example:
    nano agents/automation-insight-agent/.env.agent.automation-insight

Common agent environment variables

Agents typically require the following values:

Variable Is the variable mandatory? Description
AGENT_AUTH_TOKEN Yes Specifies the authentication token that the agent uses.
Note: The API key must match the name specified in the API Key field when activating agent registration.
AIOPS_TOKEN No Specifies the AIOps token. The agent inherits this value from .env.core or overrides it in the agent environment file.

Automation insight agent environment values

Configure the environment variables for the Automation Insight agent that provides automation monitoring and insights.

Variable Is the variable mandatory? Description Default Value
AGENT_AUTH_TOKEN Yes Specifies the authentication token that the agent uses to verify and authenticate incoming requests. None

Workload Scheduler agent environment values

Configure the environment variables for the Workload Scheduler agent that manages workload scheduling operations.

Variable Is the variable mandatory? Description Default Value
AGENT_AUTH_TOKEN Yes Specifies the authentication token that the agent uses to verify and authenticate incoming requests. None

OMEGAMON Insight agent environment values

Configure the environment variables for the OMEGAMON Insight agent that provides system monitoring and performance insights.

Variable Is the variable mandatory? Description Default Value
AGENT_AUTH_TOKEN Yes Specifies the authentication token that the agent uses to verify and authenticate incoming requests. None

Support agent environment values

Before configuring the environment variables for the Support Agent, ensure that you have completed the setup and configuration described in Ansible Automation Platform (AAP).

Configure the environment variables for the Support agent that handles support and troubleshooting operations.

Variable Is the variable mandatory? Description Default Value
AAP_ENDPOINT Yes Specifies the URL or endpoint of the Ansible Automation Platform (AAP) server that the application connects to for job execution and automation tasks. None
AAP_USERNAME Yes Specifies the username used to authenticate with the Ansible Automation Platform (AAP). None
AAP_PASSWORD Yes Specifies the password associated with the AAP user account for authentication when connecting to the Ansible Automation Platform. None
AAP_VERSION No Specifies the Ansible Automation Platform API version used for communication. v2
EXTERNAL_API_KEY No Specifies the API key used to authenticate requests to an external service or third-party API required by the application. WXA4Z_SAMPLE_API_KEY
SEND_DUMP_TRANSFER_ID Yes Specifies the transfer identifier used when sending z/OS dump files to the configured destination. sample_id
SEND_DUMP_TRANSFER_PASSWORD No Specifies the password associated with the dump transfer account or transfer identifier for secure authentication of dump transfer operations. sample_passwd
TAKE_DUMP_JOB_TEMPLATE No Specifies the name of the Ansible Automation Platform job template used to initiate and capture a z/OS dump. Take z/OS dump
SEND_DUMP_JOB_TEMPLATE No Specifies the name of the Ansible Automation Platform job template used to transfer a captured z/OS dump to the configured target location. z/OS Send Dump
AGENT_AUTH_TOKEN Yes Specifies the authentication token that the agent uses to verify incoming requests. Ensure that the token is valid and authorized for agent access. None

Upgrade agent environment values

Before you install the upgrade agent, ensure that you deploy the Token Exchange Service for pass ticket generation.

Configure the environment variables for the Upgrade agent that manages system upgrades and updates.

Variable Is the variable mandatory? Description Default Value
AGENT_AUTH_TOKEN Yes Specifies the authentication token that the agent uses to verify and authenticate incoming requests. Ensure the token is valid and authorized for agent access. None
HOST_NAME Yes Specifies the host name with the full path for serving files. None
ENABLE_DOC_INGESTION No Enables document ingestion on startup. TRUE
Note: For information on the key-value pairs for IBM Z Upgrade agent, see Configure agent connection.

zRAG agent environment values

Configure the environment variables required for the zRAG agent to support external retrieval-augmented generation capabilities.

Variable Is the variable mandatory? Description Default Value
ENABLE_WEB_SEARCH No Boolean variable that enables web search capability for the zRAG agent. False
SERPER_API_KEY No Specifies the Serper API key for web search functionality. None
AGENT_AUTH_TOKEN Yes Specifies the authentication token that the agent uses to verify and authenticate incoming requests. Ensure the token is valid and authorized for agent access. None
Note:

Serper API key is optional; the agent works without it. For information on obtaining a Serper API key, see Serper.

For more information on enabling web search, see Configuring web search for zRAG agent.

Set Up the Ansible Platform Agent (Required for the Support Agent)

Set up the Ansible Automation Platform (AAP) instance and configure its credentials.
Note: Ensure that you store playbooks in GitHub or another supported source control system before setting up AAP.
Inventory configuration
Create an inventory and configure the required environment variables.
  1. Create a new inventory.
  2. Specify a name, organization, and optional description.
  3. In the variables section, add the following values:
    _BPXK_AUTOCVT: 'ON'
  ZOAU_HOME: '{{ ZOAU }}'
  PYTHONPATH: ''
  PYTHONSTDINENCODING: cp1047
  LIBPATH: '{{ ZOAU }}/lib:{{ PYZ }}/lib:/lib:/usr/lib:.'
  PATH: '{{ ZOAU }}/bin:{{ PYZ }}/bin:/bin:/var/bin'
  _CEE_RUNOPTS: FILETAG(AUTOCVT,AUTOTAG) POSIX(ON)
  _TAG_REDIR_ERR: txt
  _TAG_REDIR_IN: txt
  _TAG_REDIR_OUT: txt
  LANG: C
  4. Save the inventory.
Host configuration
Configure a host to define system-specific connection details.
  1. Create a new host.
  2. Specify a name, assign the host to the inventory that you created, and add an optional description.
  3. In the variables section, add the following values:
    ansible_host: IP Address of the LPAR (xx.xx.xx.xx)
ansible_user: user that will perform the actions on the LPAR
ansible_python_interpreter: /path/to/your/pyz/bin/python
PYZ: /path/to/your/pyz
PYZ_VERSION: '3.xx'
ZOAU: /path/to/your/zoau/folder
ZOAU_PYTHON_LIBRARY_PATH: ''
Credential configuration

Create credentials that allow Ansible Automation Platform to access the source control repository and the target z/OS system.

Credential for GitHub
  1. Create a new credential.
  2. Specify a name and optional description.
  3. Select Source Control as the credential type.
  4. Paste the SSH private key into the appropriate field and configure any additional required values.

    Ensure that the corresponding public key exists in the source control repository.

  5. Save the credential.
Credential for LPAR
  1. Create a new credential.
  2. Specify a name and optional description.
  3. Select Machine as the credential type.
  4. Paste the SSH private key whose public key is configured on the target LPAR.
  5. Save the credential.
Creating a project
  1. Create a new project.
  2. Specify a name and optional description.
  3. Select an execution environment.
  4. Select Git as the source control type if the playbooks are stored in Git.
  5. Specify the repository URL and branch, if required.
  6. Select the source control credential that you created.
  7. Save the project.
Creating job templates
  1. Create a new job template.
  2. Specify a name and optional description.
  3. Select the inventory that you created.
  4. Select the project that you created.
  5. Select a playbook from the Playbook list.
  6. Save the job template.
  7. Repeat these steps for each additional playbook.
Testing the job templates
Configure survey questions to collect input values when users run the job templates.
  1. Click on a job template.
  2. Select Surveytab.
  3. Create the following survey questions for the playbook job template that you are editing.
    1. Dump Collection Template:
      Configure the following survey questions:
      Table 1.
      Question Variable name Answer type Default value
      Please enter the title of the dump dump_title Text None
      Please enter the job name or job names to include in the dump jobname Text None
      Please enter the SDATA parameters sdata Text (ALLNUC,CSA,GRSQ,LPA,LSQA,PSA,RGN,SQA,SUM,SWA,TRT)
      Please enter the data set name to copy the dump into copy_ds_name Text None
    2. Dump Upload Template
      Configure the following survey questions:
      Table 2.
      Question Variable name Answer Type
      Please enter your transfer ID transfer_id Text
      Please enter your transfer password transfer_pw Password
      Please enter the data set to send ds_to_send Text
      Please enter the case number to submit the data set to case_num Text
  4. After you add the survey questions, enable the survey on the Survey tab.
  5. You can now run the job templates and provide the required input values when prompted.