While vCloud Director offers impressive scalability with possibility to manage up to 20 vCenter Servers there are valid reasons why service providers deploy multiple vCloud Director instances due to fault domains (availability zones) or latency (multiple geographical regions) requirements.
In such case a single tenant (end-customer) has multiple organization accounts in multiple vCloud Director instance each with access to subset of VDCs, catalogs, VMs, etc. The service provider would usually hide this under one custom overarching portal however when the tenant wants to discover and manage his resources in programmable fashion he has to access multiple vCloud API endpoints of the vCloud Director instances.
vCloud Director version 8.0 offers a new feature: Organization Associations. If you search through vCloud API v 9.0 you will see new Admin Types: OrgAssociationType and OrgAssociationsType and related new Admin Element OrgAssociationMember. So what it is and how does it work?
The service provider can associate multiple Organizations (belonging to the same customer) together and simplify discovery of all cloud resources through single API endpoint.
Example
In my lab I have two different vCloud Director instances with URLs vcloud.fojta.com and vcloud2.fojta.com. In the first instance I have created two organizations belonging to the same customer: ACME and ACME2. In the second instance I have created organization ACME. All three organizations use the same identity source (in my case LDAP) and the same user exists in all of them with Organization Administrator credentials.
- The system administrator creates the organization associations. In this example I have associated org: ACME in the second instance with ACME and ACME2 in the first instance. This is done with the following vCloud API call:
PUT https://vcloud2.fojta.com/api/admin/org/ca5295f0-a521-4d4c-8b2e-322f154fbbea/associations Content-Type: application/vnd.vmware.admin.organizationAssociations+xml Body: <?xml version="1.0" encoding="UTF-8"?> <OrgAssociations xmlns="http://www.vmware.com/vcloud/v1.5"> <OrgAssociationMember href="https://vcloud2.fojta.com/api/admin/org/ca5295f0-a521-4d4c-8b2e-322f154fbbea/associations/02b433db-0b37-4304-b07b-0717255ec297" type="application/vnd.vmware.admin.organizationAssociation+xml"> <MemberUrl>https://vcloud.fojta.com/api/org/02b433db-0b37-4304-b07b-0717255ec297</MemberUrl> <MemberName>ACME</MemberName> <MemberEndpointCertificate>-----BEGIN CERTIFICATE----- MIIFfzCCBGegAwIBAgITTgAAARuwZOW3iRv9KQABAAABGzANBgkqhkiG9w0BAQsF ADBCMRMwEQYKCZImiZPyLGQBGRYDY29tMRUwEwYKCZImiZPyLGQBGRYFZm9qdGEx FDASBgNVBAMTC2ZvanRhLURDLUNBMB4XDTE1MDExNTE2NTAwNFoXDTE3MDExNDE2 NTAwNFowZzELMAkGA1UEBhMCQ1oxDzANBgNVBAcTBlByYWd1ZTESMBAGA1UEChMJ Zm9qdGEuY29tMRgwFgYDVQQLEw92Q2xvdWQgRGlyZWN0b3IxGTAXBgNVBAMTEHZj bG91ZC5mb2p0YS5jb20wggEiMA0GCSqGSIb3DQEBAQUAA4IBDwAwggEKAoIBAQC1 UeaPIsHjRQb8PkybTv7tfCe6oyq8UUxc7tiwX+nWvHWKJ9X6ASis1v/gT0CCa4cG fP+tezXayXMrwFSRu6OvanBSTVYvaAbUQl5CsVnQaaeCC5bTAMfGlDsl/q+LnqzW i0eG4hTpWG78v88AZkaHjIZdr5CQuDaPGJUqzOgrHjpYTLDJs+oK+S7ScpMyKhia hgeRKDfrEeQGGvSEMdHhg3Bg8RK8eyLQLjwCSCVkhYTrM5wyt4fow65beoMnOBbx LO+QpB6/amy5mJuVLVx+WJivVvuId2hmELorm2iJMjUAabybLmbMPmqHTTGyZaYw vxaDRDr0DbTMUYFyOh6LAgMBAAGjggJHMIICQzAdBgNVHQ4EFgQUi1Dhxpbkz9Dh tYOljP+MW/9GF+AwHwYDVR0jBBgwFoAUs0GCJG1KfknG9couJQXq4CZq4SQwgfoG A1UdHwSB8jCB7zCB7KCB6aCB5oaBr2xkYXA6Ly8vQ049Zm9qdGEtREMtQ0EoMSks Q049REMyLENOPUNEUCxDTj1QdWJsaWMlMjBLZXklMjBTZXJ2aWNlcyxDTj1TZXJ2 aWNlcyxDTj1Db25maWd1cmF0aW9uLERDPWZvanRhLERDPWNvbT9jZXJ0aWZpY2F0 ZVJldm9jYXRpb25MaXN0P2Jhc2U/b2JqZWN0Q2xhc3M9Y1JMRGlzdHJpYnV0aW9u UG9pbnSGMmh0dHA6Ly9EQzIuZm9qdGEuY29tL0NlcnRFbnJvbGwvZm9qdGEtREMt Q0EoMSkuY3JsMIG7BggrBgEFBQcBAQSBrjCBqzCBqAYIKwYBBQUHMAKGgZtsZGFw Oi8vL0NOPWZvanRhLURDLUNBLENOPUFJQSxDTj1QdWJsaWMlMjBLZXklMjBTZXJ2 aWNlcyxDTj1TZXJ2aWNlcyxDTj1Db25maWd1cmF0aW9uLERDPWZvanRhLERDPWNv bT9jQUNlcnRpZmljYXRlP2Jhc2U/b2JqZWN0Q2xhc3M9Y2VydGlmaWNhdGlvbkF1 dGhvcml0eTAhBgkrBgEEAYI3FAIEFB4SAFcAZQBiAFMAZQByAHYAZQByMA4GA1Ud DwEB/wQEAwIFoDATBgNVHSUEDDAKBggrBgEFBQcDATANBgkqhkiG9w0BAQsFAAOC AQEArNmceh3GkHx5Qf9s/NUlG7lh+i5nPUzlbnlhTJQeOJXSKG3DzU8ocb1xWguT x1ICyLZTQq11q3D3/3xgi9KJJaWzo8X5O/Mj81x4V8Jp9d8OgERc7lrVyrAJPbJA k7q/4tY41VOu8P5i+A21Pxuo3xELkOt5rcb2qt6QH1QizSA8Dzjq8uwCpdDo8eCP ZWUwc2lNUOyCmhFD7boNecHRJZN92i3W0YKfV+BC0cIXnqU2Y+4YEKAHWwH/gRm0 ZI41oyatyoHpTjCGFtKzrSo/mxitIoj5ZTY9wwSNPlcmziw29hOTM1fOx//rqgrW 17CREB/BoFj12Hd9bVXFgMGUSg== -----END CERTIFICATE-----</MemberEndpointCertificate> </OrgAssociationMember> <OrgAssociationMember href="https://vcloud2.fojta.com/api/admin/org/ca5295f0-a521-4d4c-8b2e-322f154fbbea/associations/13e52807-3d0a-4c0f-abdb-62d8fccb36ea" type="application/vnd.vmware.admin.organizationAssociation+xml"> <MemberUrl>https://vcloud.fojta.com/api/org/13e52807-3d0a-4c0f-abdb-62d8fccb36ea</MemberUrl> <MemberName>ACME2</MemberName> <MemberEndpointCertificate>-----BEGIN CERTIFICATE----- MIIFfzCCBGegAwIBAgITTgAAARuwZOW3iRv9KQABAAABGzANBgkqhkiG9w0BAQsF ADBCMRMwEQYKCZImiZPyLGQBGRYDY29tMRUwEwYKCZImiZPyLGQBGRYFZm9qdGEx FDASBgNVBAMTC2ZvanRhLURDLUNBMB4XDTE1MDExNTE2NTAwNFoXDTE3MDExNDE2 NTAwNFowZzELMAkGA1UEBhMCQ1oxDzANBgNVBAcTBlByYWd1ZTESMBAGA1UEChMJ Zm9qdGEuY29tMRgwFgYDVQQLEw92Q2xvdWQgRGlyZWN0b3IxGTAXBgNVBAMTEHZj bG91ZC5mb2p0YS5jb20wggEiMA0GCSqGSIb3DQEBAQUAA4IBDwAwggEKAoIBAQC1 UeaPIsHjRQb8PkybTv7tfCe6oyq8UUxc7tiwX+nWvHWKJ9X6ASis1v/gT0CCa4cG fP+tezXayXMrwFSRu6OvanBSTVYvaAbUQl5CsVnQaaeCC5bTAMfGlDsl/q+LnqzW i0eG4hTpWG78v88AZkaHjIZdr5CQuDaPGJUqzOgrHjpYTLDJs+oK+S7ScpMyKhia hgeRKDfrEeQGGvSEMdHhg3Bg8RK8eyLQLjwCSCVkhYTrM5wyt4fow65beoMnOBbx LO+QpB6/amy5mJuVLVx+WJivVvuId2hmELorm2iJMjUAabybLmbMPmqHTTGyZaYw vxaDRDr0DbTMUYFyOh6LAgMBAAGjggJHMIICQzAdBgNVHQ4EFgQUi1Dhxpbkz9Dh tYOljP+MW/9GF+AwHwYDVR0jBBgwFoAUs0GCJG1KfknG9couJQXq4CZq4SQwgfoG A1UdHwSB8jCB7zCB7KCB6aCB5oaBr2xkYXA6Ly8vQ049Zm9qdGEtREMtQ0EoMSks Q049REMyLENOPUNEUCxDTj1QdWJsaWMlMjBLZXklMjBTZXJ2aWNlcyxDTj1TZXJ2 aWNlcyxDTj1Db25maWd1cmF0aW9uLERDPWZvanRhLERDPWNvbT9jZXJ0aWZpY2F0 ZVJldm9jYXRpb25MaXN0P2Jhc2U/b2JqZWN0Q2xhc3M9Y1JMRGlzdHJpYnV0aW9u UG9pbnSGMmh0dHA6Ly9EQzIuZm9qdGEuY29tL0NlcnRFbnJvbGwvZm9qdGEtREMt Q0EoMSkuY3JsMIG7BggrBgEFBQcBAQSBrjCBqzCBqAYIKwYBBQUHMAKGgZtsZGFw Oi8vL0NOPWZvanRhLURDLUNBLENOPUFJQSxDTj1QdWJsaWMlMjBLZXklMjBTZXJ2 aWNlcyxDTj1TZXJ2aWNlcyxDTj1Db25maWd1cmF0aW9uLERDPWZvanRhLERDPWNv bT9jQUNlcnRpZmljYXRlP2Jhc2U/b2JqZWN0Q2xhc3M9Y2VydGlmaWNhdGlvbkF1 dGhvcml0eTAhBgkrBgEEAYI3FAIEFB4SAFcAZQBiAFMAZQByAHYAZQByMA4GA1Ud DwEB/wQEAwIFoDATBgNVHSUEDDAKBggrBgEFBQcDATANBgkqhkiG9w0BAQsFAAOC AQEArNmceh3GkHx5Qf9s/NUlG7lh+i5nPUzlbnlhTJQeOJXSKG3DzU8ocb1xWguT x1ICyLZTQq11q3D3/3xgi9KJJaWzo8X5O/Mj81x4V8Jp9d8OgERc7lrVyrAJPbJA k7q/4tY41VOu8P5i+A21Pxuo3xELkOt5rcb2qt6QH1QizSA8Dzjq8uwCpdDo8eCP ZWUwc2lNUOyCmhFD7boNecHRJZN92i3W0YKfV+BC0cIXnqU2Y+4YEKAHWwH/gRm0 ZI41oyatyoHpTjCGFtKzrSo/mxitIoj5ZTY9wwSNPlcmziw29hOTM1fOx//rqgrW 17CREB/BoFj12Hd9bVXFgMGUSg== -----END CERTIFICATE-----</MemberEndpointCertificate> </OrgAssociationMember> </OrgAssociations>As can be seen I am supplying URI for each Organization, its name and endpoint certificate.
- I can review organization associations with GET /admin/org/{id}/associations call or I can add or remove single association with similar POST / DELETE calls.
- Now when the end-user authenticates against the organization that has these associations he can run query calls that will run against all associated organizations. To make the query federated he must add federated=global string to the Accept header.
GET https://vcloud2.fojta.com/api/query?type=organization Accept: application/*;version=9.0;federated=global x-vcloud-authorization: 4a1f241b371b46f5a36abac85f5962c7
The reply lists all three organizations:
<?xml version="1.0" encoding="UTF-8"?> <QueryResultRecords xmlns="http://www.vmware.com/vcloud/v1.5" name="organization" page="1" pageSize="128" total="3" href="https://vcloud2.fojta.com/api/query?type=organization&page=1&pageSize=128&format=records" type="application/vnd.vmware.vcloud.query.records+xml" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:schemaLocation="http://www.vmware.com/vcloud/v1.5 http://vcloud2.fojta.com/api/v1.5/schema/master.xsd"> <Link rel="alternate" href="https://vcloud2.fojta.com/api/query?type=organization&page=1&pageSize=128&format=references" type="application/vnd.vmware.vcloud.query.references+xml"/> <Link rel="alternate" href="https://vcloud2.fojta.com/api/query?type=organization&page=1&pageSize=128&format=idrecords" type="application/vnd.vmware.vcloud.query.idrecords+xml"/> <OrgRecord canPublishCatalogs="false" deployedVMQuota="0" displayName="ACME Corporation" isEnabled="true" isReadOnly="false" name="ACME" numberOfCatalogs="1" numberOfDisks="0" numberOfGroups="7" numberOfVApps="1" numberOfVdcs="2" storedVMQuota="0" href="https://vcloud.fojta.com/api/org/02b433db-0b37-4304-b07b-0717255ec297" numberOfRunningVMs="1"/> <OrgRecord canPublishCatalogs="false" deployedVMQuota="0" displayName="ACME Inc." isEnabled="true" isReadOnly="false" name="ACME2" numberOfCatalogs="0" numberOfDisks="0" numberOfGroups="1" numberOfVApps="1" numberOfVdcs="1" storedVMQuota="0" href="https://vcloud.fojta.com/api/org/13e52807-3d0a-4c0f-abdb-62d8fccb36ea" numberOfRunningVMs="0"/> <OrgRecord canPublishCatalogs="false" deployedVMQuota="0" displayName="Acme Inc." isEnabled="true" isReadOnly="false" name="ACME" numberOfCatalogs="0" numberOfDisks="0" numberOfGroups="1" numberOfVApps="0" numberOfVdcs="0" storedVMQuota="0" href="https://vcloud2.fojta.com/api/org/ca5295f0-a521-4d4c-8b2e-322f154fbbea" numberOfRunningVMs="0"/> </QueryResultRecords>
Design Considerations
- Only GET requests for the top level Org Level data (org, sessions, tasks, templates/catalogs) and all Query Service requests by Org users can be federated.
- All System Admin query request span single vCloud Director instance and cannot be federated.
- All non-GET requests cannot be federated.
- All associated organizations must use the same identity source as the user is authenticated against all organizations and vCloud Director stores the session tokens for subsequent requests. Local accounts are not supported.
- OAuth identity source offers the lowest administration overhead when managing multiple organizations belonging to the same end-user as the user/role management can be performed centrally (see vCAT-SP for more information).
- Association works only in one direction: when organization A is associated with organization B it does not mean that organization B is associated with A. Bidirectional association must be explicitly configured for both organization.
