ansible-butler 1.2.5

A butler CLI for assistance in managing Ansible projects

ansible-butler

Butler CLI for Ansible projects

Functions

Object	Action	Description
directory	init	initialize an ansible directory
directory	clean	cleanup an ansible directory
ee	init	initialize an execution environment directory for ansible-builder
ee	inspect	quickly inpsect the python libraries and ansible collections in an execution environment
ee	dependencies[deps]	parse the dependency tree based on execution environment definition (or collection requirements)
role	list	list roles
role	dependencies[deps]	Build a dependency graph between roles in a specified directory [Example]
role	clean	clean role directory structure (remove empty yml files & dirs)
role	mk-readme	auto generate readme based on role meta and basic yml info
playbook	update	map legacy module names to FQCNs
playbook	list-collections[lc]	list collections used in a playbook (following include_* directives)
template	clone	clone a job template (including survey, schedules, and labels)

Usage

Usage:
  ansible-butler directory init [<dir>] [--config=PATH]
  ansible-butler directory clean [<dir>] [--skip-roles]
  ansible-butler ee init [<dir>] [--config=PATH]
  ansible-butler ee inspect [<image>] [--config=PATH]
  ansible-butler ee [dependencies|deps] [--config=PATH] [<name>]
  ansible-butler role list [--roles-path=PATH] [<name> --recursive]
  ansible-butler role [dependencies|deps] [--roles-path=PATH] [<master>]
  ansible-butler role clean [--roles-path=PATH] [<name> --recursive]
  ansible-butler role mk-readme [--roles-path=PATH] [<name> --recursive]
  ansible-butler playbook update [--context=CONTEXT] [--config=PATH] [<name>] [--recursive] [--force]
  ansible-butler playbook [list-collections|lc] [--context=CONTEXT] [--config=PATH] [<name>] [--recursive] [--force]
  ansible-butler template clone <id> [<name>] [--config=PATH] [--dry-run]

Arguments:
  name    name of target (accepts glob patterns)
  id      resource id
  image   name of image
  master  name of master node in graph
  dir     path to directory [default: ./]

Options:
  -h --help           Show this screen
  -r --recursive      Apply glob recursively [default: False]
  -f --force          Make file changes in place
  --dry-run           Do not make any changes - report on action behavior
  --config=PATH       Path to config file
  --roles-path=PATH   Path to roles directory [default: ./roles]
  --context=CONTEXT   Path to context directory [default: ./]
  --skip-roles        Flag to skip cleaning roles

Examples

• Initialize Ansible Directory
  • ansible-butler directory init ./sandbox
  • ansible-butler directory init ./sandbox --config=~/configs/ansible-butler.yml
• Clean an Ansible Directory
  • ansible-butler directory clean ./sandbox
  • ansible-butler directory clean ./sandbox --skip-roles
• Initialize Execution Environment Directory
  • ansible-butler ee init ./ee-windows
  • ansible-butler ee init ./ee-windows --config=~/configs/ansible-butler.yml
• Inspect an Execution Environment
  • ansible-butler ee inspect quay.io/zleblanc/ee-default
  • ansible-butler ee init quay.io/zleblanc/ee-default --config=~/configs/ansible-butler.yml
• Inspect Execution Environment Dependencies
  • ansible-butler ee dependencies execution-environment.yml
  • ansible-butler ee deps requirements.yml --config=~/configs/ansible-butler.yml
• Clean Roles
  • ansible-butler role clean my-role-1
  • ansible-butler role clean my-role-*
• List Roles
  • ansible-butler role list
  • ansible-butler role list ansible_collections/namespace/collection/roles
• Generate Dependency Graph
  • ansible-butler role deps
  • ansible-butler role deps ansible_collections/namespace/collection/roles
• Generate README
  • ansible-butler role mk-readme my-role-1
  • ansible-butler role mk-readme my-role-*
• Update Playbooks
  • ansible-butler playbook update --context=./playbooks -r
  • ansible-butler playbook update legacy-*.yml
  • ansible-butler playbook update -f
• List Collections
  • ansible-butler playbook list-collections --context=./playbooks -r
  • ansible-butler playbook lc example-playbook.yml
• Clone Job Template
  • ansible-butler template clone 1
  • ansible-butler template clone 1 --dry-run

Configuration

Create an .ansible-butler.yml in one or more of the following locations:

/etc/ansible-butler/    ## least precedence
~/
./                      ## highest precedence

You can also specify a specific path at runtime via the --config option.

# Example Configuration Schema
execution_environment:
  inspect:
    engine: auto # [auto,podman,docker]
    format: yaml # [yaml,json]
  init:
    # Refer to full schema here:
    # https://ansible.readthedocs.io/projects/builder/en/stable/definition/#overview
    version: 3
    additional_build_files:
      - src: files/ansible.cfg
        dest: configs
    ee_base_image: registry.redhat.io/ansible-automation-platform-24/ee-minimal-rhel9:latest
    dependencies:
      system:
        - ...
      python:
        - ...
      collections:
        - name: ansible.utils
          version: ">=3.1.0"
        - ...
    additional_build_steps:
      prepend_galaxy:
        - ADD _build/configs/ansible.cfg ~/.ansible.cfg

directory:
  init:
    lint: 
      enabled: true
    code_bot:
      enabled: true
      interval: weekly
    vscode:
      enabled: true
      settings:
        "files.trimTrailingWhitespace": true
        "editor.renderFinalNewline": "on"
        "files.trimFinalNewlines": true
    folders:
      - name: plugins
        folders:
          ...
        files:
          - README.md
    files:
      - playbook.yml

role:
  dependencies:
    output_fmt: html # [html,json]
    output_dest: graph.html
    include_tests: false
    master_node: role-common-setup
    initial_direction: downstream
    title: ansible-butler roles dependency graph
    title_text_color: white
    title_background_color: black
    tree_options:
      # Customize the color palette
      circleStrokeColor: '#2b8f91'
      linkStrokeColor: '#dddddd'
      closedNodeCircleColor: '#9bd3d4'
      openNodeCircleColor: white
      cyclicNodeColor: '#FF4242'
      missingNodeColor: '#CC0100'
      maxDepthNodeColor: '#FF5850'

playbook:
  update:
    modules:
      smart_device:
        redirect: zjleblanc.kasa.smart_device
      custom_module:
        redirect: company.it.custom_module

template:
  clone:
    skip_labels: false
    skip_survey: false
    skip_schedules: false

auth:
  verify_ssl: true
  # controller_host: https://controller.example.com   # Falls back to env CONTROLLER_HOST
  # controller_username: admin                        # Falls back to env CONTROLLER_USERNAME
  # controller_password: secret                       # Falls back to env CONTROLLER_PASSWORD
  # controller_token: token                           # Falls back to env CONTROLLER_OAUTH_TOKEN

🔗 Default configuration file
🔗 Example adding test plugins directory
🔗 Example adding module redirects
🔗 Example customizing directory init configs

Troubleshooting

• ansible-butler: command not found
  • check the $PATH environment variable and ensure that ~/.local/bin is included

License

GNU General Public License

Author Information

Zach LeBlanc

Red Hat