4. Ansible-LegacyRole

4.1. Introduction

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

4.2. Ansible-LegacyRole overview

Similar to the Legacy mode, this mode uses the standard Ansible functions to input settings to the different hosts.
Register structure code as packages and configure job patterns and roles.
Use Role packages provided by other departments to install the products and construct environments.

4.3. Ansible-LegacyRole Menu structure

This section explains the Ansible-LegacyRole menu structure

4.4. Ansible-LegacyRole procedure

This section explains how to use Ansible-LegacyRole

4.4.1. Ansible-LegacyRole workflow

A standard workflow using Ansible-LegacyRole 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 Role package
      From the Ansible-LegacyRole ▶ Role package management menu, register a Role package.
      For more information, see Role package management console.
    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 Role package to Movement
      From the Ansible-LegacyRole ▶ Movement-Role link menu, register a link between the registered Movement and the Role package.
      For more information, see Movement-Role link.
    15. Register Multistage variable maximum repetitions(if needed）
      From the Ansible-LegacyRole ▶ Variable nest management register maximum repetitions for the Member variable array defined in the Multistage variable arrays.
      For more information, see Variable nest management.
    16. 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.
    17. Register data to Parameter sheet
      Register data to the parameter sheet created in the previous step.
      For more information, see Parameter sheet creation function.
    18. Substitute value auto registration settings
      From the Ansible-LegacyRole ▶ 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.
    19. Execute
      From the Ansible-LegacyRole ▶ Execute menu, select the desired Movement and Operation and execute them.
      For more information, see Execute.
    20. Confirm execution status
      From the Ansible-LegacyRole ▶ 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.
    21. Confirm execution history
      From the Ansible-LegacyRole ▶ Execution management menu, users can check the history of all previously executed operations..
      For more information, see Execution management.

4.5. Ansible-LegacyRole menu operation

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

4.5.1. Basic console

For more information regarding Basic console menu, see Basic console

4.5.2. Ansible common

For more information regarding Ansible common menus, see Ansible common

4.5.3. Ansible-LegacyRole

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

Movement list

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

    図 4.13 Submenu (Movement list)

  2. Press the Register button to register Movement information.
    Registration page (Movement list)

    図 4.14 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..

Role package management console

  1. Maintains (view/register/edit/discard) Role package files .
    Make sure to register a directory with a hierarchy that has "roles" compressed in a ZIP file. For more information regarding Role package directories, see Writing Role packages .
    Submenu（Role package management）

    図 4.15 Submenu（Role package management）

  2. Press the Register to register Role packages.
    Registration page （Role package management）

    図 4.16 Registration page （Role package management）

  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 .

警告

Unique variable names in Movements
In Ansible-LegacyRole, the variable names extracted from files must be unique for each Movement.
If there are multiple variable names used for roles within the same role package and the variable structure is different, an error will occur whe nregistered to Ansible-LegacyRole ▶ Role package management.
Specificaly, if the structure for normal variable and multistage variable (or the structure between different multistage variables) are different, an error will occur if the same variable name is used.
This does not apply if the user is using different role packages.

Examples for the Specific values are as following.
e.g.)

Variable nest management

  1. Maintain (view/edit) maximum repetitions of the Member variable array from the Multistage variable defined in the Role package file（ZIP format） registered in Ansible-LegacyRole ▶ Role package management.
    For more information, see Substitute value auto registration settings.
    Submenu（Variable nest management）

    図 4.19 Submenu（Variable nest management）

  2. Press the Register button to edit the maximum amount of repetitions.
    Registration page （Variable nest management）

    図 4.20 Registration page （Variable nest management）

  3. The items found in the registration page are as following.
    表 4.11 Registration page Item list（Variable nest management）

    Item

    Description

    Input required

    Input method

    Restrictions

    Item number
    Displays an automatically numbered string of 36 characters.

    ー

    Automatic

    ー

    Maximum repetitions
    Input a value between 1～1,024 for the maximum repetitions.
    The maximum value can be changed by configuring the MAXIMUM_ITERATION_ANSIBLE-LEGACYROLE in Management Console - System settings

    〇

    Manual

    Input value from 1～1,024(Can be changed from System settings)

    Remarks

    Free description field

    ー

    Manual

    Maximum length 4000 bytes

