# ******************************************************************************
# * Copyright 2019-2020 VMware, Inc.  All rights reserved. VMware Confidential *
# ******************************************************************************
swagger: "2.0"
info:
  version: "1.0"
  title: Cloud Director Appliance API
  # When editing this description, be careful about how it renders in the docs
  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.<br/>
    <b>Note:</b> This API only returns JSON formatted data.<br/>
    <h4>Authentication</h4>
    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 <a href=#api-Sessions>below</a>.  For Basic auth, the "root" user must be used for authentication. No other headers are required.
    <h4>Asynchronous operations</h4>
    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 <code>Location</code> header.<br/>
    The caller must be prepared to handle responses to API calls by inspecting the HTTP Response code.<br/>
    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.<br/>
    <h4>Error Conditions</h4>
    <b>All</b> operations report errors using the following vCD error reporting rules:
    <ul>
      <li>401: Bad Request - If user is unauthenticated or their session has expired</li>
      <li>403: Forbidden - If the user is not authorized or the entity does not exist</li>
      <li>404: Not Found - In event of incorrect request due to incorrect data or other user error</li>
    </ul>
    <h4>OpenAPI Design Concepts and Principles</h4>
    <ul>
        <li>vCloud OpenAPI's <code>Content-Type</code> is always <code>application/json</code></li>
        <li>Each feature has a version in the path element present in its URL.<br/>
            <b>Note:</b> API URL's without a version in their paths must be considered experimental, and, as such, may change in backwards incompatible ways.<br/>
            The following two APIs are currently experimental: <b>systemSetup</b> and <b>nfsValidate</b>. </li>
        <li>Example of a valid API URL: https://192.0.2.10:5480/api/1.0.0/sessions
    </ul>

    <h4>SystemSetup API Request Body - Samples</h4>
    <ul>
        <li>The SystemSetup API requires a unique request body that must match the appliance's deployment type.</li>
        <li>The examples are provided here, and not with this specific api's definition <a href=#api-SystemSetup>below</a>, due to a limitation in OpenApi 2.0 for support of discriminators.</li>
    </ul>
    <ul class="nav nav-tabs nav-tabs-examples" >
        <li class="active">
            <a data-toggle="tab" href="#primary">Primary</a>
        </li>
        <li class="">
            <a data-toggle="tab" href="#standby">Standby</a>
        </li>
        <li class="">
            <a data-toggle="tab" href="#cell">Cell</a>
        </li>
    </ul>
    <div class="tab-content">
    <div id="primary" class="tab-pane fade in active">
    <pre class="prettyprint"><code class="json">
    {
        "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
        }
    }
    </code></pre>
    </div>
    <div id="standby" class="tab-pane fade">
    <pre class="prettyprint"><code class="json">
    {
        "applianceType": "standby",
        "storage": {
            "nfs": "192.168.100.1:/data/transfer"
        }
    }
    </code></pre>
    </div>
    <div id="cell" class="tab-pane fade">
    <pre class="prettyprint"><code class="json">
    {
        "applianceType": "cell",
        "storage": {
            "nfs": "192.168.100.1:/data/transfer"
        }
    }
    </code></pre>
    </div>
    </div>

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/systemSetup:
    post:
      tags:
        - systemSetup
      summary: Setup appliance nodes.
      x-vcloud-added-in: 35.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://<vcd-appliance-ip>:5480/api/1.0.0/task/<task-id>"


  /api/nfsValidate:
    post:
      tags:
        - nfsValidate
      summary: Validates nfs parameters and mount point. Performs mount and runs diagnostic checks.
      x-vcloud-added-in: 35.0
      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://<vcd-appliance-ip>:5480/api/1.0.0/task/<task-id>"


  /api/1.0.0/sessions:
    post:
      tags:
        - sessions
      summary: Returns Bearer Token.
      description: |
        <ul>
          <li> Token is valid for a minimum of 30 minutes.
          <li> Once token is issued or used, a 30 minute timer is started. If not used within that period it will expire.
          <li> Token is valid for a maximum of 24 hours, after which it expires.
        </ul>

      x-vcloud-added-in: 35.0
      security:
        - BasicAuth: []
        - BearerAuth: []

      operationId: postSessions
      produces:
        - "application/json"
      responses:
        500:
          description: Internal Server Error
        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/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:
        <ul>
          <li> true
          <li> false
        </ul>

      operationId: getIsPrimary
      produces:
        - "application/json"
      responses:
        500:
          description: Internal Server Error
        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.
        <ul>
          <li> local root file system
          <li> local database disk file system
          <li> nfs share file system
        </ul>

      operationId: getStorage
      produces:
        - "application/json"
      responses:
        500:
          description: Internal Server Error
        200:
          description: OK
          schema:
            $ref: '#/definitions/FileSystems'
          examples:
            application/json: |
                {
                    "nfs": {
                        "availableMB": 244719,
                        "filesystem": "<nfs-server-ip>:/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:
        <ul>
          <li> root
          <li> postgres
          <li> nfs
        <ul>
      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:
        500:
          description: Internal Server Error
        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:
        500:
          description: Internal Server Error
        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:
        <ul>
          <li> vcd alias vmware-vcd
          <li> vpostgres
          <li> repmgrd
        </ul>
      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:
        500:
          description: Internal Server Error
        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:
        500:
          description: Internal Server Error
        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=<node2-eth1-ip> user=repmgr dbname=repmgr connect_timeout=2",
                      "failover": {
                        "details": "failover = automatic",
                        "mode": "AUTOMATIC",
                        "repmgrd": {
                          "details": "On node 6753 (<node2-short-dnsname>): repmgrd = running",
                          "status": "RUNNING"
                        }
                      },
                      "id": 6753,
                      "location": "default",
                      "name": "<node2-short-dnsname>",
                      "nodeHealth": "HEALTHY",
                      "nodeRole": "STANDBY",
                      "role": "standby",
                      "status": "running",
                      "upstream": "<node3-short-dnsname>"
                    },
                    {
                      "connectionString": "host=<node2-eth1-ip> user=repmgr dbname=repmgr connect_timeout=2",
                      "failover": {
                        "details": "failover = automatic",
                        "mode": "AUTOMATIC",
                        "repmgrd": {
                          "details": "On node 13853 (<node3-short-dnsname>): repmgrd = running",
                          "status": "RUNNING"
                        }
                      },
                      "id": 13853,
                      "location": "default",
                      "name": "<node3-short-dnsname>",
                      "nodeHealth": "HEALTHY",
                      "nodeRole": "PRIMARY",
                      "role": "primary",
                      "status": "* running",
                      "upstream": ""
                    },
                    {
                      "connectionString": "host=<node1-eth1-ip> user=repmgr dbname=repmgr connect_timeout=2",
                      "failover": {
                        "details": "failover = automatic",
                        "mode": "AUTOMATIC",
                        "repmgrd": {
                          "details": "On node 25362 (<node1-short-dnsname>): repmgrd = running",
                          "status": "RUNNING"
                        }
                      },
                      "id": 25362,
                      "location": "default",
                      "name": "<node1-short-dnsname>",
                      "nodeHealth": "HEALTHY",
                      "nodeRole": "STANDBY",
                      "role": "standby",
                      "status": "running",
                      "upstream": "<node3-short-dnsname>"
                    }
                  ],
                  "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
      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.<br><br>
        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:
        500:
          description: Internal Server Error
        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 (<node2-short-dnsname>)",
                      "Daemon operation completed successfully on node_id: 13853 (<node3-short-dnsname>)",
                      "Daemon operation completed successfully on node_id: 25362 (<node1-short-dnsname>)"
                    ]
                  },
                "startedAt": "2020-03-19 23:27:10.443742 UTC",
                "status": "stopped",
                "stoppedAt": "2020-03-19 23:27:20.013664 UTC",
                "url": "https://<node1-eth0-ip>: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 '<node2-short-dnsname>' (ID: 6753)",
                    "NOTICE: promoting standby to primary",
                    "DETAIL: promoting server '<node2-short-dnsname>' (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 '<node2-short-dnsname>' (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=<node3-eth1-ip> 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 '<node2-short-dnsname>' is now primary and node '<node3-short-dnsname>' is attached as standby",
                    "NOTICE: STANDBY SWITCHOVER has completed successfully"
                    ]
                },
                "startedAt": "2020-03-19 23:30:09.768163 UTC",
                "status": "stopped",
                "stoppedAt": "2020-03-19 23:30:47.870462 UTC",
                "url": "https://<node1-eth0-ip>:5480/api/1.0.0/nodes/bos1-vcd-sp-static-211-2/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 '<node2-short-dnsname>' (ID: 6753)"
                    ]
                },
                "startedAt": "2020-03-19 23:33:31.852721 UTC",
                "status": "failed",
                "stoppedAt": "2020-03-19 23:33:46.015644 UTC",
                "url": "https://<node1-eth0-ip>:5480/api/1.0.0/nodes/<node3-short-dnsname>/promote"
              }

        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.
        <ul>
          <li> Note: The promote action requires that no healthy primary currently exists in the HA cluster.
        </ul>
        Refer to <a href="#api-TaskStatus-getTaskStatus">taskStatus</a> 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:
        500:
          description: Internal Server Error
        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://<vcd-appliance-ip>:5480/api/1.0.0/task/<task-id>"


  /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.
        <ul>
          <li> 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.
        </ul>
        Refer to <a href="#api-TaskStatus-getTaskStatus">taskStatus</a> 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:
        500:
          description: Internal Server Error
        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://<vcd-appliance-ip>:5480/api/1.0.0/task/<task-id>"


  /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:
            <ul>
                <li> automatic
                <li> manual
            </ul>
        The entire URL for the task is returned in the Location header of the response.<br>
        Refer to <a href="#api-TaskStatus-getTaskStatus">taskStatus</a> 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:
        500:
          description: Internal Server Error
        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://<vcd-appliance-ip>:5480/api/1.0.0/task/<task-id>"


  /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.
        <ul>
          <li> Note: A node must be inactive in order for it to be unregistered.
        </ul>
        Refer to <a href="#api-TaskStatus-getTaskStatus">taskStatus</a> 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:
        500:
          description: Internal Server Error
        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://<vcd-appliance-ip>:5480/api/1.0.0/task/<task-id>"

  /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://<vcd-appliance-ip>:5480/api/1.0.0/task/<task-id>"


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.
                <br>Currently supported services are:
                <ul>
                    <li> vcd alias vmware-vcd
                    <li> vpostgres
                    <li> repmgrd
                </ul>
        status:
            type: string
            description: |
                Status of service.
                Valid responses include:
                <ul>
                    <li> start
                    <li> running
                    <li> dead
                    <li> dead (normal when appliance is in manual failover mode)
                </ul>

  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:
              <ul>
                <li> true
                <li> false
              </ul>

  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:
              <ul>
                <li> "10.2.0.6000 Build 17000001"
              </ul>

  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:
              <ul>
                <li> MANUAL - all nodes have failover value set to manual in repmgrd config file and repmgrd service is not running
                <li> AUTOMATIC - all nodes have failover value set to automatic in repmgrd config file and repmgrd service is running
                <li> INDETERMINATE - all nodes have inconsisent state of failover set to either manual or automatic and repmgrd service is either running or not running
              </ul>

        localClusterHealth:
            type: string
            description: |
              HA Cluster status from the perspective of this appliance.
              Valid states are:
              <ul>
                <li> HEALTHY - all nodes online and no warnings or conflicts
                <li> 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.
                <li> 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.
                <li> NO_ACTIVE_PRIMARY - There is no active primary running. In this case, an available standby should be promoted as a new primary.
                <li> CRITICAL_PROBLEM - Either two primaries are showing up in repmgr inventory, or a standby is following an "old" primary (not the current primary)
                <li> SSH_PROBLEM - An ssh problem exists between two or more nodes. This can happen when the trust has been lost between these nodes.
              </ul>

        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.<br>
                Valid values are:
                <ul>
                    <li> HEALTHY
                    <li> UNHEALTHY
                    <li> INACCURATE_DATA
                </ul>
          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.<br>
                Valid values are:
                <ul>
                  <li> PRIMARY
                  <li> STANDBY
                  <li> OLD_PRIMARY
                  <li> UNKNOWN
                </ul>
          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.<br>
              Valid values are:
              <ul>
                 <li> running              : node is running as the standby
                 <li> * running            : node is running as the primary
                 <li> ! running            : node has an unexpected role
                 <li> ? running            : node is pingable but not accepting connections
                 <li> ? unreachable        : connection to the node cannot be made
                 <li> ! running as primary : node is running as the new primary
                 <li> ! running as standby : node is running as the new standby
              </ul>
          upstream:
            type: string
            description: |
              Value of current primary being followed.
              <ul>
                <li> Populated when this is a standby node. Empty if this is a a primary node.
              </ul>

  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.  For example,  2019-11-13 01:34:58.795160 UTC
          status:
            type: string
            description:  |
                Status of requested action.
                The values are:
                <ul>
                    <li> running
                    <li> failed
                    <li> stopped
                </ul>
          stoppedAt:
            type: string
            description:  date-time with timezone.  null while task is still in progress. Once completed, same format as startedAt field.
          url:
            type: string
            description:  |
              URL of request, which includes action and name of node to promote.


  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:
                <ul>
                    <li> MANUAL
                    <li> AUTOMATIC
                    <li> UNKNOWN
                </ul>
          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:
                <ul>
                    <li> RUNNING
                    <li> NOT RUNNING
                    <li> NOT APPLICABLE
                    <li> UNKNOWN
                </ul>
                Note: <b> NOT APPLICABLE </b> 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:
          <ul>
            <li> ON
            <li> OFF
          </ul>
      cellFips:
        type: string
        description: |
          FIPS mode of the appliance's Cloud Director server.
          Possible values are:
          <ul>
            <li> ON
            <li> ON_PENDING_RESTART
            <li> OFF
            <li> OFF_PENDING_RESTART
            <li> UNKNOWN
          </ul>
        x-vcloud-constraints:
          - constraint: ReadOnly
