Configuring and Managing Multisite Deployments

The vCloud Director Multisite feature enables a service provider or a tenant of multiple, geographically distributed vCloud Director installations (server groups) to manage and monitor those installations and their organizations as single entities.

When you associate two vCloud Director sites, you enable administration of the sites as a single entity. You also enable organizations at those sites to form associations with each other. When an organization is a member of an association, organization users can use the vCloud Director Tenant Portal to access organization assets at any member site, although each member organization and its assets are local to the site it occupies. The vCloud Director Web Console cannot be used to access resources at a remote association member.

A site or organization can form an unlimited number of associations with a peer, but each association includes exactly two members. Each site or organization must have its own private key. Association members establish a trust relationship by exchanging public keys, which are used to verify signed requests from one member to another.

Each site in an association is defined by the scope of a vCloud Director server group (a group of servers that share a vCloud Director database). Each organization in an association occupies a single site. The organization administrator controls access by organization users and groups to assets at each member site.

Site Objects and Site Associations

The installation or upgrade process creates a Site object that represents the local vCloud Director server group. A system administrator whose authority extends to more than one vCloud Director server group can configure those server groups as an association of vCloud Director sites.

Site Names

Each Site object is created with a name attribute that is a UUID.

GET https://Site-B.example.com/api/site
...
<Site name="b5920690-fe13-4c31-8e23-9e86005e7a7b" ...>
   ...
   <RestEndpoint>https://Site-A.example.com/api/org/Org-A</RestEndpoint>
   <RestEndpointCertificate>-----BEGIN CERTIFICATE-----
      MIIDDTCCAfWgAwIBAgI...Ix0eSE= -----END CERTIFICATE-----
   </RestEndpointCertificate>
   ...
</Site>

While there is no requirement that the site name match the hostname in the API endpoint, a system administrator can update the site name as an administrative convenience for vCloud API users, with a request like this one:

PUT https://Site-B.example.com/api/site
content-type: application/vnd.vmware.vcloud.site+xml
...
<Site name="Site-B" ...>
   ...
   <RestEndpoint>https://Site-A.example.com/api/org/Org-A</RestEndpoint>
   <RestEndpointCertificate>-----BEGIN CERTIFICATE-----
      MIIDDTCCAfWgAwIBAgI...Ix0eSE= -----END CERTIFICATE-----
   </RestEndpointCertificate>
   ...
</Site>

The Site element in the request body must retain the formatting in which it was returned by the GET .../site request. Additional characters, particularly carriage-returns, line feeds, or spaces, before or after the certificates can cause the system to return a bad request exception.

Associations of Organizations

After site association is complete, organization administrators at any member site can begin associating their organizations.

Note: You cannot associate a System organization with a tenant organization. The System organization at any site can be associated only with the System organization at another site.

Authorization Headers and Request Fanout

The Session response to a successful login request includes an X-VMWARE-VCLOUD-ACCESS-TOKEN header whose value is an encoded key that you can use, and the value of the X-VMWARE-VCLOUD-TOKEN-TYPE header, to construct a JWT Authorization header to include in subsequent requests in place of the deprecated x-vcloud-authorization header, which does not authenticate you to association members. See Create a vCloud API Session for more information about logging in to the vCloud API.

You can make requests that fan out to multiple association members by specifying the multisite=value pair in the Accept header. If you want the request to fan out, the value can be global or a colon-separated list of location IDs. For information about obtaining the location IDs, see Authorized Locations. When you set the value to local, the request does not fan out but includes multisite metadata included on fan-out.

For example, when you make a request such as a query that retrieves lists of resources from an association of organizations, you can specify the multisite=global pair in the Accept header so that you fan out the request to all association members and return an aggregated list.