警告

Initial registrations and Repetition count updates
he internal process initially registers the repetition count of member variable defined in the nested variable which is defined in the role package. After the initial registration, the repetition count can be updated in the "Nested variable management" menu.
Note that both the initial registration and the update does not happen in real-time, meaning that it may take time before they can be used in Substitute value auto registration settings.

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-LegacyRole ▶ Substitute value management and Ansible-LegacyRole ▶ Target host when executed by internal processes.

    Submenu (Substitute value auto registration settings)

    図 4.21 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
    Registration page (Substitute value auto registration settings)

    図 4.22 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-LegacyRole ▶ 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.
Register Substitute value auto registration settings when using Bundled parameter sheets.

Tip

※2:Only required when variable is multistage.
Member variables are only required if the variable is a Multistage variable. The variables displayed in the Member variables are the only variables that requries specific values.
Connect the stage variables with "."
For repetition arrays, connect the start position （0～）with [ ]. The amount of repeated arrays are configured in Ansible-LegacyRole ▶ Variable nest management.

e.g.） Checking the selectable member variables after updating the Variable Nest Management's maximum repetitions and the selectable member variables in Substitute value auto registration settings.
  1. Define variables to the Role package variable definition file （defaults/main.yml） as below and register Role package in Ansible-LegacyRole ▶ Role package management
    Variable definition file contents
    VAR_aaaa:
  - name: alice
    object: obj1
    directory:
      - craete_dir: /dir
    password:
      - craete_pass:
        sample:
          - sample_pass: pass1
      - craete_pass:
        sample:
          - sample_pass: pass2
    user:
      root:
        - craete_users:
          prod:
            - prod_user: user1
          dev:
            - dev_user: user2
  2. If a role package is registered with variables defined like in Step 1. the following will be registered to Ansible-LegacyRole ▶ Variable nest management and the user will able to select the following member variables in Ansible-LegacyRole ▶ Substitute value auto registration settings by default.
    表 4.12 Variable nest management registration contents

    Variable name

    Member variable name

    Maximum repetitions

    VAR_aaaa

    0

    1

    VAR_aaaa

    0.directory

    1

    VAR_aaaa

    0.password

    1

    VAR_aaaa

    0.password.sample

    1

    VAR_aaaa

    0.user.root

    1

    VAR_aaaa

    0.user.root.dev

    1

    VAR_aaaa

    0.user.root.prod

    1
    表 4.13 Selectable Member variables in Substitute value auto registration settings

    Variable name

    Member variable name

    VAR_aaaa

    [0].directory[0].create_dir

    VAR_aaaa

    [0].name

    VAR_aaaa

    [0].object

    VAR_aaaa

    [0].password[0].create_pass

    VAR_aaaa

    [0].password[0].sample[0].sample_pass

    VAR_aaaa

    [0].user.root[0].create_users

    VAR_aaaa

    [0].user.root[0].dev[0].dev_user

    VAR_aaaa

    [0].user.root[0].prod[0].prod_user
  3. In Ansible-LegacyRole ▶ Variable nest management, edit the Member variable "0.user.root.prod"'s Maximum repetitions from "1" to "3".
    表 4.14 Variable nest management edited contents

    Variable name

    Member variable name

    Maximum repetitions

    VAR_aaaa

    0.user.root.prod

    3
  4. If the member variables are edited like they were in Step 3., The selectable member variables in Ansible-LegacyRole ▶ Substitute value auto registration settings are also changed.
    (Member variable [0].user.root[0].prod[1].prod_user and [0].user.root[0].prod[2].prod_user are added to the pulldown selection)
    表 4.15 Selectable Member variables in Substitute value auto registration settings

    Variable name

    Member variable name

    VAR_aaaa

    [0].directory[0].create_dir

    VAR_aaaa

    [0].name

    VAR_aaaa

    [0].object

    VAR_aaaa

    [0].password[0].create_pass

    VAR_aaaa

    [0].password[0].sample[0].sample_pass

    VAR_aaaa

    [0].user.root[0].create_users

    VAR_aaaa

    [0].user.root[0].dev[0].dev_user

    VAR_aaaa

    [0].user.root[0].prod[0].prod_user

    VAR_aaaa

    [0].user.root[0].prod[1].prod_user

    VAR_aaaa

    [0].user.root[0].prod[2].prod_user

