2. Ansible-Legacy

2.1. Introduction

This document aims to explain how to use Ansible-Legacy.

2.2. Ansible-Legacy overview

Ansible Legacy uses the standard Ansible function to input settings to the different hosts.

Register structure code as YAML files configure them with job patterns.

It can be used to configure environments to servers, storages and network devices.

2.3. Ansible-Legacy Menu structure

This section epxlains the Ansible-Legacy menu structure.

2.3.1. Menu

1. Basic console menus

The basic console menus used by Ansible-Legacy are as following.

表 2.42 基本コンソール メニュー/画面一覧

No	メニュー画面	説明
1	オペレーション一覧	オペレーション一覧をメンテナンス(閲覧/登録/更新/廃止)できます。

2. Ansible common menus

3. Ansible-Legacy menus

The Ansible-Legacy menus are as following.

2.4. Ansible-Legacy procedure

This section explains how to use Ansible-Legacy.

2.4.1. Ansible-Legacy workflow

A standard workflow using Ansible Legacy can be seen below.

• Workflow details and references

  1. Register connection information for the target

     From the Ansible common ▶ Device list menu, register connection information for the target.

     For more information, see Device list.
  2. Register operation name

     From the Basic console ▶ Operation list menu, register an Operation list.

     For more information, see Operation list.
  3. **Register Ansible Automation Controller host information (if needed) **

     From the Ansible common ▶ Ansible Automation Controller host list menu, Register information for the Ansible Automation Controller host.

     For more information, see Ansible Automation Controller host list.
  4. Register Interface information

     From the Ansible common ▶ Interface information menu, select Ansible Core, Ansible Automation Controller or Ansible Execution Agent for the execution engine and register connection information for the execution engine server

     For more information, see Interface information.
  5. Register Execution environment definition template management(If needed)

     From the Ansible common ▶ Execution environment definition template management menu, Register the template file for the Execution environment definition file (execution-environment.yml) which is used to build the Execution environment by the ansible-builder within the Ansible Execution Agent.

     For more information, see ansible_execution_environment_definition_template_list and Using the Template file registered to Ansible common ▶ Execution environment definition template ` and :menuselection:"Execution Environment Parameter Definition" Parameter sheet`.

     Installing ITA registers a template file that allows users to add python module and ansible galaxy collections.
  6. Register "Execution environment parameter definition" parameter sheet. sheet(If needed)

     Register Parameters that will be embedded to the execution environment definition file (execution-environment.yml) template file registered in Ansible common ▶ Execution environment definition template management.

     For more information, see Using the Template file registered to Ansible common ▶ Execution environment definition template ` and :menuselection:"Execution Environment Parameter Definition" Parameter sheet`.

     Installing ITA registers , the "Execution environment parameter definition" parameter sheet with the parameters that embeds to the execution environment definition template file (execution-environment.yml) file is registered.
  7. Register Execution environment management (If needed)

     Register a link between the "Execution environment parameter definition" parameter sheet and the template file for the execution environment definition file (execution-environment.yml) registered in Ansible common ▶ Execution environment definition template management

     For more information, see Execution environment management.

     Installing ITA registers a link between the "Execution environment parameter definition" parameter sheet and Ansible common ▶ Execution environment definition template management.
  8. Register Movement

     From the Ansible-Legacy ▶ Movement list menu, register a Movement.

     For more information, see Movement list.
  9. Register Playbook

     From the Ansible-Legacy ▶ Playbook file collection menu, register a Playbook.

     For more information, see Playbook file collection.
  10. **Register Global variables (if needed) **

      From the Ansible common ▶ Global value management menu, register global variables to be used in the Playbook.

      For more information, see Global variable management.
  11. **Register Template files (if needed) **

      From the Ansible common ▶ Template management menu, register template files and template embedded variables to be used in the Playbooks.

      For more information, see Template management.
  12. **Register File material (if needed) **

      From the Ansible common ▶ File management menu, register file materials and file embedded variables to be used in the Playbooks.

      For more information, see File management.
  13. **Register Unmanaged variables (if needed) **

      From the Ansible common ▶ Unmanaged target variable list menu, register extracted variables which will not be displayed in Ansible-Legacy ▶ Substitute value auto registration's Movement name:Variable name.

      For more information, see Unmanaged target variable list.
  14. Register Playbooks to Movement

      From the Ansible-Legacy ▶ Movement-Playbook link menu, register link between Playbook and Movement.

      For more information, see Movement-Playbook link.
  15. Create parameter sheet

      From the Create/Define parameter sheets menu, create a Parameter sheet which will have data registered to it that can configure settings for the target.

      For more information, see Parameter sheet creation function.
  16. Register data to Parameter sheet

      Register data to the parameter sheet created in the previous step.

      For more information, see Parameter sheet creation function.
  17. Substitute value auto registration settings

      From the Ansible-Legacy ▶ Substitute value auto registration settings menu, link the Movement variables with the Parameter sheet's item's setting values.

      For more information, see Substitute value auto registration settings.
  18. Execute

      From the Ansible-Legacy ▶ Execute menu, select the desired Movement and Operation and execute them.

      For more information, see Execute.
  19. Confirm execution status

      From the Ansible-Legacy ▶ Confirm execution status menu,the status of all previously executed operations will be updated in realtime. Users can also monitor error logs and execution logs as well as stop them with an emergency stop.

      For more information, see Confirm execution status.
  20. Confirm execution history

      From the Ansible-Legacy ▶ Execution management menu, users can check the history of all previously executed operations..

      For more information, see Execution management.

