VMware Cloud Foundation API Reference Guide

1. Overview

1.2. License information

License : VMware Cloud Foundation
Terms of service : http://www.vmware.com/

1.3. URI scheme

Host : sddc-manager.sfo01.rainpole.local
BasePath : /
Schemes : HTTPS

1.5. API Versioning

API versioning is at the granularity of each resource.
API versioning is similar to URI versioning so that it is explicit i.e all APIs have the "/<version>/" prefix.
API version is independent of the product version and will evolve independently.

Tip

Reference APIs using the full path i.e "/v1/hosts" so that any future changes can be localized to a small scope in the automation code. This ensures that when the API version is incremented, you only need to update the references to the old APIs (which are now marked as deprecated) with the new APIs

Note

An illustration of API versioning is shown in the table below.
The illustration assumes that the product version is incremented from N to N+1, N+2 and so on.
The API version is only incremented when there are backward incompatible changes.
The older version of the APIs are deprecated when the version is incremented.

Product Version	APIs
Product Version N	/v1/hosts /v1/domains /v1/clusters
Product Version N+1	/v1/hosts /v1/domains (Deprecated) /v2/domains /v1/clusters
Product Version N+2	/v1/hosts (Deprecated) /v2/hosts /v1/domains (Deprecated) /v2/domains /v1/clusters
Product Version N+3	/v1/hosts (Deprecated) /v2/hosts (Deprecated) /v3/hosts /v1/domains (Deprecated) /v2/domains /v1/clusters

Product Version

APIs

Product Version N

/v1/hosts
/v1/domains
/v1/clusters

Product Version N+1

/v1/hosts
/v1/domains (Deprecated)
/v2/domains
/v1/clusters

Product Version N+2

/v1/hosts (Deprecated)
/v2/hosts
/v1/domains (Deprecated)
/v2/domains
/v1/clusters

Product Version N+3

/v1/hosts (Deprecated)
/v2/hosts (Deprecated)
/v3/hosts
/v1/domains (Deprecated)
/v2/domains
/v1/clusters

1.6. Security

1.6.1. Overview

All APIs are secured and need a username and password for invocation
The username and password are sent using Basic Authentication scheme
To invoke the APIs, SDDC Manager "admin" and its password is required.

Tip	For security reasons, you should periodically update the password for this account.

To use more secured APIs like Get the Credentials, Update or rotate passwords for a list of resources, Retry a failed credentials task for a given ID, dual authentication is required. A privileged user has to be created in management domain vCenter and associated to group "Sddc_Secured_Access". Along with "admin" account, Privileged user credentials has to be passed in request headers("privileged-username" and "privileged-password") of secured APIs in plain text. Please refer VMware Cloud Foundation Operations and Administration Guide for setting up privileged user.
Please note, using administrator@vsphere.local user as privileged user is not allowed.
If you write a script that invokes the APIs, the script should either prompt the user to enter the password for the "admin" account or should accept the password as a command line option. TAs a best practice, you should not encode the password for the account in the script code itself.
Script should also accept privileged user credentials if the script is invoking any secured APIs defined above.

1.6.2. Changing the "admin" account password

You can follow the below steps to change the password for the "admin" account

SSH in to the SDDC Manager VM, login as "vcf" user.
Enter su to switch to the "root" user.
Enter the following command:

/opt/vmware/vcf/commonsvcs/scripts/auth/set-basicauth-password.sh admin <password>

For <password>, enter the new password to associate with the admin account.

Password requirements:

Length: 8-12 characters
Must include: mix of upper-case and lower-case letters a number a special character such as @ ! # $ % ^ or ?
Cannot include: * { } [ ] ( ) / \ ' " ` ~ , ; : . < >

2. Usecases

2.1. SDDCs

2.1.1. Create a SDDC

The Create a Domain workflow automatically:

Configures networking on each host.
Configures vSAN or NFS storage on the hosts.
Deploys and configures the management stack - vCenter, PSC and NSX
Deploys and configures the vRealize stack - vRealize Lifecycle Manager, vRealize LogInsight, vRealize Operations Manager, vRealize Automation, vRealize Business
Deploys and configures Site Recovery Manager and vSphere Replication for Disaster recovery purposes
Deploys and configures SDDC Manager which provides the ability to perform Day 2 operations

Prerequisites

Note	The username and password for Basic Authentication scheme using the Cloud Builder "admin" account. The host in example requests is Cloud Builder address e.g. "sfo01cb01.sfo01.rainpole.local" not the SDDC Manager one.

The following data is required
- ID of the SDDC instance
- List of host details

Tip	Refer to: SddcHostSpec.

vCenter details

Tip	Refer to: SddcVcenterSpec.

Cluster details

Tip	Refer to: SddcClusterSpec.

List of Distributed Virtual Switches' details

Tip	Refer to: DvsSpec.

List of networks' details

Tip	Refer to: SddcNetworkSpec.

DNS details

Tip	Refer to: DnsSpec.

List of NTP servers

The following data is optional
- Name of the task to execute
- vSAN details

Tip	Refer to: VsanSpec.

NSX details

Tip	Refer to: NsxSpec.

SDDC Manager details

Tip	Refer to: SddcManagerSpec.

List of PSC’s details

Tip	Refer to: PscSpec.

vRealize LogInsight details

Tip	Refer to: SddcVrliDeploymentSpec.

VxManager details

Tip	Refer to: VxManagerSpec.

Name of network pool associated with the management domain
List of names of the components to be excluded
Version of the Distributed Virtual Switch
Boolean to identify if Customer Experience Improvement Program is to be enabled
PSC loadbalancer hostname

Note	The hostname must not include the domain. Instead the subDomain property from the DNS spec will be used to for the fully-qualified domain name.

PSC loadbalancer IP address

Note	This address must be from the management network address range.

Active Directory details

Tip	Refer to: AdSpec.

Name of the NFS datastore
Site Recovery Manager details

Tip	Refer to: SrmSpec.

vSphere Replication details

Tip	Refer to: VsphereReplicationSpec.

vRealize Automation details

Tip	Refer to: SddcVraDeploymentSpec.

Remote Site details

Tip	Refer to: RemoteSiteSpec.

vRealize Operation Manager details

Tip	Refer to: SddcVropsDeploymentSpec.

vRealize Business details

Tip	Refer to: SddcVrbDeploymentSpec.

SMTP details

Tip	Refer to: SmtpSpec.

Passphrase for the certificates to be used for PSC, vCenter, NSX, vRealize Automation and vRealize Operation Manager
License for the ESXi hosts
vRealize Lifecycle Manager details

Tip	Refer to: SddcVrslcmDeploymentSpec.

vSphere deployment endpoint details

Tip	Refer to: VsphereDeploymentEndpointSpec.

VxRail environment details

Tip	Refer to: VxRailSpec.

UMDS details

Tip	Refer to: UmdsSpec.

Boolean to identify if ESXi thumbprint validation is to be skipped
Modules with self-signed certificates

Note	Leave it empty if no self-signed certificate, add ALL or comma separated list of components otherwise. Initial valid values: ALL, VRA, SRM, NSX, VR, PSC, VC, VROPS, VRSLCM, LI, VRB.

Boolean to identify if vSAN should be cleaned up

Note	Should be true only if this is the very first run