Tip

※3:Only required when selected variable can have multiple specific values configured
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. Follow the example below and define variables to the Role package variable definition file（defaults/main.yml） and register a Role package in Ansible-LegacyRole ▶ Role package management.
    Variable definition file description contents
    VAR_substitutionA:
  - user-name
  - group-name
  - meta-name

VAR_substitutionB:
  - login
  - authorized
  - space
  - cluster
  2. In :menuselection:`Ansible-LegacyRole --> Substitute value auto registration settings`m link Role variables and th setting values for items registered to the Parameter sheets.
    表 4.16 Parameter sheet registration contents

    Host name

    Operation name

    Parameter

    Item1

    Item2

    Item3

    Item4

    test-host

    test-ope

    value1

    value2

    value3

    value4
    表 4.17 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
  3. 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.
The same goes for multistage variables. Only member variables with specific values registered will be output.

e.g.） Checking variables output the the Host variable file when executing Variables with specific values registered to them in the Substitute value auto registration settings.
  1. Follow the example below and define variables to the Role package variable definition file（defaults/main.yml） and register a Role package in Ansible-LegacyRole ▶ Role package management.
    Variable definition file description contents
    VAR_output:
  - name: alice
    group: root
    user:
      root:
        - craete_users:
          prod:
            - prod_user: user1
          dev:
            - dev_user: user2
  2. In the Ansible-LegacyRole ▶ Substitute value auto registration settings menu, link Role variables and setting values for items registered to the Parameter sheets.
    表 4.18 Parameter sheet registration contents

    Host name

    Operation name

    Parameter

    Item1

    Item2

    test-host

    test-ope

    value1

    value2
    表 4.19 Substitute value auto registration settings registration contents

    Menu name

    Item

    Variable name

    Member variable name

    sample-menu

    Item1

    VAR_output

    [0].name

    sample-menu

    Item2

    VAR_output

    [0].user.root[0].dev[0].dev_user
  3. 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_output:
  - name: value1
    user:
      root:
      - dev:
        - dev_user: value2

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.
    表 4.20 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.
    Define/Create parameter sheet

    図 4.23 Define/Create parameter sheet

    表 4.21 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-LegacyRole ▶ 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.
    表 4.22 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-LegacyRole ▶ Confirm execution status's Check substitute value button to check that the '{{ CPF_test }}' and '{{ TPF_sample }}' are dispalyed to the Specific value.
    Confirm execution status Substitute value management

    図 4.24 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-LegacyRole ▶ Confirm execution status where the execution process will start
Execute menu

図 4.25 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-LegacyRole ▶ 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.
Submenu (Confirm execution status)

図 4.26 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-LegacyRole.
  2. Confirm Target host
    Clicking the Check Target host button displays Ansible-LegacyRole ▶ Target host where hosts from Operations and Movements are displayed.
  3. Confirm Substitute value
    Clicking the Check Sbstitute value button displays Ansible-LegacyRole ▶ 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-LegacyRole ▶ 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>
    表 4.23 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-LegacyRole ▶ Confirm execution status where they can view detailed information regarding the execution status.
