Ansible deploy interface¶

Features¶

Similar to deploy interfaces relying on Ironic Python Agent, this deploy interface also depends on the deploy ramdisk calling back to ironic API’s heartbeat endpoint.

However, the driver is currently synchronous, so only the first heartbeat is processed and is used as a signal to start ansible-playbook process.

Bootstrap image requirements¶

• password-less sudo permissions for the user used by Ansible
• python 2.7.x
• openssh-server
• GNU coreutils
• utils-linux
• parted
• gdisk
• qemu-utils
• python-requests (for ironic callback and streaming image download)
• python-netifaces (for ironic callback)

A set of scripts to build a suitable deploy ramdisk based on TinyCore Linux and tinyipa ramdisk, and an element for diskimage-builder can be found in ironic-staging-drivers project but will be eventually migrated to the new ironic-python-agent-builder project.

Ansible-deploy options¶

openstack baremetal node set <node> \
    --deploy-interface ansible \
    --driver-info ansible_username=stack \
    --driver-info ansible_key_file=/etc/ironic/id_rsa

Expected playbooks directory layout¶

The [ansible]\playbooks_path option in the ironic configuration file is expected to have a standard layout for an Ansible project with some additions:

<playbooks_path>
|
\_ inventory
\_ add-ironic-nodes.yaml
\_ roles
 \_ role1
 \_ role2
 \_ ...
|
\_callback_plugins
 \_ ...
|
\_ library
 \_ ...

The extra files relied by this driver are:

inventory

Ansible inventory file containing a single entry of conductor ansible_connection=local. This basically defines an alias to localhost. Its purpose is to make logging for tasks performed by Ansible locally and referencing the localhost in playbooks more intuitive. This also suppresses warnings produced by Ansible about hosts file being empty.

add-ironic-nodes.yaml

This file contains an Ansible play that populates in-memory Ansible inventory with access information received from the ansible-deploy interface, as well as some per-node variables. Include it in all your custom playbooks as the first play.

The default deploy.yaml playbook is using several smaller roles that correspond to particular stages of deployment process:

• discover - e.g. set root device and image target
• prepare - if needed, prepare system, for example create partitions
• deploy - download/convert/write user image and configdrive
• configure - post-deployment steps, e.g. installing the bootloader

Some more included roles are:

• shutdown - used to gracefully power the node off in-band
• clean - defines cleaning procedure, with each clean step defined as separate playbook tag.

Extending playbooks¶

Most probably you’d start experimenting like this:

1. Create a copy of deploy.yaml playbook in the same folder, name it distinctively.
2. Create Ansible roles with your customized logic in roles folder.
   1. In your custom deploy playbook, replace the prepare role with your own one that defines steps to be run before image download/writing. This is a good place to set facts overriding those provided/omitted by the driver, like ironic_partitions or ironic_root_device, and create custom partitions or (software) RAIDs.
   2. In your custom deploy playbook, replace the configure role with your own one that defines steps to be run after image is written to disk. This is a good place for example to configure the bootloader and add kernel options to avoid additional reboots.
   3. Use those new roles in your new playbook.
3. Assign the custom deploy playbook you’ve created to the node’s driver_info/ansible_deploy_playbook field.
4. Run deployment.
   1. No ironic-conductor restart is necessary.
   2. A new deploy ramdisk must be built and assigned to nodes only when you want to use a command/script/package not present in the current deploy ramdisk and you can not or do not want to install those at runtime.

Variables you have access to¶

This driver will pass the single JSON-ified extra var argument to Ansible (as in ansible-playbook -e ..). Those values are then accessible in your plays as well (some of them are optional and might not be defined):

