API documentation

Examples

GET /api/hostgroups
200
{
  "total": 5,
  "subtotal": 5,
  "page": 1,
  "per_page": 20,
  "search": null,
  "sort": {
    "by": null,
    "order": null
  },
  "results": [
    {
      "subnet_id": null,
      "subnet_name": null,
      "operatingsystem_id": 309172073,
      "operatingsystem_name": "centos 5.3",
      "domain_id": 22495316,
      "domain_name": "mydomain.net",
      "environment_id": 334344675,
      "environment_name": "production",
      "compute_profile_id": 980190962,
      "compute_profile_name": "1-Small",
      "ancestry": null,
      "parent_id": null,
      "parent_name": null,
      "ptable_id": null,
      "ptable_name": null,
      "medium_id": 980190962,
      "medium_name": "CentOS 5.4",
      "pxe_loader": null,
      "subnet6_id": null,
      "subnet6_name": null,
      "architecture_id": 501905019,
      "architecture_name": "x86_64",
      "realm_id": null,
      "realm_name": null,
      "created_at": "2018-07-24 13:08:00 UTC",
      "updated_at": "2018-07-24 13:08:00 UTC",
      "id": 636252244,
      "name": "Common",
      "title": "Common",
      "description": null,
      "puppet_proxy_id": 182953976,
      "puppet_proxy_name": "Puppetmaster Proxy",
      "puppet_ca_proxy_id": null,
      "puppet_ca_proxy_name": null,
      "puppet_proxy": {
        "name": "Puppetmaster Proxy",
        "id": 182953976,
        "url": "http://else.where:4567"
      },
      "puppet_ca_proxy": null
    },
    {
      "subnet_id": null,
      "subnet_name": null,
      "operatingsystem_id": 309172073,
      "operatingsystem_name": "centos 5.3",
      "domain_id": null,
      "domain_name": null,
      "environment_id": 334344675,
      "environment_name": "production",
      "compute_profile_id": null,
      "compute_profile_name": null,
      "ancestry": null,
      "parent_id": null,
      "parent_name": null,
      "ptable_id": null,
      "ptable_name": null,
      "medium_id": 980190962,
      "medium_name": "CentOS 5.4",
      "pxe_loader": null,
      "subnet6_id": null,
      "subnet6_name": null,
      "architecture_id": 501905019,
      "architecture_name": "x86_64",
      "realm_id": null,
      "realm_name": null,
      "created_at": "2018-07-24 13:08:00 UTC",
      "updated_at": "2018-07-24 13:08:00 UTC",
      "id": 603241515,
      "name": "db",
      "title": "db",
      "description": null,
      "puppet_proxy_id": 182953976,
      "puppet_proxy_name": "Puppetmaster Proxy",
      "puppet_ca_proxy_id": null,
      "puppet_ca_proxy_name": null,
      "puppet_proxy": {
        "name": "Puppetmaster Proxy",
        "id": 182953976,
        "url": "http://else.where:4567"
      },
      "puppet_ca_proxy": null
    },
    {
      "subnet_id": 1018350795,
      "subnet_name": "five",
      "operatingsystem_id": 309172073,
      "operatingsystem_name": "centos 5.3",
      "domain_id": 22495316,
      "domain_name": "mydomain.net",
      "environment_id": 153855663,
      "environment_name": "global_puppetmaster",
      "compute_profile_id": 980190962,
      "compute_profile_name": "1-Small",
      "ancestry": null,
      "parent_id": null,
      "parent_name": null,
      "ptable_id": 615088209,
      "ptable_name": "Example partition table",
      "medium_id": 980190962,
      "medium_name": "CentOS 5.4",
      "pxe_loader": "PXELinux BIOS",
      "subnet6_id": 51848956,
      "subnet6_name": "six",
      "architecture_id": 501905019,
      "architecture_name": "x86_64",
      "realm_id": null,
      "realm_name": null,
      "created_at": "2018-07-24 13:08:00 UTC",
      "updated_at": "2018-07-24 13:08:00 UTC",
      "id": 1,
      "name": "Parent",
      "title": "Parent",
      "description": null,
      "puppet_proxy_id": 182953976,
      "puppet_proxy_name": "Puppetmaster Proxy",
      "puppet_ca_proxy_id": 182953976,
      "puppet_ca_proxy_name": "Puppetmaster Proxy",
      "puppet_proxy": {
        "name": "Puppetmaster Proxy",
        "id": 182953976,
        "url": "http://else.where:4567"
      },
      "puppet_ca_proxy": {
        "name": "Puppetmaster Proxy",
        "id": 182953976,
        "url": "http://else.where:4567"
      }
    },
    {
      "subnet_id": null,
      "subnet_name": "five",
      "operatingsystem_id": null,
      "operatingsystem_name": "centos 5.3",
      "domain_id": null,
      "domain_name": "mydomain.net",
      "environment_id": 334344675,
      "environment_name": "production",
      "compute_profile_id": null,
      "compute_profile_name": "1-Small",
      "ancestry": "1",
      "parent_id": 1,
      "parent_name": "Parent",
      "ptable_id": null,
      "ptable_name": "Example partition table",
      "medium_id": null,
      "medium_name": "CentOS 5.4",
      "pxe_loader": "PXELinux BIOS",
      "subnet6_id": null,
      "subnet6_name": "six",
      "architecture_id": null,
      "architecture_name": "x86_64",
      "realm_id": null,
      "realm_name": null,
      "created_at": "2018-07-24 13:08:00 UTC",
      "updated_at": "2018-07-24 13:08:00 UTC",
      "id": 928644285,
      "name": "inherited",
      "title": "Parent/inherited",
      "description": null,
      "puppet_proxy_id": null,
      "puppet_proxy_name": "Puppetmaster Proxy",
      "puppet_ca_proxy_id": null,
      "puppet_ca_proxy_name": "Puppetmaster Proxy",
      "puppet_proxy": {
        "name": "Puppetmaster Proxy",
        "id": 182953976,
        "url": "http://else.where:4567"
      },
      "puppet_ca_proxy": {
        "name": "Puppetmaster Proxy",
        "id": 182953976,
        "url": "http://else.where:4567"
      }
    },
    {
      "subnet_id": null,
      "subnet_name": null,
      "operatingsystem_id": null,
      "operatingsystem_name": null,
      "domain_id": null,
      "domain_name": null,
      "environment_id": null,
      "environment_name": null,
      "compute_profile_id": null,
      "compute_profile_name": null,
      "ancestry": null,
      "parent_id": null,
      "parent_name": null,
      "ptable_id": null,
      "ptable_name": null,
      "medium_id": null,
      "medium_name": null,
      "pxe_loader": null,
      "subnet6_id": null,
      "subnet6_name": null,
      "architecture_id": null,
      "architecture_name": null,
      "realm_id": null,
      "realm_name": null,
      "created_at": "2018-07-24 13:08:00 UTC",
      "updated_at": "2018-07-24 13:08:00 UTC",
      "id": 866317115,
      "name": "Unusual",
      "title": "Unusual",
      "description": null,
      "puppet_proxy_id": 182953976,
      "puppet_proxy_name": "Puppetmaster Proxy",
      "puppet_ca_proxy_id": null,
      "puppet_ca_proxy_name": null,
      "puppet_proxy": {
        "name": "Puppetmaster Proxy",
        "id": 182953976,
        "url": "http://else.where:4567"
      },
      "puppet_ca_proxy": null
    }
  ]
}

