foreman_hammer

Table of Contents

• Description
• Setup
  • Requirements
  • Install requirements
  • Beginning with foreman_hammer
    • Foreman host templates
    • Dynamic foreman host templates
    • Hiera
    • Bolt inventory.yaml
• Usage
  • Examples
    • Bolt plan foreman::hosts
• Limitations
• Know Issues
  • Fetch missing ca certificate for foreman
• Development
  • Running acceptance tests
  • Release Process
  • Contributing

Description

This module includes Bolt task and plans for managing hosts in foreman with hammer-cli. Sensitive information like the foreman password could be encrypted as a bolt secret and read from inventory.yaml. Multiple host can be generated from yaml templates.

More information about foreman: https://theforeman.org/

More information about hammer-cli: https://github.com/theforeman/hammer-cli

Setup

Requirements

The Bolt target host requires:

• python3
• ruamel.yaml
• Jinja2
• hammer-cli-foreman

Install requirements

For examples on how to install the needed requirements look at the acceptance test setup file spec/spec_helper_acceptance_local.rb.

Beginning with foreman_hammer

There a different parts to setup the module.

Foreman host templates

A foreman host template is written in YAML and provides information on how to build the hammer-cli command for the host using this template.

There a 2 basic rules:

1. YAML scalars create hammer-cli command options
2. YAML maps create parameters which are comma-separated list of key=value pairs

To create a host named test-host you can specify the following host template:

---
hostgroup: my_hostgroup
compute-resource: libvirt
compute-attributes:
  cpus: 2
interface:
  - primary: true
    compute_type: network
    compute_network: default
volume:
  - capacity: 5G
  - capacity: 10G
    format_type: qcow2

and the following hammer-cli command will be used for creating the host:

hammer host create
  --hostgroup=my_hostgroup                   # most of the settings is done in the hostgroup
  --compute-resource=libvirt                 # set the libvirt provider
  --compute-attributes="cpus=2"              # specify the provider specific options, see the list below
  --interface="primary=true,compute_type=network,compute_network=default" # add a network interface, can be passed multiple times
  --volume="capacity=5G"                     # add a volume, can be passed multiple times
  --volume="capacity=10G,format_type=qcow2"  # add another volume with different size and type
  --name="test-host" 

See the following example as a base for building your own foreman host templates: data/host_templates/centos7.yaml

Dynamic foreman host templates

You could use the Jinja2 template engine with your foreman host templates to build resuable and more flexible host templates.

The following template use the Jinja2 template syntax:

---
hostgroup: my_hostgroup
compute-resource: libvirt
compute-attributes:
  cpus: 2
interface:
  - primary: true
    compute_type: network
    compute_network: default
volume:
  {% for name, config in volumes.items() %}
  - capacity: {{ config['capacity'] }}
    {% if config['format_type'] %}
    format_type: {{ config['format_type'] }}
    {% endif %}
  {% endfor %}

with the following template variables defined in hiera:

template_vars:
  volumes:
    disk1:
      capacity: 5G
    disk2:
      capacity: 10G
      format_type: qcow2
    disk3:
      capacity: 30G
      format_type: qcow2

will produce the following hammer-cli command for creating the host:

hammer host create
  --hostgroup=my_hostgroup                   
  --compute-resource=libvirt                 
  --compute-attributes="cpus=2"              
  --interface="primary=true,compute_type=network,compute_network=default" 
  --volume="capacity=5G"                     
  --volume="capacity=10G,format_type=qcow2"  
  --volume 'capacity=30G,format_type=qcow2'  
  --name="test-host" 

Hiera

The Bolt plans in this module will lookup the configuration how to manage hosts using hiera.

It specifies a list of host which will be managed and the unique information needed for each host e.g. ip, cpu, mem, the foreman host template, template variables etc..

See all available options in data/common.yaml.

For a example look at examples/example_common.yaml

Bolt inventory.yaml

The Bolt plans in this module will lookup the configuration how to access foreman with Bolt inventory file variables.

