Forge Home

Modules

Puppet

Resources

PuppetEcosystemPuppet CommunityUpdates

foreman_hammer

Bolt task and plans to managing foreman with hammer_cli
Project URLRSS FeedReport issues

3,153 downloads

1,951 latest version

Version information

  • 1.2.0 (latest)
  • 1.1.0
  • 1.0.1
  • 1.0.0
released Sep 2nd 2020
This version is compatible with:
  • Puppet Enterprise 2019.8.x, 2019.7.x, 2019.5.x, 2019.4.x, 2019.3.x, 2019.2.x, 2019.1.x, 2019.0.x, 2018.1.x, 2017.3.x, 2017.2.x, 2016.4.x
  • Puppet >= 4.10.0 < 7.0.0
  • , , , , ,
Tasks:
  • create_host
  • get_host
  • update_host
Plans:
  • hosts

Start using this module

  • r10k or Code Manager
  • Bolt
  • Manual installation
  • Direct download

Add this module to your Puppetfile:

mod 'andeman-foreman_hammer', '1.2.0'
Learn more about managing modules with a Puppetfile

Add this module to your Bolt project:

bolt module add andeman-foreman_hammer
Learn more about using this module with an existing project

Manually install this module globally with Puppet module tool:

puppet module install andeman-foreman_hammer --version 1.2.0

Direct download is not typically how you would use a Puppet module to manage your infrastructure, but you may want to download the module in order to inspect the code.

Download

Documentation

andeman/foreman_hammer — version 1.2.0 Sep 2nd 2020

Build Status Puppet Forge Puppet Forge Downloads

foreman_hammer

Table of Contents

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:

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:

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