Params

Param name	Description
puppetclass_id optional	ID of Puppet class Validations: Must be a String
location_id optional	Scope by locations Validations: Must be a Integer
organization_id optional	Scope by organizations Validations: Must be a Integer
search optional	filter results Validations: Must be a String
order optional	Sort field and order, eg. ‘id DESC’ Validations: Must be a String
page optional	paginate results Validations: Must be a String
per_page optional	number of entries per request Validations: Must be a String
include optional	Array of extra information types to include Validations: Must be an array of [parameters]

Search fields

Field name	Type	Possible values
architecture	string
class	string
config_group	string
environment	string
host	string
id	integer
label	string
location	string
location_id	integer
medium	string
name	string
organization	string
organization_id	integer
os	string
os_description	string
os_id	integer
os_major	string
os_minor	string
os_title	string
params	text
template	string
title	string

Examples

GET /api/hostgroups/928644286
200
{
  "subnet_id": null,
  "subnet_name": null,
  "operatingsystem_id": null,
  "operatingsystem_name": null,
  "domain_id": null,
  "domain_name": null,
  "environment_id": null,
  "environment_name": null,
  "compute_profile_id": null,
  "compute_profile_name": null,
  "ancestry": null,
  "parent_id": null,
  "parent_name": null,
  "ptable_id": null,
  "ptable_name": null,
  "medium_id": null,
  "medium_name": null,
  "pxe_loader": null,
  "subnet6_id": null,
  "subnet6_name": null,
  "architecture_id": null,
  "architecture_name": null,
  "realm_id": null,
  "realm_name": null,
  "created_at": "2018-07-24 12:55:49 UTC",
  "updated_at": "2018-07-24 12:55:49 UTC",
  "id": 928644286,
  "name": "hostgroup78",
  "title": "hostgroup78",
  "description": null,
  "puppet_proxy_id": null,
  "puppet_proxy_name": null,
  "puppet_ca_proxy_id": null,
  "puppet_ca_proxy_name": null,
  "puppet_proxy": null,
  "puppet_ca_proxy": null,
  "parameters": [
    {
      "priority": 60,
      "created_at": "2018-07-24 12:55:49 UTC",
      "updated_at": "2018-07-24 12:55:49 UTC",
      "id": 767575239,
      "name": "foo",
      "value": "*****"
    }
  ],
  "template_combinations": [],
  "puppetclasses": [],
  "config_groups": [],
  "all_puppetclasses": [],
  "locations": [
    {
      "id": 255093256,
      "name": "Location 1",
      "title": "Location 1",
      "description": null
    }
  ],
  "organizations": [
    {
      "id": 447626438,
      "name": "Organization 1",
      "title": "Organization 1",
      "description": null
    }
  ]
}