Submenu (Execution management)

図 4.27 Submenu (Execution management)

  1. The items found in the page are as following.
    表 4.24 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-LegacyRole ▶ 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.
    Submenu (Target host)

    図 4.28 Submenu (Target host)

  2. The items found in the view page are as following.
    表 4.25 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.
    Submenu (Substitute value management)

    図 4.29 Submenu (Substitute value management)

  2. The items found in the page are as following.
    表 4.26 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

4.6. Describing Structure code

4.6.1. Writing Role packages

For more information regarding Role package formats, see the official Ansible Manuals.
This section explains the the role packages ZIP file uploaded to "Role package management console" and which directory it should contain.
（Upper directory）
│
├─── site.yml                                             ・・・・・・・・・・・・・・・・・・・・・・・・ （1）
│
├─── hosts                                                ・・・・・・・・・・・・・・・・・・・・・・・・ （2）
│
├─── group_vars                                           ・・・・・・・・・・・・・・・・・・・・・・・・ （3）
│
├─── host_vars                                            ・・・・・・・・・・・・・・・・・・・・・・・・ （4）
│
├─── ITA readme                                           ・・・・・・・・・・・・・・・・・・・・・・・・ （5）
│
└─── roles                                                ・・・・・・・・・・・・・・・・・・・・・・・・ （6）
        │
        ├─ [role name①]                                    ・・・・・・・・・・・・・・・・・・・・・・・・ （7）
        │     │
        │     ├── readme.md                               ・・・・・・・・・・・・・・・・・・・・・・・・ （8）
        │     │
        │     ├── tasks                                   ・・・・・・・・・・・・・・・・・・・・・・・・ （9）
        │     │      ├── main.yml
        │     │      └── user_files
        │     │      └── user.yml
        │     │
        │     ├── handlers                                ・・・・・・・・・・・・・・・・・・・・・・・・ （10）
        │     │      ├── main.yml
        │     │      └── user_files
        │     │      └── user.yml
        │     │
        │     ├── templates                               ・・・・・・・・・・・・・・・・・・・・・・・・ （11）
        │     │      ├── hosts.j2
        │     │      └── user_files
        │     │      └── user.j2
        │     │
        │     ├── files                                   ・・・・・・・・・・・・・・・・・・・・・・・・ （12）
        │     │      └── sudoers
        │     │
        │     ├── vars                                    ・・・・・・・・・・・・・・・・・・・・・・・・ （13）
        │     │      └─ main.yml
        │     │
        │     ├── defaults                                ・・・・・・・・・・・・・・・・・・・・・・・・ （14）
        │     │      ├── main.yml
        │     │      └── user_files
        │     │              └── user.yml
        │     │
        │     ├── meta                                    ・・・・・・・・・・・・・・・・・・・・・・・・ （15）
        │     │      └── main.yml
        │     │
        │     If there are other directories and files, ITA will not recognize them.
        │
        └─ [role name②] roles have no specific limits.
Should include
〇　：Required
△　：Optional

Handled by ITA

（1）　site.yml　（Master Playbook）

△

Created by ITA. Will be overwritten if exists.

（2）　hosts

△

Created by ITA. Will be overwritten if exists.

（3）　group_vars

△

Not handled by ITA. Will be deleted if exists

（4）　host_vars

△

Created by ITA. Will be overwritten if exists.

（5）　ITA readme

△
ITA readme is defined for every role. Error doesn't occur even if the file deosn't exist.
ITA readme character code should be UTF-8 without BOM.
For more information, see "Writing ITAreadme"

（6）　roles

〇

An Upload error will occur if the roles directory does not exist.

（7）　roles/[role name①]

〇
An Upload error will occur if the role name directory does not exist.
Handles directories (tasks directory included) as role.
Directory hierarchy can be deep.

（8）　roles/[role name①]/readme.md

△

Not recognized by ITA.