2.5. Ansible-Legacy menu operation

This section explains how to operate the Ansible-Legacy menus.

2.5.1. Basic console

For more information regarding Basic console menu, see Basic console

2.5.2. Ansible common

For more information regarding Ansible common menus, see Ansible common

2.5.3. Ansible-Legacy

This section explains how to operate the Ansible-Legacy menus.

Movement list

1. Maintains (view.register/edit/discard) Movement information.

   

   図 2.19 Submenu (Movement list)

2. Press the Register button to register Movement information.

   

   図 2.20 Registration page (Movement list)

3. The items found in the registration page are as following.

   Tip

   ※1 If the has "become: yes" configured.

   The following settings must be configured to the target.

   Login user must have sudo permission NOPASSWD configured to /etc/sudoers with NOPASSWD.

   
   

   　　　Demo_user ALL=(ALL) NOPASSWD:ALL

   Tip

   ※2 Select from data fetched from Ansible Automation Controller data synchronization.

   警告

   If WinRM connection is set to "True", the connecting hosts will be all Windows servers..

Playbook file collection

1. Maintains (view/register/edit/discard) user created Playbooks.

   For more information regarding describing Playbooks, see Describing Playbook (Ansible-Legacy).

   The Playbook file collection menu will contains some sample Playbooks by default.

   The Sample playbook names have names that starts with [Exastro standard]

   Sample playbooks can be used by linking them to Movements.

   

   図 2.21 Submenu (Playbook file collection)

2. Press the Register button to register Playbooks.

   

   図 2.22 Registration page (Playbook file collection)

3. The items found in the registration page are as following.

警告

When variables defined within Playbooks are extracted

The variables defined within Playbooks files are extracted by internal processes.The variables can have specific values registered to them in Substitute value auto registration settings

The variables are not extracted in realtime, meaning that it may take time before they can be used in Substitute value auto registration settings .

Movement-Playbook link

1. Maintains (view/register/edit/discard) links between Movements and Playbooks.

   

   図 2.23 Submenu (Movement-Playbook link)

2. Press the Register button to register Movement and Playbook links.

   

   図 2.24 Registration page (Movement-Playbook link)

