/ home / theforeman / theforeman.foreman / 4.0.0 / module / host

theforeman.foreman.host (4.0.0) — module

Manage Hosts

| "added in version" 1.0.0 of theforeman.foreman"

Authors: Bernhard Hopfenmueller (@Fobhep) ATIX AG

Install collection

Install with ansible-galaxy collection install theforeman.foreman:==4.0.0

Add to requirements.yml

  collections:
    - name: theforeman.foreman
      version: 4.0.0

Description

Create, update, and delete Hosts

Requirements

requests

Usage examples

Scanned by Steampunk Spotter

- 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

Scanned by Steampunk Spotter

- 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

Scanned by Steampunk Spotter

- 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

Scanned by Steampunk Spotter

- 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

Scanned by Steampunk Spotter

- 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

Scanned by Steampunk Spotter

- 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

Scanned by Steampunk Spotter

- 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

Scanned by Steampunk Spotter

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

Inputs

ip:
description:
- IP address of the primary interface of the host.
required: false
type: str

mac:
description:
- 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
required: false
type: str

name:
description:
- Fully Qualified Domain Name of host
required: true
type: str

build:
description:
- Whether or not to setup build context for the host
required: false
type: bool

image:
description:
- The image to use when I(provision_method=image).
- The I(compute_resource) parameter is required to find the correct image.
required: false
type: str

owner:
description:
- Owner (user) of the host.
- Users are looked up by their C(login).
- Mutually exclusive with I(owner_group).
required: false
type: str

realm:
description: Realm name
required: false
type: str

state:
choices:
- present
- absent
default: present
description:
- State of the entity
type: str

domain:
description: Domain name
required: false
type: str

medium:
aliases:
- media
description:
- Medium name
- Mutually exclusive with I(kickstart_repository).
required: false
type: str

ptable:
description: Partition table name
required: false
type: str

subnet:
description: IPv4 Subnet name
required: false
type: str

comment:
description:
- Comment about the host.
required: false
type: str

enabled:
description:
- Include this host within reporting
required: false
type: bool

managed:
description:
- Whether a host is managed or unmanaged.
- Forced to true when I(build=true)
required: false
type: bool

subnet6:
description: IPv6 Subnet name
required: false
type: str

location:
description:
- Name of related location
required: false
type: str

password:
description:
- Password of the user accessing the Foreman server.
- If the value is not specified in the task, the value of environment variable C(FOREMAN_PASSWORD)
will be used instead.
required: true
type: str

username:
description:
- Username accessing the Foreman server.
- If the value is not specified in the task, the value of environment variable C(FOREMAN_USERNAME)
will be used instead.
required: true
type: str

hostgroup:
description:
- Title of related hostgroup
- 'Example: A child hostgroup I(bar) within a parent hostgroup I(foo) would have the
title I(foo/bar).'
required: false
type: str

root_pass:
description:
- Root password.
- Will result in the entity always being updated, as the current password cannot be
retrieved.
required: false
type: str

parameters:
description:
- Entity domain specific host parameters
elements: dict
required: false
suboptions:
name:
description:
- Name of the parameter
required: true
type: str
parameter_type:
choices:
- string
- boolean
- integer
- real
- array
- hash
- yaml
- json
default: string
description:
- Type of the parameter
type: str
value:
description:
- Value of the parameter
required: true
type: raw
type: list

pxe_loader:
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
description: PXE Bootloader
required: false
type: str

server_url:
description:
- URL of the Foreman server.
- If the value is not specified in the task, the value of environment variable C(FOREMAN_SERVER_URL)
will be used instead.
required: true
type: str

environment:
description: Puppet environment name
required: false
type: str

owner_group:
description:
- Owner (user group) of the host.
- Mutually exclusive with I(owner).
required: false
type: str

architecture:
description: Architecture name
required: false
type: str

content_view:
description:
- Content view.
- Only available for Katello installations.
required: false
type: str

organization:
description:
- Name of related organization
required: false
type: str

puppet_proxy:
description: Puppet server proxy name
required: false
type: str

config_groups:
description: Config groups list
elements: str
required: false
type: list

puppetclasses:
description: List of puppet classes to include in this host group. Must exist for
hostgroup's puppet environment.
elements: str
required: false
type: list

content_source:
description:
- Content Source (Smart Proxy with Content) name.
- Only available for Katello installations.
required: false
type: str

openscap_proxy:
description:
- OpenSCAP proxy name.
- Only available when the OpenSCAP plugin is installed.
required: false
type: str

validate_certs:
default: true
description:
- 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 C(FOREMAN_VALIDATE_CERTS)
will be used instead.
type: bool