Params

Param name	Description
location_id optional	Scope by locations Validations: Must be a Integer
organization_id optional	Scope by organizations Validations: Must be a Integer
id required	Validations: Must be an identifier, string from 1 to 128 characters containing only alphanumeric characters, space, underscore(_), hypen(-) with no leading or trailing space.
show_hidden_parameters optional	Display hidden parameter values Validations: Must be one of: `true`, `false`, `1`, `0`

Examples

POST /api/hostgroups
{
  "hostgroup": {
    "name": "TestHostgroup"
  }
}
201
{
  "subnet_id": null,
  "subnet_name": null,
  "operatingsystem_id": null,
  "operatingsystem_name": null,
  "domain_id": null,
  "domain_name": null,
  "environment_id": null,
  "environment_name": null,
  "compute_profile_id": null,
  "compute_profile_name": null,
  "ancestry": null,
  "parent_id": null,
  "parent_name": null,
  "ptable_id": null,
  "ptable_name": null,
  "medium_id": null,
  "medium_name": null,
  "pxe_loader": null,
  "subnet6_id": null,
  "subnet6_name": null,
  "architecture_id": null,
  "architecture_name": null,
  "realm_id": null,
  "realm_name": null,
  "created_at": "2018-07-24 13:08:01 UTC",
  "updated_at": "2018-07-24 13:08:01 UTC",
  "id": 928644287,
  "name": "TestHostgroup",
  "title": "TestHostgroup",
  "description": null,
  "puppet_proxy_id": null,
  "puppet_proxy_name": null,
  "puppet_ca_proxy_id": null,
  "puppet_ca_proxy_name": null,
  "puppet_proxy": null,
  "puppet_ca_proxy": null,
  "parameters": [],
  "template_combinations": [],
  "puppetclasses": [],
  "config_groups": [],
  "all_puppetclasses": [],
  "locations": [],
  "organizations": []
}

Params