Accept: application/*;version=30.0;multisite=global

The multisite=global value is recognized for requests specifying API version 29 and later. Starting with API version 31, you can specify a colon-separated list of location IDs, for example, multisite=ID-a:ID-b:ID-x. Unless you include this value in the Accept header, the request returns only those resources owned by the organization that is the target of the request. Unless you are making a request to the same organization that you authenticated to, you must also include a X-VMWARE-VCLOUD-AUTH-CONTEXT header that specifies the name of the organization that will fulfill your request.

When an authentication request includes the multisite=value pair, the response includes Link elements if the request failed at any association member. The category of the failure is represented by the rel value of the link.

rel="fanout:failed": Member status was ACTIVE but authentication at the member failed for some other reason.
rel="fanout:skipped": Authentication at the member was skipped because the association status was ASYMMETRIC or UNREACHABLE.

The failed or skipped request URL is in the href the value of the Link.

Authorized Locations

When you authenticate to a site that is a member of an association, the Session response includes an AuthorizedLocations element that provides vCloud API and vCloud Director Tenant Portal endpoints for other association members. In this example:

Site-A.example.com and Site-B.example.com are associated.
The user logs in to Site-A as a system administrator.

Request:

POST https://Site-A.example.com/api/sessions
Authorization: Basic ...
Accept: application/*;version=30.0
...

Response:

200 OK
...
X-VMWARE-VCLOUD-ACCESS-TOKEN: eyJhbGciOiJSUzI1NiJ9....Rn4Xw
X-VMWARE-VCLOUD-TOKEN-TYPE: Bearer
Content-Type: application/vnd.vmware.vcloud.session+xml;version=30.0;multisite=global
...
<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<Session ...
   ...  
   <AuthorizedLocations>
      <Location>
         <LocationId>a93c9db9-7471-3192-8d09-a8f7eeda85f9@9a41...
         </LocationId>
         <SiteName>Site-A</SiteName>
         <OrgName>System</OrgName>
         <RestApiEndpoint>https://site-a.example.com
         </RestApiEndpoint>
         <UIEndpoint>https://site-a.example.com
         </UIEndpoint>
         <AuthContext>System</AuthContext>
      </Location>
      <Location>
         <LocationId>a93c9db9-7471-3192-8d09-a8f7eeda85f9@4f56...
         </LocationId>
         <SiteName>Site-B</SiteName>
         <OrgName>System</OrgName>
         <RestApiEndpoint>https://site-b.example.com
         </RestApiEndpoint>
         <UIEndpoint>https://site-b.example.com
         </UIEndpoint>
         <AuthContext>System</AuthContext>
      </Location>
   </AuthorizedLocations>
</Session>

User and Group Identities

Associations of sites and organizations must agree to use the same identity provider (IDP). User and group identities for all organizations in the association must be managed through this IDP.

With the exception of the System organization, which must use the vCloud Director integrated IDP, associations are free to choose the IDP that works best for them. See About Federation and Single Sign-On for more information about the IDPs that vCloud Director supports.

Site Access Control for Organization Users and Groups

Organization administrators can configure their IDP to generate user or group access tokens that are valid at all member sites, or valid at only a subset of member sites. While user and group identities must be the same in all member organizations, user and group rights are constrained by the roles those users and groups are assigned in each member organization. Assignment of a role to a user or group is local to a member organization, as are any custom roles you create.

Load Balancer Requirements

Effective implementation of a Multisite deployment requires you to configure a load balancer that distributes requests arriving at an institutional endpoint such as https://vcloud.example.com to the endpoints for each member of the site association (for example, https://us.vcloud.example.com and https://uk.vcloud.example.com). Unless a site has only a single cell, it must also configure a load balancer that distributes incoming requests across all its cells, so that a request to https://us.vcloud.example.com can be handled by https://cell1.us.vcloud.example.com , https://cell2.us.vcloud.example.com, and so on.

Association Member Status

After you have created an association of sites or organizations, the local system periodically retrieves the status of each remote association member and updates that status in the local site's vCloud Director database. Member status is visible in the Status element of an SiteAssociationMember or OrgAssociationMember. This element can have one of three values:

ACTIVE: The association has been established by both parties, and communication with remote party was successful.
ASYMMETRIC: The association has been established at the local site, but the remote site has not yet reciprocated.
UNREACHABLE: An association has been created by both parties, but the remote site is not currently reachable on the network.

The member status "heartbeat" process runs with the identity of the Multisite system user, a local vCloud Director user account created in the System organization during vCloud Director installation. Although this account is a member of the System organization, it does not have system administrator rights. It has only a single right, Multisite: System Operations, which gives it permission to make a vCloud API request that retrieves the status of the remote member of a site association.