activation_keys:
description:
- Activation Keys used for deployment.
- Comma separated list.
- Only available for Katello installations.
required: false
type: str

compute_profile:
description: Compute profile name
required: false
type: str

operatingsystem:
description:
- 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.
required: false
type: str

puppet_ca_proxy:
description: Puppet CA proxy name
required: false
type: str

compute_resource:
description: Compute resource name
required: false
type: str

provision_method:
choices:
- build
- image
- bootdisk
description:
- The method used to provision the host.
- I(provision_method=bootdisk) is only available if the bootdisk plugin is installed.
required: false
type: str

compute_attributes:
description:
- Additional compute resource specific attributes.
- When this parameter is set, the module will not be idempotent.
- When you provide a I(cluster) here and I(compute_resource) is set, the cluster id
will be automatically looked up.
required: false
type: dict

kickstart_repository:
description:
- Kickstart repository name.
- You need to provide this to use the "Synced Content" feature.
- Mutually exclusive with I(medium).
- Only available for Katello installations.
required: false
type: str

interfaces_attributes:
description:
- Additional interfaces specific attributes.
elements: dict
required: false
suboptions:
attached_devices:
description:
- Identifiers of attached interfaces, e.g. ['eth1', 'eth2'].
- For bond interfaces those are the slaves.
- Only for bond and bridges interfaces.
elements: str
type: list
attached_to:
description:
- Identifier of the interface to which this interface belongs, e.g. eth1.
- Only for virtual interfaces.
type: str
bond_options:
description:
- Space separated options, e.g. miimon=100.
- Only for bond interfaces.
type: str
compute_attributes:
description:
- Additional compute resource specific attributes for the interface.
- When this parameter is set, the module will not be idempotent.
- When you provide a I(network) here and I(compute_resource) is set, the network
id will be automatically looked up.
- On oVirt/RHV I(cluster) is required in the hosts I(compute_attributes) for the
lookup to work.
type: dict
domain:
description:
- Domain name
- Required for primary interfaces on managed hosts.
type: str
execution:
description:
- Should this interface be used for Remote Execution?
- Each managed hosts should have one remote execution interface.
type: bool
identifier:
description:
- Device identifier, e.g. eth0 or eth1.1
- You need to set one of I(identifier), I(name) or I(mac) to be able to update
existing interfaces and make execution idempotent.
type: str
ip:
description:
- IPv4 address of interface
type: str
ip6:
description:
- IPv6 address of interface
type: str
mac:
description:
- 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 I(identifier), I(name) or I(mac) to be able to update
existing interfaces and make execution idempotent.
type: str
managed:
description:
- Should this interface be managed via DHCP and DNS smart proxy and should it
be configured during provisioning?
type: bool
mode:
choices:
- balance-rr
- active-backup
- balance-xor
- broadcast
- 802.3ad
- balance-tlb
- balance-alb
description:
- Bond mode of the interface.
- Only for bond interfaces.
type: str
mtu:
description:
- MTU, this attribute has precedence over the subnet MTU.
type: int
name:
description:
- Interface's DNS name
- You need to set one of I(identifier), I(name) or I(mac) to be able to update
existing interfaces and make execution idempotent.
type: str
password:
description:
- Password for BMC authentication.
- Only for BMC interfaces.
type: str
primary:
description:
- Should this interface be used for constructing the FQDN of the host?
- Each managed hosts needs to have one primary interface.
type: bool
provider:
choices:
- IPMI
- Redfish
- SSH
description:
- Interface provider, e.g. IPMI.
- Only for BMC interfaces.
type: str
provision:
description:
- Should this interface be used for TFTP of PXELinux (or SSH for image-based hosts)?
- Each managed hosts needs to have one provision interface.
type: bool
subnet:
description:
- IPv4 Subnet name
type: str
subnet6:
description:
- IPv6 Subnet name
type: str
tag:
description:
- VLAN tag, this attribute has precedence over the subnet VLAN ID.
- Only for virtual interfaces.
type: str
type:
choices:
- interface
- bmc
- bond
- bridge
description:
- Interface type.
type: str
username:
description:
- Username for BMC authentication.
- Only for BMC interfaces.
type: str
virtual:
description:
- Alias or VLAN device
type: bool
type: list
version_added: 1.5.0
version_added_collection: theforeman.foreman

lifecycle_environment:
description:
- Lifecycle environment.
- Only available for Katello installations.
required: false
type: str

Outputs

entity:
  contains:
    hosts:
      description: List of hosts.
      elements: dict
      type: list
  description: Final state of the affected entities grouped by their type.
  returned: success
  type: dict