3. The items found in the registration page are as following.

   表 2.43 Registration page item list (Movement-Playbook link)

   Item	Description	Input required	Input method	Restrictions
   Item number	Displays an automatically numbered string of 36 characters.	ー	Automatic	ー
   Movement	Displays Movement names registered in Ansible-Legacy ▶ Movement list. Select Movement.	〇	List selection	Same as description.
   Playbook file	Displays Playbook file names registered in Ansible-Legacy ▶ Playbook file collection. Select the Playbook file that will be included in the Movement.	〇	List selection	Same as description.
   Include order	Input an include order (1～) for the Playbook. The included Playbook files will be executed in order based on their include order (rising).	〇	Manual	1～2,147,483,647
   Remarks	Free description field	ー	Manual	Maximum length 4000 bytes

Substitute value auto registration settings

1. Links (view/register/edit/discard) parameter item setting values and Movement variables.

   |The registered information is displayed in Ansible-Legacy ▶ Substitute value management and Ansible-Legacy ▶ Target host when executed by internal processes.

   

   図 2.25 Submenu (Substitute value auto registration settings)

2. Press the Register button to register a link between the Movement variables and Parameter sheet item setting values

   

   図 2.26 Registration page (Substitute value auto registration settings)

3. The items found in the registration page are as following.

Tip

※1:Only required if the Parammeter sheet has Bundles active.

In order to link Movement variables with Parameter sheets with bundles, the user must input a substitute order for the Parameter sheet (From) in Ansible-Legacy ▶ Substitute value auto registration settings.

See the following figure for more information regarding the relationship between bundled parameter sheets and Substitute value auto registration settings.

Tip

※2 Input Substitute order

In Ansible-Legacy, if no Substitute order is input, the variables will be handled as normal variables.

If Substitute order has been input, they will be handled as multiple specific value variables. Even If the Multiple Specific Value Variable doesnt need multiple specific values,

(Specific value can be 1 or more), make sure to input a substitute order.

Substitute orders does not need to succeed particular Multiple specific value variables.

e.g.) Input Substitute order for multiple specific value variables and executing.

1. In Ansible-Legacy ▶ Substitute value auto registration settings, link Playbook variables and setting values for items registered to the Parameter sheets.

   表 2.44 Parameter sheet registration contents

   Host name	Operation name	Parameter
   		Item1	Item2	Item3	Item4
   test-host	test-ope	value1	value2	value3	value4

   表 2.45 Substitute value auto registration settings registration contents

   Menu name	Item	Variable name	Substitute order
   sample-menu	Item1	VAR_substitutionA	30
   sample-menu	Item2	VAR_substitutionA	10
   sample-menu	Item3	VAR_substitutionA	20
   sample-menu	Item1	VAR_substitutionB	2
   sample-menu	Item2	VAR_substitutionB	4
   sample-menu	Item3	VAR_substitutionB	1
   sample-menu	Item4	VAR_substitutionB	3

2. When executed, the host variable file (host_vars/test-host) will have the variables registered in Substitute value auto registration settings output similarly to the example below.

   Output to Host variable file

   VAR_substitutionA:
     - value2
     - value3
     - value1
   VAR_substitutionB:
     - value3
     - value1
     - value4
     - value2
   

Tip

Output to Host variable file

Only variables registered in the Substitute value auto registration settings menu are output to the Host variable file when executed.

Even if the Playbook variables are not registered to Substitute value auto registration settings, the user will be able to Execute them. However, executing Ansible with non-defined variables might cause an error.

Tip

Examples using Playbook variables linked to File embedded variables and Template embedded variables

e.g.) If the File embedded variable, CPF_test, and Template embedded variable, TPF_sample, is linked to the Playbook variable in the Substitute value auto registration settings menu.

1. Register the following in:menuselection:Ansible common --> File management / Ansible common ▶ Template management.

   表 2.46 File management registration contents

   File embedded Variable name	File material
   CPF_test	test_file.txt

   表 2.47 Template management registration contents

   Template embedded Variable name	Template file
   TPF_sample	sample.tpl

