theforeman.foreman.host – Manage Hosts

Note

This plugin is part of the theforeman.foreman collection (version 2.1.1).

To install it use: ansible-galaxy collection install theforeman.foreman.

To use it in a playbook, specify: theforeman.foreman.host.

New in version 1.0.0: of theforeman.foreman

Synopsis

  • Create, update, and delete Hosts

Requirements

The below requirements are needed on the host that executes this module.

  • requests

Parameters

Parameter Choices/Defaults Comments
activation_keys
string
Activation Keys used for deployment.
Comma separated list.
Only available for Katello installations.
architecture
string
Architecture name
build
boolean
    Choices:
  • no
  • yes
Whether or not to setup build context for the host
comment
string
Comment about the host.
compute_attributes
dictionary
Additional compute resource specific attributes.
When this parameter is set, the module will not be idempotent.
When you provide a cluster here and compute_resource is set, the cluster id will be automatically looked up.
compute_profile
string
Compute profile name
compute_resource
string
Compute resource name
config_groups
list / elements=string
Config groups list
content_source
string
Content source.
Only available for Katello installations.
content_view
string
Content view.
Only available for Katello installations.
domain
string
Domain name
enabled
boolean
    Choices:
  • no
  • yes
Include this host within reporting
environment
string
Puppet environment name
hostgroup
string
Name of related hostgroup.
image
string
The image to use when provision_method=image.
The compute_resource parameter is required to find the correct image.
interfaces_attributes
list / elements=dictionary
added in 1.5.0 of theforeman.foreman
Additional interfaces specific attributes.
attached_devices
list / elements=string
Identifiers of attached interfaces, e.g. ['eth1', 'eth2'].
For bond interfaces those are the slaves.
Only for bond and bridges interfaces.
attached_to
string
Identifier of the interface to which this interface belongs, e.g. eth1.
Only for virtual interfaces.
bond_options
string
Space separated options, e.g. miimon=100.
Only for bond interfaces.
compute_attributes
dictionary
Additional compute resource specific attributes for the interface.
When this parameter is set, the module will not be idempotent.
When you provide a network here and compute_resource is set, the network id will be automatically looked up.
On oVirt/RHV cluster is required in the hosts compute_attributes for the lookup to work.
domain
string
Domain name
Required for primary interfaces on managed hosts.
identifier
string
Device identifier, e.g. eth0 or eth1.1
You need to set one of identifier, name or mac to be able to update existing interfaces and make execution idempotent.
ip
string
IPv4 address of interface
ip6
string
IPv6 address of interface
mac
string
MAC address of interface. Required for managed interfaces on bare metal.
Please include leading zeros and separate nibbles by colons, otherwise the execution will not be idempotent.
Example EE:BB:01:02:03:04
You need to set one of identifier, name or mac to be able to update existing interfaces and make execution idempotent.
managed
boolean
    Choices:
  • no
  • yes
Should this interface be managed via DHCP and DNS smart proxy and should it be configured during provisioning?
mode
string
    Choices:
  • balance-rr
  • active-backup
  • balance-xor
  • broadcast
  • 802.3ad
  • balance-tlb
  • balance-alb
Bond mode of the interface.
Only for bond interfaces.
mtu
integer
MTU, this attribute has precedence over the subnet MTU.
name
string
Interface's DNS name
You need to set one of identifier, name or mac to be able to update existing interfaces and make execution idempotent.
password
string
Password for BMC authentication.
Only for BMC interfaces.
primary
boolean
    Choices:
  • no
  • yes
Should this interface be used for constructing the FQDN of the host?
Each managed hosts needs to have one primary interface.
provider
string
    Choices:
  • IPMI
  • Redfish
  • SSH
Interface provider, e.g. IPMI.
Only for BMC interfaces.
provision
boolean
    Choices:
  • no
  • yes
Should this interface be used for TFTP of PXELinux (or SSH for image-based hosts)?
Each managed hosts needs to have one provision interface.
subnet
string
IPv4 Subnet name
subnet6
string
IPv6 Subnet name
tag
string
VLAN tag, this attribute has precedence over the subnet VLAN ID.
Only for virtual interfaces.
type
string
    Choices:
  • interface
  • bmc
  • bond
  • bridge
Interface type.
username
string
Username for BMC authentication.
Only for BMC interfaces.
virtual
boolean
    Choices:
  • no
  • yes
Alias or VLAN device
ip
string
IP address of the primary interface of the host.
kickstart_repository
string
Kickstart repository name.
You need to provide this to use the "Synced Content" feature.
Mutually exclusive with medium.
Only available for Katello installations.
lifecycle_environment
string
Lifecycle environment.
Only available for Katello installations.
location
string
Name of related location
mac
string
MAC address of the primary interface of the host.
Please include leading zeros and separate nibbles by colons, otherwise the execution will not be idempotent.
Example EE:BB:01:02:03:04
managed
boolean
    Choices:
  • no
  • yes
Whether a host is managed or unmanaged.
Forced to true when build=true
medium
string
Medium name
Mutually exclusive with kickstart_repository.

