On this page

    Clouds

    A cloud represents a compute environment (AWS) in which Dremio Cloud engines run. A cloud can be associated with many projects. This API allows you to add, modify, delete, and list clouds.

    Cloud Object
      {
        "name": "aws-cloud",
        "id": "88535550-b138-441f-a705-a46ac1808508",
        "createdBy": "de8a47bf-432a-4d83-b60e-90d86cda8d70",
        "modifiedBy": "de8a47bf-432a-4d83-b60e-90d86cda8d70",
        "createdAt": "Thu Aug 19 14:39:52 UTC 2021",
        "modifiedAt": "Thu Aug 19 14:40:17 UTC 2021",
        "attributes": {
          "vendor": "aws",
          "region": "US_WEST_2",
          "subnets": [
            "subnet-f4dec3df",
            "subnet-e9a0fedd"
          ],
          "securityGroups": [
            "sg-03b443cd073634008"
          ],
          "credentials": {
            "type": "ACCESS_KEY",
            "accessKeyId": "AKIAJIPU77TQL8LR6OIR",    
            "secretAccessKey": null
          },
          "vpcEndpointId": "vpce-020b6e4fc2c494f27"
        }
      }
    

    Attributes

    name

    String

    The user-defined name for a cloud.

    Example aws-cloud


    id

    String (UUID)

    Unique identifier of a cloud.

    Example 035f6176-f785-4cec-a37d-8c2826b71f7c


    createdBy

    String

    The user who created the cloud.

    Example dremio


    modifiedBy

    String

    The user who last modified the cloud.

    Example dremio


    createdAt

    String

    The date and time that the cloud was created.

    Example Thu Aug 19 14:39:52 UTC 2021


    modifiedAt

    String

    The date and time that the cloud was last modified.

    Example Thu Aug 19 14:40:17 UTC 2021


    attributes

    object

    The cloud attributes associated with the cloud account.


    attributes

    credentials

    type

    String

    The type of credentials you are using to configure the compute settings for the cloud.

    Enum ACCESS_KEY , IAM_ROLE

    Example ACCESS_KEY


    accessKeyId

    String

    The access key generated from the AWS IAM User you created to provide Dremio Cloud with compute capabilities. This field is required if you selected ACCESS_KEY for credentials.

    Example AKIAJIPU77TQL8LR6OIR


    secretAccessKey

    String

    The secret key generated from the AWS IAM User you created to provide Dremio Cloud with compute capabilities. This field is required if you selected ACCESS_KEY for credentials.

    Example vJalrXUtnFEMI/K7MDENG/bPxRfiDYEXAMPLEKEY


    roleArn

    String

    The cross-account role ARN for the AWS IAM Role you created to provide Dremio Cloud with compute capabilities. To create this IAM Role, you need to provide the Trust Account ID (572051091487). This field is required if you selected IAM_ROLE for credentials.


    externalId

    String

    Needed to create an IAM role. This field is required if you selected IAM_ROLE for credentials.

    Example 940075727122


    Listing All Clouds

    Returns a list of all the clouds and the metadata for each cloud.

    Listing All Clouds
    GET /v0/clouds
    
    Example Request
    curl -X GET 'https://api.dremio.cloud/v0/clouds' \
    -H 'Authorization: Bearer <personal access token>' \
    -H 'Content-Type: application/json' 
    
    Example Response
    [
      {
        "name": "Default",
        "id": "436d7b40-d665-469a-a7fc-9110d0226488",
        "createdBy": "72974047-213c-497d-8ead-281f5ea25812",
        "modifiedBy": "f6f25d77-8322-4fa0-96c7-575c9e65c210",
        "createdAt": "Thu Jul 01 18:02:38 UTC 2021",
        "modifiedAt": "Tue Dec 21 03:38:43 UTC 2021",
        "attributes": {
          "vendor": "aws",
          "region": "US_WEST_2",
          "subnets": [
            "subnet-f4dec3df",
            "subnet-e9a0fedd"        
          ],
          "securityGroups": [
            "sg-0e0f5c5e4b105262d"
          ],
          "credentials": {
            "type": "IAM_ROLE",
            "roleArn": "arn:aws:iam::388677480418:role/user-test3-DremioIAMCloudComputeRole-ULX75AWAKA0O",
            "externalId": null
          },
          "vpcEndpointId": null
        },
        "projectRefs": []
      },
      {
        "name": "docCloud",
        "id": "52217be6-9f05-487a-ab2d-c8e38081d683",
        "createdBy": "f6f25d77-8322-4fa0-96c7-574c9f65c210",
        "modifiedBy": "f6f25d77-8322-4fa0-96c7-574c9f65c210",
        "createdAt": "Fri Dec 17 20:36:16 UTC 2021",
        "modifiedAt": "Fri Dec 17 20:36:16 UTC 2021",
        "attributes": {
          "vendor": "aws",
          "region": "US_WEST_2",
          "subnets": [
            "subnet-81e255f9"
          ],
          "securityGroups": [
            "sg-03b443cd073634008"
          ],
          "credentials": {
            "type": "ACCESS_KEY",
            "accessKeyId": "AKIAJIQU77TQL8LR6OIR",
            "secretAccessKey": null
          },
          "vpcEndpointId": null
        },
        "projectRefs": []
      }
    ]
    

    Responses

    200

    OK

    403

    Forbidden. Your authentication credentials are correct, but you do not have the right permission to make the request.


    Adding a Cloud

    Add a cloud.

    Adding a Cloud
    POST /v0/clouds
    

    Parameters

    Cloud

    name

    query

    String

    The user-defined name for a cloud.


    attributes

    query

    object

    The cloud attributes associated with the cloud account.


    requestId

    query

    string (UUID)

    Optional

    User-defined idempotency key, which is a unique value generated by the user that the server uses to register consequent retries of the same request. Generate the request ID by using a UUID generator tool. For more information, see idempotent requests .

    attributes

    vendor

    query

    String

    The cloud provider. Currently only supports AWS.


    region

    query

    String

    The region with which your cloud account is associated. For more information, see supported AWS regions .


    subnets

    String

    An array of one or more IDs of subnets that are associated with your Amazon VPC. Dremio Cloud uses the subnets to spin up engines for running queries.

    Example subnet-f4dec3df


    securityGroups

    query

    [string]

    The security group for your VPC that has an outbound rule to allow Dremio Cloud engines to connect over TLS.


    credentials

    query

    object

    The credentials you are using to configure the compute settings. Select from ACCESS_KEY or IAM_ROLE.


    vpcEndpointId

    String

    The VPC endpoint ID to use to discover the associated AWS PrivateLink Elastic Network Interface (ENI). When this value is empty, Dremio does not attempt discovery of associated AWS PrivateLink ENI and falls back to the configured DNS entry for the Dremio Gateway. If you have set up an AWS PrivateLink endpoint manually and enabled private DNS hostnames, Dremio uses the PrivateLink endpoint identified by the given ID. The default value is null.

    Example vpce-020b6e4fc2c494f27


    credentials

    type

    query

    String

    The type of credentials you are using to configure the compute settings for the cloud.

    Enum ACCESS_KEY , IAM_ROLE


    accessKeyID

    query

    String

    Optional

    The access key generated from the AWS IAM User you created to provide Dremio Cloud with compute capabilities. This field is required if you selected ACCESS_KEY for credentials.


    secretAccessKey

    query

    String

    Optional

    The secret key generated from the AWS IAM User you created to provide Dremio Cloud with compute capabilities. This field is required if you selected ACCESS_KEY for credentials.


    roleArn

    query

    String

    Optional

    The cross-account role ARN for the AWS IAM Role you created to provide Dremio Cloud with compute capabilities. To create this IAM Role, you need to provide the Trust Account ID (572051091487). This field is required if you selected IAM_ROLE for credentials.


    externalId

    query

    String

    Optional

    Needed to create an IAM role. This field is required if you selected IAM_ROLE for credentials.


    Example Request
    curl -X POST 'https://api.dremio.cloud/v0/clouds' \
    -H 'Authorization: Bearer <personal access token>' \
    -H 'Content-Type: application/json' \
    -d '{
      "name": "docCloud",
      "attributes": {
        "vendor": "AWS",
        "region": "US_WEST_2",
        "subnets": [
          "subnet-81e255f9"
        ],
        "securityGroups": [
          "sg-03b443cd073634008"
        ],
        "credentials": {
          "type": "ACCESS_KEY",
          "accessKeyId": "AKIAJIPU77TQL8LR6OIR",
          "secretAccessKey": "vJalrXUtnFEMI/K7MDENG/bPxRfiDYEXAMPLEKEY"
        },
        "vpcEndpointId": "vpce-020b6e4fc2c494f27"
      },
      "requestId": "302272c0-d357-4bcc-9087-19f3056a9a73"
    }'
    
    Example Response
    {
      "id": "e43e8505-8a44-4dc5-8181-75be1067cf99"
    }
    

    Responses

    200

    OK

    400

    Bad Request

    401

    Unauthorized. Your authorization credentials are incorrect.

    403

    Forbidden. Your authentication credentials are correct, but you do not have the right permission to make the request.

    500

    Internal Server Error


    Retrieving a Cloud

    Get the cloud metadata for an existing cloud by providing the cloud ID that was returned on creation of the cloud.

    Retrieving a Cloud
    GET /v0/clouds/{id}
    

    Parameters

    id

    path

    String

    The ID of the cloud for which you want to retrieve metadata.

    Example Request
    curl -X GET 'https://api.dremio.cloud/v0/clouds/e43e8505-8a44-4dc5-8181-75be1067cf99' \
    -H 'Authorization: Bearer <personal access token>' \
    -H 'Content-Type: application/json' 
    
    Example Response
      {
      "name": "docCloud",
      "id": "e43e8505-8a44-4dc5-8181-75be1067cf99",
      "createdBy": "de8a47bf-432a-4d83-b60e-90d86cda8d70",
      "modifiedBy": "de8a47bf-432a-4d83-b60e-90d86cda8d70",
      "createdAt": "Sat Aug 21 16:37:18 UTC 2021",
      "modifiedAt": "Sat Aug 21 16:37:18 UTC 2021",
      "attributes": {
        "vendor": "aws",
        "region": "US_WEST_2",
        "subnets": [
          "subnet-f4dec3df",
          "subnet-e9a0fedd"
        ],
        "securityGroups": [
          "sg-03b443cd073634008"
        ],
        "credentials": {
          "type": "ACCESS_KEY",
          "accessKeyId": "AKIAJIPU77TQL8LR6OIR",
          "secretAccessKey": null
        },
        "vpcEndpointId": "vpce-020b6e4fc2c494f27"
      }
    }
    

    Responses

    200

    OK

    400

    Bad Request

    401

    Unauthorized. Your authorization credentials are incorrect.

    403

    Forbidden. Your authentication credentials are correct, but you do not have the right permission to make the request.

    500

    Internal Server Error


    Modifying a Cloud

    Modify the cloud by providing the cloud ID that was returned on creation of the cloud. Parameters that are not provided will be left unchanged.

    Modifying a Cloud
    PUT /v0/clouds/{id}
    

    Parameters

    Cloud

    id

    path

    String (UUID)

    Unique identifier of a cloud.


    name

    query

    String

    The user-defined name for a cloud.


    attributes

    query

    object

    Optional

    The cloud attributes associated with the cloud account.


    attributes

    vendor

    query

    String

    Optional

    The cloud provider. Currently only supports AWS.


    region

    query

    String

    Optional

    The region with which your cloud account is associated. For more information, see supported AWS regions .


    subnets

    String

    An array of one or more IDs of subnets that are associated with your Amazon VPC. Dremio Cloud uses the subnets to spin up engines for running queries.

    Example subnet-f4dec3df


    securityGroups

    query

    [string]

    Optional

    The security group for your VPC that has an outbound rule to allow Dremio Cloud engines to connect over TLS.


    credentials

    query

    object

    Optional

    The credentials you are using to configure the compute settings. Select from ACCESS_KEY or IAM_ROLE.


    vpcEndpointId

    String

    The VPC endpoint ID to use to discover the associated AWS PrivateLink Elastic Network Interface (ENI). When this value is empty, Dremio does not attempt discovery of associated AWS PrivateLink ENI and falls back to the configured DNS entry for the Dremio Gateway. If you have set up an AWS PrivateLink endpoint manually and enabled private DNS hostnames, Dremio uses the PrivateLink endpoint identified by the given ID. The default value is null.

    Example vpce-020b6e4fc2c494f27


    credentials

    type

    query

    String

    Optional

    The type of credentials you are using to configure the compute settings for the cloud.

    Enum ACCESS_KEY , IAM_ROLE


    accessKeyId

    query

    String

    Optional

    The access key generated from the AWS IAM User you created to provide Dremio Cloud with compute capabilities. This field is required if you selected ACCESS_KEY for credentials.


    secretAccessKey

    query

    String

    Optional

    The secret key generated from the AWS IAM User you created to provide Dremio Cloud with compute capabilities. This field is required if you selected ACCESS_KEY for credentials.


    roleArn

    query

    String

    Optional

    The cross-account role ARN for the AWS IAM Role you created to provide Dremio Cloud with compute capabilities. To create this IAM Role, you need to provide the Trust Account ID (572051091487). This field is required if you selected IAM_ROLE for credentials.


    externalId

    query

    String

    Optional

    Needed to create an IAM role. This field is required if you selected IAM_ROLE for credentials.


    Example Request
    curl -X PUT 'https://api.dremio.cloud/v0/clouds/290f1ee-6c54-4b01-90e6-d701748f0851' \
    -H 'Authorization: Bearer <personal access token>' \
    -H 'Content-Type: application/json' \
    -d '{
      "name": "myCloud",
      "attributes": {
        "vendor": "aws",
        "region": "US_WEST_2",
        "subnets": [
          "subnet-81e255f9"
        ],
        "securityGroups": [
          "sg-00507c41e91010ebf"
        ],
        "credentials": {
          "type": "ACCESS_KEY",
          "accessKeyId": "AKIAJIPU77TQL8LR6OIR",
          "secretAccessKey": "vJalrXUtnFEMI/K7MDENG/bPxRfiDYEXAMPLEKEY"
        },
        "vpcEndpointId": "vpce-020b6e4fc2c494f27"
      }
    }'
    
    Example Response
    No response
    

    Responses

    204

    No Content

    400

    Bad Request

    401

    Unauthorized. Your authorization credentials are incorrect.

    403

    Forbidden. Your authentication credentials are correct, but you do not have the right permission to make the request.


    Deleting a Cloud

    Delete the cloud by providing the cloud ID that was returned on creation of the cloud.

    Deleting a Cloud
    DELETE /v0/clouds/{id}
    

    Parameters

    id

    path

    String

    The ID of the cloud that you want to delete.

    Example Request
    curl -X DELETE 'https://api.dremio.cloud/v0/clouds/290f1ee-6c54-4b01-90e6-d701748f0851' \
    -H 'Authorization: Bearer <personal access token>' \
    -H 'Content-Type: application/json' 
    
    Example Response
    No response
    

    Responses

    204

    No Content

    400

    Bad Request

    401

    Unauthorized. Your authorization credentials are incorrect.

    403

    Forbidden. Your authentication credentials are correct, but you do not have the right permission to make the request.

    500

    Internal Server Error