# How to Add Roles to Hypervisors Using API Calls

## Problem

API calls are needed to automate host onboarding and add new roles to Hypervisors.

## Environment

* Platform9 Managed OpenStack - v5.4 and Higher.

## Procedure

The steps are listed below:

1. Obtain Keystone Token:

Follow the instructions found in <https://developer.openstack.org/api-ref/identity/v3/?expanded=password-authentication-with-unscoped-authorization-detail,assign-role-to-user-on-projects-owned-by-domain-detail,password-authentication-with-scoped-authorization-detail#password-authentication-with-scoped-authorization>. The OpenStack CLI can also be used to obtain a Keystone token by running:

{% tabs %}
{% tab title="Token issue" %}

```javascript
# openstack token issue
```

{% endtab %}
{% endtabs %}

2. Install host installer on the host (on the host):

Download the installer from Platform9 and run it on the host. You can use the Clarity UI for it Refer to:

<https://DU_FQDN/clarity/index.html#/infrastructure/addhosts>

3. Get the host UUID of the host (on the host)

On the host, get the UUID by running the following command:

{% tabs %}
{% tab title="Host UUID" %}

```javascript
# grep host_id /etc/pf9/host_id.conf | awk '{print $3}'​
```

{% endtab %}
{% endtabs %}

4. Check that the host has phoned in

Verify that the host connected back fine to the Platform9 Management plane using the following command:

{% tabs %}
{% tab title="Verify host" %}

```javascript
# curl -H "X-Auth-Token:<keystone token>" https://<pf9-url>/resmgr/v1/hosts/<host uuid>
```

{% endtab %}
{% endtabs %}

5. Apply Neutron roles for the host (Optional)

There are multiple commands to be run if you intend to run any network service on this host. These commands set up Neutron DHCP agent, L3 agent, OVS agent (DVR mode) and Metadata service. Note that the pf9-neutron-base role is mandatory if any Neutron services are going to be run on this host. The other roles should be set up depending on whether you intend to run on this host.

{% tabs %}
{% tab title="Apply role to host" %}

```javascript
# curl -X PUT -H "X-Auth-Token:<keystone token>" https://<pf9-url>/resmgr/v1/hosts/<host uuid>/roles/pf9-neutron-base


# curl -X PUT -H "X-Auth-Token:<keystone token>" https://<pf9-url>/resmgr/v1/hosts/<host uuid>/roles/pf9-neutron-metadata-agent


# curl -X PUT -H "X-Auth-Token:<keystone token>" -H "Content-Type: application/json" https://<pf9-url>/resmgr/v1/hosts/<host uuid>/roles/pf9-neutron-dhcp-agent -d '{"dnsmasq_dns_servers": "207.200.0.230,207.200.0.25", "dns_domain": "openstacklocal", "rpc_response_timeout": "240"}'


# curl -X PUT -H "X-Auth-Token:<keystone token>" -H "Content-Type: application/json" https://<pf9-url>/resmgr/v1/hosts/<host uuid>/roles/pf9-neutron-l3-agent -d '{"agent_mode": "dvr_snat", "rpc_response_timeout": "240"}'


# curl -X PUT -H "X-Auth-Token:<keystone token>" -H "Content-Type: application/json" https://<pf9-url>/resmgr/v1/hosts/<host uuid>/roles/pf9-neutron-ovs-agent -d '{"allow_dhcp_vms": "False", "local_ip": "10.16.35.13", "rpc_response_timeout": "240", "enable_tunneling": "True", "ovsdb_interface": "vsctl", "net_type": "vlan,vxlan", "of_interface": "ovs-ofctl", "tunnel_types": "vxlan", "enable_distributed_routing": "True", "bridge_mappings": "physnet:br-vlan"}'
```

{% endtab %}
{% endtabs %}

6. Apply Cinder roles for the host(Optional)

There are multiple commands to be run if you intend to run any Cinder service on this host. These commands set up Ceph, HPE 3PAR with Cinder. Note that the pf9-cindervolume-base role is mandatory if any Cinder services are going to be run on this host. The other roles should be setup depending on which storage backend you intend to support through this host.

{% tabs %}
{% tab title="Sample" %}

```javascript
# curl -X PUT -H "X-Auth-Token:<keystone token>" https://<pf9-url>/resmgr/v1/hosts/<host uuid>/roles/pf9-cindervolume-base
curl -X PUT -H "X-Auth-Token:<keystone token>" -H "Content-Type: application/json"
 https://<pf9-url>/resmgr/v1/hosts/<host uuid>/roles/pf9-cindervolume-ceph -d '{"rbd_store_chunk_size": "4", "rbd_ceph_conf": "/etc/ceph/ceph.conf", "volume_backend_name": "ceph", "rbd_secret_uuid": "24d6317e-aaa4-48f1-9ac2-8a7f0dcd1f2a", "volume_driver": "cinder.volume.drivers.rbd.RBDDriver", "rbd_pool": ".cinder", "rbd_flatten_volume_from_snapshot": "true", "rbd_max_clone_depth": "5", "rbd_user": "cinder"}'
curl -X PUT -H "X-Auth-Token:<keystone token>" -H "Content-Type: application/json" https://<pf9-url>/resmgr/v1/hosts/<host uuid>/roles/pf9-cindervolume-other -d '{"volume_driver": "cinder.volume.drivers.hpe.hpe_3par_iscsi.HPE3PARISCSIDriver", "volume_backend_name": "3PAR"}'
```

{% endtab %}
{% endtabs %}

7. Apply Hypervisor role for the host (Optional)

If you intend to run virtual machines on this host, the following command sets up the nova-compute service on the host.

{% tabs %}
{% tab title="Sample" %}

```javascript
#	curl -X PUT -H "X-Auth-Token:<keystone token>" -H "Content-Type: application/json" https://<pf9-url>/resmgr/v1/hosts/<host uuid>/roles/pf9-ostackhost-neutron -d '{"reclaim_instance_interval": "0", "find_orphaned_vms_interval": "-1", "cpu_allocation_ratio": "0.0", "instances_path": "/opt/pf9/data/instances/", "ram_allocation_ratio": "0.0", "consul_ip": "", "images_type": "default", "novncproxy_base_url": "http://10.17.3.13:6080/vnc_auto.html"}'
```

{% endtab %}
{% endtabs %}

8. Apply Ceilometer role for the host(Optional)

This command setups ceilometer service on the host.

{% tabs %}
{% tab title="Sample" %}

```javascript
# curl -X PUT -H "X-Auth-Token:<keystone token>" -H "Content-Type: application/json" https://<pf9-url>/resmgr/v1/hosts/<host uuid>/roles/pf9-ceilometer -d '{"kvm_instance_disk_path": "/opt/pf9/data/instances/"}'
```

{% endtab %}
{% endtabs %}

9. Check host role status for the host

After all the required roles are applied to the host, the status of the host can be tracked with the following command. The value of the role\_status field indicates the status of the role application.

{% tabs %}
{% tab title="Check host status" %}

```javascript
# curl -H "X-Auth-Token:<keystone token>" https://<pf9-url>/resmgr/v1/hosts/<host uuid>
```

{% endtab %}
{% endtabs %}

## Definition of different roles:

| State      | Description                                                                                         |
| ---------- | --------------------------------------------------------------------------------------------------- |
| ok         | The roles were successfully applied                                                                 |
| converging | Application of roles is in progress                                                                 |
| retrying   | Application of role may have hit a temporary error. A retry to apply the role again is in progress. |
| failed     | Application of the roles have failed.                                                               |


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://platform9.com/kb/pmo/how-to/how-to-add-roles-to-hypervisors-using-calls.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.