Image Management

pyATS Clean has a feature that can manage passing images between stages to help reduce the size and complexity of the Clean YAML. Images can be defined in the Clean YAML or can be passed via command line arguments (See Passing images through CLI).

To illustrate the difference, please see the Clean YAML below without using Image Management. The highlighted lines are the lines that Image Management would automatically populate if used.

Note

Some stage arguments may be missing in order to be brief. This is not a working example.

 1cleaners:
 2    PyatsDeviceClean:
 3        module: genie.libs.clean
 4        devices: [PE1]
 5
 6devices:
 7    PE1:
 8        connect:
 9
10        copy_to_linux:
11            origin:
12                files: /path/to/image.bin
13            destination:
14                directory: /tftp-server
15                hostname: 127.0.0.1
16            unique_number: 12345
17
18        copy_to_device:
19            origin:
20                files: /tftp-server/image_12345.bin
21                hostname: 127.0.0.1
22            destination:
23                directory: 'bootflash:'
24
25        change_boot_variable:
26            images:
27            - bootflash:/image_12345.bin
28
29        reload:
30
31        verify_running_image:
32            images:
33            - bootflash:/image_12345.bin
34
35        order:
36        - connect
37        - copy_to_linux
38        - copy_to_device
39        - change_boot_variable
40        - reload
41        - verify_running_image

Now with Image Management used, see how the image only needs to be provided once, rather than in each stage that requires it. pyATS Clean will pass the correct image value automatically between stages.

 1cleaners:
 2    PyatsDeviceClean:
 3        module: genie.libs.clean
 4        devices: [PE1]
 5
 6devices:
 7    PE1:
 8
 9        images:
10        - /path/to/image.bin
11
12        connect:
13
14        copy_to_linux:
15            destination:
16                directory: /tftp-server
17                hostname: 127.0.0.1
18            unique_number: 12345
19
20        copy_to_device:
21            origin:
22                hostname: 127.0.0.1
23            destination:
24                directory: 'bootflash:'
25
26        change_boot_variable:
27
28        reload:
29
30        verify_running_image:
31
32        order:
33        - connect
34        - copy_to_linux
35        - copy_to_device
36        - change_boot_variable
37        - reload
38        - verify_running_image

Images key structure for Image Management

Different platforms require different structures for the images key. See the below table to find the correct structure. Some platforms may support multiple structure types.

os

platform

schema

iosxe

 
Structure #1
------------
images:
- /path/to/image.bin
- /path/to/optional_package1
- /path/to/optional_package2

Structure #2
------------
images:
  image:
  - /path/to/image.bin
  packages:   <<< optional
  - /path/to/optional_package1
  - /path/to/optional_package2

Structure #3
------------
images:
  image:
    file:
    - /path/to/image.bin
  packages:  <<< optional
    file:
    - /path/to/optional_package1
    - /path/to/optional_package2

iosxr

 
Structure #1
------------
images:
- /path/to/image.bin
- /path/to/optional_package1
- /path/to/optional_package2

Structure #2
------------
images:
  image:
  - /path/to/image.bin
  packages:   <<< optional
  - /path/to/optional_package1
  - /path/to/optional_package2

Structure #3
------------
images:
  image:
    file:
    - /path/to/image.bin
  packages:  <<< optional
    file:
    - /path/to/optional_package1
    - /path/to/optional_package2

nxos

aci

 
Structure #1
------------
images:
- /path/to/switch_image.bin

Structure #2
------------
images:
  switch:
  - /path/to/switch_image.bin

Structure #3
------------
images:
  switch:
    file:
    - /path/to/switch_image.bin

apic

 
Structure #1
------------
images:
- /path/to/controller_image.bin
- /path/to/switch_image.bin

Structure #2
------------
images:
  controller:
  - /path/to/controller_image.bin
  switch:
  - /path/to/switch_image.bin

Structure #3
------------
images:
  controller:
    file:
    - /path/to/controller_image.bin
  switch:
    file:
    - /path/to/switch_image.bin

nxos

n3k

 
Structure #1
------------
images:
- /path/to/image.bin

Structure #2
------------
images:
  system:
  - /path/to/image.bin

Structure #3
------------
images:
  system:
    file:
    - /path/to/image.bin

nxos

n9k

 
Structure #1
------------
images:
- /path/to/image.bin

Structure #2
------------
images:
  system:
  - /path/to/image.bin

Structure #3
------------
images:
  system:
    file:
    - /path/to/image.bin

nxos

n7k

 
Structure #1
------------
images:
- /path/to/kickstart.bin
- /path/to/system.bin

Structure #2
------------
images:
  kickstart:
  - /path/to/kickstart.bin
  system:
  - /path/to/system.bin

Structure #3
------------
images:
  kickstart:
    file:
    - /path/to/kickstart.bin
  system:
    file:
    - /path/to/system.bin

Images override behavior

By default, the image(s) specified under a stage will be overridden by the image management service.

For IOSXE, this behavior can be modified with below configuration. This has not yet been implemented for other operating systems such as NXOS or IOSXR.

This behavior can be changed by adding a configuration stage called image_management with setting override_stage_images set to False. This overrides the default behavior and allows stages to keep their image configuration as specified in the clean yaml file.

Example clean yaml file with default behavior.

 1cleaners:
 2    PyatsDeviceClean:
 3        module: genie.libs.clean
 4        devices: [PE1]
 5
 6devices:
 7    PE1:
 8        images:
 9        - /path/to/image.bin
10
11        change_boot_variable:
12            images:
13            - bootflash:/image_12345.bin

with the above configuration, the image specified on line 13, will be overridden by the value on line 9.

Example clean yaml with updated configuration setting.

 1cleaners:
 2    PyatsDeviceClean:
 3        module: genie.libs.clean
 4        devices: [PE1]
 5
 6devices:
 7    PE1:
 8        image_management:
 9          override_stage_images: False
10
11        images:
12        - /path/to/image.bin
13
14        change_boot_variable:
15            images:
16            - bootflash:/image_12345.bin

With the above configuration, the image specified on line 16 will be used as is.