-- Leo's gemini proxy

-- Connecting to gmi.runtimeterror.dev:1965...

-- Connected

-- Sending request

-- Meta line: 20 text/gemini;lang=en-US

curl -X 'POST' \
  'https://vra.lab.bowdre.net/csp/gateway/am/api/login' \
  -H 'accept: */*' \
  -H 'Content-Type: application/json' \
  -d '{
  "username": "vra",
  "password": "********",
  "domain": "lab.bowdre.net",
  "scope": ""
}'

{
  "content": [
    {
      "flavorMappings": {
        "mapping": {
          "1vCPU | 2GB [tiny]": {
            "cpuCount": 1,
            "memoryInMB": 2048
          },
          "1vCPU | 1GB [micro]": {
            "cpuCount": 1,
            "memoryInMB": 1024
          },
          "2vCPU | 4GB [small]": {
            "cpuCount": 2,
            "memoryInMB": 4096
          }
        },
        "_links": {
          "region": {
            "href": "/iaas/api/regions/3617c011-39db-466e-a7f3-029f4523548f"
          }
        }
      },
      "externalRegionId": "Datacenter:datacenter-39056",
      "cloudAccountId": "75d29635-f128-4b85-8cf9-95a9e5981c68",
      "name": "",
      "id": "61ebe5bf-5f55-4dee-8533-7ad05c067dd9-3617c011-39db-466e-a7f3-029f4523548f",
      "updatedAt": "2022-05-05",
      "organizationId": "61ebe5bf-5f55-4dee-8533-7ad05c067dd9",
      "orgId": "61ebe5bf-5f55-4dee-8533-7ad05c067dd9",
      "_links": {
        "self": {
          "href": "/iaas/api/flavor-profiles/61ebe5bf-5f55-4dee-8533-7ad05c067dd9-3617c011-39db-466e-a7f3-029f4523548f"
        },
        "region": {
          "href": "/iaas/api/regions/3617c011-39db-466e-a7f3-029f4523548f"
        }
      }
    },
    {
      "flavorMappings": {
        "mapping": {
          "2vCPU | 8GB [medium]": {
            "cpuCount": 2,
            "memoryInMB": 8192
          },
          "1vCPU | 2GB [tiny]": {
            "cpuCount": 1,
            "memoryInMB": 2048
          },
          "8vCPU | 16GB [giant]": {
            "cpuCount": 8,
            "memoryInMB": 16384
          },
          "1vCPU | 1GB [micro]": {
            "cpuCount": 1,
            "memoryInMB": 1024
          },
          "2vCPU | 4GB [small]": {
            "cpuCount": 2,
            "memoryInMB": 4096
          },
          "4vCPU | 12GB [large]": {
            "cpuCount": 4,
            "memoryInMB": 12288
          }
        },
        "_links": {
          "region": {
            "href": "/iaas/api/regions/c0d2a662-9ee5-4a27-9a9e-e92a72668136"
          }
        }
      },
      "externalRegionId": "Datacenter:datacenter-1001",
      "cloudAccountId": "75d29635-f128-4b85-8cf9-95a9e5981c68",
      "name": "",
      "id": "61ebe5bf-5f55-4dee-8533-7ad05c067dd9-c0d2a662-9ee5-4a27-9a9e-e92a72668136",
      "updatedAt": "2022-05-05",
      "organizationId": "61ebe5bf-5f55-4dee-8533-7ad05c067dd9",
      "orgId": "61ebe5bf-5f55-4dee-8533-7ad05c067dd9",
      "_links": {
        "self": {
          "href": "/iaas/api/flavor-profiles/61ebe5bf-5f55-4dee-8533-7ad05c067dd9-c0d2a662-9ee5-4a27-9a9e-e92a72668136"
        },
        "region": {
          "href": "/iaas/api/regions/c0d2a662-9ee5-4a27-9a9e-e92a72668136"
        }
      }
    }
  ],
  "totalElements": 2,
  "numberOfElements": 2
}