2. After creating "Ansible common:File management:File embedded variable name" and "Ansible common:Template management:Template embedded variable name" as Parameter sheet items in Define/Create parameter sheet , register File embedded variables and Template embedded variables as the Parameter sheets' item values.

   

   図 2.27 Define/Create parameter sheet

   表 2.48 Sample parameter sheet registration contents

   Host name	Operation name	Parameter
   		File management	Template management
   test-host	test-ope	CPF_test	TPF_sample

3. In Ansible-Legacy ▶ Substitute value auto registration settings, link the Playbook variable and the Item setting value of the Parameter sheet registered in Step 2. and Execute Ansible in Ansible-Legacy ▶ Execute.

   表 2.49 Substitute value auto registration settings registration contents

   Menu name	Item	Variable name
   Sample parameter sheet	File management	VAR_filetest
   Sample parameter sheet	Template management	VAR_temptest

4. Click the Ansible-Legacy ▶ Confirm execution status's Check substitute value button to check that the '{{ CPF_test }}' and '{{ TPF_sample }}' are dispalyed to the Specific value.

   

   図 2.28 Confirm execution status Substitute value management

Execute

Select a Movement from the Movement list.

Select an Operation from the Operation list.

There are 3 different types of execution types. Clicking the one of the execution buttons moves the user to Ansible-Legacy ▶ Confirm execution status where the execution process will start

図 2.29 Execute menu

See the following for information regarding the different execution types.

1. Execute

   Press the Execute button to run operations to the execution target.
2. Dry run

   Clicking the Dry run button allows the user to perform a dry run where the operation is not executed to the execution target.

   Dry runs will execute the Ansible-Playbook command's --check parameter.
3. Check Parameter

   Clicking the Check Parameter button allows users to check that the information registered in Ansible-Legacy ▶ Substitute value auto registration settings and the Operation and Movement link information is displayed to Ansible-Legacy ▶ Substitute value management and Ansible-Legacy ▶ Target host without actually executing to the execution target.

Tip

Specify reservation date

Inputing a Reservation date allows users to reserve executions.

Reservation dates can only contain a date/time later than the current date/time.

Confirm execution status

Allows users to monitor execution statuses.

図 2.30 Submenu (Confirm execution status)

1. Execution status display

   The status matching the Execution status is displayed.

   The execution log and error log also displays detailed information regarding the execution status.

   If the execute type is "Execute", "Normal" will be displayed. If Dry run is selected, "Dry run". If Parameter check is selected, "Parameter check" will be displayed.

   If the status ends in an unexpected error, a message will be displayed in the error log.

   "Call Conductor" displays which Conductor was executed. This field will be blank if directly executed from Ansible-Legacy driver.
2. Confirm Target host

   Clicking the Check Target host button displays Ansible-Legacy ▶ Target host where hosts from Operations and Movements are displayed.
3. Confirm Substitute value

   Clicking the Check Sbstitute value button displays Ansible-Legacy ▶ Substitute value management where users can see Specific values and Variables from Operations and Movements.
4. Emergency stop/Delete reservation

   Users can press the Emergency stop button to stop the operation.

   If the status was "Reserved execution", the Delete reservation button will be displayed. Check the Delete reservation button to delete the reservation
5. Display execution log

   When Ansible Automation Controller is executed, the Playbook is executed in units of the device to be built grouped by the item values of Ansible common ▶ Device list's User ・ Password ・ssh secret key file ・ Passphrase ・ Connection type ・ Instance group, which splits the execution logs.

   By specifying the number of job slices in the Option parameter in Ansible common ▶ Interface information or Ansible-Legacy ▶ Movement list, the grouped targets can be further divided into the number of specified job slices before the Playbook is executed and the execution log is further divided.

   If the execution log has been divided, the execution log will be divided into tabs, where the user can select which execution log they want to see.
   The log file names displayed in the execution log's pulldown menu are as following.

   exec.log: Log file containing all execution logs.

   Not exec.log: Divided execution log. The file convention are as following.

   exec_<Group number>_<Serial number>

   表 2.50 Divided execution log file naming convention

   Component	Contents
   Group number	The Execution target's serial number grouped by the Ansible common ▶ Device list's User ・ Password ・ ssh secret key file ・ Passphrase ・ Connection type ・ Instance group items.
   Serial number	Serial number from 1 that divides the group by setting the number of job slices. If 0, no division of job slicing was done.