ironic:
  nodes:
  - ip: "<IPADDRESS>"
    name: "<NODE_UUID>"
    user: "<USER ANSIBLE WILL USE>"
    extra: "<COPY OF NODE's EXTRA FIELD>"
  image:
    url: "<URL TO FETCH THE USER IMAGE FROM>"
    disk_format: "<qcow2|raw|...>"
    container_format: "<bare|...>"
    checksum: "<hash-algo:hashstring>"
    mem_req: "<REQUIRED FREE MEMORY TO DOWNLOAD IMAGE TO RAM>"
    tags: "<LIST OF IMAGE TAGS AS DEFINED IN GLANCE>"
    properties: "<DICT OF IMAGE PROPERTIES AS DEFINED IN GLANCE>"
  configdrive:
    type: "<url|file>"
    location: "<URL OR PATH ON CONDUCTOR>"
  partition_info:
    label: "<msdos|gpt>"
    preserve_ephemeral: "<bool>"
    ephemeral_format: "<FILESYSTEM TO CREATE ON EPHEMERAL PARTITION>"
    partitions: "<LIST OF PARTITIONS IN FORMAT EXPECTED BY PARTED MODULE>"

ironic.nodes

List of dictionaries (currently of only one element) that will be used by add-ironic-nodes.yaml play to populate in-memory inventory. It also contains a copy of node’s extra field so you can access it in the playbooks. The Ansible’s host is set to node’s UUID.

ironic.image

All fields of node’s instance_info that start with image_ are passed inside this variable. Some extra notes and fields:

• mem_req is calculated from image size (if available) and config option [ansible]extra_memory.
• if checksum is not in the form <hash-algo>:<hash-sum>, hashing algorithm is assumed to be md5 (default in Glance).
• validate_certs - boolean (yes/no) flag that turns validating image store SSL certificate on or off (default is ‘yes’). Governed by [ansible]image_store_insecure option in ironic configuration file.
• cafile - custom CA bundle to use for validating image store SSL certificate. Takes value of [ansible]image_store_cafile if that is defined. Currently is not used by default playbooks, as Ansible has no way to specify the custom CA bundle to use for single HTTPS actions, however you can use this value in your custom playbooks to for example upload and register this CA in the ramdisk at deploy time.
• client_cert - cert file for client-side SSL authentication. Takes value of [ansible]image_store_certfile option if defined. Currently is not used by default playbooks, however you can use this value in your custom playbooks.
• client_key - private key file for client-side SSL authentication. Takes value of [ansible]image_store_keyfile option if defined. Currently is not used by default playbooks, however you can use this value in your custom playbooks.

ironic.partition_info.partitions

Optional. List of dictionaries defining partitions to create on the node in the form:

partitions:
- name: "<NAME OF PARTITION>"
  unit: "<UNITS FOR SIZE>"
  size: "<SIZE OF THE PARTITION>"
  type: "<primary|extended|logical>"
  align: "<ONE OF PARTED_SUPPORTED OPTIONS>"
  format: "<PARTITION TYPE TO SET>"
  flags:
    flag_name: "<bool>"

The driver will populate this list from root_gb, swap_mb and ephemeral_gb fields of instance_info. The driver will also prepend the bios_grub-labeled partition when deploying on GPT-labeled disk, and pre-create a 64 MiB partition for configdrive if it is set in instance_info.

Please read the documentation included in the ironic_parted module’s source for more info on the module and its arguments.

ironic.partition_info.ephemeral_format

Optional. Taken from instance_info, it defines file system to be created on the ephemeral partition. Defaults to the value of [pxe]\default_ephemeral_format option in ironic configuration file.

ironic.partition_info.preserve_ephemeral

Optional. Taken from the instance_info, it specifies if the ephemeral partition must be preserved or rebuilt. Defaults to no.

As usual for Ansible playbooks, you also have access to standard Ansible facts discovered by setup module.

Included custom Ansible modules¶

The provided playbooks_path/library folder includes several custom Ansible modules used by default implementation of deploy and prepare roles. You can use these modules in your playbooks as well.

stream_url

Streaming download from HTTP(S) source to the disk device directly, tries to be compatible with Ansible’s get_url module in terms of module arguments. Due to the low level of such operation it is not idempotent.

ironic_parted

creates partition tables and partitions with parted utility. Due to the low level of such operation it is not idempotent. Please read the documentation included in the module’s source for more information about this module and its arguments. The name is chosen so that the parted module included in Ansible is not shadowed.