For an example look at examples/inventory.yaml.dist

Usage

For detailed instructions about the bolt task and plans look at REFERENCE.md.

Examples

Bolt plan foreman::hosts

This Bolt plan will create nonexistent host and update existing ones in foreman.

Create a bolt secret key pair for encrypting secrets (will not overwrite existing ones):

bolt secret createkeys

Generate example inventory.yaml:

./examples/generate_inventory

Provide the required infos for the script:

Generating inventory: ./examples/inventory.yaml from template: ./examples/inventory.yaml.dist
Backup existing inventory to: ./examples/inventory.yaml.2020-08-05_16:02:50
Please enter your value for <FOREMAN_URL>: https://foreman.example.de/
Please enter your value for <FOREMAN_USERNAME>: admin
Please enter your value for <SECRET_FOREMAN_PASSWORD>: ***********

This will produce this inventory.yaml:

# Inventory file for Bolt
version: 2
groups:
  - name: hammer-local
    targets:
      - hammer-local.127.0.0.1.nip.io
    config:
      transport: local
    vars:
      foreman:
        server_url: "https://foreman.example.de/"
        hammer_cli_bin: "hammer"
        username: 'admin'
        password:
          _plugin: pkcs7
          encrypted_value: ENC[PKCS7,MIIBiQYJFoZIhvcNAQcDoIIBeDDAXYCAQAxggEhMIIBHQIBADAFMAA.................==]

Execute the bolt plan on localhost and connect the foreman api with hammer-cli:

bolt plan run foreman_hammer::hosts -i examples/inventory.yaml --target hammer-local --hiera-config examples/hiera.yaml

The following files will be used for the configuration of the bolt plan:

• foreman host template: data/host_templates/centos7.yaml
• hiera configuration examples/example_common.yaml
• foreman access credentials: examples/inventory.yaml

Please adapt the examples to work with your individual foreman setup.

Happy automating!

Limitations

See metadata.json

Know Issues

Fetch missing ca certificate for foreman

CA Certificate for foreman server specified in server_url in inventory.yaml is missing:

Failed on hammer-local.127.0.0.1.nip.io:
  Could not load the API description from the server: SSL certificate verification failed
  Make sure you configured the correct URL and have the server's CA certificate installed on your system.
  
  You can use hammer to fetch the CA certificate from the server. Be aware that hammer cannot verify whether the certificate is correct and you should verify its authenticity after downloading it.
  
Download the certificate as follows:

  $ hammer --fetch-ca-cert https://foreman.example.de/

Solution:

Fetch the certificate with the hammer binary specified in hammer_cli_bin

hammer --fetch-ca-cert https://foreman.example.de/

Development

Running acceptance tests

To run the acceptance tests you can use Puppet Litmus https://puppetlabs.github.io/litmus/.

Install needed requirements:

https://puppetlabs.github.io/litmus/Running-acceptance-tests.html

Create test environment:

./scripts/create_test_env

Run the acceptance tests:

./scripts/run_tests

Remove the test environment:

./scripts/remove_test_env

Optional

Run the tests only on one machine:

./scripts/run_vm_test 2222

Run only one test on one machine:

scripts/run_single_test spec/acceptance/tasks/create_host_spec.rb 2222

Create the test env for e.g. ubuntu - see provision.yaml

scripts/create_test_env travis_ub

Contributing

Please use the GitHub issues functionality to report any bugs or requests for new features. Feel free to fork and submit pull requests for potential contributions.

All contributions must pass all existing tests, new features should provide additional unit/acceptance tests.

Release Process

scripts/make-release

git push

Reference

Table of Contents

Tasks

• create_host: Create a host in foreman from a template
• get_host: Get information about a host from foreman
• update_host: Update a host in foreman from a template

Plans

• foreman_hammer::hosts: Create or update an existing host from a list of hosts with hammer_cli in foreman

Tasks

create_host

Create a host in foreman from a template

Supports noop? true

Parameters

hostname

Data type: Stdlib::Host

The Hostname. e.g. mail01

template