Param name	Description
location_id optional	Scope by locations Validations: Must be a Integer
organization_id optional	Scope by organizations Validations: Must be a Integer
hostgroup required	Validations: Must be a Hash
hostgroup[name] required	Name of the host group Validations: Must be a String
hostgroup[description] optional , nil allowed	Host group description Validations: Must be a String
hostgroup[parent_id] optional , nil allowed	Parent ID of the host group Validations: Must be a number.
hostgroup[environment_id] optional , nil allowed	Environment ID Validations: Must be a number.
hostgroup[compute_profile_id] optional , nil allowed	Compute profile ID Validations: Must be a number.
hostgroup[compute_resource_id] optional , nil allowed	Compute resource ID Validations: Must be a number.
hostgroup[operatingsystem_id] optional , nil allowed	Operating system ID Validations: Must be a number.
hostgroup[architecture_id] optional , nil allowed	Architecture ID Validations: Must be a number.
hostgroup[pxe_loader] optional , nil allowed	DHCP filename option (Grub2/PXELinux by default) Validations: Must be one of: `None`, `PXELinux BIOS`, `PXELinux UEFI`, `Grub UEFI`, `Grub2 UEFI`, `Grub2 UEFI SecureBoot`.
hostgroup[medium_id] optional , nil allowed	Media ID Validations: Must be a number.
hostgroup[ptable_id] optional , nil allowed	Partition table ID Validations: Must be a number.
hostgroup[subnet_id] optional , nil allowed	Subnet ID Validations: Must be a number.
hostgroup[domain_id] optional , nil allowed	Domain ID Validations: Must be a number.
hostgroup[realm_id] optional , nil allowed	Realm ID Validations: Must be a number.
hostgroup[config_group_ids] optional , nil allowed	IDs of associated config groups Validations: Must be an array of any type
hostgroup[group_parameters_attributes] optional , nil allowed	Array of parameters Validations: Must be an Array of nested elements
hostgroup[group_parameters_attributes][name] required	Name of the parameter Validations: Must be a String
hostgroup[group_parameters_attributes][value] required	Parameter value Validations: Must be a String
hostgroup[puppet_proxy_id] optional , nil allowed	Puppet proxy ID Validations: Must be a number.
hostgroup[puppet_ca_proxy_id] optional , nil allowed	Puppet CA proxy ID Validations: Must be a number.
hostgroup[root_pass] optional , nil allowed	Root password on provisioned hosts Validations: Must be a String
hostgroup[location_ids] optional , nil allowed	REPLACE locations with given ids Validations: Must be an array of any type
hostgroup[organization_ids] optional , nil allowed	REPLACE organizations with given ids. Validations: Must be an array of any type

Examples

PUT /api/hostgroups/928644286
{
  "hostgroup": {
    "puppet_proxy_id": 182953976
  }
}
200
{
  "subnet_id": null,
  "subnet_name": null,
  "operatingsystem_id": null,
  "operatingsystem_name": null,
  "domain_id": null,
  "domain_name": null,
  "environment_id": null,
  "environment_name": null,
  "compute_profile_id": null,
  "compute_profile_name": null,
  "ancestry": null,
  "parent_id": null,
  "parent_name": null,
  "ptable_id": null,
  "ptable_name": null,
  "medium_id": null,
  "medium_name": null,
  "pxe_loader": null,
  "subnet6_id": null,
  "subnet6_name": null,
  "architecture_id": null,
  "architecture_name": null,
  "realm_id": null,
  "realm_name": null,
  "created_at": "2018-07-24 13:08:00 UTC",
  "updated_at": "2018-07-24 13:08:00 UTC",
  "id": 928644286,
  "name": "hostgroup124",
  "title": "hostgroup124",
  "description": null,
  "puppet_proxy_id": 182953976,
  "puppet_proxy_name": "Puppetmaster Proxy",
  "puppet_ca_proxy_id": 182953976,
  "puppet_ca_proxy_name": "Puppetmaster Proxy",
  "puppet_proxy": {
    "name": "Puppetmaster Proxy",
    "id": 182953976,
    "url": "http://else.where:4567"
  },
  "puppet_ca_proxy": {
    "name": "Puppetmaster Proxy",
    "id": 182953976,
    "url": "http://else.where:4567"
  },
  "parameters": [],
  "template_combinations": [],
  "puppetclasses": [],
  "config_groups": [],
  "all_puppetclasses": [],
  "locations": [
    {
      "id": 255093256,
      "name": "Location 1",
      "title": "Location 1",
      "description": null
    }
  ],
  "organizations": [
    {
      "id": 447626438,
      "name": "Organization 1",
      "title": "Organization 1",
      "description": null
    }
  ]
}

Params

