# ****************************************************************************** # * Copyright 2019-2022 VMware, Inc. All rights reserved. VMware Confidential * # ****************************************************************************** swagger: "2.0" info: version: "36.2" title: Cloud Director Appliance API # When editing this description, be careful about how it renders in the docs contact: name: VMware, Inc. url: https://code.vmware.com email: support@vmware.com license: name: '' url: 'https://code.vmware.com/support' description: | The Cloud Director Appliance API can be used to get and change the state information of your Cloud Director appliances. The API is only accessible on port 5480.
Note: This API only returns JSON formatted data.

Authentication

You can authenticate using the HTTP Basic auth for each request or you can use a Bearer Token, which you can retrieve from the sessions api below. For Basic auth, the "root" user must be used for authentication. No other headers are required.

Asynchronous operations

The appliance processes asynchronous operations received through a POST request. The tasks associated with these operations are unique to that appliance and are identified by the task IDs. In these cases, the server responds with an HTTP Response code 202 and an empty body. The tracking task is linked via the URI provided in the Location header.
The caller must be prepared to handle responses to API calls by inspecting the HTTP Response code.
Tasks are not persisted upon appliance reboot. Tasks are also relative to the appliance that the request was sent to – if a POST was sent to appliance A, then appliance B won't know about it and cannot be queried.

Error Conditions

All operations report errors using the following vCD error reporting rules:

OpenAPI Design Concepts and Principles

SystemSetup API Request Body - Samples


    {
        "applianceType": "primary",
        "storage": {
            "nfs": "192.168.100.1:/data/transfer"
        },
        "appliance": {
            "dbPassword": "vcloud",
            "ceip": true
        },
        "sysAdmin": {
            "username": "administrator",
            "password": "secret-password",
            "fullName": "cloud administrator",
            "email": "my-email@my-company.com"
        },
        "installation": {
            "name": "vcd5",
            "id": 5
        }
    }
    

    {
        "applianceType": "standby",
        "storage": {
            "nfs": "192.168.100.1:/data/transfer"
        }
    }
    

    {
        "applianceType": "cell",
        "storage": {
            "nfs": "192.168.100.1:/data/transfer"
        }
    }
    
securityDefinitions: BasicAuth: type: basic BearerAuth: type: basic description: This is bearer, despite the type field setting. A limitation of OpenApi 2.0. basePath: / paths: /api/1.0.0/systemSetup: post: tags: - systemSetup summary: Setup appliance nodes. x-vcloud-added-in: 36.0 security: - BasicAuth: [] - BearerAuth: [] operationId: performSystemSetup consumes: - application/json parameters: - in: body name: appliance required: true schema: $ref: '#/definitions/ApplianceSystemSetup' produces: - application/json responses: 202: description: | Response Body is empty. Response includes Location header with URL to related task-id. headers: Location: type: "string" description: "Task URL. Example: https://:5480/api/1.0.0/tasks/" /api/systemSetup: post: tags: - systemSetup summary: Setup appliance nodes. x-vcloud-added-in: 35.0 x-vcloud-deprecated-in: 36.0 x-vcloud-deprecated-alternative: /api/1.0.0/systemSetup x-vcloud-removed-in: 36.0 security: - BasicAuth: [] - BearerAuth: [] operationId: postSystemSetup consumes: - application/json parameters: - in: body name: appliance required: true schema: $ref: '#/definitions/ApplianceSystemSetup' produces: - application/json responses: 202: description: | Response Body is empty. Response includes Location header with URL to related task-id. headers: Location: type: "string" description: "Task URL. Example: https://:5480/api/1.0.0/tasks/" /api/nfsValidate: post: tags: - nfsValidate summary: Validates nfs parameters and mount point. Performs mount and runs diagnostic checks. x-vcloud-added-in: 35.0 x-vcloud-deprecated-in: 36.1 x-vcloud-deprecated-alternative: /api/1.0.0/mount/validate security: - BasicAuth: [] - BearerAuth: [] operationId: postNfsValidate consumes: - application/json parameters: - in: body name: nfs required: true schema: $ref: '#/definitions/NfsMountInfo' produces: - application/json responses: 202: description: | Response Body is empty. Response includes Location header with URL to related task-id. headers: Location: type: "string" description: "Task URL. Example: https://:5480/api/1.0.0/tasks/" /api/1.0.0/mount: get: tags: - mount summary: Returns the current NFS mount point information. x-vcloud-added-in: 36.1 security: - BasicAuth: [] - BearerAuth: [] operationId: queryNfsMount produces: - "application/json" responses: 200: description: OK schema: $ref: '#/definitions/NfsMountInfo' put: tags: - mount summary: Mount or unmount nfs share specified. To unmount specify nfs parameter value as empty string. x-vcloud-added-in: 36.1 security: - BasicAuth: [] - BearerAuth: [] operationId: mountNfs consumes: - application/json parameters: - in: body name: nfs required: true schema: $ref: '#/definitions/NfsMountInfo' produces: - application/json responses: 202: description: | Response Body is empty. Response includes Location header with URL to related task-id. headers: Location: type: "string" description: "Task URL. Example: https://:5480/api/1.0.0/tasks/" /api/1.0.0/mount/validate: post: tags: - mount summary: Validates nfs parameters and mount point. Performs mount and runs diagnostic checks. x-vcloud-added-in: 36.1 security: - BasicAuth: [] - BearerAuth: [] operationId: validateNfs consumes: - application/json parameters: - in: body name: nfs required: true schema: $ref: '#/definitions/NfsMountInfo' - in: query name: overwrite required: false type: boolean default: false description: | Value "true" means the NFS validator will allow the presence of "appliance-nodes", "cells", and "responses.properties" on the share, however validation will fail if the node directories within "appliance-nodes" have been modified within the last two minutes. It will not actively remove or overwrite anything on the share. The default is "false" meaning that the NFS validator will insist that share be empty. produces: - application/json responses: 202: description: | Response Body is empty. Response includes Location header with URL to related task-id. headers: Location: type: "string" description: "Task URL. Example: https://:5480/api/1.0.0/tasks/" /api/1.0.0/sessions: post: tags: - sessions summary: Returns Bearer Token. description: |
  • Token is valid for a minimum of 30 minutes.
  • Once token is issued or used, a 30 minute timer is started. If not used within that period it will expire.
  • Token is valid for a maximum of 24 hours, after which it expires.