Data type: String[1]

The template to create the host from

ip

Data type: Optional[Stdlib::IP::Address::V4]

The ip for the primary interface

cpus

Data type: Optional[Integer]

The number of CPU cores

mem

Data type: Optional[Integer]

The amount of memory in GB

template_basedir

Data type: String[1]

The template basedir.

template_vars

Data type: Hash

Variables to build the YAML with Jinja2

hammer_cli_bin

Data type: Optional[String]

The base path under which the hammer is installed.

server_url

Data type: Optional[Stdlib::Httpsurl]

URL to access foreman e.g. https://foreman.example.com

username

Data type: Optional[String[1]]

Username to access foreman

password

Data type: Optional[String[1]]

Password for foreman.

verbose

Data type: Boolean

Turn on verbose mode. Show passwords in noop mode.

get_host

Get information about a host from foreman

Supports noop? true

Parameters

name

Data type: Stdlib::Fqdn

The name of the host to get information about e.g. mail01.example.net

hammer_cli_bin

Data type: Optional[String]

The base path under which the hammer is installed.

server_url

Data type: Optional[Stdlib::Httpsurl]

URL to access foreman e.g. https://foreman.example.com

username

Data type: Optional[String[1]]

Username to access foreman

password

Data type: Optional[String[1]]

Password for foreman.

verbose

Data type: Boolean

Turn on verbose mode. Show passwords in noop mode.

update_host

Update a host in foreman from a template

Supports noop? true

Parameters

id

Data type: Integer

The ID for the host from foreman.

template

Data type: String

The template to update the host from

build

Data type: Optional[Boolean]

Should foreman rebuild the host?

ip

Data type: Optional[Stdlib::IP::Address::V4]

The ip for the primary interface

cpus

Data type: Optional[Integer]

The number of CPU cores

mem

Data type: Optional[Integer]

The amount of memory in GB

template_basedir

Data type: String

The template basedir.

template_vars

Data type: Hash

Variables to build the YAML with Jinja2

hammer_cli_bin

Data type: Optional[String]

The base path under which the hammer is installed.

server_url

Data type: Optional[Stdlib::Httpsurl]

URL to access foreman e.g. https://foreman.example.com

username

Data type: Optional[String[1]]

Username to access foreman

password

Data type: Optional[String[1]]

Password for foreman.

verbose

Data type: Boolean

Turn on verbose mode. Show passwords in noop mode.

Plans

foreman_hammer::hosts

Create or update an existing host from a list of hosts with hammer_cli in foreman

Parameters

The following parameters are available in the foreman_hammer::hosts plan.

targets

Data type: TargetSpec

The list of targets to run the plan

lookup_key

Data type: String

The hiera base lookup key.

Default value: 'foreman_hammer'

hosts

Data type: Hash

A list of hosts to create or update.

Default value: lookup("${lookup_key}::hosts", Hash, 'deep', {})

template_basedir

Data type: String

The base directory for the foreman yaml templates

Default value: lookup("${lookup_key}::template_basedir", String, 'deep', 'data/host_templates')

noop

Data type: Boolean

Turn on noop mode.

Default value: false

verbose

Data type: Boolean

Turn on verbose mode.

Default value: false

Change log

All notable changes to this project will be documented in this file. The format is based on Keep a Changelog and this project adheres to Semantic Versioning.

v1.2.0 (2020-09-02)

Full Changelog

Changed

• Use ruamel.yaml instead of pyyaml #7 (andeman)

v1.1.0 (2020-08-20)

Full Changelog

Added

• Implement Jinja2 template engine for dynamic Foreman YAML Templates #6 (andeman)

Fixed

• allow empty cpu and mem keys for $hosts for foreman_hammer::hosts #5 (andeman)

v1.0.1 (2020-08-07)

Full Changelog

Added

• Bolt plan: host and Bolt tasks: create_host, update_host, get_host #3 (andeman)

v1.0.0 (2020-08-06)

Full Changelog

* This Changelog was automatically generated by github_changelog_generator