=> https://httpie.io/docs/cli/debian-and-ubuntu [4] Debian package
Once installed, running `http` will give me a quick overview of how to use this new tool:

HTTPie cleverly interprets anything passed after the URL as a request item [5], and it determines the item type based on a simple key/value syntax:
> Each request item is simply a key/value pair separated with the following characters: `:` (headers), `=` (data field, e.g., JSON, form), `:=` (raw data field), `==` (query parameters), `@` (file upload).
=> https://httpie.io/docs/cli/request-items [5] request item
So my earlier request for an authentication token becomes:

<-- note -->
If your vRA endpoint is using a self-signed or otherwise untrusted certificate, pass the HTTPie option `--verify=no` to ignore certificate errors:

<-- /note -->
Running that will return a bunch of interesting headers but I'm mainly interested in the response body:

There's the auth token that I'll need for subsequent requests. I'll store that in a variable so that it's easier to wield:

So now if I want to find out which images have been configured in vRA, I can ask:

<-- note -->
Remember from above that HTTPie will automatically insert key/value pairs separated by a colon into the request header.
<-- /note -->
And I'll get back some headers followed by an JSON object detailing the defined image mappings broken up by region:

This doesn't give me the *name* of the regions, but I could use the `_links.region.href` data to quickly match up images which exist in a given region.
You'll notice that HTTPie also prettifies the JSON response to make it easy for humans to parse. This is great for experimenting with requests against different API endpoints and getting a feel for what data can be found where. And firing off tests in HTTPie can be a lot quicker (and easier to format) than with other tools.
Now let's take what we've learned and see about implementing it as vRO actions.
### vRealize Orchestrator actions
My immediate goal for this exercise is create a set of vRealize Orchestrator actions which take in a zone/location identifier from the Cloud Assembly request and return a list of images which are available for deployment there. I'll start with some utility actions to do the heavy lifting, and  then I'll be able to call them from other actions as things get more complicated/interesting. Before I can do that, though, I'll need to add the vRA instance as an HTTP REST endpoint in vRO.
<-- note -->
A lot of what follows was borrowed *heavily* from a very helpful post by Oktawiusz Poranski over at Automate Clouds [6] so be sure to check out that site for more great tips on working with APIs!
<-- /note -->
=> https://automateclouds.com/2021/vrealize-automation-8-rest-api-how-to/ [6] very helpful post by Oktawiusz Poranski over at Automate Clouds
### Creating the endpoint
I can use the predefined **Add a REST host** workflow to create the needed endpoint.
=> add_rest_host_properties.png Image: Add a REST host workflow - host properties
Configuring the host properties here is very simple: just give it a name and the URL of the vRA instance.
=> add_rest_host_auth.png Image: Add a REST host workflow - authentication
On the Authentication tab, I set the auth type to `NONE`; I'll handle the authentication steps directly.
With those parameters in place I can kick off the workflow. Once it completes, I can check **Administration > Inventory > HTTP-REST** to see the newly-created endpoint:
=> new_rest_host_in_inventory.png Image: New HTTP-REST endpoint
### Creating a Configuration for the endpoint
I don't want to hardcode any endpoints or credentials into my vRO actions so I'm also going to create a Configuration to store those details. This will make it easy to reference those same details from multiple actions as well.
To create a new Configuration, I'll head to **Assets > Configurations**, select a folder (or create a new one) where I want the Configuration to live, and then click the **New Configuration** button.
=> config_element_1.png Image: Location of the Configurations
I'm going to call this new Configuration `Endpoints` since I plan to use it for holding host/credentials for additional endpoints in the future. After giving it a name, I'll go ahead and click **Save** to preserve my efforts thus far.
=> config_element_2.png Image: Creating the new Configuration
I'll then click over to the **Variables** tab and create a new variable to store my vRA endpoint details; I'll call it `vRAHost`, and hit the *Type* dropdown and select **New Composite Type**.
=> vrahost_variable_1.png Image: Creating the new variable
This new composite type will let me use a single variable to store multiple values - basically everything I'll need to interact with a single REST endpoint:

=> new_composite_type.png Image: Creating a new composite type
I can then map the appropriate values for this new variable and hit **Create**.
=> vrahost_variable_2.png Image: Assigning values to the vRAHost
I make sure to **Save** my work and then gaze at the new Configuration's majesty:
=> created_configuration.png Image: Newly-created Configuration
Okay, enough prep work - let's get into some Actions!
### Utility actions
### `getConfigValue` action
I'll head into **Library > Actions** to create a new action inside my `com.virtuallypotato.utility` module. This action's sole purpose will be to extract the details out of the configuration element I just created. Right now I'm only concerned with retrieving the one `vRAHost` configuration but I'm a fan of using generic pluggable modules where possible. This one will work to retrieve the value of *any* variable defined in *any* configuration element so I'll call it `getConfigValue`.
=> getConfigValue_action.png Image: getConfigValue action

### `vraLogin` action
Next, I'll create another action in my `com.virtuallypotato.utility` module which will use the `getConfigValue` action to retrieve the endpoint details. It will then submit a `POST` request to that endpoint to log in, and it will return the authentication token. Later actions will be able to call upon `vraLogin` to grab a token and then pass that back to the IaaS API in the request headers - but I'm getting ahead of myself. Let's get the login sorted:
=> vraLogin_action.png Image: vraLogin action

### `vraLogout` action
I like to clean up after myself so I'm also going to create a `vraLogout` action in my `com.virtuallypotato.utility` module to tear down the API session when I'm finished with it.
=> vraLogout_action.png Image: vraLogout action

### `vraExecute` action
My final "utility" action for this effort will run in between `vraLogin` and `vraLogout`, and it will handle making the actual API call and returning the results. This way I won't have to implement the API handler in every single action which needs to talk to the API - they can just call my new action, `vraExecute`.
=> vraExecute_action.png Image: vraExecute action

### Bonus: `vraTester` action
That's it for the core utility actions - but wouldn't it be great to know that this stuff works before moving on to handling the request input? Enter `vraTester`! It will be handy to have an action I can test vRA REST requests in before going all-in on a solution.
This action will:
* Call `vraLogin` to get an API token.
* Call `vraExecute` with that token, a REST method, and an API endpoint to retrieve some data.
* Call `vraLogout` to terminate the API session.
* Return the data so we can see if it worked.
Other actions wanting to interact with the vRA REST API will follow the same basic formula, though with some more logic and capability baked in.
Anyway, here's my first swing:

Pretty simple, right? Let's see if it works:
=> vraTester_action.png Image: vraTester action
It did! Though that result is a bit hard to parse visually, so I'm going to prettify it a bit:

I can see that it returned two Cloud Zones, named `NUC` (for my NUC 9 host [7]) and `QTZ` (for my Quartz64 SBC running ESXi-ARM [8]). Each Zone also includes data about other objects associated with the Zone, such as that `_links.region.href` property I mentioned earlier.
=> /vmware-home-lab-on-intel-nuc-9/ [7] NUC 9 host
=> /esxi-arm-on-quartz64/ [8] Quartz64 SBC running ESXi-ARM
My compute targets live at the Zone level, each Zone lives inside a given Region, and the Image Profiles reside within a Region. See where this is going? I now have the information I need to link a Zone to the Image Profiles available within that Zone.
### Input actions
So now I'm ready to work on the actions that will handle passing information between the vRA REST API and the Cloud Assembly deployment request form. For organization purposes, I'll stick them in a new module which I'll call `com.virtuallypotato.inputs`. And for the immediate purposes, I'm going to focus on just two fields in the request form: `Zone` (for where the VM should be created) and `Image` (for what VM template it will be spawned from). The `Zone` dropdown will be automatically populated when the form loads, and `Image` options will show up as soon as a the user has selected a Zone.
### `vraGetZones` action
This action will basically just repeat the call that I tested above in `vraTester`, but parse the result to extract just the Zone names. It will pop those into an array of strings which can be rendered as a dropdown on the Cloud Assembly side.
=> vraGetZones_action.png Image: vraGetZones action