（9）　roles/[role name①]/tasks

〇
tasks directory is required.
playbook character code should be UTF-8 without BOM.
An Upload error will occur if main.yml does not exist.
Can contain other files than main.yml
Can deploy other files than main.yml in the sub-directory.

（10）　roles/[role name①]/handlers

△
handlers directory is not recognized.
playbook character code should be UTF-8 without BOM.
main.yml is not recognized.
Can contain other files than main.yml
Can deploy files into the sub-directory.

（11）　roles/[role name①]/templates

△
templates directory is not recognized.
The file character code should be UTF-8 without BOM.
Can deploy files into the sub-directory.

（12）　roles/[role name①]/files

△
files directory is not recognized.
File or sub-directory is not recognized.
File contents are not recognized.

（13）　roles/[role name①]/vars

△
vars directory is not recognized.
playbook character code should be UTF-8 without BOM.
File or sub-directory is not recognized.
File contents are not recognized.

（14）　roles/[role name①]/defaults

△
defaults directory is not recognized.
playbook character code should be UTF-8 without BOM.
main.yml is not recognized.
Can contain other files than main.yml
Can deploy other files than main.yml in the subdirectory.

（15）　roles/[role name①]/meta

△
meta directory is not recognized.
playbook character code should be UTF-8 without BOM.
File or sub-directory is not recognized.
File contents are not recognized.

Master Playbook

The Master Playbook created by ITA consists of a header section and Roles section.
  1. Header section
    Header sections have default values, but users can change them by using Ansible-LegacyRole ▶ 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. roles section
    Roles from uploaded role packages are executed according to the Include order in Ansible-LegacyRole ▶ Movement-Role link.
    ../../_images/role_session.png

Points to note when the role name in the role package is set to the directory hierarchy.

he following directory hierarchy role package will be explained as an example.
└── roles
       ├── parent
       │     ├── sample_role1
       │     │ ├── defaults
       │     │ └── tasks
       │     └── sample_role2
       │            ├── defaults
       │            ├── sample_role3
       │            │     ├── defaults
       │            │     └── tasks
       │            ├── sample_role4
       │            │     ├── defaults
       │            │     └── tasks
       │            └── tasks
       ├── sample_role5
       │     └── defaults
       └── sample_role6
              ├── defaults
              └── tasks
  1. he directory recognized as a role is the directory containing the tasks directory.
    In this example. There are three directory hierarchies (role names) to be handled by roles.

    • parent/sample_role1

    • parent/sample_role2

    • sample_role6

  2. Exclude directory hierarchies with multiple tasks directories
    There are tasks directories in parent/sample_role2/sample_role3 and parent/sample_role2/sample_role4, but parent/sample_role2 has a tasks directories and recognizes them as roles, meaning they are not handaled as a role.

4.6.2. Writing ITAreadme

The substitution value management function interpretes the variable type defined in defaults variable definition file and sets the variable value of each variable and its' member variable.

ITA readme file naming convention

　ita_readme_[Role name].yml
　e.g.）

Role name

File name

mysql

ita_readme_mysql.yml

mysql/install

ita_readme_mysql%install.yml

警告

If the Role directory hierarchy is deep, the user will have to change "/" with "%" in the Role name.

ITA readme format

The format is YAML format.
Make sure the character code is UTF-8 without BOM.
The flow of the output of the concrete values of the variables defined in the ITA readme to the host variable file is henceforth referred to as " Substitute value management function".
If variable definitions overlap in the ITA readme and the defaults variable definition file, the variable structure of the ITA readme is applied.

Tip

If variable definitions overlap in the ITA readme and the defaults variable definition file,the following rules are applied.
表 4.27 Variable adoption rule

defaults variable definition file

ITA readme

Variable structure destination

Defined

Not defined

Default variable definition file

Not defined

Defined

ITA readme

Defined

Defined