Param name	Description
location_id optional	Scope by locations Validations: Must be a Integer
organization_id optional	Scope by organizations Validations: Must be a Integer
id required	Validations: Must be an identifier, string from 1 to 128 characters containing only alphanumeric characters, space, underscore(_), hypen(-) with no leading or trailing space.
hostgroup required	Validations: Must be a Hash
hostgroup[name] optional	Name of the host group Validations: Must be a String
hostgroup[description] optional , nil allowed	Host group description Validations: Must be a String
hostgroup[parent_id] optional , nil allowed	Parent ID of the host group Validations: Must be a number.
hostgroup[environment_id] optional , nil allowed	Environment ID Validations: Must be a number.
hostgroup[compute_profile_id] optional , nil allowed	Compute profile ID Validations: Must be a number.
hostgroup[compute_resource_id] optional , nil allowed	Compute resource ID Validations: Must be a number.
hostgroup[operatingsystem_id] optional , nil allowed	Operating system ID Validations: Must be a number.
hostgroup[architecture_id] optional , nil allowed	Architecture ID Validations: Must be a number.
hostgroup[pxe_loader] optional , nil allowed	DHCP filename option (Grub2/PXELinux by default) Validations: Must be one of: `None`, `PXELinux BIOS`, `PXELinux UEFI`, `Grub UEFI`, `Grub2 UEFI`, `Grub2 UEFI SecureBoot`.
hostgroup[medium_id] optional , nil allowed	Media ID Validations: Must be a number.
hostgroup[ptable_id] optional , nil allowed	Partition table ID Validations: Must be a number.
hostgroup[subnet_id] optional , nil allowed	Subnet ID Validations: Must be a number.
hostgroup[domain_id] optional , nil allowed	Domain ID Validations: Must be a number.
hostgroup[realm_id] optional , nil allowed	Realm ID Validations: Must be a number.
hostgroup[config_group_ids] optional , nil allowed	IDs of associated config groups Validations: Must be an array of any type
hostgroup[group_parameters_attributes] optional , nil allowed	Array of parameters Validations: Must be an Array of nested elements
hostgroup[group_parameters_attributes][name] optional	Name of the parameter Validations: Must be a String
hostgroup[group_parameters_attributes][value] optional	Parameter value Validations: Must be a String
hostgroup[puppet_proxy_id] optional , nil allowed	Puppet proxy ID Validations: Must be a number.
hostgroup[puppet_ca_proxy_id] optional , nil allowed	Puppet CA proxy ID Validations: Must be a number.
hostgroup[root_pass] optional , nil allowed	Root password on provisioned hosts Validations: Must be a String
hostgroup[location_ids] optional , nil allowed	REPLACE locations with given ids Validations: Must be an array of any type
hostgroup[organization_ids] optional , nil allowed	REPLACE organizations with given ids. Validations: Must be an array of any type

Examples

DELETE /api/hostgroups/866317115-Unusual
{
  "hostgroup": {}
}
200
{
  "id": 866317115,
  "name": "Unusual",
  "created_at": "2018-07-24T13:08:00.411Z",
  "updated_at": "2018-07-24T13:08:00.411Z",
  "environment_id": null,
  "operatingsystem_id": null,
  "architecture_id": null,
  "medium_id": null,
  "ptable_id": null,
  "root_pass": null,
  "puppet_ca_proxy_id": null,
  "use_image": null,
  "image_file": "",
  "ancestry": null,
  "vm_defaults": null,
  "subnet_id": null,
  "domain_id": null,
  "puppet_proxy_id": 182953976,
  "title": "Unusual",
  "realm_id": null,
  "compute_profile_id": null,
  "grub_pass": "",
  "lookup_value_matcher": "hostgroup=Unusual",
  "subnet6_id": null,
  "pxe_loader": null,
  "description": null,
  "compute_resource_id": null
}

Params

Param name

Description

location_id
optional

Scope by locations

Validations:

Must be a Integer

organization_id
optional

Scope by organizations

Validations:

Must be a Integer

id
required

Validations:

Must be an identifier, string from 1 to 128 characters containing only alphanumeric characters, space, underscore(_), hypen(-) with no leading or trailing space.

Examples