6. Search log

   Users can filter information to narrow down information in the execution log and the error log.

   Input the string the user wants to search for and tick the "Corresponding lines only" checkbox to view only the lines corresponding to the string.

   The refresh interval and maximum display lines can be configured by changing the "Status monitoring cycle item" and "Progress status display lines" items in Ansible common ▶ Interface information.
7. Input data

   Users can download executed Playbooks.

   For more information, see Link between ITA menus and Input data when executing Ansible.
8. Result data

   Users can download execution logs and error logs.

   For more information, see Result data created when executing Ansible.

Execution management

Allows userse to view execution histories. | Specify search conditions and press the Filter button to view a table of executions. | Pressing the Details button moves the user to Ansible-Legacy ▶ Confirm execution status where they can view detailed information regarding the execution status.

図 2.31 Submenu (Execution management)

1. The items found in the page are as following.

   表 2.51 View page item list (Execution management)

   Item			Description
   Execution number.			Displays an automatically given unique ID (36 characters)
   Execution type			Displays the Execution type.
   Status			Displays the status of the Execution.
   Emergency stop flag			Displays whether the operation has been stopped by the Emergency stop button from the Ansible-Legacy ▶ Execution status check menu.or not.
   Execution engine			Displays the Execution engine used.
   Called Conductor			Displays the Conductor name if executed from Conductor.
   Execution user			Displays the user who executed the Ansible.
   Registration date			Displays when the Execute button was clicked.
   Movement	ID		Displays the selected Movement ID.
   	name		Displays the selected Movement name
   	Delay timer		Displays the delay timer value configured to the Movement.
   	Ansible use information	Host specification format	Displays the selected Movement's Host specification format.
   		WinRM connection	Displays the selected Movement's WinRM connection.
   		Header section	Displays the selected Movement's header section.
   		ansible.cfg	Allows users to download the selected Movement's ansible.cfg file.
   	Ansible Execution Agent use information	Execution environment	Displays the Ansible Execution Agent's execution environment of the selected Movement.
   		ansible-builderparameter	Displays the ansible-builder of the selected Movement.
   	Ansible Automation Controller use information	Execution environment	Displays the selected Movement's execution environment.
   Operation	No.		Displays the selected Operation's ID
   	Name		Displays the selected Operation's name
   Input data			Allows users to download the input data in a Zip file
   Result data			Allows users to download the result data in a Zip file.
   Execution status	Reservation date		Displays the reservation date if the execution is reserved.
   	Start date		Displays when the execution will start.
   	End date		Displays when the execution will end.
   Collect status	Status		Displays the Connection function's status.
   	Collection log		Allows users to downlaod the Collection function's log.
   Conductor instance number			Displays the Conductor instance number if executed from Conductor.

Target host

1. Allows users to view Target hosts.

   

   図 2.32 Submenu (Target host)

2. The items found in the view page are as following.

   表 2.52 View page item list (Target host)

   Item	Description
   Item number	Displays an automatically given unique ID (36 characters)
   Execution number	Displays the Execution number when executed.
   Operation	Displays the Operation when executed.
   Movement name	Displays the Movement when executed.
   Host name	Displays the Target host when Executed.
   Remarks	Free description field

Substitute value management

1. Displays the Variable's specific values.

   

   図 2.33 Submenu (Substitute value management)

