This is the first post in the Automating Private Cloud Director series. Everything you can do in the Private Cloud Director (PCD) UI, you can do through an API. Creating VMs, managing networks, configuring storage, assigning users to tenants. All of it. That’s not an afterthought; the UI itself is an API client.
In this post, I’d like to cover how the API works, how authentication flows, and how to make your first API calls. We’ll use curl to keep things transparent, then look at how pcdctl, our PCD-specific command line tool, and the OpenStack CLI make day-to-day operations faster. This foundation is what every other post in the series builds on, whether you’re using Terraform, Ansible, or Python scripts.
The API Surface
Private Cloud Director exposes REST APIs for its core services. Under the hood, these are standard OpenStack APIs, which means any tool that speaks OpenStack works with PCD out of the box. Here’s the mental model:
| PCD Service | Built On | What It Manages | API Path |
|---|---|---|---|
| Identity Service | Keystone | Users, tenants, domains, roles, authentication tokens | /keystone/v3 |
| Compute Service | Nova | VMs, flavors, key pairs, server actions (start, stop, migrate) | /nova/v2.1 |
| Block Storage Service | Cinder | Volumes, volume types, snapshots | /cinder/v3 |
| Networking Service | Neutron | Networks, subnets, routers, security groups, ports, floating IPs | /neutron/v2.0 |
| Image Library Service | Glance | VM images | /glance/v2 |
Every operation in the PCD UI maps to one or more calls against these service endpoints. When you click “Deploy New VM” in the UI, the UI is calling the Compute Service’s POST /servers endpoint behind the scenes.
The key benefit of this architecture: every tool that speaks OpenStack APIs works with PCD. That includes Terraform (via the OpenStack provider), Ansible (via the openstack.cloud collection), the OpenStack Python SDK, and plain curl. You’re not locked into a proprietary SDK or plugin.
Authentication: How It Works
Private Cloud Director’s Identity Service uses OpenStack Keystone for authentication. The flow is:
- You send your credentials (username, password, domain, and project scope) to the Keystone endpoint.
- Keystone validates them and returns a token in the X-Subject-Token response header.
- You include that token in the X-Auth-Token header on every subsequent API call.
The token is scoped to a specific tenant (project) and domain. It has an expiration time, after which you need to request a new one.
This is conceptually similar to how vSphere API authentication works (you authenticate to vCenter, get a session token, and pass it on subsequent calls), but the mechanism is standard OpenStack rather than proprietary.
Getting Your Credentials
PCD provides the environment variables you need on the API Access page. In the PCD UI:
- Navigate to Settings > API Access.
- You’ll see the pcdctl RC contents displayed on the page. Copy the contents and save them to a local file (e.g., ~/pcdctlrc).
The file contains environment variables for authentication:
Before sourcing it, add your password and (if your environment uses self-signed certificates) the insecure flag:
OS_INSECURE=true tells the OpenStack client libraries, pcdctl, Terraform, and Ansible to skip SSL certificate verification. This is common in lab environments. In production with proper certificates, you can omit it.
Source the file to load the variables into your shell:
These environment variables are consumed by pcdctl, the OpenStack CLI, Terraform, Ansible, and the Python SDK. One set of credentials for everything.
Your First API Call with curl
Let’s walk through the token flow manually. Obtaining the token first is what every tool does behind the scenes.
Step 1: Request a token.
In the response headers, look for X-Subject-Token. That’s your auth token. Save it:
The response body also includes the service catalog, which lists the endpoint URLs for each service in your region. You’ll see entries for compute, volumev3, network, identity, and image.
Step 2: Use the token to list VMs.
You should see a JSON response with your VMs. If you have none yet, you’ll get an empty servers array. That’s fine; it means auth is working.
Step 3: List available images.
Step 4: List networks.
Now you might be thinking: “This is a lot of typing just to list some VMs.” You’re right. That’s why CLIs exist.
Exploring the API
A few patterns that are consistent across all PCD APIs:
Listing resources is always GET /<resource> (e.g., GET /servers, GET /networks, GET /volumes). You can add query parameters for filtering: ?name=my-vm, ?status=ACTIVE.
Getting details on a specific resource is GET /<resource>/<uuid>.
Creating resources is POST /<resource> with a JSON body.
Deleting resources is DELETE /<resource>/<uuid>.
Performing actions on a VM (start, stop, reboot, resize, migrate) is POST /servers/<uuid>/action with a JSON body specifying the action.
The full API reference for each service is available in the PCD API Documentation. This documents the specific API calls that PCD supports, which may differ from what upstream OpenStack exposes:
- Compute Service API Reference
- Block Storage Service API Reference
- Networking Service API Reference
- Identity Service API Reference
- Image Service API Reference
The CLI Options: pcdctl and OpenStack CLI
For day-to-day work, you’ll want a CLI rather than raw curl.
pcdctl
pcdctl is Platform9’s unified CLI for Private Cloud Director. It wraps the OpenStack CLI, so any openstack command works by replacing openstack with pcdctl. It also adds PCD-specific commands for host onboarding (prep-node), decommissioning, and support bundle generation that aren’t part of the OpenStack API surface. Everything that works with openstack works with pcdctl by swapping the command prefix.
One thing to be aware of: PCD’s underlying OpenStack services follow the SLURP (Skip Level Upgrade Release Process) upgrade cadence rather than tracking every upstream release. This means the API version and CLI behavior match a specific, tested OpenStack release, not necessarily the latest upstream. Use the version of pcdctl or python-openstackclient that PCD provides or recommends, rather than installing the latest from PyPI, to avoid compatibility issues with newer API microversions or features that PCD hasn’t adopted yet.
Install it:
Export your PCD environment variables:
Then use it like you would the OpenStack CLI, replacing openstack with pcdctl:
Which should you use?
Use pcdctl if you want a single tool that handles both OpenStack operations and PCD-specific tasks like host onboarding. You can use the OpenStack CLI if you already have it installed, but make sure the version aligns with what PCD supports. For automation with Terraform and Ansible, neither CLI is needed because those tools talk to the API directly and negotiate the supported API version automatically.
For VMware Admins: How This Maps
| VMware | Private Cloud Director (PCD) |
|---|---|
| vSphere API / MOB (Managed Object Browser) | PCD service REST APIs (Identity, Compute, Block Storage, Networking, Image Library), built on OpenStack |
| PowerCLI | pcdctl or OpenStack CLI |
| vCenter session token | Identity Service auth token (scoped to tenant and domain) |
| vSphere SDK (Python, Go, Java) | OpenStack SDK (Python openstacksdk), or any HTTP client |
| Proprietary WSDL/SOAP (older) and REST (newer) endpoints | Standard, documented REST APIs with JSON payloads |
| Aria Automation Orchestrator (vRO) for workflow automation | Terraform, Ansible or any tool that speaks REST |
The biggest difference: VMware’s API surface is proprietary and requires vendor-specific SDKs and documentation. PCD’s API surface is standard OpenStack, which means community docs, community tools, and skills that transfer to any OpenStack-compatible cloud.
What’s Next
Now that you understand how PCD’s API works and how to authenticate, you’re ready to automate. In the next post in this series, I’ll cover Terraform: installing it, pointing it at your PCD, and deploying a VM with a network, security group, and persistent volume in a single main.tf.
If you want to get ahead, copy your RC file from Settings > API Access, save it locally, and run pcdctl server list to confirm you’re connected. Everything from here builds on that.
Thanks for reading along with me :)