POST /api/hostgroups/636252244/clone
{
  "name": "EGjKEjHqQe",
  "hostgroup": {
    "name": "EGjKEjHqQe"
  }
}
201
{
  "id": 928644291,
  "name": "EGjKEjHqQe",
  "created_at": "2018-07-24T13:08:03.135Z",
  "updated_at": "2018-07-24T13:08:03.135Z",
  "environment_id": 334344675,
  "operatingsystem_id": 309172073,
  "architecture_id": 501905019,
  "medium_id": 980190962,
  "ptable_id": null,
  "root_pass": "$1$foreman$NW1XVtbk4/XkJqmKNrFWV0",
  "puppet_ca_proxy_id": 182953976,
  "use_image": null,
  "image_file": "",
  "ancestry": null,
  "vm_defaults": null,
  "subnet_id": null,
  "domain_id": 22495316,
  "puppet_proxy_id": 182953976,
  "title": "EGjKEjHqQe",
  "realm_id": null,
  "compute_profile_id": 980190962,
  "grub_pass": "$1$foreman$NW1XVtbk4/XkJqmKNrFWV0",
  "lookup_value_matcher": "hostgroup=EGjKEjHqQe",
  "subnet6_id": null,
  "pxe_loader": null,
  "description": null,
  "compute_resource_id": null
}

Params

Param name

Description

location_id
optional

Scope by locations

Validations:

Must be a Integer

organization_id
optional

Scope by organizations

Validations:

Must be a Integer

name
required

Validations:

Must be a String

Examples

POST /api/hostgroups/928644293-hostgroup128/rebuild_config
{
  "only": [
    "TFTP"
  ],
  "hostgroup": {}
}
200
{
  "message": "Configuration successfully rebuilt."
}

Params

Param name	Description
location_id optional	Scope by locations Validations: Must be a Integer
organization_id optional	Scope by organizations Validations: Must be a Integer
id required	Validations: Must be an identifier, string from 1 to 128 characters containing only alphanumeric characters, space, underscore(_), hypen(-) with no leading or trailing space.
only optional	Limit rebuild steps, valid steps are DHCP, DNS, TFTP Validations: Must be an array of any type
children_hosts optional	Operate on child hostgroup hosts Validations: Must be one of: `true`, `false`, `1`, `0`

Hostgroups

GET /api/hostgroups
List all host groups

GET /api/puppetclasses/:puppetclass_id/hostgroups
List all host groups for a Puppet class

GET /api/locations/:location_id/hostgroups
List all host groups per location

GET /api/organizations/:organization_id/hostgroups
List all host groups per organization

Examples

Params

Search fields

GET /api/hostgroups/:id
Show a host group

Examples

Params

POST /api/hostgroups
Create a host group

Examples

Params

PUT /api/hostgroups/:id
Update a host group

Examples

Params

DELETE /api/hostgroups/:id
Delete a host group

Examples

Params

POST /api/hostgroups/:id/clone
Clone a host group

Examples

Params

PUT /api/hostgroups/:id/rebuild_config
Rebuild orchestration config

Examples

Params

Hostgroups

GET /api/hostgroups List all host groups

GET /api/puppetclasses/:puppetclass_id/hostgroups List all host groups for a Puppet class

GET /api/locations/:location_id/hostgroups List all host groups per location

GET /api/organizations/:organization_id/hostgroups List all host groups per organization

Examples

Params

Search fields

GET /api/hostgroups/:id Show a host group

Examples

Params

POST /api/hostgroups Create a host group

Examples

Params

PUT /api/hostgroups/:id Update a host group

Examples

Params

DELETE /api/hostgroups/:id Delete a host group

Examples

Params

POST /api/hostgroups/:id/clone Clone a host group

Examples

Params

PUT /api/hostgroups/:id/rebuild_config Rebuild orchestration config

Examples

Params

GET /api/hostgroups
List all host groups

GET /api/puppetclasses/:puppetclass_id/hostgroups
List all host groups for a Puppet class

GET /api/locations/:location_id/hostgroups
List all host groups per location

GET /api/organizations/:organization_id/hostgroups
List all host groups per organization

GET /api/hostgroups/:id
Show a host group

POST /api/hostgroups
Create a host group

PUT /api/hostgroups/:id
Update a host group

DELETE /api/hostgroups/:id
Delete a host group

POST /api/hostgroups/:id/clone
Clone a host group

PUT /api/hostgroups/:id/rebuild_config
Rebuild orchestration config