aliases: media
name
string / required
Fully Qualified Domain Name of host
openscap_proxy
string
OpenSCAP proxy name.
Only available when the OpenSCAP plugin is installed.
operatingsystem
string
Operating systems are looked up by their title which is composed as "<name> <major>.<minor>".
You can omit the version part as long as you only have one operating system by that name.
organization
string
Name of related organization
owner
string
Owner (user) of the host.
Users are looked up by their login.
Mutually exclusive with owner_group.
owner_group
string
Owner (user group) of the host.
Mutually excluside with owner.
parameters
list / elements=dictionary
Entity domain specific host parameters
name
string / required
Name of the parameter
parameter_type
string
    Choices:
  • string ←
  • boolean
  • integer
  • real
  • array
  • hash
  • yaml
  • json
Type of the parameter
value
raw / required
Value of the parameter
password
string / required
Password of the user accessing the Foreman server.
If the value is not specified in the task, the value of environment variable FOREMAN_PASSWORD will be used instead.
provision_method
string
    Choices:
  • build
  • image
  • bootdisk
The method used to provision the host.
provision_method=bootdisk is only available if the bootdisk plugin is installed.
ptable
string
Partition table name
puppet_ca_proxy
string
Puppet CA proxy name
puppet_proxy
string
Puppet server proxy name
puppetclasses
list / elements=string
List of puppet classes to include in this host group. Must exist for hostgroup's puppet environment.
pxe_loader
string
    Choices:
  • PXELinux BIOS
  • PXELinux UEFI
  • Grub UEFI
  • Grub2 BIOS
  • Grub2 ELF
  • Grub2 UEFI
  • Grub2 UEFI SecureBoot
  • Grub2 UEFI HTTP
  • Grub2 UEFI HTTPS
  • Grub2 UEFI HTTPS SecureBoot
  • iPXE Embedded
  • iPXE UEFI HTTP
  • iPXE Chain BIOS
  • iPXE Chain UEFI
  • None
PXE Bootloader
realm
string
Realm name
root_pass
string
Root password.
Will result in the entity always being updated, as the current password cannot be retrieved.
server_url
string / required
URL of the Foreman server.
If the value is not specified in the task, the value of environment variable FOREMAN_SERVER_URL will be used instead.
state
string
    Choices:
  • present ←
  • absent
State of the entity
subnet
string
IPv4 Subnet name
subnet6
string
IPv6 Subnet name
username
string / required
Username accessing the Foreman server.
If the value is not specified in the task, the value of environment variable FOREMAN_USERNAME will be used instead.
validate_certs
boolean
    Choices:
  • no
  • yes ←
Whether or not to verify the TLS certificates of the Foreman server.
If the value is not specified in the task, the value of environment variable FOREMAN_VALIDATE_CERTS will be used instead.

Examples

- name: "Create a host"
  theforeman.foreman.host:
    username: "admin"
    password: "changeme"
    server_url: "https://foreman.example.com"
    name: "new_host"
    hostgroup: my_hostgroup
    state: present

- name: "Create a host with build context"
  theforeman.foreman.host:
    username: "admin"
    password: "changeme"
    server_url: "https://foreman.example.com"
    name: "new_host"
    hostgroup: my_hostgroup
    build: true
    state: present

- name: "Create an unmanaged host"
  theforeman.foreman.host:
    username: "admin"
    password: "changeme"
    server_url: "https://foreman.example.com"
    name: "new_host"
    managed: false
    state: present

- name: "Create a VM with 2 CPUs and 4GB RAM"
  theforeman.foreman.host:
    username: "admin"
    password: "changeme"
    server_url: "https://foreman.example.com"
    name: "new_host"
    compute_attributes:
      cpus: 2
      memory_mb: 4096
    state: present

- name: "Create a VM and start it after creation"
  theforeman.foreman.host:
    username: "admin"
    password: "changeme"
    server_url: "https://foreman.example.com"
    name: "new_host"
    compute_attributes:
      start: "1"
    state: present

- name: "Create a VM on specific ovirt network"
  theforeman.foreman.host:
    username: "admin"
    password: "changeme"
    server_url: "https://foreman.example.com"
    name: "new_host"
    interfaces_attributes:
    - type: "interface"
      compute_attributes:
        name: "nic1"
        network: "969efbe6-f9e0-4383-a19a-a7ee65ad5007"
        interface: "virtio"
    state: present

- name: "Create a VM with 2 NICs on specific ovirt networks"
  theforeman.foreman.host:
    username: "admin"
    password: "changeme"
    server_url: "https://foreman.example.com"
    name: "new_host"
    interfaces_attributes:
    - type: "interface"
      primary: true
      compute_attributes:
        name: "nic1"
        network: "969efbe6-f9e0-4383-a19a-a7ee65ad5007"
        interface: "virtio"
    - type: "interface"
      name: "new_host_nic2"
      managed: true
      compute_attributes:
        name: "nic2"
        network: "969efbe6-f9e0-4383-a19a-a7ee65ad5008"
        interface: "e1000"
    state: present

- name: "Delete a host"
  theforeman.foreman.host:
    username: "admin"
    password: "changeme"
    server_url: "https://foreman.example.com"
    name: "new_host"
    state: absent

Return Values

Common return values are documented here, the following are the fields unique to this module:

Key Returned Description
entity
dictionary
success
Final state of the affected entities grouped by their type.
 
hosts
list / elements=dictionary
success
List of hosts.


Authors

  • Bernhard Hopfenmueller (@Fobhep) ATIX AG