ITA readme
The ITA readme is cut of from the Role package when executed.
Variables and specific values written in the ITA readme file will not be given to Ansible.

"ita_readme" use example

This section uses 7 cases to explain how the "ita_readmy" file can be used in Ansible-LegacyRole.

This section assumes that Ansible-LegacyRole ("roles" directory) is fetched from an external source.
The following figure illustrates of using the ita_readme file to uploading it and checking the results.
Overall image

図 4.30 Overall image

The 7 use examples uses the previous figure as a base.
表 4.28 Ansible Automation Controller system requirements

No.

Case

1

Using externally fetched Ansible-LegacyRole without editing it.

2

"ita_readme" role

3

Variable definitions and default values described in the "defaults/main.yml" file.

4

"host_vars" files and "ITA Parameter sheet"

5

Adding variables to “defaults/main.yml”

6

Applying Playbook Length evaluation

7

Applying Playbook Defined evaluation
  • Case １：Using externally fetched Ansible-LegacyRole without editing it
    Users can use Ansible-Legacy Role (roles directory) acquired from anexternal source without modifying it.
    Therefore, users can put the ita_readme file and/or substitute table in the “roles” directory and assign parameters to the variables used inside the directory.
Case １ figure

図 4.31 Case １ figure

  • Case ２："ita_readme" role
    The ita_readme file is used to send variables/variable types to ITA.
    In other words, they are not used to define specific values (Parameters).
    ITA will not be able to read any specific values written in them.
    Please see the other cases below for information on how to assign specific values.
Case ２ figure

図 4.32 Case ２ figure

  • Case ３：Variable definitions and default values described in the "defaults/main.yml" file
    The "defaults/main.yml" file stored under "roles" is automatically passed to ansible.
    The file will be automatically sent as long only if no variables or default values are defined in host_vars.(E.g: "VAR_A：aaa").
Case ３ figure

図 4.33 Case ３ figure

  • Case ４："host_vars" files and "ITA Parameter sheet"
    Host_vars files are automatically created everytime ITA parameter sheets executes something.
Case ４ figure

図 4.34 Case ４ figure

  • Case ５：Adding variables to “defaults/main.yml”
    In order to add any changes to Ansible-Legacy Role ("roles" directory), users can describe variable names/types in the "ita_readme" file.

    Users do not have to define any variables in the ita_readme file that are already defined in the "defaults/main.yml" file.
    If there are different definitions for the same variables in the files, the ones in the "ita_readme" file will be prioritized.

    ※The figure below illustrates that it is possible to add variables by describing a variable(VAR_H) in the ita_readme file
Case ５ figure

図 4.35 Case ５ figure

  • Case ６：Applying Playbook Length evaluation
    Depending on whether a variable has a concrete value or not, it can be used as a conditional branch for length evaluation.
    For example if "VAR_C：[]" is written in "defaults/main.yml", the length will equal 0 if the operation is executed with no specific value set to "VAR_C".
    On the other hand, doing the same with a specific value set will have length be <0 (length<0). (E.g.: VAR_X：sss)
Case ６ figure

図 4.36 Case ６ figure

  • Case ７：Applying Playbook Defined evaluation
    Depending on whether a variable has a concrete value or not, it can be used as a conditional branch for defined valuation.
    For example, first write a definition for the variables "VAR_G" and "VAR_H" in the "ita_readme" file. By doing so, they can be used by ITA parameter sheets.

    Running an operation without giving a specific value to "VAR_G" while it is not defined in "defaults/main.yml" or "host_vars" will turn "defined" to "false".
    On the other hand, if the specific value "kkk" is added to "VAR_H", "defined" will turn into "true".
Case ７ figure

図 4.37 Case ７ figure

4.7. Appendix

4.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-LegacyRole ▶ Confirm execution status menu's Result data in a ZIP file.

Ansible-LegacyRole result data File list

表 4.29 Ansible-LegacyRole result data File list

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

〇