x-vcloud-added-in: 35.0 security: - BasicAuth: [] - BearerAuth: [] operationId: postSessions produces: - "application/json" responses: 401: description: Unauthorized 200: description: OK schema: $ref: '#/definitions/Session' examples: application/json: | { "authToken": "N846tVa9bZG2-FpnnPwKETrJ1oYUpGd8tHupouVTJAg", "expires": "2020-06-24T23:11:23Z" } /api/1.0.0/sessions/{auth-token}: delete: tags: - invalidateToken summary: Invalidate the Bearer token passed in the request URL. description: | The value of 'current' could also be provided for the URL auth-token parameter when the request's authentication method is bearer token. x-vcloud-added-in: 35.0 security: - BasicAuth: [] - BearerAuth: [] operationId: invalidateToken produces: - "application/json" parameters: - name: "auth-token" in: "path" description: "auth-token which is being invalidated" required: true type: "string" responses: 204: description: The server successfully processed the request. Response Body is empty. 400: description: | If the Authorization header of the request does not use a Bearer token, the specific auth-token must be passed as a URL parameter instead of using "current". /api/1.0.0/isPrimary: get: tags: - isPrimary summary: Returns boolean describing if this appliance is currently the primary of the HA cluster x-vcloud-added-in: 34.0 security: [] # No security description: | Valid response values are:
  • true
  • false
operationId: getIsPrimary produces: - "application/json" responses: 404: description: API not applicable for cell-type appliances 200: description: OK schema: $ref: '#/definitions/IsPrimary' examples: application/json: | { "isPrimary": false } /api/1.0.0/version: get: tags: - version summary: appliance version information x-vcloud-added-in: 35.0 security: - BasicAuth: [] - BearerAuth: [] description: Returns current appliance version operationId: getVersion produces: - "application/json" responses: 200: description: OK schema: $ref: '#/definitions/Version' examples: application/json: | { "appliance": "10.2.0.5000 Build 170000" } /api/1.0.0/storage: get: tags: - storage summary: Returns information about all file systems mounted in this appliance. x-vcloud-added-in: 34.0 security: - BasicAuth: [] - BearerAuth: [] description: | Returns file system information for the following file systems on the appliance.
  • local root file system
  • local database disk file system
  • nfs share file system