2. The items found in the page are as following.

   表 2.53 View page item list (Substitute value management)

   Item			Description
   Item number			Displays an automatically given unique ID (36 characters).
   Execution number			Displays the Execution number when executed.
   Operation			Displays the selected Operation.
   Movement name			Displays the selected Movement.
   Host name			Displays the selected Target host.
   Movement name:Variable name			Displays the Variable name when executed
   Specific value	String	Sensitive settings	Displays either "True" or "False".
   		Value	Displays the Variable's Specific value when executed. If the Sensitive settings are set to "True" The Specific value input to the Parameter sheet will be encrypted and not be viewable on ITA. The variable's Specific value has its encrypted contents configured by ansible-vault. If the Sensitive settings are set to "False" The Specific value input to the Parameter sheets will be displayed.
   	File		Displays the File name linked to the Variables.
   Substitute order			If the variable is a Multiple Specific Value Variable, the Substitute order will be displayed.
   Remarks			Free description field

2.6. Describing Playbook (Ansible-Legacy)

Playbooks uploaded to Playbook file collection are executed in include format by the Master playbook generated by ITA.

The Master Playbook are configured by the Header section and tasks section.

2.6.1. Header section

Playbooks does not require a header section when being uploaded.

Header sections have default values, but users can change them by using Ansible-Legacy ▶ Movement list's Header section.

▼Header section default value

- hosts: all
  remote_user: "{{ __loginuser__ }}"
  gather_facts: no
  become: yes
# For winrm connections, "become: yes" is ommited.

2.6.2. tasks section

Uploaded Playbooks are executed in include format by the Master playbook generated by ITA.

For more information regarding Playbooks, see Ansible's official manuals.

e.g.) Playbook example

- name: Comment
  template:
    src:   "{{ item.src }}"
    dest:  "{{ item.dest }}"
    owner: "{{ item.owner is none |ternary('root', item.owner) }}"
    group: "{{ item.group is none |ternary('bacula', item.group) }}"
    mode:  "{{ item.mode is none |ternary('0654', item.mode) }}"

Uploaded Playbooks are included according to Ansible-Legacy ▶ Movement-Playbook link's Include order.

2.7. Appendix

2.7.1. Link between ITA menus and Input data when executing Ansible

Information from the different ITA menus are extracted in order to create input data required to execute Ansible. When this happens, Password items in the Ansible common ▶ Device list menu and items with their Sensitive settings set to "True" in the Ansible-Legacy ▶ Substitute value management menu.

The Input data can be downloaded from the Ansible-Legacy ▶ Confirm execution status menu's Input data.

Useres can also directly execute Ansible by unzipping the downloaded input data in a specified directory.

The relationships between the different data and ITA menus are as following.

Ansible-Legacy input data

2.7.2. Result data created when executing Ansible

The results from executing "Input data" with Ansible are saved as "Result data" in a ZIP file.

"Result data" can be downloaded from Ansible-Legacy ▶ Confirm execution status menu's Result data in a ZIP file.

File list saved to Legacy result data

表 2.54 File list saved to Legacy result data

File name	Recorded contents	Ansible Core	Ansible Automation Controller	Ansible Execution Agent
result.txt	Records Ansible execution result's execution results	〇
error.log	Error output file with Executing. Ansible-playbbok command standard error output file. Contents displayed in the Execute confirmation error log.	〇	〇	〇
exec.log.org	xecution log output by Ansible-playbook	〇	〇	〇
exec.log	Edited Aexec.log.org Contents displayed to the Execution confirmation execution log	〇	〇	〇
exec_<Execution number>_<group number>	Divided execution log file For more information regarding file name conventions, see the execution log in Confirm execution status .		〇
forced.txt	Text file if stopped with Emergency stop	〇		〇
user_files	A directory where files are recorded when some file is output to ITA's original variable "__workflowdir__" in the playbook executed.	〇	〇	〇
child_exec.log child_error.log	ansible-builder execution log			〇