### `vraGetImages` action
Once the user has selected a Zone from the dropdown, the `vraGetImages` action will first contact the same `/iaas/api/zones` API to get the same list of available Zones. It will look through that list to find the one with the matching name, and then extract the `._links.region.href` URI for the Zone.
Next it will reach out to `/iaas/api/images` to retrieve all the available images. For each image, it will compare its associated `._links.region.href` URI to that of the designated Zone; if there's a match, the action will add the image to an array of strings which will then be returned back to the request form.
Oh, and the whole thing is wrapped in a conditional so that the code only executes when `zoneName` has been set on the request form; otherwise it simply returns an empty string.

I'll use the **Debug** button to test this action real quick-like, providing the `NUC` Zone as the input:
=> vraGetImages_action.png Image: vraGetImages action
It works! Well, at least when called directly. Let's see how it does when called from Cloud Assembly.
### Cloud Assembly request
For now I'm really only testing using my new vRO actions so my Cloud Template is going to be pretty basic. I'm not even going to add any resources to the template; I don't even need it to be deployable.
=> blank_template.png Image: Completely blank template
What I do need are two inputs. I'd normally just write the inputs directly as YAML, but the syntax for referencing vRO actions can be a bit tricky and I don't want to mess it up. So I pop over to the **Inputs** tab in the editor pane on the right and click the **New Cloud Template Input** button.
=> need_input.png Image: Need input!
I'll start with an input called `zoneName`, which will be a string:
=> zoneName_input_1.png Image: zoneName input
I'll then click on **More Options** and scroll to the bottom to select that the field data should come from an *External Source*:
=> zoneName_input_2.png Image: zoneName more options
I click the **Select** button and can then search for the `vraGetZones` action I wish to use:
=> zoneName_input_3.png Image: zoneName selecting the action
And then hit **Create** to add the new input to the template.
Next I'll repeat the same steps to create a new `image` input. This time, though, when I select the `vraGetImages` action I'll also need to select another input to bind to the `zoneName` parameter:
=> image_input.png Image: Binding the input
The full code for my template now looks like this:

And I can use the **Test** button at the bottom of the Cloud Assembly template editor to confirm that everything works:
=> recording.gif Image: Testing the request fields
It does!
### Conclusion
This has been a very quick introduction on how to start pulling data from the vRA APIs, but it (hopefully) helps to consolidate all the knowledge and information I had to find when I started down this path - and maybe it will give you some ideas on how you can use this ability within your own vRA environment.
In the near future, I'll also have a post on how to do the same sort of things with the vCenter REST API, and I hope to follow that up with a deeper dive on all the tricks I've used to make my request forms as dynamic as possible with the absolute minimum of hardcoded data in the templates. Let me know in the comments if there are any particular use cases you'd like me to explore further.
Until next time!


---

=> mailto:blogreply.getting-started-vra-rest-api@runtimeterror.dev?subject=Re%3A%20Getting%20Started%20with%20the%20vRealize%20Automation%20REST%20API 📧 Reply by email


## Related articles

=> /display-tempest-weather-static-site/index.gmi Displaying Data from a Tempest Weather Station on a Static Site
=> /enable-fips-fix-aria-lifecycle/index.gmi Enabling FIPS Compliance Fixes Aria Lifecycle 8.14
=> /automating-camera-notifications-home-assistant-ntfy/index.gmi Automating Security Camera Notifications With Home Assistant and Ntfy
---

=> / Home
=> https://runtimeterror.dev/getting-started-vra-rest-api/ This page on the big web
-- Response ended
-- Page fetched on Fri May 10 02:55:21 2024