第5章 Using the Red Hat Satellite API

This chapter provides a range of examples of how to use the Red Hat Satellite API to perform different tasks. You can use the API on Satellite Server via HTTPS on port 443, or on Capsule Server via HTTPS on port 8443.

You can address these different port requirements within the script itself. For example, in Ruby, you can specify the Satellite and Capsule URLs as follows:

url = 'https://satellite.example.com/api/v2/'
capsule_url = 'https://capsule.example.com:8443/api/v2/'
katello_url = 'https://satellite.example.com/katello/api/v2/'

For the host that is subscribed to Satellite Server or Capsule Server, you can determine the correct port required to access the API from the /etc/rhsm/rhsm.conf file, in the port entry of the [server] section. You can use these values to fully automate your scripts, removing any need to verify which ports to use.

This chapter uses curl for sending API requests. For more information, see 「API Requests with curl」.

Examples in this chapter use the Python json.tool module to format the output.

5.1. Working with Hosts

Listing Hosts

This example returns a list of Satellite hosts.

Example request:

$ curl -request GET --insecure --user sat_username:sat_password \
https://satellite.example.com/api/v2/hosts | python -m json.tool

Example response:

{
      ...
       "total" => 2,
    "subtotal" => 2,
        "page" => 1,
    "per_page" => 1000,
      "search" => nil,
        "sort" => {
           "by" => nil,
        "order" => nil
    },
     "results" => [
      ...
}

Requesting Information for a Host

This request returns information for the host satellite.example.com.

Example request:

$  curl --request GET --insecure --user sat_username:sat_password \
https://satellite.example.com/api/v2/hosts/satellite.example.com \
| python -m json.tool

Example response:

{
    "all_puppetclasses": [],
    "architecture_id": 1,
    "architecture_name": "x86_64",
    "build": false,
    "capabilities": [
        "build"
    ],
    "certname": "satellite.example.com",
    "comment": null,
    "compute_profile_id": null,
    ...
}

Listing Host Facts

This request returns all facts for the host satellite.example.com.

Example request:

$ curl --request GET --insecure --user sat_username:sat_password \
https://satellite.example.com/api/v2/hosts/satellite.example.com/facts \
| python -m json.tool

Example response:

{
    ...
    "results": {
        "satellite.example.com": {
            "augeasversion": "1.0.0",
            "bios_release_date": "01/01/2007",
            "bios_version": "0.5.1",
            "blockdevice_sr0_size": "1073741312",
            "facterversion": "1.7.6",
            ...
}

Searching for Hosts with Matching Patterns

This query returns all hosts that match the pattern "example".

Example request:

$ curl --request GET --insecure --user sat_username:sat_password \
https://satellite.example.com/api/v2/hosts?search=example \
| python -m json.tool

Example response:

{
    ...
    "results": [
        {
            "name": "satellite.example.com",
            ...
        }
    ],
    "search": "example",
    ...
}

Searching for Hosts in an Environment

This query returns all hosts in the production environment.

Example request:

$ curl --request GET --insecure --user sat_username:sat_password \
https://satellite.example.com/api/v2/hosts?search=environment=production \
| python -m json.tool

Example response:

{
    ...
    "results": [
        {
            "environment_name": "production",
            "name": "satellite.example.com",
            ...
        }
    ],
    "search": "environment=production",
    ...
}

Searching for Hosts with a Specific Fact Value

This query returns all hosts with a model name RHEV Hypervisor.

Example request:

$ curl --request GET --insecure --user sat_username:sat_password \
https://satellite.example.com/api/v2/hosts?search=model=\"RHEV+Hypervisor\" \
| python -m json.tool

Example response:

{
    ...
    "results": [
        {
            "model_id": 1,
            "model_name": "RHEV Hypervisor",
            "name": "satellite.example.com",
            ...
        }
    ],
    "search": "model=\"RHEV Hypervisor\"",
    ...
}

Deleting a Host

This request deletes a host with a name host1.example.com.

Example request:

$ curl --request DELETE --insecure --user sat_username:sat_password \
https://satellite.example.com/api/v2/hosts/host1.example.com \
| python -m json.tool

Downloading a Full Boot Disk Image

This request downloads a full boot disk image for a host by its ID.

Example request:

$ curl --request GET --insecure --user sat_username:sat_password \
https://satellite.example.com/bootdisk/api/hosts/host_ID?full=true \
--output image.iso