operationId: getStorage produces: - "application/json" responses: 200: description: OK schema: $ref: '#/definitions/FileSystems' examples: application/json: | { "nfs": { "availableMB": 244719, "filesystem": ":/data/transfer", "mountedOn": "/opt/vmware/vcloud-director/data/transfer", "percentUsed": 1, "status": "available", "usedMB": 61, "volumeSizeMB": 257903 }, "postgres": { "availableMB": 72053, "filesystem": "/dev/mapper/database_vg-vpostgres", "mountedOn": "/var/vmware/vpostgres", "percentUsed": 6, "status": "available", "usedMB": 3971, "volumeSizeMB": 80119 }, "root": { "availableMB": 24326, "filesystem": "/dev/sda3", "mountedOn": "/", "percentUsed": 8, "status": "available", "usedMB": 1959, "volumeSizeMB": 27698 } } /api/1.0.0/storage/{filesystem-name}: get: tags: - fileSystem summary: Returns current statistics for the requested filesystem mounted on this appliance. x-vcloud-added-in: 34.0 description: | Current supported input values are:
  • root
  • postgres
  • nfs
      security: - BasicAuth: [] - BearerAuth: [] operationId: getFileSystem produces: - "application/json" parameters: - name: "filesystem-name" in: "path" description: | Name of file system whose details you want returned. required: true type: "string" responses: 404: description: filesystem-name value specified is not valid. 200: description: OK schema: $ref: '#/definitions/FileSystem' /api/1.0.0/services: get: tags: - applianceServices summary: Returns current operational state for the vcd, vpostgres, repmgrd and appliance-sync.timer services running on this appliance. x-vcloud-added-in: 34.0 security: - BasicAuth: [] - BearerAuth: [] operationId: getServices produces: - "application/json" responses: 200: description: OK schema: $ref: '#/definitions/ApplianceServices' examples: application/json: | #Response Example on a primary or standby type of vcd appliance node: [ { "serviceName": "vmware-vcd", "status": "running" }, { "serviceName": "vpostgres", "status": "running" }, { "serviceName": "repmgrd", "status": "running" }, { "serviceName": "appliance-sync.timer", "status": "waiting" } ] #Response Example on a cell type vcd appliance node would be different: [ { "serviceName": "vmware-vcd", "status": "running" }, { "serviceName": "appliance-sync.timer", "status": "waiting" } ] /api/1.0.0/services/{service-name}: get: tags: - applianceService summary: Returns current operational state for the requested service running on this appliance. x-vcloud-added-in: 34.0 security: - BasicAuth: [] - BearerAuth: [] description: | Valid input values are:
      • vcd (alias of vmware-vcd)
      • vmware-vcd
      • vpostgres
      • repmgrd
      • appliance-sync.timer
      operationId: getServiceStatus produces: - "application/json" parameters: - name: "service-name" in: "path" description: Name of service whose details you want returned required: true type: "string" responses: 404: description: service-name value specified is not valid. 200: description: OK schema: $ref: '#/definitions/ApplianceService' examples: application/json: | { "serviceName": "vmware-vcd", "status": "running" } /api/1.0.0/nodes: get: tags: - nodes summary: Returns postgres HA state of all nodes from this appliance's point of view. x-vcloud-added-in: 34.0 security: - BasicAuth: [] - BearerAuth: [] operationId: getNodes produces: - "application/json" responses: 404: description: API not applicable for cell-type appliances 200: description: OK schema: $ref: '#/definitions/NodesStatus' examples: application/json: | { "localClusterFailover": "AUTOMATIC", "localClusterHealth": "HEALTHY", "localClusterState": [ { "connectionString": "host= user=repmgr dbname=repmgr connect_timeout=2", "failover": { "details": "failover = automatic", "mode": "AUTOMATIC", "repmgrd": { "details": "On node 6753 (): repmgrd = running", "status": "RUNNING" } }, "id": 6753, "location": "default", "name": "", "nodeHealth": "HEALTHY", "nodeRole": "STANDBY", "role": "standby", "status": "running", "upstream": "" }, { "connectionString": "host= user=repmgr dbname=repmgr connect_timeout=2", "failover": { "details": "failover = automatic", "mode": "AUTOMATIC", "repmgrd": { "details": "On node 13853 (): repmgrd = running", "status": "RUNNING" } }, "id": 13853, "location": "default", "name": "", "nodeHealth": "HEALTHY", "nodeRole": "PRIMARY", "role": "primary", "status": "* running", "upstream": "" }, { "connectionString": "host= user=repmgr dbname=repmgr connect_timeout=2", "failover": { "details": "failover = automatic", "mode": "AUTOMATIC", "repmgrd": { "details": "On node 25362 (): repmgrd = running", "status": "RUNNING" } }, "id": 25362, "location": "default", "name": "", "nodeHealth": "HEALTHY", "nodeRole": "STANDBY", "role": "standby", "status": "running", "upstream": "" } ], "warnings": [] } /api/1.0.0/task/{task-id}: get: tags: - taskStatus summary: Returns the status of the asynchronous task uniquely identified by the task-id in the request. x-vcloud-added-in: 34.0 x-vcloud-deprecated-in: 36.0 x-vcloud-deprecated-alternative: /api/1.0.0/tasks/{task-id} and associated queryTaskStatus operationId description: >- The response code corresponds to the task being successfully retrieved, and not to the asynchoronous operation itself. The status of the asynchronous operation can be viewed in the response body.

      Tasks are per cell and remain in memory till the respective appliance nodes is rebooted. This means that tasks that were triggered prior to reboot are lost upon reboot. security: - BasicAuth: [] - BearerAuth: [] operationId: getTaskStatus produces: - "application/json" parameters: - name: "task-id" in: "path" description: "ID of task to return" required: true type: "string" responses: 200: description: OK schema: $ref: '#/definitions/Task' examples: application/json: | #Example 1: Response body of a failover mode to change from manual to automatic { "id": "42c30dfd-d585-4758-9105-3f131a69b64a", "result": { "message": "Daemon operation completed successfully on all nodes.", "result": [ "Daemon operation completed successfully on node_id: 6753 ()", "Daemon operation completed successfully on node_id: 13853 ()", "Daemon operation completed successfully on node_id: 25362 ()" ] }, "startedAt": "2020-03-19T23:27:10-04:00", "status": "stopped", "stoppedAt": "2020-03-19T23:27:20-04:00", "url": "https://:5480/api/1.0.0/nodes/failover/automatic" } #Example 2: Response body of a switchover task { "id": "6298e6f6-5510-4118-bff7-bab5d06ec9cb", "result": { "message": "Switchover completed successfully", "result": [ "NOTICE: executing switchover on node '' (ID: 6753)", "NOTICE: promoting standby to primary", "DETAIL: promoting server '' (ID: 6753) using '/opt/vmware/vpostgres/current/bin/pg_ctl -w -D '/var/vmware/vpostgres/current/pgdata' promote'", "waiting for server to promote.... done", "server promoted", "NOTICE: waiting up to 30 seconds (parameter 'promote_check_timeout') for promotion to complete", "NOTICE: STANDBY PROMOTE successful", "DETAIL: server '' (ID: 6753) was successfully promoted to primary", "INFO: local node 13853 can attach to rejoin target node 6753", "DETAIL: local node's recovery point: 1/D9B2E448; rejoin target node's fork point: 1/D9B2E4B8", "NOTICE: setting node 13853's upstream to node 6753", "WARNING: unable to ping 'host= user=repmgr dbname=repmgr connect_timeout=2'", "DETAIL: PQping() returned 'PQPING_NO_RESPONSE'", "NOTICE: starting server using 'sudo /usr/bin/systemctl start vpostgres'", "NOTICE: NODE REJOIN successful", "DETAIL: node 13853 is now attached to node 6753", "NOTICE: executing STANDBY FOLLOW on 1 of 1 siblings", "INFO: STANDBY FOLLOW successfully executed on all reachable sibling nodes", "NOTICE: switchover was successful", "DETAIL: node '' is now primary and node '' is attached as standby", "NOTICE: STANDBY SWITCHOVER has completed successfully" ] }, "startedAt": "2020-03-19T23:30:09-04:00", "status": "stopped", "stoppedAt": "2020-03-19T23:30:47-04:00", "url": "https://:5480/api/1.0.0/nodes//switchover" } #Example 3: Response body of a promote task { "id": "350bdf5a-e422-4f58-bd65-042b34fb4503", "result": { "message": "The failover could not be executed.", "result": [ "ERROR: this replication cluster already has an active primary server", "DETAIL: current primary is '' (ID: 6753)" ] }, "startedAt": "2020-03-19T23:33:31-04:00", "status": "failed", "stoppedAt": "2020-03-19T23:33:46-04:00", "url": "https://:5480/api/1.0.0/nodes//promote" } 404: description: 404 NOT FOUND /api/1.0.0/tasks/{task-id}: get: tags: - taskStatus summary: Returns the status of the asynchronous task uniquely identified by the task-id in the request. x-vcloud-added-in: 36.0 description: >- The response code corresponds to the task being successfully retrieved, and not to the asynchoronous operation itself. The status of the asynchronous operation can be viewed in the response body.

      Tasks are per cell and remain in memory till the respective appliance nodes is rebooted. This means that tasks that were triggered prior to reboot are lost upon reboot. security: - BasicAuth: [] - BearerAuth: [] operationId: queryTaskStatus produces: - "application/json" parameters: - name: "task-id" in: "path" description: "ID of task to return" required: true type: "string" responses: 200: description: OK schema: $ref: '#/definitions/Task' examples: application/json: | #Example 1: Response body of a failover mode to change from manual to automatic { "id": "42c30dfd-d585-4758-9105-3f131a69b64a", "result": { "message": "Daemon operation completed successfully on all nodes.", "result": [ "Daemon operation completed successfully on node_id: 6753 ()", "Daemon operation completed successfully on node_id: 13853 ()", "Daemon operation completed successfully on node_id: 25362 ()" ] }, "startedAt": "2020-03-19T23:27:10-04:00", "status": "stopped", "stoppedAt": "2020-03-19T23:27:20-04:00", "url": "https://:5480/api/1.0.0/nodes/failover/automatic" } #Example 2: Response body of a switchover task { "id": "6298e6f6-5510-4118-bff7-bab5d06ec9cb", "result": { "message": "Switchover completed successfully", "result": [ "NOTICE: executing switchover on node '' (ID: 6753)", "NOTICE: promoting standby to primary", "DETAIL: promoting server '' (ID: 6753) using '/opt/vmware/vpostgres/current/bin/pg_ctl -w -D '/var/vmware/vpostgres/current/pgdata' promote'", "waiting for server to promote.... done", "server promoted", "NOTICE: waiting up to 30 seconds (parameter 'promote_check_timeout') for promotion to complete", "NOTICE: STANDBY PROMOTE successful", "DETAIL: server '' (ID: 6753) was successfully promoted to primary", "INFO: local node 13853 can attach to rejoin target node 6753", "DETAIL: local node's recovery point: 1/D9B2E448; rejoin target node's fork point: 1/D9B2E4B8", "NOTICE: setting node 13853's upstream to node 6753", "WARNING: unable to ping 'host= user=repmgr dbname=repmgr connect_timeout=2'", "DETAIL: PQping() returned 'PQPING_NO_RESPONSE'", "NOTICE: starting server using 'sudo /usr/bin/systemctl start vpostgres'", "NOTICE: NODE REJOIN successful", "DETAIL: node 13853 is now attached to node 6753", "NOTICE: executing STANDBY FOLLOW on 1 of 1 siblings", "INFO: STANDBY FOLLOW successfully executed on all reachable sibling nodes", "NOTICE: switchover was successful", "DETAIL: node '' is now primary and node '' is attached as standby", "NOTICE: STANDBY SWITCHOVER has completed successfully" ] }, "startedAt": "2020-03-19T23:30:09-04:00", "status": "stopped", "stoppedAt": "2020-03-19T23:30:47-04:00", "url": "https://:5480/api/1.0.0/nodes//switchover" } #Example 3: Response body of a promote task { "id": "350bdf5a-e422-4f58-bd65-042b34fb4503", "result": { "message": "The failover could not be executed.", "result": [ "ERROR: this replication cluster already has an active primary server", "DETAIL: current primary is '' (ID: 6753)" ] }, "startedAt": "2020-03-19T23:33:31-04:00", "status": "failed", "stoppedAt": "2020-03-19T23:33:46-04:00", "url": "https://:5480/api/1.0.0/nodes//promote" } 404: description: 404 NOT FOUND /api/1.0.0/tasks: get: tags: - taskList summary: Returns a list of statuses asynchronous tasks, possibly filtered, sorted, and/or paginated. x-vcloud-added-in: 36.0 description: >- The response code corresponds to the task list being successfully retrieved, and not to the asynchoronous operations themselves. The status of the asynchronous operation(s) can be viewed in the response body.

      Tasks are per cell and remain in memory till the respective appliance node is rebooted. This means that tasks that were triggered prior to reboot are lost upon reboot. security: - BasicAuth: [] - BearerAuth: [] operationId: queryTaskList produces: - "application/json" parameters: - name: "filter" in: "query" description: query filter. values may be "status==running", "status==failed", or "status==stopped" required: false type: "string" - name: "sortAsc" in: "query" description: sortAsc=field means to sort on field in ascending order. values may be "startedAt" or "stoppedAt" required: false type: "string" - name: "sortDesc" in: "query" description: sortDesc=field means to sort on field in descending order. values may be "startedAt" or "stoppedAt" type: "string" required: false - name: "page" in: "query" type: "integer" minimum: 1 default: 1 required: false description: The number of pages to skip before starting to collect the result set. page sequence starts at 1. - name: "pageSize" in: "query" type: "integer" minimum: 1 maximum: 100 default: 20 required: false description: The number of items that may be returned in a page. responses: 200: description: OK schema: $ref: '#/definitions/TaskList' examples: application/json: | { "pageCount": 1, "pageSize": 3, "resultTotal": 3, "listOfTasks": [ { "id": "42c30dfd-d585-4758-9105-3f131a69b64a", "result": { "message": "Daemon operation completed successfully on all nodes.", "result": [ "Daemon operation completed successfully on node_id: 6753 ()", "Daemon operation completed successfully on node_id: 13853 ()", "Daemon operation completed successfully on node_id: 25362 ()" ] }, "startedAt": "2020-03-19T23:27:10-04:00", "status": "stopped", "stoppedAt": "2020-03-19T23:27:20-04:00", "url": "https://:5480/api/1.0.0/nodes/failover/automatic" }, { "id": "6298e6f6-5510-4118-bff7-bab5d06ec9cb", "result": { "message": "Switchover completed successfully", "result": [ "NOTICE: executing switchover on node '' (ID: 6753)", "NOTICE: promoting standby to primary", "DETAIL: promoting server '' (ID: 6753) using '/opt/vmware/vpostgres/current/bin/pg_ctl -w -D '/var/vmware/vpostgres/current/pgdata' promote'", "waiting for server to promote.... done", "server promoted", "NOTICE: waiting up to 30 seconds (parameter 'promote_check_timeout') for promotion to complete", "NOTICE: STANDBY PROMOTE successful", "DETAIL: server '' (ID: 6753) was successfully promoted to primary", "INFO: local node 13853 can attach to rejoin target node 6753", "DETAIL: local node's recovery point: 1/D9B2E448; rejoin target node's fork point: 1/D9B2E4B8", "NOTICE: setting node 13853's upstream to node 6753", "WARNING: unable to ping 'host= user=repmgr dbname=repmgr connect_timeout=2'", "DETAIL: PQping() returned 'PQPING_NO_RESPONSE'", "NOTICE: starting server using 'sudo /usr/bin/systemctl start vpostgres'", "NOTICE: NODE REJOIN successful", "DETAIL: node 13853 is now attached to node 6753", "NOTICE: executing STANDBY FOLLOW on 1 of 1 siblings", "INFO: STANDBY FOLLOW successfully executed on all reachable sibling nodes", "NOTICE: switchover was successful", "DETAIL: node '' is now primary and node '' is attached as standby", "NOTICE: STANDBY SWITCHOVER has completed successfully" ] }, "startedAt": "2020-03-19T23:30:09-04:00", "status": "stopped", "stoppedAt": "2020-03-19T23:30:47-04:00", "url": "https://:5480/api/1.0.0/nodes//switchover" }, { "id": "350bdf5a-e422-4f58-bd65-042b34fb4503", "result": { "message": "The failover could not be executed.", "result": [ "ERROR: this replication cluster already has an active primary server", "DETAIL: current primary is '' (ID: 6753)" ] }, "startedAt": "2020-03-19T23:33:31-04:00", "status": "failed", "stoppedAt": "2020-03-19T23:33:46-04:00", "url": "https://:5480/api/1.0.0/nodes//promote" } ] 400: description: 400 BAD REQUEST 404: description: 404 NOT FOUND /api/1.0.0/nodes/{node-name}/promote: post: tags: - promote summary: Returns the task-id URL for the requested promote action. x-vcloud-added-in: 34.0 security: - BasicAuth: [] - BearerAuth: [] description: | The entire URL for the task is returned in the Location header of the response.
      • Note: The promote action requires that no healthy primary currently exists in the HA cluster.
      Refer to taskStatus API's Response Example tab for an example of promote task operationId: postPromote produces: - "application/json" parameters: - name: "node-name" in: "path" description: "name of the node which is being promoted" required: true type: "string" responses: 202: description: | Response Body is empty. Response includes Location header with URL to related task-id. Note: cell-type appliance nodes will give this response, but the spawned task will always fail on these nodes. headers: Location: type: "string" description: "Task URL. Example: https://:5480/api/1.0.0/tasks/" /api/1.0.0/nodes/{node-name}/switchover: post: tags: - switchover summary: Returns the task-id URL for the requested switchover action. x-vcloud-added-in: 34.0 security: - BasicAuth: [] - BearerAuth: [] description: | The entire URL for the task is returned in the Location header of the response.
      • Note: The switchover action requires all nodes in the HA cluster to be healthy. Switchover causes the VMware Cloud Director database to be unavailable for 30–60 seconds. To avoid unexpected task failures, quiesce the activity on all cells in the cluster before the switchover.
      Refer to taskStatus API's Response Example tab for an example of switchover task operationId: postSwitchover produces: - "application/json" parameters: - name: "node-name" in: "path" description: "name of the node which is being switched from standby to primary role" required: true type: "string" responses: 202: description: | Response Body is empty. Response includes Location header with URL to related task-id. Note: cell-type appliance nodes will give this response, but the spawned task will always fail on these nodes. headers: Location: type: "string" description: "Task URL. Example: https://:5480/api/1.0.0/tasks/" /api/1.0.0/nodes/failover/{desired-mode}: post: tags: - failover-mode summary: Returns the task-id URL for the requested failover-mode change action. x-vcloud-added-in: 34.0 security: - BasicAuth: [] - BearerAuth: [] description: | Valid values are:
      • automatic
      • manual
      The entire URL for the task is returned in the Location header of the response.
      Refer to taskStatus API's Response Example tab for an example of failover mode task operationId: postSetFailoverMode produces: - "application/json" parameters: - name: "desired-mode" in: "path" description: Name of the desired failover mode. required: true type: "string" responses: 404: description: API not applicable for cell-type appliances 202: description: Response Body is empty. Response includes Location header with URL to related task-id. headers: Location: type: "string" description: "Task URL. Example: https://:5480/api/1.0.0/tasks/" /api/1.0.0/nodes/{node-name}: delete: tags: - unregister summary: Returns the task-id URL for the requested unregister action. x-vcloud-added-in: 35.0 security: - BasicAuth: [] - BearerAuth: [] description: | The entire URL for the task is returned in the Location header of the response.
      • Note: A node must be inactive in order for it to be unregistered.
      Refer to taskStatus API's Response Example tab for an example of an unregister task operationId: deleteUnregister produces: - "application/json" parameters: - name: "node-name" in: "path" description: "name of the node which is being unregistered" required: true type: "string" responses: 404: description: API not applicable for cell-type appliances 202: description: Response Body is empty. Response includes Location header with URL to related task-id. headers: Location: type: "string" description: "Task URL. Example: https://:5480/api/1.0.0/tasks/" /api/1.0.0/fips: get: tags: - fipsStatusList summary: Returns the FIPS mode of all appliances and Cloud Director cells x-vcloud-added-in: 35.2 security: - BasicAuth: [] - BearerAuth: [] operationId: getFipsStatusList produces: - "application/json" responses: 200: description: OK schema: $ref: '#/definitions/FipsStatusList' examples: application/json: | #Response Example from a three node appliance deployment where the Cloud Director server group FIPS mode is "ON" (but its status is "UPDATING") and the first appliance has had its FIPS mode activated: #In this environment, the second and third appliances are awaiting have their appliance FIPS mode activated. [ { "name": "example-appliance-a", "ip": "10.0.0.1", "applianceFips": "ON", "cellFips": "ON" }, { "name": "example-appliance-b", "ip": "10.0.0.2", "applianceFips": "OFF", "cellFips": "ON_PENDING_RESTART" }, { "name": "example-appliance-c", "ip": "10.0.0.3", "applianceFips": "OFF", "cellFips": "ON_PENDING_RESTART" } ] /api/1.0.0/fips/{node-name}: get: tags: - fipsStatus summary: Returns the FIPS mode of a single appliance and its Cloud Director cell x-vcloud-added-in: 35.2 security: - BasicAuth: [] - BearerAuth: [] operationId: getFipsStatus produces: - "application/json" parameters: - name: "node-name" in: "path" description: "Node name of the machine to retreive the FIPS of." required: true type: "string" responses: 200: description: OK schema: $ref: '#/definitions/FipsStatus' put: tags: - fipsToggle summary: Activate or deactivate the appliance's FIPS mode. x-vcloud-added-in: 35.2 security: - BasicAuth: [] - BearerAuth: [] description: | This will activate or deactivate only the appliance's FIPS mode and will not activate or deactivate the Cloud Director server group's FIPS mode. To activate an appliance's FIPS mode, the Cloud Director server's FIPS mode must be "On Pending Restart" or "On". To deactivate an appliance's FIPS mode, the Cloud Director server's FIPS mode must be "Off Pending Restart" or "Off". operationId: fipsToggle consumes: - "application/json" produces: - "application/json" parameters: - name: "node-name" in: "path" description: "Node name of the machine to update the appliance FIPS mode. This must be the appliance which is processing the request." required: true type: "string" - in: body name: fips required: true schema: $ref: '#/definitions/FipsStatus' responses: 202: description: | Response Body is empty. Response includes Location header with URL to related task-id. headers: Location: type: "string" description: "Task URL. Example: https://:5480/api/1.0.0/tasks/" /api/1.0.0/backups: get: tags: - Backup summary: Returns the list of backup bundles available in /opt/vmware/vcloud-director/data/transfer/backups/ x-vcloud-added-in: 36.1 security: - BasicAuth: [] - BearerAuth: [] operationId: queryBackupList produces: - "application/json" parameters: - name: "filter" in: "query" description: query filter. values may be "date=ge=some-date", "date=gt=some-date", "date=le=some-date", "date=lt=some-date" or "version==full-appliance-version" required: false type: "string" - name: "sortAsc" in: "query" description: sortAsc=field means to sort on field in ascending order. Only supported value is "date" required: false type: "string" - name: "sortDesc" in: "query" description: sortDesc=field means to sort on field in descending order. Only supported value is "date" type: "string" required: false - name: "page" in: "query" type: "integer" minimum: 1 default: 1 required: false description: The number of pages to skip before starting to collect the result set. page sequence starts at 1. - name: "pageSize" in: "query" type: "integer" minimum: 1 maximum: 100 default: 20 required: false description: The number of items that may be returned in a page. responses: 200: description: OK schema: $ref: '#/definitions/BackupList' examples: application/json: | #Response Example { "listOfBackupFiles": [ { "date": "2021-09-02T15:25:22+00:00", "location": "/opt/vmware/vcloud-director/data/transfer/backups/backup-2021-09-02T152522+0000.zip", "name": "backup-2021-09-02T152522+0000.zip", "size": 5059424, "version": "10.3.1.10225 Build 49704518" }, { "date": "2021-08-23T14:55:01+00:00", "location": "/opt/vmware/vcloud-director/data/transfer/backups/backup-2021-08-23T145501+0000.zip", "name": "backup-2021-08-23T145501+0000.zip", "size": 5979875, "version": "10.3.1.6526 Build 18441687" } ], "pageCount": 1, "pageSize": 2, "resultTotal": 2 } post: tags: - Backup summary: create backup of cloud director appliance primary DB, and other important files x-vcloud-added-in: 36.1 security: - BasicAuth: [] - BearerAuth: [] description: | This will create a backup of the postgresql DB of the appliance, as well as other vcd specific certificate files needed during restore process. This api endpoint should only be executed on the current postgresql HA primary appliance. The task will fail on Standby and Application-Cell appliances. operationId: createBackup produces: - "application/json" responses: 202: description: | Response Body is empty. Response includes Location header with URL to related task-id. headers: Location: type: "string" description: "Task URL. Example: https://:5480/api/1.0.0/tasks/" /api/1.0.0/backups/{backup-name}: get: tags: - Backup summary: Returns the backup file details for the specified backup instance x-vcloud-added-in: 36.1 security: - BasicAuth: [] - BearerAuth: [] operationId: getBackupInfo produces: - "application/json" parameters: - name: "backup-name" in: "path" description: "Name of backup file name from which to retreive the additional details. For example: backup-2021-07-13T215410+0000.zip" required: true type: "string" responses: 404: description: backup-name value specified is not valid. Does not exist on transfer share. 200: description: OK schema: $ref: '#/definitions/Backup' examples: application/json: | #Response Example { "date": "2021-09-02T15:25:22+00:00", "location": "/opt/vmware/vcloud-director/data/transfer/backups/backup-2021-09-02T152522+0000.zip", "name": "backup-2021-09-02T152522+0000.zip", "size": 5059424, "version": "10.3.1.10225 Build 49704518" } delete: tags: - Backup summary: Delete the specified backup file x-vcloud-added-in: 36.2 security: - BasicAuth: [] - BearerAuth: [] description: | This will delete the backup file package specified, from the backups directory in the transfer share. operationId: deleteBackup produces: - "application/json" parameters: - name: "backup-name" in: "path" description: "File name of the backup package to be deleted from the transfer share. For example: backup-2021-07-13T215410+0000.zip" required: true type: "string" responses: 202: description: | Response Body is empty. Response includes Location header with URL to related task-id. headers: Location: type: "string" description: "Task URL. Example: https://:5480/api/1.0.0/tasks/" /api/1.0.0/backups/{backup-name}/restore: post: tags: - Backup summary: restore backup of cloud director appliance primary DB, and other important files x-vcloud-added-in: 36.1 security: - BasicAuth: [] - BearerAuth: [] description: | This will restore the specified backup of the postgresql DB of the appliance, as well as other vcd specific files. This api endpoint should only be executed on the current postgresql HA primary appliance. The task will fail on Standby and Application-Cell appliances. operationId: restorePrimaryBackup consumes: - application/json parameters: - in: path name: backup-name required: true description: "File name of the backup package to be restored from the transfer share. For example: backup-2021-07-13T215410+0000.zip" type: string - in: body name: nfs required: true schema: $ref: '#/definitions/NfsMountInfo' produces: - application/json responses: 202: description: | Response Body is empty. Response includes Location header with URL to related task-id. headers: Location: type: "string" description: "Task URL. Example: https://:5480/api/1.0.0/tasks/" definitions: ApplianceSystemSetup: x-vcloud-added-in: 35.0 description: Spec for the appliance for systemSetup. type: object discriminator: applianceType properties: applianceType: type: string description: type of appliance (primary, standby, cell) storage: $ref: '#/definitions/NfsMountInfo' description: nfs mount info for transfer file location required: - applianceType - storage example: applianceType: primary storage: nfs: 192.168.100.1:/data/transfer appliance: dbPassword: vcloud ceip: true sysAdmin: username: administrator password: secret-password fullName: cloud administrator email: my-email@my-company.com installation: name: vcd5 id: 5 standby: x-vcloud-added-in: 35.0 description: Spec for the Standby appliance for systemSetup. allOf: - $ref: '#/definitions/ApplianceSystemSetup' cell: x-vcloud-added-in: 35.0 description: Spec for the Cell appliance for systemSetup. allOf: - $ref: '#/definitions/ApplianceSystemSetup' primary: x-vcloud-added-in: 35.0 description: Spec for the Primary appliance for systemSetup. allOf: - $ref: '#/definitions/ApplianceSystemSetup' - type: object properties: appliance: $ref: '#/definitions/ApplianceSpec' description: appliance spec. sysAdmin: $ref: '#/definitions/SysAdminSpec' description: sysAdmin spec. installation: $ref: '#/definitions/InstallationSpec' description: installation spec ApplianceSpec: x-vcloud-added-in: 35.0 description: Spec for the appliance. Only required for primary appliance configuration. type: object properties: dbPassword: type: string description: DB password for the 'vcloud' user x-vcloud-password: true ceip: type: boolean description: participant in the Customer Experience Improvement Program (true or false) required: - dbPassword - ceip SysAdminSpec: x-vcloud-added-in: 35.0 description: Spec for the sysadmin. Only required for primary appliance configuration. type: object properties: username: type: string description: user name of the system administrator password: type: string description: password for the system administrator account x-vcloud-password: true fullName: type: string description: full name of the system administrator email: type: string description: email address of the system administrator x-vcloud-constraints: - constraint: Email required: - username - password - fullName - email InstallationSpec: x-vcloud-added-in: 35.0 description: Spec for the installation. Only required for primary appliance configuration. type: object properties: name: type: string description: name of installation id: type: integer format: int32 description: id of installation, in the range of 1 to 63 required: - name - id NfsMountInfo: x-vcloud-added-in: 35.0 description: Spec for the nfs configuration used by this appliance. Valid for all appliance types. type: object properties: nfs: type: string description: NFS mount for transfer file location required: - nfs example: nfs: 192.168.100.1:/data/transfer Session: x-vcloud-added-in: 35.0 type: object properties: authToken: type: string description: | Bearer token value. expires: format: date-time type: string description: | Expiration time of the token. ApplianceServices: x-vcloud-added-in: 34.0 description: Current state of the services we expose via api, running in the appliance. Currently support vmware-vcd and vpostgres services. type: array items: $ref: '#/definitions/ApplianceService' ApplianceService: x-vcloud-added-in: 34.0 description: Current state of the service running in the appliance. type: object properties: serviceName: type: string description: | Name of service.
      Currently supported services are:
      • vcd alias vmware-vcd
      • vpostgres
      • repmgrd
      status: type: string description: | Status of service. Valid responses include:
      • start
      • running
      • dead
      • dead (normal when appliance is in manual failover mode)
      IsPrimary: x-vcloud-added-in: 34.0 description: Boolean check if appliance is the existing Database HA primary. type: object properties: isPrimary: type: boolean description: | Is this appliance hosting the primary HA database. A valid response is:
      • true
      • false
      Version: x-vcloud-added-in: 35.0 description: Appliance version information. type: object properties: appliance: type: string description: | Appliance version retrieved via vamicli --version appliance. A valid response sample is:
      • "10.2.0.6000 Build 17000001"
      NodesStatus: x-vcloud-added-in: 34.0 description: A complete list of HA status from the perspective of this appliance. type: object properties: localClusterFailover: type: string description: | HA Cluster failover status from the perspective of this appliance. Valid states are:
      • MANUAL - all nodes have failover value set to manual in repmgrd config file and repmgrd service is not running
      • AUTOMATIC - all nodes have failover value set to automatic in repmgrd config file and repmgrd service is running
      • INDETERMINATE - all nodes have inconsisent state of failover set to either manual or automatic and repmgrd service is either running or not running
      localClusterHealth: type: string description: | HA Cluster status from the perspective of this appliance. Valid states are:
      • HEALTHY - all nodes online and no warnings or conflicts
      • DEGRADED - One standby node is offline, such that only one remaining standby node is still healthy. It is recommended that a minimum of two healthy standby nodes are maintained at all times.
      • READ_ONLY_PRIMARY - The primary is in read-only mode. This happens when there is not at least one active standby that is connected to the primary.
      • NO_ACTIVE_PRIMARY - There is no active primary running. In this case, an available standby should be promoted as a new primary.
      • CRITICAL_PROBLEM - Either two primaries are showing up in repmgr inventory, or a standby is following an "old" primary (not the current primary)
      • SSH_PROBLEM - An ssh problem exists between two or more nodes. This can happen when the trust has been lost between these nodes.
      localClusterState: type: array description: The current list of nodes and their status. items: $ref: '#/definitions/NodeHaStatus' warnings: type: array items: type: "string" NodeHaStatus: x-vcloud-added-in: 34.0 type: object properties: connectionString: type: string description: Set during the initial repmgr configuration. It defines how other repmgr nodes can communicate with this node. location: type: string description: Location of node. This parameter is currently always default. name: type: string description: Short name of appliance, via reverse lookup of the eth0 ip address of the appliance. nodeHealth: type: string description: | Interpreted state of the health of the node, based upon analysis of state information of all nodes in the HA cluster.
      Valid values are:
      • HEALTHY - node is functioning normally
      • UNHEALTHY - node is not functioning normally
      • INACCURATE_DATA - this data is stale and may be inaccurate
      • UNRECOVERABLE - a standby node has fallen too far behind in the replication stream
      nodeRole: type: string description: | Interpreted state of the role of the node, based upon analysis of state information of all nodes in the HA cluster.
      Valid values are:
      • PRIMARY
      • STANDBY
      • OLD_PRIMARY
      • UNKNOWN
      failover: $ref: '#/definitions/FailoverState' description: Current failover state, including mode, details and repmgrd status, details. id: type: integer format: int32 description: Unique ID assigned by repmgr to each node in HA cluster, as reported by repmgr cluster show. role: type: string description: | Current role of node, as reported by the "repmgr cluster show" command. status: type: string description: | Current status of node, as reported by the "repmgr cluster show" command.
      Valid values are:
      • running : node is running as the standby
      • * running : node is running as the primary
      • ! running : node has an unexpected role
      • ? running : node is pingable but not accepting connections
      • ? unreachable : connection to the node cannot be made
      • ! running as primary : node is running as the new primary
      • ! running as standby : node is running as the new standby
      upstream: type: string description: | Value of current primary being followed.
      • Populated when this is a standby node. Empty if this is a a primary node.
      Task: x-vcloud-added-in: 34.0 type: object properties: id: type: string description: 36 character UUID generated for each task. result: $ref: '#/definitions/TaskResult' description: Nested information, including message, and additional details in nested result section. startedAt: type: string description: date-time with timezone in ISO-8601 format. For example, 2021-06-08T18:27:30-04:00. status: type: string description: | Status of requested action. The values are:
      • running
      • failed
      • stopped
      stoppedAt: type: string description: date-time with timezone in ISO-8601 format. null while task is still in progress. Once completed, same format as startedAt field. url: type: string description: | URL of request, which includes action. TaskList: x-vcloud-added-in: 36.0 type: object properties: resultTotal: type: integer format: int32 description: How many results there are in total (i.e., considering all pages). pageCount: type: integer format: int32 description: How many pages there are in total. pageSize: type: integer format: int32 description: Result count for page that was fetched. listOfTasks: type: array description: List of Task objects. items: $ref: '#/definitions/Task' TaskResult: x-vcloud-added-in: 34.0 type: object properties: message: type: string description: Short statement of success of failover with name of attempted action. result: type: array description: List of detailed log statements gathered during execution of action, which could be used for debugging. items: type: string FileSystems: x-vcloud-added-in: 34.0 description: A complete list of file systems that are mounted in this appliance. type: object additionalProperties: $ref: '#/definitions/FileSystem' FileSystem: x-vcloud-added-in: 34.0 description: Information on requested file system. type: object properties: availableMB: type: integer format: int32 filesystem: type: string mountedOn: type: string percentUsed: type: integer format: int32 status: type: string description: Value of either available or unavailable. If unavailable, then other properties will have values of None. usedMB: type: integer format: int32 volumeSizeMB: type: integer format: int32 FailoverState: x-vcloud-added-in: 34.0 description: Information on failover setting for this HA cluster type: object properties: mode: type: string description: | The current failover mode. The valid values are:
      • MANUAL
      • AUTOMATIC
      • UNKNOWN
      details: type: string description: Additional info on the failover mode that would be useful in triaging error cases. repmgrd: $ref: '#/definitions/RepmgrdState' description: repmgrd status and details. RepmgrdState: x-vcloud-added-in: 34.0 type: object properties: status: type: string description: | Status of repmgrd service. Valid states are:
      • RUNNING
      • NOT RUNNING
      • NOT APPLICABLE
      • UNKNOWN
      Note: NOT APPLICABLE status is displayed when failover mode is MANUAL details: type: string description: Additional info on the repmgrd state that would be useful in triaging error cases. FipsStatusList: x-vcloud-added-in: 35.2 description: Status of FIPS modes for each appliance. type: array items: $ref: '#/definitions/FipsStatus' FipsStatus: x-vcloud-added-in: 35.2 type: object properties: name: type: string description: Node name of the appliance. x-vcloud-constraints: - constraint: ReadOnly ip: type: string description: eth0 IP of the appliance. x-vcloud-constraints: - constraint: ReadOnly applianceFips: type: string description: | FIPS mode of the appliance's operating system. Possible values are:
      • ON
      • OFF
      cellFips: type: string description: | FIPS mode of the appliance's Cloud Director server. Possible values are:
      • ON
      • ON_PENDING_RESTART
      • OFF
      • OFF_PENDING_RESTART
      • UNKNOWN
      x-vcloud-constraints: - constraint: ReadOnly BackupList: x-vcloud-added-in: 36.0 description: List of appliance backup packages available on transfer share. type: object properties: resultTotal: type: integer format: int32 description: How many results there are in total (i.e., considering all pages). pageCount: type: integer format: int32 description: How many pages there are in total. pageSize: type: integer format: int32 description: Result count for page that was fetched. listOfBackupFiles: type: array description: List of Backup objects. items: $ref: '#/definitions/Backup' Backup: x-vcloud-added-in: 36.0 type: object properties: name: type: string description: Name of the appliance backup file. x-vcloud-constraints: - constraint: ReadOnly location: type: string description: absolute path to appliance backup file. x-vcloud-constraints: - constraint: ReadOnly size: type: integer format: int64 description: Size of appliance backup file in bytes. x-vcloud-constraints: - constraint: ReadOnly date: type: string description: Creation date of the appliance backup file. x-vcloud-constraints: - constraint: ReadOnly version: x-vcloud-added-in: 36.1 type: string description: Full appliance build version. x-vcloud-constraints: - constraint: ReadOnly