NAV

Introduction

Getting Started

This guide helps you get started quickly and easily on the ObjectRocket platform. For a more in-depth discussion of these steps, check out our blog. Follow along on the Sign Up page!

1) Create an Account

Sign up for ObjectRocket.

2) Verify your Email

We'll send you an email. Click the link provided in the email and then click Log In Again once this is complete.

3) Create an Organization

Enter in an Organization name and primary phone number for us to reach you at. Click Next to continue.

4) Billing Information

Enter in your billing information.

Authentication

To get an api token, go to the api token section of your Profile Management page. Add a name for the token and then click the "GENERATE API TOKEN" button.

This will generate a token to use against our api.

Include the header "Api-Token" with your token to authenticate against the api.

Api-Token: <Your api token here>

Or if you're using our Insomnia template, add the api-token to the environment to automatically add it to the header.

Insomnia Template

We have provided an Insomnia Template to assist in working with the Public API - Public API Insomnia Template

Safely Performing Updates

All api objects have a revision field. This field is an opaque token that helps ensure clients do not perform updates with stale data. Endpoints that support the PUT method must include this field with their update. If the revision provided does not match the revision stored on the object, a 400 response will be returned. Clients should then GET the latest revision of the object and retry the update. PATCH updates do not require the revision field so perform these carefully.

Catalog

List cloud providers

GET /cloudproviders/

Returns a list of cloud providers.

Example response

[
  {
    "id": "b1b46267-00ad-4cce-ba9c-c7535fde66a5",
    "dtCreated": "2018-06-13T18:22:37.882000Z",
    "dtModified": "2018-06-13T18:22:37.882000Z",
    "name": "aws"
  }
]

List regions

GET /regions/

GET /regions/?provider=aws

Returns a list of regions

Example response

[
  {
    "id": "09711c09-4425-4e43-80c6-ee5c7e2b8807",
    "dtCreated": "2018-06-13T18:22:37.882000Z",
    "dtModified": "2018-06-13T18:22:37.882000Z",
    "name": "us-east",
    "namePretty": "",
    "pricingMultiplier": "1.00",
    "cloudProvider": "f8091c0c-70e1-4a53-91b3-059d0b96b9fe",
    "providerName": "aws",
    "serviceSubtypes": [
      "85413ec3-bf8c-4d4d-9a71-55cd64113692"
      ]
  }
]

Query parameters to list regions

Parameter Default Required Description
provider none false the name of the cloud provider to filter by (see List cloud providers)

List services

GET /services/

Returns a list of services.

Example response

[
  {
    "id": "254a608d-b0b3-49d7-aa84-9e566016b995",
    "dtCreated": "2017-03-20T21:20:33.975000Z",
    "dtModified": "2017-03-20T21:20:33.975000Z",
    "name": "Elasticsearch"
  }
]

List service subtypes

GET /servicesubtypes/

GET /servicesubtypes/?serviceName=Elasticsearch

Returns a list of service subtypes.

Example response

[
  {
    "id": "85413ec3-bf8c-4d4d-9a71-55cd64113692",
    "dtCreated": "2019-01-22T19:24:05.433306Z",
    "dtModified": "2019-03-06T17:26:06.406818Z",
    "name": "elasticsearch_cluster",
    "description": "Elasticsearch Cluster where all nodes share all roles",
    "service": "9a33f633-9d46-4211-ab4b-fbe3b7ccdabb",
    "regions": [
      "09711c09-4425-4e43-80c6-ee5c7e2b8807",
    ],
     "versions": [
      "b08fc00d-39f7-4e34-a80a-d340b2e1bcb4",
      "ce6445e8-bba4-40ee-b791-63523aa22f4e"
    ],
    "serviceName": "Elasticsearch"
  },
  {
    "id": "91580366-57c4-4e8d-b060-5f08fb9ff83d",
    "dtCreated": "2019-01-22T19:24:05.516426Z",
    "dtModified": "2019-03-06T17:26:08.933088Z",
    "name": "elasticsearch_kibana",
    "description": "Elasticsearch Kibana",
    "service": "9a33f633-9d46-4211-ab4b-fbe3b7ccdabb",
    "regions": [
      "09711c09-4425-4e43-80c6-ee5c7e2b8807",
    ],
     "versions": [],
    "serviceName": "Elasticsearch"
  },
  {
    "id": "197d0a17-9ba5-422c-a480-74ef61d71fac",
    "dtCreated": "2019-01-22T19:24:05.521191Z",
    "dtModified": "2019-03-06T17:26:08.948542Z",
    "name": "elasticsearch_cerebro",
    "description": "Elasticsearch Cerebro",
    "service": "9a33f633-9d46-4211-ab4b-fbe3b7ccdabb",
    "regions": [
      "09711c09-4425-4e43-80c6-ee5c7e2b8807",
    ],
     "versions": [],
    "serviceName": "Elasticsearch"
  }
]

Query parameters to list service subtypes

Parameter Default Required Description
serviceName none false the name of the service to filter by (see List services)

List versions

GET /versions/

GET /versions/?serviceName=Elasticsearch

GET /versions/?serviceSubtypeName=elasticsearch_cluster

Returns a list of versions

Example response

[
  {
    "id": "46515c66-1c98-4e18-a037-db7dcec7993c",
    "dtCreated": "2019-02-20T21:43:21.956540Z",
    "dtModified": "2019-02-20T21:43:21.956566Z",
    "name": "7.7.1",
    "serviceSubtype": "85413ec3-bf8c-4d4d-9a71-55cd64113692",
    "serviceSubtypeName": "elasticsearch_cluster",
    "serviceName": "Elasticsearch"
  },
  {
    "id": "442297b5-6ff9-4229-ae72-68b1c6abee94",
    "dtCreated": "2019-01-22T19:24:05.511706Z",
    "dtModified": "2019-02-20T21:43:21.965084Z",
    "name": "6.8.10",
    "serviceSubtype": "85413ec3-bf8c-4d4d-9a71-55cd64113692",
    "serviceSubtypeName": "elasticsearch_cluster",
    "serviceName": "Elasticsearch"
  }
]

Query parameters to list versions

Parameter Default Required Description
name none false the name of the version to filter by
serviceName none false the name of the service to filter by (see List services)
serviceSubtypeName none false the name of the service subtype to filter by (see List service subtypes)

List flavors

GET /flavors/

GET /flavors/?name=Standard

GET /flavors/?service=Elasticsearch

GET /flavors/?serviceSubtypeName=elasticsearch_cluster

Returns a list of flavors

Example response

[
  {
    "id": "9920dd84-c5fe-497d-a117-3724a1a35b89",
    "dtCreated": "2019-03-04T15:47:18.627318Z",
    "dtModified": "2019-03-04T15:47:18.627348Z",
    "name": "Standard",
    "service": "Elasticsearch",
    "description": "Most implementations\nBalanced performance and cost per PG\nMulti-use Production ElasticSearch deployments\nModerate indexing and query load",
    "serviceSubtype": "606fe969-7228-4276-ac63-0169762a4ccd",
    "serviceSubtypeName": "elasticsearch_cluster"
  }
]

Query parameters to list flavors

Parameter Default Required Description
name none false the name of the flavor to filter by
service none false the name of the service the plan applies to (see List services)
serviceSubtypeName none false the name of the service subtype the plan applies to (see List service subtypes)

List plans

GET /plans/

GET /plans/?name=Standard_48GB

GET /plans/?service=Elasticsearch

GET /plans/?serviceSubtypeName=elasticsearch_cluster

GET /plans/?flavorName=standard

Returns a list of plans.

Plans are named as follows: [flavor]_[size]

Example response

[
  {
    "id": "276b71cd-7919-4a4c-a2e7-f9ff3322c8c6",
    "dtCreated": "2019-03-04T15:47:18.631074Z",
    "dtModified": "2019-03-04T15:47:18.631099Z",
    "name": "Standard_48GB",
    "service":"Elasticsearch",
    "description": "48GB Storage and 3GB Memory",
    "serviceSubtype": "606fe969-7228-4276-ac63-0169762a4ccd",
    "flavor": "9920dd84-c5fe-497d-a117-3724a1a35b89",
    "serviceSubtypeName": "elasticsearch_cluster",
    "flavorName": "Standard",
    "nodes": {
      "elasticsearch": {
        "memoryMb": 1024,
        "diskSizeGb": 16,
        "quantity": 3
      },
      "kibana": {
        "memoryMb": 512,
        "diskSizeGb": 0,
        "quantity": 1
      },
      "cerebro": {
        "memoryMb": 512,
        "diskSizeGb": 0,
        "quantity": 1
      }
    }
  }
]

Query parameters to list plans

Parameter Default Required Description
name none false the name of the plan to filter by
flavorName none false the name of the flavor the plan applies to (see List flavors)
service none false the name of the service the plan applies to (see List services)
serviceSubtypeName none false the name of the service subtype the plan applies to (see List service subtypes)

List addons

GET /addons/

GET /addons/?serviceSubtypeName=elasticsearch_cluster

Returns a list of addons. Addons are additional customizations for certain databases, such as additional replicas for HA PSQL or dedicated master for Elasticsearch.

Addons can only be added to the service that they match.

Example response

[
    {
        "id": "74c887d8-148b-45e1-9e78-e4aaff8ff10a",
        "name": "dedicated_master",
        "displayName": "Dedicated Masters",
        "description": "Dedicated Elasticsearch masters ensure that the master nodes are not under data pressure.",
        "maturityLevel": 3,
        "displaySetting": 1,
        "dtCreated": "2019-02-13T20:31:36.439349Z",
        "dtModified": "2019-02-13T20:31:36.439370Z",
        "serviceSubtype": "2567567567776-413e-9554-9a2cf8b630fc",
        "serviceSubtypeName": "elasticsearch_cluster",
        "default": false,
        "value": {
            "type": "string",
            "enum": "['2GB RAM/8GB Disk', '4GB RAM/16GB Disk', '8GB RAM/32GB Disk']"
        }
    },
    {
        "id": "24534534577d6-413e-9554-9a2cf8b630fc",
        "name": "replicas_for_ha",
        "displayName": "Replicas for HA",
        "description": "Add replicas to your PostgreSQL instance for high availability",
        "maturityLevel": 2,
        "displaySetting": 1,
        "dtCreated": "2019-02-13T20:31:36.439349Z",
        "dtModified": "2019-02-13T20:31:36.439370Z",
        "serviceSubtype": "6577776-413e-9554-9a2cf8b630fc",
        "serviceSubtypeName": "postgresql_cluster",
        "default": false,
        "value": {
            "type": "integer",
            "min": 1,
            "max": 2,
            "default": 2
        }
    }
]

Query parameters to list addons

Parameter Default Required Description
serviceSubtypeName none false the name of the service subtype the plan applies to (see List service subtypes)

List configurations

GET /configurations/

GET /configurations/?serviceSubtype=elasticsearch_cluster

Returns a list of valid datastore specific custom settings which can be applied to an instance of a particular service subtype and version.

Example response

[
    {
        "id": "74c887d8-148b-45e1-9e78-e4aaff8ff10a",
        "revision": "aea8646bd75aa16d337c2548ccfef75d",
        "dtCreated": "2019-02-13T20:31:36.439349Z",
        "dtModified": "2019-02-13T20:31:36.439370Z",
        "maturityLevel": 3,
        "displaySetting": 1,
        "name": "max_connections",
        "description": "",
        "restartRequired": true,
        "value": {
            "type": "integer",
            "default": 100,
            "maximum": 262143,
            "minimum": 25
        },
        "serviceSubtype": "c2d77e6f-c773-4730-8f85-eb6f801511cc",
        "versions": [
            "77ca9903-3263-4bed-a239-6150cc39a674"
        ]
    },
    {
        "id": "e3c9054b-3a9c-41f0-86c7-521efa3f5a98",
        "revision": "e4e064cd9712b2b9e4aec175d60aea6a",
        "dtCreated": "2019-03-18T20:31:36.439349Z",
        "dtModified": "2019-03-18T20:31:36.439370Z",
        "maturityLevel": 3,
        "displaySetting": 1,
        "name": "reindex.remote.whitelist",
        "description": "Comma-separated list of whitelisted source Elasticsearch hosts for remote reindexing",
        "restartRequired": true,
        "value": {
            "type": "string"
        },
        "serviceSubtype": "689d0301-93a2-4375-9ac8-6d26cf1c8265",
        "versions": [
            "b08fc00d-39f7-4e34-a80a-d340b2e1bcb4"
        ]
    }
]

Query parameters to list configurations

Parameter Default Required Description
serviceSubtype none false the name of the service subtype (see List service subtypes)

Pricing

Get pricing for an instance

GET pricing?region=20b2e8ef-566a-42a2-9f2a-2986c3d542ea&plan=a69dffe8-1294-4d8c-b1dd-cf3504ad631d

Returns the price in cents of an instance of the specified plan in the specified region.

GET pricing?region=20b2e8ef-566a-42a2-9f2a-2986c3d542ea&plan=a69dffe8-1294-4d8c-b1dd-cf3504ad631d&addon=20419341-1117-4d0e-9acd-519adc9fd0df_value_2&addon=74c887d8-148b-45e1-9e78-e4aaff8ff10a_value_true

Returns the price in cents of an instance of the specified plan with custom addon selections in the specified region.

Example response

{
    "priceInCents": 25000
}

Query parameters for pricing

Parameter Default Required Description
region none true id of the desired region
plan none true id of the desired plan
addon none false Format: {addon_id}_value_{addon_value} - id of the addon (see List addons) along with desired addon value

Organization

List your organization

GET /organizations/

Returns information about an organization you are a member and owner of.

Example response

{
    "count": 1,
    "next": null,
    "previous": null,
    "results": [
        {
            "id": "13f8e769-0bb2-4cb5-8218-202411e48e50",
            "primaryEmail": "my.email@gmail.com",
            "billingSetupComplete": true,
            "dtCreated": "2019-02-14T17:02:10.757234Z",
            "dtModified": "2019-02-14T17:02:33.473886Z",
            "companyName": "Company",
            "phoneNumber": "5168359427",
            "supportLevel": null,
            "trialCreditCents": 20000,
            "enforceSameDomainEmail": true
        }
    ]
}

Get organization by id

GET /organizations/<organization_id>

Returns information about an organization you are a member and owner of.

Example response

{
    "id": "13f8e769-0bb2-4cb5-8218-202411e48e50",
    "primaryEmail": "my.email@gmail.com",
    "billingSetupComplete": true,
    "dtCreated": "2019-02-14T17:02:10.757234Z",
    "dtModified": "2019-02-14T17:02:33.473886Z",
    "companyName": "Company",
    "phoneNumber": "5168359427",
    "supportLevel": null,
    "trialCreditCents": 20000,
    "enforceSameDomainEmail": true
}

Update organization

PATCH /organization/<organization_id>/

Updates an organization you are a member and owner of.

Note that only companyName, primaryEmail, and phoneNumber can be updated this way. Contact support with any additional needs.

Body parameters to update an organization

Parameter Default Required Description
companyName none false current company name or name to change to
phoneNumber none false phone number to contact in case of support
primaryEmail none false email to contact in case of support

Example request

{
    "companyName": "ObjectRocketing",
    "primaryEmail": "bob@objectrocket.com"
}

Example response

{
    "id": "a77da3a4-8ee0-42cb-8c5e-36a9c653a915",
    "primaryEmail": "bob@objectrocket.com",
    "dtCreated": "2018-07-26T16:05:59.618470Z",
    "dtModified": "2018-07-26T16:36:57.711589Z",
    "companyName": "ObjectRocketing",
    "phoneNumber": "777-777-7777"
}

Invoice

Get upcoming invoice

GET /invoices/upcoming/

Returns upcoming invoice details of the organization you are a member and owner of.

Example response

{
    "totalBeforeDiscountCents": 25000,
    "totalAfterDiscountCents": 25000,
    "discountAmountCents": 0,
    "amountDueCents": 25000,
    "paid_status": "Estimate",
    "date": "2019-06-15T15:54:13"
}

Get past invoices

GET /invoices/past/

Returns past invoice details of the organization you are a member and owner of.

Example response

{
    "data": [
        {
            "totalBeforeDiscountCents": 25000,
            "totalAfterDiscountCents": 25000,
            "discountAmountCents": 0,
            "amountDueCents": 25000,
            "paid_status": "Paid",
            "date": "2019-05-15T15:54:13"
        },
        {
            "totalBeforeDiscountCents": 25000,
            "totalAfterDiscountCents": 25000,
            "discountAmountCents": 0,
            "amountDueCents": 25000,
            "paid_status": "Past due",
            "date": "2019-03-15T15:54:13"
        }
    ]
}

Users

List users

GET /users/

Returns a list of users from an organization you are a member and owner of.

Example response

{
    "count": 1,
    "results": [
        {
            "id": "6ff32947-ccd0-4d91-dsfsdfsdfsdfsdfe8349a",
            "username": "auth0|9acf3ae5c87a614890980999999",
            "email": "example@objectrocket.com",
            "dateJoined": "2019-08-26T22:09:51.052730Z",
            "dtCreated": "2019-08-26T22:09:51.053140Z",
            "dtModified": "2019-08-26T22:09:51.053154Z",
            "organizationId": "2b258bc1-57asdasdasdasdasda-a6c3-988a68ef21d9",
            "roles": ["owner"],
            "ssoUsername": "TestSSO"
        }
    ]
}

Get a specific user

GET /users/<user_id>/

Returns a user from an organization you are a member and owner of.

Example response

{

    "id": "6ff32947-ccd0-4sdfsdfsdfsdfsdf2ba4e8349a",
    "username": "auth0|9acf3ae5c87a614890980999999",
    "email": "example@objectrocket.com",
    "dateJoined": "2019-08-26T22:09:51.052730Z",
    "dtCreated": "2019-08-26T22:09:51.053140Z",
    "dtModified": "2019-08-26T22:09:51.053154Z",
    "organizationId": "2b258bc1-57asdasdasdasdasda-a6c3-988a68ef21d9",
    "roles": ["owner"],
    "ssoUsername": "TestSSO"

}

Filter users by email

GET /users/?email=example@objectrocket.com

Returns a list of users from an organization you are a member and owner of.

NB: only filtering by email is currently supported

Example response

{
    "count": 1,
    "results": [
        {
            "id": "6ff329sdfsdfsdfsdfsdfsdf2ba4e8349a",
            "username": "auth0|9acf3ae5c87a614890980999999",
            "email": "example@objectrocket.com",
            "dateJoined": "2019-08-26T22:09:51.052730Z",
            "dtCreated": "2019-08-26T22:09:51.053140Z",
            "dtModified": "2019-08-26T22:09:51.053154Z",
            "organizationId": "2b258bc1-5asdasdasdasdasdsdc3-988a68ef21d9",
            "roles": ["owner"],
            "ssoUsername": "TestSSO"
        }
    ]
}

Delete a specific user

DELETE /users/<user_id>/

Deletes a user from an organization you are a member and owner of (non-owner usage will result in an error).

Example response

{
  "message": {
        "user": "user@yourorg.com",
        "removed from support": "Success",
        "removed from identity": "Success",
        "removed from database": "Success",
    }
}

Patch a specific user

PATCH /users/<user_id>/

Changes to a user in the organization you are a member and owner of. Only the fields listed can be modified.

Body Parameters

Parameter Default Required Description
role none false the new role for the user
access_dedicated none false whether ot not the user is allowed to access an organization's dedicated cloud

Example request

{
    "role": "readonly user",
    "access_dedicated": true
}

Example response

{  
    "id": "6ff32947-ccd0-4sdfsdfsdfsdfsdf2ba4e8349a",
    "username": "auth0|9acf3ae5c87a614890980999999",
    "email": "example@objectrocket.com",
    "dateJoined": "2019-08-26T22:09:51.052730Z",
    "dtCreated": "2019-08-26T22:09:51.053140Z",
    "dtModified": "2019-08-26T22:09:51.053154Z",
    "organizationId": "2b258bc1-57asdasdasdasdasda-a6c3-988a68ef21d9",
    "roles": ["readonly user"],
    "ssoUsername": "TestSSO",
    "access_dedicated": true        
}

Instances

Instance status

Every instance has a status field and a human-readable statusDisplay field to record what status the instance is in.

Status Status Display Meaning
1 "Ready" Instance is running and ready for use
2 "Failed" Instance has entered a failure state
3 "Deleted" Instance has been deleted
4 "Create Requested" The request for an instance has been received and queued
5 "Update Requested" The request for an instance update has been received and queued
6 "Delete Requested" The request for an instance delete has been received and queued
7 "Building" The instance is being built
8 "Updating" The instance is being updated
9 "Deleting" The instance is being deleted
10 "Restart requested" The request for an instance restart has been received and queued
11 "Restarting" The instance is being restarted

List instances

GET /instances/

GET /instances/?region=us-east-1


Deprecated: The '/instanceslist' route is deprecated and will be removed at a later date. Use the '/instances' route instead.


GET /instanceslist/

GET /instanceslist/?region=us-east-1

Returns a list of instances for your organization.

Example response

[
  {
    "id": "081df6db-2f18-4d82-89e7-f6af577a3847",
    "name": "cockroachdb_testing1",
    "service": "CockroachDB",
    "serviceSubtype": "cockroachdb_singlecluster",
    "provider": "AWS",
    "hosts": [],
    "plan": "Alpha_30GB",
    "features": {
      "addons": {}
    },
    "settings": {},
    "acls": [
      {
        "id": "25ffae8c-cfbf-4252-a37e-3b64187ef55a",
        "cidr": "7.7.7.7/32",
        "kind": 6,
        "name": "our_app"
      },
    ],
    "statusDisplay": "Active",
    "dtCreated": "2017-01-31T19:39:57.266995Z",
    "dtModified": "2017-02-02T04:59:01.978902Z",
    "version": "19.2.2",
    "clusterID": "081df6db-2f18-4d82-89e7-f6af577a3857",
    "region": "us-east-1",
    "status": 2,
    "completed": "2017-02-02T04:59:01.978662Z",
    "metadata": {
      "multiInstanceId": "ca846997-f165-45a2-90d9-0f37e285200a"
    }
  }
]

Query parameters to list instances

Parameter Default Required Description
plan none false instance plan, e.g. 20GB (see List plans)
region none false cloud region the instance was provisioned in (see List regions)
service none false which datastore service the instance is (see List services)
serviceSubtype none false which service subtype the instance is (see List service subtypes)
status none false status code of the instance
version none false datastore version (see List versions)

ACLs

ACLs are attached to instances of a particular product type.

Current product types:

List ACLs

GET /instances/{product}/<instance_id>/acls/

Returns a list of ACLs for an instance of a product.

For example, for an elasticsearch instance with the id of 062a0fa2-2d26-45d8-a379-ec185b8fee59, the call would be to

/instances/elasticsearch/062a0fa2-2d26-45d8-a379-ec185b8fee59/acls/.

Example response

[
  {
    "cidr": "127.0.0.1/32",
    "kind": 1,
    "name": "us-east"
  },
  {
    "cidr": "192.168.0.0/16",
    "kind": 1,
    "name": "us-west"
  }
]

Get a specific ACL

GET /instances/{product}/<instance_id>/acls/<acl_id>/

Returns an ACL for an instance of a product.

Example response

{
  "id": "80f99064-737f-4134-9157-95de0e624bfc",
  "cidr": "192.168.0.0/16",
  "kind": 1,
  "name": "us-west"
}

Create an instance ACL

POST /instances/{product}/<instance_id>/acls/

Requests that an ACL be created by the build system. A successful request will return HTTP 202.

Note: kind is required for ACLs added to products that potentially have multiple available hosts.

For example, a single Elasticsearch instance might also include Kibana and Cerebro hosts; kind is required so that you can specify which host you want to connect to (Elasticsearch, Kibana, or Cerebro).

For another example, a single Redis instance only has one host to connect to (the master), so kind is not required.

Body parameters to create an instance ACL

Parameter Default Required Description
cidr none true ip address or CIDR block to apply
kind 1 false (see Note above) a qualifier which identifies the kind of ACL (see chart below)
name none true a name for the ACL

ACL kind per product

Kind Product Host Type
1 Redis --
2 Elasticsearch Elasticsearch
4 Elasticsearch Kibana
5 Elasticsearch Cerebro
6 Cockroach Cockroach
7 Cockroach Cockroach Admin
8 PostgreSQL PostgreSQL
9 PostgreSQL PostgreSQL replica (in an HA instance)
10 TimescaleDB TimescaleDB
11 TimescaleDB TimescaleDB replica (in an HA instance)

Example request

{
  "cidr": "192.168.0.0/16",
  "kind": 4,
  "name": "datacenter"
}

Example response

{
  "id": "728edd1e-02c2-49a2-9859-58fdeac32df2",
  "transactionId": "74d8470e-d1f4-40b8-b089-86545b1b88dc"
}

Delete ACLs

DELETE /instances/{product}/<instance_id>/acls/<acl_id>/

Requests that an ACL be deleted.

Delete requests currently return no body and a response code of 204.

Backups

Backups are created for instances of a particular product type.

Current product types:

List Backups

GET /instances/{product}/<instance_id>/backups/

Returns a list of Backups for an instance of a product.

For example, for a postgresql instance with the id of 062a0fa2-2d26-45d8-a379-ec185b8fee59, the call would be to

/instances/postgresql/062a0fa2-2d26-45d8-a379-ec185b8fee59/backups/.

Example response

[
  {
    "id": "ed123d32-47d0-4d85-96ff-3dc54e7f1268",
    "statusDisplay": "Succeeded",
    "backupSchedule": {
      "id": "0e1a1bf7-1f75-47ff-b06f-9282a44b974f",
      "dtCreated": "2019-05-04T11:11:33.678000Z",
      "dtModified": "2019-05-04T11:11:33.980000Z",
      "dtDeleted": null,
      "name": "default_daily_backup",
      "schedule": "11 11 * * *",
      "destination": "Amazon S3"
    },
    "dtCreated": "2019-05-05T11:11:33.123000Z",
    "dtModified": "2019-05-05T11:11:33.653000Z",
    "dtDeleted": null,
    "start": "2019-05-05T11:11:33.123000Z",
    "end": "2019-05-05T11:11:33.653000Z",
    "retention": 14,
    "recurring": true,
    "backupTransactionId": "5cc611b5-a569-4878-8574-7b08252243c8",
    "status": 2,
    "instance": "062a0fa2-2d26-45d8-a379-ec185b8fee59",
    "metadata": {
      "backup_name": "base_000000010000000000000002",
      "time": "2019-11-13T15:43:18.265Z",
      "wal_file_name": "000000010000000000000002",
      "start_time": "2019-07-26T22:23:30.971366Z",
      "finish_time": "2019-07-26T22:23:55.220618Z",
      "date_fmt": "%Y-%m-%dT%H:%M:%S.%fZ",
      "hostname": "pgsql-062a0fa2-2d26-45d8-a379-ec185b8fee59-0",
      "data_dir": "/home/postgres/pgdata/pgroot/data",
      "pg_version": 110005,
      "start_lsn": 33554472,
      "finish_lsn": 50331784,
      "is_permanent": false,
      "system_identifier": 6758816836649042000,
      "uncompressed_size": 23937998,
      "compressed_size": 6668650,
      "user_data": {
        "backup_transaction_id": "5cc611b5-a569-4878-8574-7b08252243c8"
      }
    }
  },
  {
    "id": "246859c1-ae0a-4cf3-8437-d417bc560092",
    "statusDisplay": "Succeeded",
    "backupSchedule": {
      "id": "0e1a1bf7-1f75-47ff-b06f-9282a44b974f",
      "dtCreated": "2019-05-04T11:11:33.678000Z",
      "dtModified": "2019-05-04T11:11:33.980000Z",
      "dtDeleted": null,
      "name": "default_daily_backup",
      "schedule": "11 11 * * *",
      "destination": "Amazon S3"
    },
    "dtCreated": "2019-05-04T11:11:33.678000Z",
    "dtModified": "2019-05-04T11:11:33.980000Z",
    "dtDeleted": null,
    "start": "2019-05-04T11:11:33.678000Z",
    "end": "2019-05-04T11:11:33.980000Z",
    "retention": 14,
    "recurring": true,
    "backupTransactionId": "d6981195-1b7f-410b-b878-ae2abf888e11",
    "status": 2,
    "instance": "062a0fa2-2d26-45d8-a379-ec185b8fee59",
    "metadata": {
      "backup_name": "base_000000010000000000000004",
      "time": "2019-11-13T15:43:18.265Z",
      "wal_file_name": "000000010000000000000002",
      "start_time": "2019-07-26T22:23:30.971366Z",
      "finish_time": "2019-07-26T22:23:55.220618Z",
      "date_fmt": "%Y-%m-%dT%H:%M:%S.%fZ",
      "hostname": "pgsql-062a0fa2-2d26-45d8-a379-ec185b8fee59-0",
      "data_dir": "/home/postgres/pgdata/pgroot/data",
      "pg_version": 110005,
      "start_lsn": 33554472,
      "finish_lsn": 50331784,
      "is_permanent": false,
      "system_identifier": 6758816836649042000,
      "uncompressed_size": 23937998,
      "compressed_size": 6668650,
      "user_data": {
        "backup_transaction_id": "d6981195-1b7f-410b-b878-ae2abf888e11"
      }
    }
  }
]

Get a specific Backup

GET /instances/{product}/<instance_id>/backups/<backup_id>/

Returns a Backup for an instance of a product.

Example response

{
  "id": "246859c1-ae0a-4cf3-8437-d417bc560092",
  "statusDisplay": "Succeeded",
  "backupSchedule": {
    "id": "0e1a1bf7-1f75-47ff-b06f-9282a44b974f",
    "dtCreated": "2019-05-04T11:11:33.678000Z",
    "dtModified": "2019-05-04T11:11:33.980000Z",
    "dtDeleted": null,
    "name": "default_daily_backup",
    "schedule": "11 11 * * *",
    "destination": "Amazon S3"
  },
  "dtCreated": "2019-05-04T11:11:33.678000Z",
  "dtModified": "2019-05-04T11:11:33.980000Z",
  "dtDeleted": null,
  "start": "2019-05-04T11:11:33.678000Z",
  "end": "2019-05-04T11:11:33.980000Z",
  "retention": 14,
  "recurring": true,
  "backupTransactionId": "d6981195-1b7f-410b-b878-ae2abf888e11",
  "status": 2,
  "instance": "062a0fa2-2d26-45d8-a379-ec185b8fee59",
  "metadata": {
    "backup_name": "base_000000010000000000000004",
    "time": "2019-11-13T15:43:18.265Z",
    "wal_file_name": "000000010000000000000002",
    "start_time": "2019-07-26T22:23:30.971366Z",
    "finish_time": "2019-07-26T22:23:55.220618Z",
    "date_fmt": "%Y-%m-%dT%H:%M:%S.%fZ",
    "hostname": "pgsql-062a0fa2-2d26-45d8-a379-ec185b8fee59-0",
    "data_dir": "/home/postgres/pgdata/pgroot/data",
    "pg_version": 110005,
    "start_lsn": 33554472,
    "finish_lsn": 50331784,
    "is_permanent": false,
    "system_identifier": 6758816836649042000,
    "uncompressed_size": 23937998,
    "compressed_size": 6668650,
    "user_data": {
      "backup_transaction_id": "d6981195-1b7f-410b-b878-ae2abf888e11"
    }
  }
}

Elasticsearch Instances

List all Elasticsearch instances

GET /instances/elasticsearch/

Returns a list of all Elasticsearch instances.

Example response

  [{
    "id": "081df6db-2f18-4d82-89e7-f6af577a3847",
    "name": "arbiters_testing1",
    "service": "Elasticsearch",
    "serviceSubtype": "elasticsearch_cluster",
    "provider": "AWS",
    "hosts": [],
    "plan": "Standard_48GB",
    "features": {
      "addons": {}
    },
    "settings": {},
    "acls": [
      {
        "id": "25ffae8c-cfbf-4252-a37e-3b64187ef55a",
        "cidr": "7.7.7.7/32",
        "kind": 4,
        "name": "our_app"
      },
    ],
    "statusDisplay": "Ready",
    "dtCreated": "2017-01-31T19:39:57.266995Z",
    "dtModified": "2017-02-02T04:59:01.978902Z",
    "version": "7.7.1",
    "clusterID": "081df6db-2f18-4d82-89e7-f6af577a3857",
    "region": "us-east-1",
    "status": 2,
    "completed": "2017-02-02T04:59:01.978662Z",
    "metadata": {}
  }
]

Get specific Elasticsearch instance (by id)

GET /instances/elasticsearch/<instance_id>/

Returns a specific Elasticsearch instance.

Example response

{
  "id": "081df6db-2f18-4d82-89e7-f6af577a3847",
  "name": "arbiters_testing1",
  "service": "Elasticsearch",
  "serviceSubtype": "elasticsearch_cluster",
  "provider": "AWS",
  "hosts": [],
  "plan": "Standard_48GB",
  "features": {
    "addons": {}
  },
  "settings": {},
  "acls": [
    {
      "id": "25ffae8c-cfbf-4252-a37e-3b64187ef55a",
      "cidr": "7.7.7.7/32",
      "kind": 4,
      "name": "our_app"
    },
  ],
  "statusDisplay": "Ready",
  "dtCreated": "2017-01-31T19:39:57.266995Z",
  "dtModified": "2017-02-02T04:59:01.978902Z",
  "version": "7.7.1",
  "clusterID": "081df6db-2f18-4d82-89e7-f6af577a3857",
  "region": "us-east-1",
  "status": 2,
  "completed": "2017-02-02T04:59:01.978662Z",
  "metadata": {}
}

Create an Elasticsearch instance

POST /instances/elasticsearch/

Requests that an Elasticsearch instance be created by the build system.

A successful request will return HTTP 202. At this point the instance will have a status of 4 and status_display of Create Requested. Once the build system is actively building the instance, it will have a status of 7 (Building).

Once the instance has been fully built out the record will be updated to status 1 and status_display Ready. Additionally the record will be updated with member hosts, connection strings, etc.

Body parameters to create an Elasticsearch instance

Parameter Default Required Description
acls none false creates acls for instance on build
features none true instance features dependent on service
features.addons none false elasticsearch addons that can be toggled on or off
features.addons.kibana true false enables Kibana
features.addons.cerebro true false enables Cerebro
name none true a name for the instance
plan none true a valid plan identifier (see List plans)
provider none true currently only AWS (see List cloud providers)
region none true which cloud region to deploy to, e.g. us-east-1 (see List regions)
service none true which service is requested (see List services)
serviceSubtype none true elasticsearch_cluster for elasticsearch (see List service subtypes)
settings none false settings for instance like custom configurations
settings.datastoreConfigurations none false key-value pairs of custom elasticsearch settings. For a valid list (see List configurations)
settings.customPlugins none false list of custom elasticsearch plugins. (see List plugins)
version none true requested version of service (see List versions)

Note: settings.datastoreConfigurations and settings.customPlugins cannot be updated in the same request

Example request

{
    "plan": "Standard_48GB",
    "name": "whatever",
    "version": "7.7.1",
    "region": "us-east-1",
    "service": "Elasticsearch",
    "features": {},
    "acls": [
      {
        "cidr": "192.168.0.0/16",
        "kind": 2,
        "name": "datacenter"
      }
    ],
    "settings": {},
    "provider": "AWS",
    "serviceSubtype": "elasticsearch_cluster"
}

Example request to create an Elasticsearch instance with custom configs

{
    "plan": "Standard_48GB",
    "name": "whatever",
    "version": "7.7.1",
    "region": "us-east-1",
    "service": "Elasticsearch",
    "features": {},
    "settings": {
      "datastoreConfigurations": {
        "reindex.remote.whitelist": "remotehostname:remoteportnumber"
      }
    },
    "provider": "AWS",
    "serviceSubtype": "elasticsearch_cluster"
}

Example response

{
  "id": "728edd1e-02c2-49a2-9859-58fdeac33df2",
  "transactionId": "74d8470e-d1f4-40b8-b089-86545b1c88dc"
}

Rename an Elasticsearch instance

PATCH /instances/elasticsearch/<instance_id>/

Requests the instance be renamed to the specified value.

Body parameters to rename an Elasticsearch instance

Parameter Default Required Description
name none true a name for the instance

Example request

{
    "name": "adifferentname"
}

Example response

{
  "id": "728edd1e-02c2-49a2-9859-58fdeac32df2",
  "name": "adifferentname"
}

Delete an Elasticsearch instance

DELETE /instances/elasticsearch/<instance_id>/

Requests that an Elasticsearch instance be deleted.

This will set the instance to status 4 (Delete Requested).

Delete requests currently return no body and a response code of 204.

Create an Elasticsearch Instance with Dedicated Masters

Elasticsearch with Dedicated Masters

POST /instances/elasticsearch/

Refer here for details on creating an Elasticsearch instance.

Additional body parameters to specify in order to create an Elasticsearch instance with dedicated masters.

You can retrieve the valid options for the dedicated masters addon here

Parameter Default Required Description
features.addons.dedicated_master none true must be set in order to build the Elasticsearch instance with dedicated masters

Example request

{
    "plan": "Standard_48GB",
    "name": "whatever",
    "version": "7.7.1",
    "region": "us-east-1",
    "service": "elasticsearch",
    "features": {
      "addons": {
        "dedicated_master": "2GB RAM/8GB Disk"
      }
    },
    "acls": [
      {
        "cidr": "192.168.0.0/16",
        "kind": 2,
        "name": "datacenter"
      }
    ],
    "settings": {},
    "provider": "AWS",
    "serviceSubtype": "elasticsearch_cluster"
}

Example response

{
  "id": "728edd1e-02c2-49a2-9859-58fdeac33df2",
  "transactionId": "74d8470e-d1f4-40b8-b089-86545b1c88dc"
}

Elasticsearch Scaling

Scale nodes for an Elasticsearch instance

POST /instances/elasticsearch/<instance_id>/scale/

Requests that an Elasticsearch instance be scaled.

This scales the instance nodes to the specified value(s). Elasticsearch instances can be scaled in the following ways:

Adding Dedicated Masters

A multirole cluster can have dedicated masters added using this /scale endpoint.

Both desiredPerNodeMemoryMb and desiredPerNodeDiskSizeGb are required to determine dedicated master resources. Valid values for both of these parameters are based on dedicated_master addon values. For example to select 2GB RAM/8GB Disk, desiredPerNodeMemoryMb: 2048 and desiredPerNodeDiskSizeGb: 8 would be the parameters set. You can retrieve the valid options for the dedicated masters addon here

Body Parameters

Parameter Default Required Description
desiredQuantity none true Number of nodes to scale to. The minimum number of nodes is 1 and the maximum is 5 for multi/data nodes. When scaling-in (decreasing nodes), only one node can be removed at a time; and scaling-in is not allowed on an instance with closed indices.
role none true Name of node/host role to scale. The only valid option is "elasticsearch" and "dedicated_master".
desiredPerNodeMemoryMb none false Memory in MB for new master nodes to scale to.
desiredPerNodeDiskSizeGb none false Disk size in GB for new master nodes to scale to.

Example request of scaling multi/data nodes

{
  "desiredQuantity": 5,
  "role": "elasticsearch"
}

Success HTTP Status Code: 202 Accepted

Example response

{
  "detail": "Request to scale elasticsearch nodes of instance 728edd1e-02c2-49a2-9859-58fdeac32df2 from 3 to 5 has been accepted"
}

Example request of scaling (adding) dedicated master nodes to multi-role cluster

{
  "desiredQuantity": 3,
  "role": "dedicated_master",
  "desiredPerNodeMemoryMb": 2048,
  "desiredPerNodeDiskSizeGb": 8
}

Success HTTP Status Code: 202 Accepted

Example response

{
  "detail": "Request to add dedicated masters nodes of 2GB RAM/8GB Disk for instance 728edd1e-02c2-49a2-9859-58fdeac32df2 has been accepted"
}

Elasticsearch User Management

List Elasticsearch instance users

GET /instances/elasticsearch/<instance_id>/users/

Returns a list of users for the specified Elasticsearch instance.

Example response

[
    {
        "id": "0bccec0f-62e9-42b8-bd4f-f36e0ea9834e",
        "username": "customer_readonly_user",
        "role": [
            "readonly"
        ]
    },
    {
        "id": "02602cda-9247-46de-b9a1-bb02d170af95",
        "username": "customer_admin",
        "role": [
            "admin"
        ]
    }
]

Get a specific Elasticsearch instance user (by id)

GET /instances/elasticsearch/<instance_id>/users/<user_id>/

Returns the user specified for the specified Elasticsearch instance.

Example response

{
    "id": "0bccec0f-62e9-42b8-bd4f-f36e0ea9834e",
    "username": "customer_readonly_user",
    "role": [
        "readonly"
    ]
}

Create Elasticsearch instance user

POST /instances/elasticsearch/<instance_id>/users/

Creates a new Elasticsearch user for an Elasticsearch instance.

Example request

{
    "username": "new_user_3",
    "password": "abc",
    "roles": ["admin"]
}

Example response

{
    "id": "0bccec0f-62e9-42b8-bd4f-f36e0ea9834e",
    "dtCreated": "2018-09-06T17:43:25.671836Z",
    "dtModified": "2018-09-06T17:43:25.671865Z",
    "dtDeleted": null,
    "username": "new_user_3",
    "instance": "26b9955f-9b56-443b-be7a-54bda5725391",
    "role": [
        "ba2ca9cc-c4c1-46a5-bd1f-33385e1fbba0"
    ]
}

Body parameters to create an Elasticsearch instance user

Parameter Default Required Description
password none true password for the user
roles none true list of roles assigned to the user. Choices are "admin", "kibana", and "readonly". Multiple roles are supported
username none true username for the new user

Update Elasticsearch instance user

PATCH /instances/elasticsearch/<instance_id>/users/<user_id>

Updates an existing Elasticsearch user for an Elasticsearch instance.

Example request

{
    "username": "new_username",
    "roles": ["readonly", "kibana"]
}

Example response

{
    "id": "02602cda-9247-46de-b9a1-bb02d170af95",
    "dtCreated": "2018-09-06T17:43:18.091435Z",
    "dtModified": "2018-09-06T17:43:48.241937Z",
    "dtDeleted": null,
    "username": "new_user",
    "instance": "26b9955f-9b56-443b-be7a-54bda5725391",
    "role": [
        "adf45913-4669-4f7c-9957-865a4bdb8527",
        "ba13ha9c-c4c1-4ca5-bd1f-33385e1fbba0"
    ]
}

Body parameters to update an Elasticsearch instance user

Parameter Default Required Description
password none false new password for the user
roles none false new list of roles assigned to the user. Choices are "admin", "kibana", and "readonly". Multiple roles are supported
username none false new username for the user

Delete Elasticsearch instance user

DELETE /instances/elasticsearch/<instance_id>/users/

Deletes an Elasticsearch user belonging to the Elasticsearch instance (instance_id).

Body parameters to delete an Elasticsearch user

Parameter Default Required Description
username none true Name of the user.

Example request

{
    "username": "myadmin"
}

Success HTTP Status Code: 202 Accepted

Example response

{
  "detail": "Request to delete user myadmin from instance afa83127-f122-40a6-a7f7-b0a5e9a056cc is being processed"
}

Update Configuration for an Elasticsearch Instance

Update configuration for an Elasticsearch Instance

PATCH /instances/elasticsearch/<instance_id>/

This endpoint uses the JSON Merge Patch Strategy for applying settings.

This will trigger a rolling restart of the Elasticsearch cluster.

Body parameters to update the configuration of an Elasticsearch instance

Parameter Default Required Description
settings.datastoreConfigurations none false To specify updated settings. Simply specify the Elasticsearch configuration setting as a key and the desired value. To remove a setting, set its value to "null". These settings will override any defaults. For a valid list (see List configurations)

Example request to update the configuration of an Elasticsearch instance

{
  "settings": {
    "datastoreConfigurations": {
      "reindex.remote.whitelist": "remotehostname:remoteportnumber"
    }
  }
}

Example response

Success HTTP Status Code: 202 Accepted

{
  "id": "14c4074f-1f5c-483a-b3c5-3eb83dad409b",
  "revision": "9dc6b7ebb90b971b77d4240ee536b8d0",
  "service": "Elasticsearch",
  "hosts": [],
  "acls": [],
  "statusDisplay": "Ready",
  "serviceSubtype": "elasticsearch_cluster",
  "dtCreated": "2020-03-25T20:01:13.510479Z",
  "dtModified": "2020-03-25T20:01:13.510501Z",
  "dtDeleted": null,
  "provider": "AWS",
  "name": "es-test1",
  "version": "7.7.1",
  "features": {
    "addons": {}
  },
  "settings": {
    "datastoreConfigurations": {
      "reindex.remote.whitelist": "remotehostname:remoteportnumber"
    }
  },
  "metadata": {},
  "status": 1,
  "organization": "3ee9202d-429a-44a9-9ffb-fdd75ed51a50",
  "region": "us-east-1"
}

Elasticsearch Plugins

List all Elasticsearch plugins

GET /elasticsearch/plugins/

Returns a list of all Elasticsearch plugins belonging to your organization.

Example response

  [{
    "id": "c2957fc1-3626-4c15-9e7d-668badd21b08",
    "revision": "4de21d88ebd034cec09b9d8010544c87",
    "metadata": {},
    "dtCreated": "2020-05-20T12:35:54.719916Z",
    "dtModified": "2020-05-20T12:35:54.719940Z",
    "dtDeleted": null,
    "name": "plugin_test",
    "organization": "9232c41e-cf25-4fed-9610-af2a251ccb17"
  },
  {
    "id": "fc35b7f2-30eb-42a0-bfd7-5a35e27a8cac",
    "revision": "3ba488426d251c7bef5f6f17837083dc",
    "metadata": {},
    "dtCreated": "2020-05-20T19:03:32.037953Z",
    "dtModified": "2020-05-20T19:03:32.038042Z",
    "dtDeleted": null,
    "name": "plugin_test1",
    "organization": "dd69d435-9779-427c-8c4c-448fa5668af3"
  }
]

CockroachDB Instances

List all CockroachDB instances

GET /instances/cockroachdb/

Returns a list of all CockroachDB instances.

Example response

[
  {
    "id": "081df6db-2f18-4d82-89e7-f6af577a3847",
    "name": "cockroachdb_testing1",
    "service": "CockroachDB",
    "serviceSubtype": "cockroachdb_singlecluster",
    "provider": "AWS",
    "hosts": [],
    "plan": "Alpha_30GB",
    "features": {
      "addons": {}
    },
    "settings": {},
    "acls": [
      {
        "id": "25ffae8c-cfbf-4252-a37e-3b64187ef55a",
        "cidr": "7.7.7.7/32",
        "kind": 6,
        "name": "our_app"
      },
    ],
    "statusDisplay": "Active",
    "dtCreated": "2017-01-31T19:39:57.266995Z",
    "dtModified": "2017-02-02T04:59:01.978902Z",
    "version": "19.2.2",
    "clusterID": "081df6db-2f18-4d82-89e7-f6af577a3857",
    "region": "us-east-1",
    "status": 2,
    "completed": "2017-02-02T04:59:01.978662Z",
    "metadata": {
      "multiInstanceId": "ca846997-f165-45a2-90d9-0f37e285200a"
    }
  }
]

Get specific CockroachDB instance (by id)

GET /instances/cockroachdb/<instance_id>/

Returns a specific CockroachDB instance.

Example response

{
  "id": "081df6db-2f18-4d82-89e7-f6af577a3847",
  "name": "cockroachdb_testing1",
  "service": "CockroachDB",
  "serviceSubtype": "cockroachdb_singlecluster",
  "provider": "AWS",
  "hosts": [],
  "plan": "Alpha_30GB",
  "features": {
    "addons": {}
  },
  "settings": {},
  "acls": [
    {
      "id": "25ffae8c-cfbf-4252-a37e-3b64187ef55a",
      "cidr": "7.7.7.7/32",
      "kind": 6,
      "name": "our_app"
    },
  ],
  "statusDisplay": "Active",
  "dtCreated": "2017-01-31T19:39:57.266995Z",
  "dtModified": "2017-02-02T04:59:01.978902Z",
  "version": "19.2.2",
  "clusterID": "081df6db-2f18-4d82-89e7-f6af577a3857",
  "region": "us-east-1",
  "status": 2,
  "completed": "2017-02-02T04:59:01.978662Z",
  "metadata": {
      "multiInstanceId": "ca846997-f165-45a2-90d9-0f37e285200a"
  }
}

Create a CockroachDB instance

POST /instances/cockroachdb/

Requests that a CockroachDB instance be created by the build system.

A successful request will return HTTP 202. At this point the instance will have a status of 1 and status_display of Requested. Once the instance has been fully built out the record will be updated to status 2 and status_display Active. Additionally the record will be updated with member hosts, connection strings, etc.

Body Parameters

Parameter Default Required Description
acls none false creates acls for instance on build
name none true a name for the instance
plan none true a valid plan identifier (see List plans)
provider none true currently only AWS (see List cloud providers)
region none true which cloud region to deploy to, e.g. us-east-1 (see List regions)
service none true which service is requested (see List services)
serviceSubtype none true cockroachdb_singlecluster for CockroachDB (see List service subtypes)
version none true requested version of service (see List versions)
metadata.multiInstanceId none false a unique id used to link multiple instance nodes as a single cluster. This value is returned when using any GET method on the instances route. (see list instances)

Note Multi Instance: When creating a new instance using the multiInstanceID value (adding a new node to an existing cluster), the combination of region and provider values must be unique.

Example request

NOTE: When first creating the instance the provider is AWS and region is us-east-1.

{
    "plan": "Alpha_30GB",
    "name": "cockroach-test",
    "version": "19.2.2",
    "region": "us-east-1",
    "provider": "AWS",
    "service": "CockroachDB",
    "features": {},
    "settings": {},
    "serviceSubtype": "cockroachdb_singlecluster"
}

Example response

{
  "id": "728edd1e-02c2-49a2-9859-58fdeac33df2",
  "transactionId": "74d8470e-d1f4-40b8-b089-86545b1c88dc"
}

Example request - Multi Instance (Adding a new node to an existing cluster)

NOTE: When adding the second node notice that this time provider is still AWS, but the region changed to us-west-1. Also notice that the multiInstanceID is also set now.

{
    "plan": "Alpha_30GB",
    "name": "cockroach-test2",
    "version": "19.2.2",
    "region": "us-west-1",
    "provider": "AWS",
    "service": "CockroachDB",
    "features": {},
    "settings": {},
    "metadata": {
      "multiInstanceId": "ca846997-f165-45a2-90d9-0f37e285200a"
    },
    "serviceSubtype": "cockroachdb_singlecluster"
}

Example response

{
  "id": "a8cd34c3-a220-485f-b0cc-c6f32e5affff",
  "transactionId": "74d8470e-d1f4-40b8-b089-86545b1c88dc"
}

Rename a CockroachDB instance

PATCH /instances/cockroachdb/<instance_id>/

Requests the instance be renamed to the specified value.

Body Parameters

Parameter Default Required Description
name none true a name for the instance

Example request

{
    "name": "adifferentname"
}

Example response

{
  "id": "728edd1e-02c2-49a2-9859-58fdeac32df2",
  "name": "adifferentname"
}

Delete a CockroachDB instance

DELETE /instances/cockroachdb/<instance_id>/

Requests that a CockroachDB instance be deleted.

This will set the instance to status 4 (Delete Requested). The status will be updated to 5 (Deleted) once the resources have been removed.

If the instance is part of a Multiregion cluster then all of the instances in that cluster must be in the Ready state or this will return an error.

Delete requests currently return no body and a response code of 204.

Example response

Scale nodes for a CockroachDB instance

POST /instances/cockroachdb/<instance_id>/scale/

Requests that a CockroachDB instance be scaled out.

This scales the instance nodes to the specified value(s).

Body Parameters

Parameter Default Required Description
desiredQuantity none true number of nodes to scale to
role none true name of node/host role to scale

Example request

{
    "desiredQuantity": 5,
    "role": "cockroachdb"
}

Success HTTP Status Code: 202 Accepted

Example response

{
  "detail": "Request to scale cockroachdb nodes of instance 707034c3-a220-485f-b0cc-c6f32e5a0088 from 3 to 5 has been accepted"
}

CockroachDB Databases

List databases for a CockroachDB instance

GET /instances/cockroachdb/<instance_id>/databases/

List databases on an instance.

Example response

[
  {
    "name": "testdb"
  },
  {
    "name": "testdb2"
  }
]

Retrieve a database for a CockroachDB instance

GET /instances/cockroachdb/<instance_id>/databases/<database_name>/

Example response

{
  "name": "testdb"
}

Create a database for a CockroachDB instance

POST /instances/cockroachdb/<instance_id>/databases/

Create a new CockroachDB database. A successful request will return HTTP 201.

Example request

{
  "name": "exampledb",
}

Body parameters to create a database for a CockroachDB instance

Parameter Default Required Description
name none true name of the database to create

Delete a database for a CockroachDB instance

DELETE /instances/cockroachdb/<instance_id>/databases/<database_name>/

A successful request will return HTTP 204.

CockroachDB Users

List users for a CockroachDB instance

GET /instances/cockroachdb/<instance_id>/users/

List users on an instance.

Example response

[
  {
    "username": "testuser",
  },
  {
    "username": "testuser2"
  }
]

Retrieve a user for a CockroachDB instance

GET /instances/cockroachdb/<instance_id>/users/<user_name>/

Example response

{
  "username": "testuser"
}

Create a user for a CockroachDB instance

POST /instances/cockroachdb/<instance_id>/users/

Create a new CockroachDB user. A successful request will return HTTP 201.

Example request

{
  "username": "testuser",
  "password": "testpass"
}

Query parameters to create a user for a CockroachDB instance

Parameter Example Default Required Description
force_create force_create=true none false Set this query parameter equal to true to force an insecure user recreate (if a username was deleted before that had an associated client certificate and the CA has not been fully rotated).

Body parameters to create a user for a CockroachDB instance

Parameter Default Required Description
username none true Name of the user
password none false Password of the user for password authentication.

NOTE: If you do not provide a password you must authenticate using certificates. Certificate instructions are provided here.

Delete a user for a CockroachDB instance

DELETE /instances/cockroachdb/<instance_id>/users/

Body parameters to delete a CockroachDB user

Parameter Default Required Description
username none true Name of the CockroachDB user.

Example request

{
    "username": "testuser"
}

Success HTTP Status Code: 200 OK

Example response

{
  "detail": "User successfully deleted from instance afa83127-f122-40a6-a7f7-b0a5e9a056cc"
}

NOTE: If you delete a username that has an associated client certificate with an active certificate authority on the instance. That username will essentially be locked out from being recreated on the instance until you complete a CA rotation (explained here) or use the force_create query parameter flag during user create (WARNING: The use of this flag is insecure).

CockroachDB Certificates Instructions

Connecting to your CockroachDB instance securely with SSL

Create a database user

  1. Create a database user as described here

Generate CSR (Certificate Signing Request)

  1. Make sure you have a ssl utility like openssl installed (openssl)

  2. Generate a RSA private key file to create your CSR: openssl genrsa -out /path/to/certs/client.<username>.key 2048

  3. Generate the CSR file using your private key: openssl req -new -key /path/to/certs/client.<username>.key -out /path/to/certs/<username>.csr This will prompt you to enter X.509 DN attributes, but only enter the CN (Common Name) attribute and it must be the username of the database user you created above. Leave everything else blank.

  4. Extract the PEM data string from <username>.csr that you created and use it to get a signed certificate for your database. The data should look exactly like the example shown here: create client certificate

  5. Now you must retrieve the signed certificate PEM data by requesting the client certificate shown here: get client certs with pem data. Pay close attention to the URL params download=true, this must be present to get the PEM data.

  6. Once you have copied the signed certificate PEM data you will need to create a new file: /path/to/certs/client.<username>.crt and add the contents of the PEM data there.

Retrieve CA certificate bundle

  1. Create an empty file called: /path/to/certs/ca.crt

  2. Now retrieve the CA bundle (intermediate CA + root CA) by making a get request as shown here: get ca certs with pem data. Pay close attention to the URL params type=intermediate and download=true, both of these params must be present to get the CA bundle.

  3. Once you have copied the CA bundle PEM data you will need to add the contents of the PEM data to the ca.crt file.

Connect using certificates

  1. Now that you have all the certificates files you can connect to your CockroachDB instance securely.

Example connection - cockroach client

cockroach sql --url='postgres://<username>@servername:26257/mydb?sslmode=verify-full&sslrootcert=path/to/ca.crt&sslcert=path/to/client.<username>.crt&sslkey=path/to/client.<username>.key'

Example connection - psql client

psql 'postgres://<username>@servername:26257/mydb?sslmode=verify-full&sslrootcert=path/to/ca.crt&sslcert=path/to/client.<username>.crt&sslkey=path/to/client.<username>.key'

CockroachDB Client Certificate Delete (Revoke) Process

Call the delete endpoint in API

  1. Trigger a delete request by calling the certificates delete endpoint shown here: revoke client cert. Make sure to set the body parameter cert_type to client and the certificate_id to the target client certificate primary key id.

  2. The target certificate will then be revoked, because CockroachDB does not currently support CRLs (Certificate Revocation List), when this call is made we automatically begin a CA rotation process. You must follow the steps below to remove old CA after you've updated your application to use the newly generated CA.

Generate New Client Certificates

By calling delete on a client certificate you will now be presented with two CA certificates the current CA that has signed your CSRs thus far, now the secondary CA (This secondary CA will not sign CSRs anymore but will stay present on the CockroachDB nodes until deleted) and a new CA that will now be your primary instance CA.

This primary CA will now sign your new CSRs and will stay active on the node when the secondary is deleted. NOTE: CockroachDB currently does not support CRLs, so everytime you revoke a client certificate the instance CA will be rotated.

  1. Get all of your instance CAs by calling the list certificates endpoint shown here: list all intermediate CAs for instance. The URL params type=intermediate must present to get the CA certficates. You will now see a total of 2 CA certificates and their signed client certificates. The primary CA will have the primary field set to true and the secondary CA will have the primary field set to false.

  2. You must now create new client certificates for your users following similar steps mentioned here. NOTE: The new primary CA will be chosen to sign your client certficates now.

  3. Once you have created your new client certificates from the primary CA, you must complete the revocation process by calling the certificate delete endpoint shown here: complete CA rotation. Make sure to set the body parameter cert_type to intermediate in order to delete the secondary CA and complete the client certificate revocation process.

Once you have removed the secondary CA from the instance you can safely swap it out with the new primary CA in the ca.crt file. NOTE: At this point in the process, there might be connection disruptions to your application if you have not modified your certificates and restarted your app(s) manually.

CockroachDB Rotate CA (Renewal) Process

Create a new CA

  1. To trigger the CA rotation process you can create a new instance CA by calling the certificates create endpoint shown here: create new primary ca. Once created, this new CA will become your primary CA and will sign your new client certificate signing requests. The current primary instance CA will be demoted into a secondary CA (Assuming there is no other secondary CA currently on the instance) and the newly created instance CA will become the new primary CA. At the end of this step your instance will have 1 primary CA (new CA that will sign your CSRs) and 1 secondary CA (old CA that should be deleted).

Call the delete endpoint in API

  1. To complete the CA rotation process, make a request by calling the certificates delete endpoint shown here: complete CA certificate. Make sure to set the body parameter cert_type to intermediate. The rotation process completes when you only have 1 primary CA, so you must make sure you are not completing the rotation process early by calling the certificate delete endpoint, before you have generated your new signed client certificates.

  2. Follow the steps here for more information. Step 3 will complete the CA rotation process.

CockroachDB Certificates

CA - List all CockroachDB certificates

GET instances/cockroachdb/<instance_id>/certificates/?type=intermediate

Returns a list of all CockroachDB Instance CA certificates.

Example response

[
  {
    "id": "871f38e9-9c79-4de8-b79e-1cb8cf30d183",
    "clientCertificates": [],
    "dtCreated": "2019-09-04T15:11:24.791049Z",
    "dtModified": "2019-09-04T15:11:24.791080Z",
    "dtDeleted": null,
    "expiration": null,
    "name": "instance_intermediate_ca",
    "primary": true,
    "instance": "f50ea96f-bd62-4195-a66a-d1c65aa4385a"
  }
]
[
  {
    "id": "871f38e9-9c79-4de8-b79e-1cb8cf30d183",
    "clientCertificates": [
      {
        "id": "f18fe623-710c-495e-957e-191346f05b78",
        "dtCreated": "2019-09-04T16:06:27.766956Z",
        "statusDisplay": "Active",
        "dtModified": "2019-09-04T16:06:27.767006Z",
        "dtDeleted": null,
        "expiration": null,
        "subjectAlternative": "",
        "status": 2,
        "instance": "f50ea96f-bd62-4195-a66a-d1c65aa4385a",
        "caCertificate": "871f38e9-9c79-4de8-b79e-1cb8cf30d183"
      }
    ],
    "dtCreated": "2019-09-04T15:11:24.791049Z",
    "dtModified": "2019-09-04T15:11:24.791080Z",
    "dtDeleted": null,
    "expiration": null,
    "name": "instance_intermediate_ca",
    "primary": true,
    "instance": "f50ea96f-bd62-4195-a66a-d1c65aa4385a"
  }
]

CA - Get specific CockroachDB Certificate (by id)

GET /instances/cockroachdb/<instance_id>/certificates/<ca_certificate_id>/?type=intermediate

Returns a specific CockroachDB instance CA certificate.

Example response

{
  "id": "871f38e9-9c79-4de8-b79e-1cb8cf30d183",
  "clientCertificates": [],
  "dtCreated": "2019-09-04T15:11:24.791049Z",
  "dtModified": "2019-09-04T15:11:24.791080Z",
  "dtDeleted": null,
  "expiration": null,
  "name": "instance_intermediate_ca",
  "primary": true,
  "instance": "f50ea96f-bd62-4195-a66a-d1c65aa4385a"
}

CA certificates with PEM data

GET /instances/cockroachdb/<instance_id>/certificates/<ca_certificate_id>/?type=intermediate&download=true

Example response

{
  "id": "871f38e9-9c79-4de8-b79e-1cb8cf30d183",
  "clientCertificates": [
    {
      "id": "f18fe623-710c-495e-957e-191346f05b78",
      "dtCreated": "2019-09-04T16:06:27.766956Z",
      "statusDisplay": "Active",
      "dtModified": "2019-09-04T16:06:27.767006Z",
      "dtDeleted": null,
      "expiration": null,
      "subjectAlternative": "",
      "status": 2,
      "instance": "f50ea96f-bd62-4195-a66a-d1c65aa4385a",
      "caCertificate": "871f38e9-9c79-4de8-b79e-1cb8cf30d183",
      "certificate": ""
    }
  ],
  "dtCreated": "2019-09-04T15:11:24.791049Z",
  "dtModified": "2019-09-04T15:11:24.791080Z",
  "dtDeleted": null,
  "expiration": null,
  "name": "instance_intermediate_ca",
  "primary": true,
  "instance": "f50ea96f-bd62-4195-a66a-d1c65aa4385a",
  "certificate": "-----BEGIN CERTIFICATE-----\nMIIDjTCCAnWgAwIBAgIUGISqfxcyjB5PkA7fiz7XZIqmhocwDQYJKoZIhvcNAQEL\nBQAwNDEVMBMGA1UEChMMT2JqZWN0cm9ja2V0MRswGQYDVQQDExJsZWFwcGFkIFJv\nb3QgQ0EgWDEwHhcNMTkwOTA0MTUxMDU0WhcNMjgwOTAzMTkzNDEyWjAyMTAwLgYD\nVQQDEydmNTBlYTk2Zi1iZDYyLTQxOTUtYTY2YS1kMWM2NWFhNDM4NWEtQ0EwggEi\nMA0GCSqGSIb3DQEBAQUAA4IBDwAwggEKAoIBAQDXOK4D+gs2O3n/AqcVW773DB+r\njiPSz/16RJkJHOfIaS7/u5kAG6IR7mOJIzLGsqJJl2/a3vBPWOvuvx1N4rtAVW4C\nQIou1ONBsPuf9p+DKcrc7W/LCfrMVSLNC55nz1HBLSEA1zZlyagE2GdI4/aF+SHN\nNHXq2rUD6G/svJMYrY3rSuylpbBupjbuGpS3VQHj1cnG2sV1FplpmWIBxwKwgQqv\nAubx5suOVEmTduxFPESg9NUb8PU67PO86POCcuu9S0jvRwCFKGfRQ+2w+k0YKYcy\njdA765SFG999yGrYGFpF/cxJxuxH3M00VqHIf1c3CXewbyAwu8rafo3n58bXAgMB\nAAGjgZgwgZUwDgYDVR0PAQH/BAQDAgEGMA8GA1UdEwEB/wQFMAMBAf8wHQYDVR0O\nBBYEFAWIP3yi9QPB9auEUHIvFRVcWPw3MB8GA1UdIwQYMBaAFCp70vxYhxnUHzRL\nXMsibH9Q4jvZMDIGA1UdEQQrMCmCJ2Y1MGVhOTZmLWJkNjItNDE5NS1hNjZhLWQx\nYzY1YWE0Mzg1YS1DQTANBgkqhkiG9w0BAQsFAAOCAQEAjHLJD8ifvRMt2ithwJig\nciI7OexeA+BpdlO704YSLDu5J8BLRHPX8LY2iGLU7RI5Crdinbd8Bi8JclSJcOI9\nJks6DmZXu/TAXrNCZ+f1n50EwYelzNGOi31yAEfJjETpxGOh3d9RT2gVUJDiNkLP\n56BYyVtDcnhGbXgtTRSj8fpoEtqxbDnunloQyU3kXTMKK2g+BH+9BTMIsiZf9KLy\nD3wJqV1k71/k/ajgBNk8V+8tmEtDUwF9rN56qiPti80qMWU3IpKdSltzNq4z7K/Z\n5eyUpBt5ohAcokdfZW+mJvh82nqxFe8Mss63ZvVAV32VuMneQ97jyVuCrLOAqyIw\nVA==\n-----END CERTIFICATE-----"
}

CA - Create a CockroachDB certificate

POST /instances/cockroachdb/<instance_id>/certificates/

Create a new CockroachDB CA certificate. A successful request will return HTTP 200.

Body Parameters

Parameter Default Required Description
cert_type none true certificate type; must be "intermediate"

Example request

{
    "cert_type": "intermediate"
}

Example response

{
  "id": "728edd1e-02c2-49a2-9859-58fdeac33df2",
  "transactionId": "74d8470e-d1f4-40b8-b089-86545b1c88dc"
}

CA - Delete a CockroachDB certificate

DELETE /instances/cockroachdb/<instance_id>/certificates/

NOTE: Calling this endpoint will remove the secondary CA on your instance thus completing CA rotation process. Make sure to take precautions and use sparingly.

NOTE: Using this endpoint will complete a CA rotation and thus remove the secondary CA from the instance. All of the associated client certificates (the certs that were signed by the deleted CA) will be deleted as well.

Body Parameters

Parameter Default Required Description
cert_type none true certificate type; must be "intermediate"

Example request

{
    "cert_type": "intermediate"
}

Success HTTP Status Code: 202 ACCEPTED

Example response

{
    "detail": "CA Certificate deletion was accepted for instance 707034c3-a220-485f-b0cc-c6f32e5a0088"
}

Client - List all CockroachDB certificates

GET instances/cockroachdb/<instance_id>/certificates/?type=client

Returns a list of all CockroachDB Instance client certificates.

Example response

[
  {
    "id": "f18fe623-710c-495e-957e-191346f05b78",
    "dtCreated": "2019-09-04T16:06:27.766956Z",
    "statusDisplay": "Requested",
    "dtModified": "2019-09-04T16:06:27.767006Z",
    "dtDeleted": null,
    "expiration": null,
    "subjectAlternative": "",
    "username": "rrtestuser",
    "status": 1,
    "instance": "f50ea96f-bd62-4195-a66a-d1c65aa4385a",
    "caCertificate": "871f38e9-9c79-4de8-b79e-1cb8cf30d183"
  }
]

Client - Get specific CockroachDB Certificate (by id)

GET /instances/cockroachdb/<instance_id>/certificates/<client_certificate_id>/?type=client

Example response

{
  "id": "f18fe623-710c-495e-957e-191346f05b78",
  "dtCreated": "2019-09-04T16:06:27.766956Z",
  "statusDisplay": "Active",
  "dtModified": "2019-09-04T16:06:27.767006Z",
  "dtDeleted": null,
  "expiration": null,
  "subjectAlternative": "",
  "username": "rrtestuser",
  "status": 2,
  "instance": "f50ea96f-bd62-4195-a66a-d1c65aa4385a",
  "caCertificate": "871f38e9-9c79-4de8-b79e-1cb8cf30d183"
}

Client certificates with PEM data

GET /instances/cockroachdb/<instance_id>/certificates/<client_certificate_id>/?type=client&download=true

Example response

{
  "id": "f18fe623-710c-495e-957e-191346f05b78",
  "dtCreated": "2019-09-04T16:06:27.766956Z",
  "statusDisplay": "Active",
  "dtModified": "2019-09-04T16:06:27.767006Z",
  "dtDeleted": null,
  "expiration": null,
  "subjectAlternative": "",
  "username": "rrtestuser",
  "status": 2,
  "instance": "f50ea96f-bd62-4195-a66a-d1c65aa4385a",
  "caCertificate": "871f38e9-9c79-4de8-b79e-1cb8cf30d183",
  "certificate": "-----BEGIN CERTIFICATE-----\nMIIEdTCCA12gAwIBAgIUGu6S00ZKKuXbuoW+rvNsxCb8elYwDQYJKoZIhvcNAQEL\nBQAwMjEwMC4GA1UEAxMnZjUwZWE5NmYtYmQ2Mi00MTk1LWE2NmEtZDFjNjVhYTQz\nODVhLUNBMB4XDTE5MDkwNDE2MDU1OFoXDTE5MTAwNjE2MDYyOFowKzEUMBIGA1UE\nChMLcnJTdGdUZXN0MTgxEzARBgNVBAMTCnJydGVzdHVzZXIwggIiMA0GCSqGSIb3\nDQEBAQUAA4ICDwAwggIKAoICAQNS0ptZyhJeKj0Ohcld8hr1ISxK9iZ2PEOOlwfc\nOVHVkT5Wt73JKaijHaMFX/djJD/eb12qpVMBXK80m394P9zDPg4MF4+u8CaWtvaW\nt5XOd3WtCaryw/19rruLIO2HHnut38xgisYZ0cMwUePR6LxipUjwJxTZ4Fvvt4GW\n9xn2es5rkMPt+MUDarhvbTIxLua3NcWxdcE5aNKq4sslKdrxohlb6s7y3zv9t/d1\n1MpHYQiIznziC/ySuRlMAwHCSYqZkq+dHVGcEKZy5JUt1gyQMQZ2YL71nRxNf9FX\ngP/TPzT9Ou8d0Zm2FygNvLgGsE/BWIKOgMVCqsV/zJeDb7Gdtu3OeHJ69pRtzYU7\nzXKolpm8BHG4EDu/CbVfeuNRbV8GinRLCNY4HmNgJQg/S2CYBG2j+ERpO61Dm7ko\nbOACBmny/WGMdLB3MkLtCvD7ASdvDo4ldzfGYHxSxDBubsUGCnhef/8U8QZJ4YnW\nmCbIbE50zDofS980xRMDDK3xhktL9A+1zk/0/M8PVQCeKJ2DLEyyYmeqwZLkYN1y\n2DDJ3D71mVj2vxSGBPxN7c8Q4P6jzJy4LafF9OahqIDZzxAVy4HUCEltG3hKXMiw\nRrWmXAHjW6rIxuIDan4CSjJbMmHWYQ7Hml64l5WnQG8GmBZEq6cen235nm3iYdsm\nKm7QiwIDAQABo4GJMIGGMA4GA1UdDwEB/wQEAwIDqDAdBgNVHSUEFjAUBggrBgEF\nBQcDAQYIKwYBBQUHAwIwHQYDVR0OBBYEFKXzsFBe2ZYpw5uYBiy8j0n2QNfwMB8G\nA1UdIwQYMBaAFAWIP3yi9QPB9auEUHIvFRVcWPw3MBUGA1UdEQQOMAyCCnJydGVz\ndHVzZXIwDQYJKoZIhvcNAQELBQADggEBAI6IQGzZ6ITW+dKVDA1hV3gkgQNZcE0I\nFBiB79N5DobMI/Z3PlGsM8aGhcD3HK3mt73tCh1Pfnv65sUgrNqsDaeq9rYRuOqh\nZDhFuET04M/HdNdkeEad1efl/Ax/b5phcc/fjVmm40RxpEcL16O6DPtFgm6G7d6f\nkZ/UmD7o856Gvdtjq4U+QCD0sRSJOojUJHY3NQZtSGMmb1polr3LUAY5WWr3FDOV\nQARQLsohOMohUnnpeSo5VvNgCUn23b3nEyy9rXvVq3rc/ejXFaDKtifEY/VBs9HD\nLb+D/dxeuW9U+b6HRw8G4c5airfYJiwRUqMetBkQu3DsVxxL7an0pk0=\n-----END CERTIFICATE-----"
}

Client - Create a CockroachDB certificate

POST /instances/cockroachdb/<instance_id>/certificates/

Create a new CockroachDB client certificate. A successful request will return HTTP 200.

Body Parameters

Parameter Default Required Description
cert_type none true certificate type; must be "client"
certificate_signing_request none true a valid CSR PEM data string (Only the CN attribute is accepted and it must be your database Username)

Example request

{
    "cert_type": "client",
    "certificate_signing_request": "-----BEGIN CERTIFICATE REQUEST-----\nMIICWjCCAUICAQAwFTETMBEGA1UEAwwKcnJ0ZXN0dXNlcjCCASIwDQYJKoZIhvcN\nAQEBBQADggEPADCCAQoCggEBAMqWiwPSP39+3Y81U+L5RYkn2AEpF2lRFeCVipyL\nUyAO4s2rhJUr0kBElOk9UQt5kWcZBEV0X0+HUzSieGNZ83a0XVQdII0ceALj16ri\nOm6ge/aU89glsM1DgGaYN6UTtoAV+C0jWBbp68XpZN0SV7kdUIinkpZhcQl2/1rA\nXH07WFRbIvXBAsKwK0tDTX2Zo+oelhbQzCQGai2+yIc+PS0qpRxoXuugbzVfLux4\n8cqCuHua9PfEdXHzB13j3NBQ3qjGvpOBTCNsCff4muJ/WQRQBWC7gQ/5J/g1FwWT\nBSFIfZWt9WoiGJJpEciAMUmkVbQUEN8dxilnxCWCkFmLJ2cCAwEAAaAAMA0GCSqG\nSIb3DQEBCwUAA4IBAQCbiUR6Ry74VOdEWcQ/a8iO7EgJub5zzClzdyutAgdtPifB\npYe9nm/PuwXMEhBeFWSd6s7+Nal4JJoRFvQTKX3DTdTa6xXJ1mAYB5pV+BZVsAzy\ny9UT3CZVRqO4DsGz/Lol1QAeDrzPawTxBffIPz4fj4Fvai6Q+UtwAeM0F113ybXL\nkB9SJtwDtAP23EaFfjM+xh+6FyiLlbtciOuIqPkA5gVpkBmPL0oLIlZW23/NFNOM\ndwKUqF8BSoG6SbG5B2EQrE7dTBlWv+0cUhGAIzS+4GhLT7S3yALASGccVFHzwFSm\nHuChcRjAW3XXz/IYwGa7dZmNTBiWUq27l9f1QphN\n-----END CERTIFICATE REQUEST-----"
}

Example response

{
  "id": "f18fe623-710c-495e-957e-191346f05b78",
  "transactionId": "6ce86bbc-866b-45b2-965d-1833254a8dec"
}

Client - Delete a CockroachDB certificate

DELETE /instances/cockroachdb/<instance_id>/certificates/

Body Parameters

Parameter Default Required Description
cert_type none true certificate type; must be "client"
certificate_id none true the client certificate pk id

Example request

{
    "cert_type": "client",
    "certificate_id": "3598b33b-5fad-4697-9c03-6ce5ff134263"
}

Success HTTP Status Code: 202 ACCEPTED

Example response

{
    "detail": "Certificate deletion was accepted for instance 707034c3-a220-485f-b0cc-c6f32e5a0088"
}

PostgreSQL Instances

List all PostgreSQL instances

GET /instances/postgresql/

Returns a list of all PostgreSQL instances.

Example response

Success HTTP Status Code: 200 OK

[
  {
    "id": "eb9add74-6663-4ad8-a4a9-c387900009db",
    "name": "pgsql-test1",
    "service": "PostgreSQL",
    "hosts": [
      {
        "id": "9b9a2ad1-5196-4c11-9b0e-db90997ab889",
        "connectionUri": "postgres://<username>:<password>@ingress.w98sujpz.launchpad.objectrocket.cloud:4115/postgres?sslmode=require",
        "dtCreated": "2019-07-01T15:50:31.023744Z",
        "dtModified": "2019-07-01T15:50:37.101465Z",
        "dtDeleted": null,
        "role": "postgresql",
        "fqdn": "ingress.w98sujpz.launchpad.objectrocket.cloud",
        "port": 4115,
        "cpu": "0.2",
        "memoryMb": 1024,
        "diskSizeGb": 20,
        "iops": 0,
        "metadata": null,
        "quantity": 1
      }
    ],
    "features": {},
    "settings": {},
    "acls": [
      {
        "id": "1de94e87-97b6-4f50-89f9-8920e5b4fea5",
        "cidr": "0.0.0.0/0",
        "instance": "eb9add74-6663-4ad8-a4a9-c387900009db",
        "kind": 8,
        "dtCreated": "2019-07-01T15:49:53.640199Z",
        "dtModified": "2019-07-01T15:49:53.640219Z",
        "dtDeleted": null,
        "name": "anyipacl"
      }
    ],
    "statusDisplay": "Ready",
    "metadata": {},
    "dtCreated": "2019-07-01T15:49:53.385027Z",
    "dtModified": "2019-07-01T15:49:53.385054Z",
    "dtDeleted": null,
    "provider": "AWS",
    "version": "12.3",
    "status": 1,
    "organization": "4f10ffde-247f-4286-8ba6-31996baf67bf",
    "region": "us-east-1",
    "serviceSubtype": "postgresql_cluster",
    "connectionString": "postgres://USERNAME:PASSWORD@ingress.w98sujpz.launchpad.objectrocket.cloud:4115/postgres?sslmode=require"
  }
]

Get specific PostgreSQL instance (by id)

GET /instances/postgresql/<instance_id>/

Returns a specific PostgreSQL instance.

Example response

Success HTTP Status Code: 200 OK

{
  "id": "eb9add74-6663-4ad8-a4a9-c387900009db",
  "name": "pgsql-test1",
  "service": "PostgreSQL",
  "hosts": [
    {
      "id": "9b9a2ad1-5196-4c11-9b0e-db90997ab889",
      "connectionUri": "postgres://<username>:<password>@ingress.w98sujpz.launchpad.objectrocket.cloud:4115/postgres?sslmode=require",
      "dtCreated": "2019-07-01T15:50:31.023744Z",
      "dtModified": "2019-07-01T15:50:37.101465Z",
      "dtDeleted": null,
      "role": "postgresql",
      "fqdn": "ingress.w98sujpz.launchpad.objectrocket.cloud",
      "port": 4115,
      "cpu": "0.2",
      "memoryMb": 1024,
      "diskSizeGb": 20,
      "iops": 0,
      "metadata": null,
      "quantity": 1
    }
  ],
  "features": {},
  "settings": {},
  "acls": [
    {
      "id": "1de94e87-97b6-4f50-89f9-8920e5b4fea5",
      "cidr": "0.0.0.0/0",
      "instance": "eb9add74-6663-4ad8-a4a9-c387900009db",
      "kind": 8,
      "dtCreated": "2019-07-01T15:49:53.640199Z",
      "dtModified": "2019-07-01T15:49:53.640219Z",
      "dtDeleted": null,
      "name": "anyipacl"
    }
  ],
  "statusDisplay": "Ready",
  "metadata": {},
  "dtCreated": "2019-07-01T15:49:53.385027Z",
  "dtModified": "2019-07-01T15:49:53.385054Z",
  "dtDeleted": null,
  "provider": "AWS",
  "version": "12.3",
  "status": 1,
  "organization": "4f10ffde-247f-4286-8ba6-31996baf67bf",
  "region": "us-east-1",
  "serviceSubtype": "postgresql_cluster",
  "connectionString": "postgres://USERNAME:PASSWORD@ingress.w98sujpz.launchpad.objectrocket.cloud:4115/postgres?sslmode=require"
}

Create a PostgreSQL instance

POST /instances/postgresql/

Requests that a PostgreSQL instance be created by the build system.

A successful request will return HTTP 202. At this point the instance will have a status of 4 and status_display of Create Requested and will transition to status of 7 and status_display of Building. Once the instance has been fully built out the record will be updated to status 1 and status_display Ready. Additionally the record will be updated with member hosts, connection strings, etc.

Body parameters to create a PostgreSQL instance

Parameter Default Required Description
acls none false creates acls for instance on build
features none false To specify any additional instance features. Eg: addons.
features.addons none false To specify addons (see List addons).
name none true a name for the instance
plan none true a valid plan identifier (see List plans)
provider none true currently only AWS (see List cloud providers)
region none true which cloud region to deploy to, e.g. us-east-1 (see List regions)
service none true which service is requested (see List services)
serviceSubtype none true a valid service subtype for PostgreSQL (see List service subtypes)
settings none false settings for instance like custom configurations
settings.datastoreConfigurations none false key-value pairs of custom PostgreSQL settings. For a valid list (see List configurations)
version none true requested version of service (see List versions)

Example request

{
    "plan": "Standard_20GB",
    "name": "postgresql-test",
    "version": "12.3",
    "region": "us-east-1",
    "provider": "AWS",
    "service": "PostgreSQL",
    "features": {},
    "settings": {},
    "serviceSubtype": "postgresql_cluster"
}

Example request to create a PostgreSQL instance with custom configs

{
    "plan": "Standard_20GB",
    "name": "postgresql-test",
    "version": "12.3",
    "region": "us-east-1",
    "provider": "AWS",
    "service": "PostgreSQL",
    "features": {},
    "settings": {
      "datastoreConfigurations": {
        "max_connections": 50,
        "log_executor_stats": "on"
      }
    },
    "serviceSubtype": "postgresql_cluster"
}

Example response

Success HTTP Status Code: 202 Accepted

{
  "id": "728edd1e-02c2-49a2-9859-58fdeac33df2",
  "transactionId": "74d8470e-d1f4-40b8-b089-86545b1c88dc"
}

Rename a PostgreSQL instance

PATCH /instances/postgresql/<instance_id>/

Requests the instance be renamed to the specified value.

Body parameters to rename a PostgreSQL instance

Parameter Default Required Description
name none true a name for the instance

Example request

{
    "name": "adifferentname"
}

Example response

Success HTTP Status Code: 200 OK

{
  "id": "eb9add74-6663-4ad8-a4a9-c387900009db",
  "name": "adifferentname",
  "service": "PostgreSQL",
  "hosts": [
    {
      "id": "9b9a2ad1-5196-4c11-9b0e-db90997ab889",
      "connectionUri": "postgres://<username>:<password>@ingress.w98sujpz.launchpad.objectrocket.cloud:4115/postgres?sslmode=require",
      "dtCreated": "2019-07-01T15:50:31.023744Z",
      "dtModified": "2019-07-01T15:50:37.101465Z",
      "dtDeleted": null,
      "role": "postgresql",
      "fqdn": "ingress.w98sujpz.launchpad.objectrocket.cloud",
      "port": 4115,
      "cpu": "0.2",
      "memoryMb": 1024,
      "diskSizeGb": 20,
      "iops": 0,
      "metadata": null,
      "quantity": 1
    }
  ],
  "features": {},
  "settings": {},
  "acls": [
    {
      "id": "1de94e87-97b6-4f50-89f9-8920e5b4fea5",
      "cidr": "0.0.0.0/0",
      "instance": "eb9add74-6663-4ad8-a4a9-c387900009db",
      "kind": 8,
      "dtCreated": "2019-07-01T15:49:53.640199Z",
      "dtModified": "2019-07-01T15:49:53.640219Z",
      "dtDeleted": null,
      "name": "anyipacl"
    }
  ],
  "statusDisplay": "Ready",
  "metadata": {},
  "dtCreated": "2019-07-01T15:49:53.385027Z",
  "dtModified": "2019-07-01T15:49:53.385054Z",
  "dtDeleted": null,
  "provider": "AWS",
  "version": "12.3",
  "status": 1,
  "organization": "4f10ffde-247f-4286-8ba6-31996baf67bf",
  "region": "us-east-1",
  "serviceSubtype": "postgresql_cluster"
}

Delete a PostgreSQL instance

DELETE /instances/postgresql/<instance_id>/

Requests that a PostgreSQL instance be deleted.

This will set the instance to status 6 (Delete Requested). The status will be updated to 3 (Deleted) once the resources have been removed.

Delete requests currently return no body and a response code of 204.

Example response

Create a High-Availability PostgreSQL instance

Create an HA PostgreSQL instance

POST /instances/postgresql/

Refer here for details on creating a PostgreSQL instance.

Additional body parameters to specify in order to create an HA postgresql instance.

Parameter Default Required Description
features.addons.replicas_for_ha none false Number of replicas to configure instance for High-Availability. Minimum - 1, Maximum - 2.

Example request

{
    "plan": "Standard_20GB",
    "name": "postgresql-ha-test",
    "version": "12.2",
    "region": "us-east-1",
    "provider": "AWS",
    "service": "PostgreSQL",
    "features": {
        "addons": {
            "replicas_for_ha": 2
        }
    },
    "settings": {},
    "serviceSubtype": "postgresql_cluster"
}

Example response

Success HTTP Status Code: 202 Accepted

{
  "id": "728edd1e-02c2-49a2-9859-58fdeac33df2",
  "transactionId": "74d8470e-d1f4-40b8-b089-86545b1c88dc"
}

Restore PostgreSQL Instance from Backup

Restore a PostgreSQL instance from backup

POST /instances/postgresql/

Refer here for details on creating a PostgreSQL instance.

Refer here for details on listing backups to find the requested backup.

Additional body parameters to restore a PostgreSQL instance

Parameter Default Required Description
settings none false To specify any create settings
settings.restoreFromBackup none false To specify restore specific settings
settings.restoreFromBackup.instanceId none true The id of the instance to restore from. Instances must be owned by the organization requesting the restore. When no backupId or restoreTimestamp is included, the new instance is restored to the latest state of the source instance's WAL archives
settings.restoreFromBackup.backupId none false The id of the backup to restore from. Backup must be from the instance specified by the instanceId (above)
settings.restoreFromBackup.restoreTimestamp none false The timestamp upto which the backup is to be restored, to support Point In Time Recovery (PITR). Accepted format - 'YYYY-MM-DDThh:mm:ssZ'. Example: 2019-07-26T23:00:00Z. The closest previous successful full backup and WAL archives until the specified timestamp will be used for restore

Note

  1. WAL archives are updated depending on volume of updates.
  2. Always specify an instanceId.
  3. Include either
    • no other field (full restore to the latest state of the source instance's WAL archives),
    • a backupID (to restore up till that backup),
    • a restoreTimestamp (to restore up till that time)
  4. If both backupId and restoreTimestamp are included, restoreTimestamp will be preferred.
  5. The provider, region, service, serviceSubtype, and version of the restored instance should be the same as the source instance of the backup, being specified for restore.
  6. The storage size of the plan should also be equal to or greater than the source instance storage size.
  7. The organization of the source instance should match that of the restored instance.

To use the latest available full backup of a specified instance: example request

{
    "plan": "Standard_20GB",
    "name": "postgresql-test",
    "version": "12.3",
    "region": "us-east-1",
    "provider": "AWS",
    "service": "PostgreSQL",
    "features": {},
    "settings": {
        "restoreFromBackup": {
            "instanceId": "afa83127-f122-40a6-a7f7-b0a5e9a056cc"
        }
    },
    "serviceSubtype": "postgresql_cluster"
}

Example response

Success HTTP Status Code: 202 Accepted

{
  "id": "728edd1e-02c2-49a2-9859-58fdeac33df2",
  "transactionId": "74d8470e-d1f4-40b8-b089-86545b1c88dc"
}

To restore an instance using a backup Id: example request

{
    "plan": "Standard_20GB",
    "name": "postgresql-test",
    "version": "12.3",
    "region": "us-east-1",
    "provider": "AWS",
    "service": "PostgreSQL",
    "features": {},
    "settings": {
        "restoreFromBackup": {
            "instanceId": "afa83127-f122-40a6-a7f7-b0a5e9a056cc",
            "backupId": "2bc70e37-484b-4055-a9f5-40f2f3345829"
        }
    },
    "serviceSubtype": "postgresql_cluster"
}

Example response

{
  "id": "728edd1e-02c2-49a2-9859-58fdeac33df2",
  "transactionId": "74d8470e-d1f4-40b8-b089-86545b1c88dc"
}

PITR of an instance: example request

{
    "plan": "Standard_20GB",
    "name": "postgresql-test",
    "version": "12.3",
    "region": "us-east-1",
    "provider": "AWS",
    "service": "PostgreSQL",
    "features": {},
    "settings": {
        "restoreFromBackup": {
            "instanceId": "afa83127-f122-40a6-a7f7-b0a5e9a056cc",
            "restoreTimestamp": "2019-07-26T23:00:00Z"
        }
    },
    "serviceSubtype": "postgresql_cluster"
}

Example response

{
  "id": "728edd1e-02c2-49a2-9859-58fdeac33df2",
  "transactionId": "74d8470e-d1f4-40b8-b089-86545b1c88dc"
}

PostgreSQL Users

Create a user for a PostgreSQL instance

POST /instances/postgresql/<instance_id>/users/

Creates a new user for the specified PostgreSQL instance (ID).

Note on usernames: pg_ or objectrocket_ cannot be used as prefixes to usernames as these prefixes are reserved for PostgreSQL built-in roles and ObjectRocket system users.

Body parameters to create a PostgreSQL user

Parameter Default Required Description
username none true Name of the user/PostgreSQL role. Avoid using pg_ or objectrocket_ as a user prefix since this naming convention is used for built-in roles and system users.
password none true Password of the user for password authentication.
roles none true List of user privileges. Refer below table for additional details.

PostgreSQL privileges assigned for a specific role included in roles parameter

Role PostgreSQL privilges assigned by system Description
admin LOGIN, CREATEROLE, CREATEDB This role can be used to create and manage permissions of other users/roles

Example request

{
    "username": "myadmin",
    "password": "myadminpswd",
    "roles": ["admin"]
}

Example response

Success HTTP Status Code: 201 Created

{
    "detail": "User successfully created for instance afa83127-f122-40a6-a7f7-b0a5e9a056cc"
}

List users for a PostgreSQL instance

GET /instances/postgresql/<instance_id>/users/

Gets the user list for the specified PostgreSQL instance (ID).

This is meant to mimic the built-in \du query on a PostgreSQL instance. Like the standard \du query to list users, this endpoint does not return the default roles.

This endpoint will also return ObjectRocket-specific system users, which are used for replication, metrics, etc. These system users cannot be deleted or interacted with through the API and should not be deleted in the PostgreSQL instance.

Example response

Success HTTP Status Code: 200 OK

[
  {
    "username":"cluster_admin_user"
  },
  {
    "username":"my_app"
  },
  {
    "username":"objectrocket_admin",
    "systemUser": true
  },
  {
    "username":"objectrocket_postgres_exporter",
    "systemUser": true
  },
  {
    "username":"objectrocket_replicationuser",
    "systemUser": true
  },
  {
    "username":"postgres",
    "systemUser": true
  }
]

Delete a user from a PostgreSQL instance

DELETE /instances/postgresql/<instance_id>/users/

Deletes a user from the specified PostgreSQL instance (ID).

Built-in and system users cannot be deleted (see Create a user for a PostgreSQL instance).

Body parameters to delete a PostgreSQL user

Parameter Default Required Description
username none true Name of the user/PostgreSQL role.

Example request

{
    "username": "myadmin"
}

Success HTTP Status Code: 200 OK

Example response

{
  "detail": "User successfully deleted from instance afa83127-f122-40a6-a7f7-b0a5e9a056cc"
}

Update Configuration for PostgreSQL Instance

Update configuration for PostgreSQL Instance

PATCH /instances/postgresql/<instance_id>/

This endpoint uses the JSON Merge Patch Strategy for applying settings.

NOTE: Settings with the attribute "restartRequired" will trigger a restart of PostgreSQL. See List configurations to verify if the option(s) being modified require a restart.

Body parameters to update the configuration of a PostgreSQL instance

Parameter Default Required Description
settings.datastoreConfigurations none false To specify updated settings. Simply specify the PostgreSQL configuration setting as a key and the desired value. To remove a setting, set its value to "null". These settings will override any defaults. See List configurations for the configurable options, including defaults and allowable settings.

Max Connections

The maximum number of max_connections is based on plan size

Plan (Mem) Maximum max_connections
1GB 112
2GB 225
4GB 450
8GB 901
16GB 1802
24GB 2703

Example request to update the configuration of a PostgreSQL instance

{
  "settings": {
    "datastoreConfigurations": {
      "max_connections": 50,
      "log_executor_stats": "on"
    }
  }
}

Example response

Success HTTP Status Code: 202 Accepted

{
  "id": "d9d9aba0-aaf7-48da-8144-affe274aafe5",
  "service": "PostgreSQL",
  "hosts": [
    {
      "id": "54253cb3-7030-47e8-8a2a-cfe4c737a101",
      "connectionUri": "postgres://<username>:<password>@192.168.99.101:4129/postgres?sslmode=require",
      "dtCreated": "2017-03-28T19:40:52.341000Z",
      "dtModified": "2017-03-28T19:40:52.341000Z",
      "dtDeleted": null,
      "role": "postgresql",
      "fqdn": "192.168.99.101",
      "port": 4129,
      "cpu": "1.0",
      "memoryMb": 512,
      "diskSizeGb": 10,
      "iops": 1000,
      "metadata": {},
      "quantity": 1
    }
  ],
  "acls": [],
  "statusDisplay": "Ready",
  "serviceSubtype": "postgresql_cluster",
  "dtCreated": "2020-02-07T17:22:38.609326Z",
  "dtModified": "2020-02-07T17:22:38.609354Z",
  "dtDeleted": null,
  "provider": "AWS",
  "name": "pgsql-test1",
  "version": "12.3",
  "features": {},
  "settings": {
    "datastoreConfigurations": {
      "maxReplicationSlots": 15,
      "maxWorkerProcesses": 10
    }
  },
  "metadata": {},
  "status": 1,
  "organization": "72b46554-e135-43ab-a638-c27c940e5b90",
  "region": "us-east-1"
}

PostgreSQL/TimescaleDB Extensions

The timescaledb extension is not available in PostgreSQL instances but is built in to TimescaleDB instances. TimescaleDB and PostgreSQL instances share all other extensions.

PostgreSQL extensions are packaged modules that add or extend certain related functionality to the database.

For instance, if a database required cryptographic functions (for encrypting and decoding passwords), you could install the pgcrypto extension, which provides functions for generating and validating encrypted test.

For more on extensions, see here.

Adding Extensions

You can add extensions to your PostgreSQL instance with the following command:

CREATE EXTENSION <<extension_name_here>>;

Available Extensions

You can see what extensions are available in your PostgreSQL instance with the following command:

SHOW extwlist.extensions;

PostgreSQL instances have the following extensions available for installation out of the box:

Extension Notes
address_standardizer docs
address_standardizer_data_us docs
amcheck docs
autoinc docs
bloom docs
btree_gin docs
btree_gist docs
citext docs
cube docs
dblink docs
dict_int docs
dict_xsyn docs
earthdistance docs
fuzzystrmatch docs
hstore docs
insert_username docs
intagg docs
intarray docs
isn docs
lo docs
ltree docs
moddatetime docs
pageinspect docs
pg_buffercache docs
pgcrypto docs
pg_freespacemap docs
pg_prewarm docs
pg_repack docs
pgrowlocks docs
pg_stat_statements docs
pgstattuple docs
pg_trgm docs
pg_visibility docs
plperl docs
postgis docs
postgis_sfcgal docs
postgis_tiger_geocoder docs
postgis_topology docs
postgres_fdw docs
refint docs
seg docs
sslinfo docs
tablefunc docs
tcn docs
timetravel docs -- only available in PostgreSQL 11.5
tsm_system_rows docs
tsm_system_time docs
unaccent docs
uuid-ossp docs
xml2 docs

PostgreSQL Certificate Instructions

Connecting to your database instance securely with TLS/SSL

Refer to the PostgreSQL SSL support documentation to understand various ssl modes. The below steps outline the process of CA cert retrieval, which can be used additionally to verify the server ('verify-ca' sslmode).

  1. List CA certificates for your PostgreSQL database instance as shown here: List certs.

  2. Retrieve CA certificate using the certificate id as shown here: Get cert. Pay close attention to the URL params type=intermediate and download=true, both of these params must be present to get the certificate.

  3. Copy the pem data (present on the "certificate" attribute of the response) into an empty file /path/to/certs/ca. Note that the newlines (\n) in the json output should be dereferenced correctly. Example: sed 's/\\n/\'$'\n''/g' /path/to/certs/ca > /path/to/certs/sslca.pem.

  4. Now, connect securely to your instance:

Example connection

psql 'postgres://myusername:mypassword@ingress.w98sujpz.launchpad.objectrocket.cloud:4097/postgres?sslmode=verify-ca&sslrootcert=/path/to/certs/sslca.pem'

PostgreSQL Certificates

CA - List all PostgreSQL instance certificates

GET instances/postgresql/<instance_id>/certificates/?type=intermediate

Example response

Success HTTP Status Code: 200 OK

[
  {
    "id": "871f38e9-9c79-4de8-b79e-1cb8cf30d183",
    "clientCertificates": [],
    "dtCreated": "2019-09-04T15:11:24.791049Z",
    "dtModified": "2019-09-04T15:11:24.791080Z",
    "dtDeleted": null,
    "expiration": "2019-12-25T10:00:00.578000Z",
    "name": "instance_intermediate_ca",
    "primary": true,
    "instance": "f50ea96f-bd62-4195-a66a-d1c65aa4385a"
  }
]

CA - Get specific PostgreSQL instance certificate (by id)

GET /instances/postgresql/<instance_id>/certificates/<ca_certificate_id>/?type=intermediate

Example response

Success HTTP Status Code: 200 OK

{
    "id": "871f38e9-9c79-4de8-b79e-1cb8cf30d183",
    "clientCertificates": [],
    "dtCreated": "2019-09-04T15:11:24.791049Z",
    "dtModified": "2019-09-04T15:11:24.791080Z",
    "dtDeleted": null,
    "expiration": "2019-12-25T10:00:00.578000Z",
    "name": "instance_intermediate_ca",
    "primary": true,
    "instance": "f50ea96f-bd62-4195-a66a-d1c65aa4385a"
}

CA - Get specific PostgreSQL instance certificate (by id) with PEM data

GET /instances/postgresql/<instance_id>/certificates/<ca_certificate_id>/?type=intermediate&download=true

Example response

Success HTTP Status Code: 200 OK

{
   "id":"871f38e9-9c79-4de8-b79e-1cb8cf30d183",
   "clientCertificates":[],
   "dtCreated":"2019-09-04T15:11:24.791049Z",
   "dtModified":"2019-09-04T15:11:24.791080Z",
   "dtDeleted":null,
   "expiration":"2019-12-25T10:00:00.578000Z",
   "name":"instance_intermediate_ca",
   "primary":true,
   "instance":"f50ea96f-bd62-4195-a66a-d1c65aa4385a",
   "certificate":"-----BEGIN CERTIFICATE-----\nMIIDXTCCAkWgAwIBAgIQClXvAC05ndGrOtV0jjI/lTANBgkqhkiG9w0BAQsFADBE\nMRwwGgYDVQQKExNQb3N0Z3JlU1FMIE9wZXJhdG9yMSQwIgYDVQQDExtwb3N0Z3Jl\nc3FsLm9iamVjdHJvY2tldC5jb20wHhcNMTkwODE2MjAwNjA1WhcNMTkxMTE0MjAw\nNjA1WjBEMRwwGgYDVQQKExNQb3N0Z3JlU1FMIE9wZXJhdG9yMSQwIgYDVQQDExtw\nb3N0Z3Jlc3FsLm9iamVjdHJvY2tldC5jb20wggEiMA0GCSqGSIb3DQEBAQUAA4IB\nDwAwggEKAoIBAQDIEwhfZ6ymYd6WCpuwEWGc5g9nYIZDjQQKneB7U5OBeOGSC14F\nl2BGqZe89ndQ6qUj8znfokfbWFqUvRuTc15RgPmB31xy79lP/0LbzY6YOL9/Wk64\nw2FSB5rEF6q3eHeMas9MOtpchVZIhGoUndTl2ZNP0rhTxd9PTe5DVHsuhsGU/xgd\nnNAJYKpYpf3gyaMYV8RQqjtAlcr1xT+8Sfv4HO36IRzkU6D1oQFIRsGhhvAuEvra\n9ESRqxjAeDF1O6tgzOGo0TmlE4opBOgy/SIPkUl+gfJsZISyCCQr+Vtl24iTN03N\nxqT0hSrcugqCmz+OMHhzECs7xag58XgkC5lvAgMBAAGjSzBJMA4GA1UdDwEB/wQE\nAwICpDAPBgNVHRMBAf8EBTADAQH/MCYGA1UdEQQfMB2CG3Bvc3RncmVzcWwub2Jq\nZWN0cm9ja2V0LmNvbTANBgkqhkiG9w0BAQsFAAOCAQEArASbcFYtOV3AAgZthIa1\n43uOFPrD3PUW7LtoYwZqAuRqasB4v9tq4oCui1ZnrU2XdAIHB0ZORXqBpM+AE6kJ\nxEJDI5saXefJs5Df1GfYWZDheIEK3vMSUK7AegZjT98fno2RzhSJenXfkaJ2JOIX\n1tVF5Ik00DMybFbNdicgD+648kLlMGT3NYHE6XRg7bFoWufc/1+UDvWYx9l24m2P\nI1Iu/LCOF0K8wKg0mEHXRGRO2ian2hwi8e4IhMzdaNt1/DQmGrh2LiTfIprwfcw7\n1wrAy/hKwwnwtcFZ9zq2vc4KEX2nSUpHewRPB8D47mYKXdys48rZMUiRIY8T8E3N\nyQ==\n-----END CERTIFICATE-----"
}

TimescaleDB Instances

List all TimescaleDB instances

GET /instances/timescaledb/

Returns a list of all TimescaleDB instances.

Success HTTP Status Code: 200 OK

Example response

[
  {
    "id": "3d41d516-6d21-47f0-9360-2c78972b3c0d",
    "revision": "e07aab59ab5b7b760f9d8370c71518a6",
    "service": "TimescaleDB",
    "hosts": [
      {
        "id": "914d271c-09ed-4389-b288-c02a5570c7f9",
        "revision": "e07aab59ab5b7b760f9d8370c71518a6",
        "connectionUri": "postgres://<username>:<password>@192.168.99.101:3115/postgres?sslmode=require",
        "dtCreated": "2020-02-17T21:20:34.001000Z",
        "dtModified": "2020-02-17T21:20:34.001000Z",
        "dtDeleted": null,
        "role": "timescaledb",
        "fqdn": "192.168.99.101",
        "port": 3115,
        "cpu": "1.0",
        "memoryMb": 512,
        "diskSizeGb": 10,
        "iops": 1000,
        "metadata": {},
        "quantity": 1
      }
    ],
    "acls": [],
    "statusDisplay": "Ready",
    "serviceSubtype": "timescaledb_cluster",
    "dtCreated": "2020-02-17T21:20:34.001000Z",
    "dtModified": "2020-02-17T21:20:34.001000Z",
    "dtDeleted": null,
    "provider": "AWS",
    "name": "ortest_timescaledb",
    "version": "12.3-tsdb-1.7.1",
    "features": {},
    "settings": {},
    "metadata": {},
    "status": 1,
    "organization": "2b258bc1-5791-49ca-a6c3-988a68ef21d9",
    "region": "us-east-1",
    "connectionString": "postgres://USERNAME:PASSWORD@192.168.99.101:3115/postgres?sslmode=require"
  }
]

Get specific TimescaleDB instance (by id)

GET /instances/timescaledb/<instance_id>/

Returns a specific TimescaleDB instance.

Success HTTP Status Code: 200 OK

Example response

{
  "id": "3d41d516-6d21-47f0-9360-2c78972b3c0d",
  "revision": "e07aab59ab5b7b760f9d8370c71518a6",
  "service": "TimescaleDB",
  "hosts": [
    {
      "id": "914d271c-09ed-4389-b288-c02a5570c7f9",
      "revision": "e07aab59ab5b7b760f9d8370c71518a6",
      "connectionUri": "postgres://<username>:<password>@192.168.99.101:3115/postgres?sslmode=require",
      "dtCreated": "2020-02-17T21:20:34.001000Z",
      "dtModified": "2020-02-17T21:20:34.001000Z",
      "dtDeleted": null,
      "role": "timescaledb",
      "fqdn": "192.168.99.101",
      "port": 3115,
      "cpu": "1.0",
      "memoryMb": 512,
      "diskSizeGb": 10,
      "iops": 1000,
      "metadata": {},
      "quantity": 1
    }
  ],
  "acls": [],
  "statusDisplay": "Ready",
  "serviceSubtype": "timescaledb_cluster",
  "dtCreated": "2020-02-17T21:20:34.001000Z",
  "dtModified": "2020-02-17T21:20:34.001000Z",
  "dtDeleted": null,
  "provider": "AWS",
  "name": "ortest_timescaledb",
  "version": "12.3-tsdb-1.7.1",
  "features": {},
  "settings": {},
  "metadata": {},
  "status": 1,
  "organization": "2b258bc1-5791-49ca-a6c3-988a68ef21d9",
  "region": "us-east-1",
  "connectionString": "postgres://USERNAME:PASSWORD@192.168.99.101:3115/postgres?sslmode=require"
}

Create a TimescaleDB instance

POST /instances/timescaledb/

Requests that a TimescaleDB instance be created by the build system.

A successful request will return HTTP 202. At this point the instance will have a status of 4 and status_display of Create Requested and will transition to status of 7 and status_display of Building. Once the instance has been fully built out the record will be updated to status 1 and status_display Ready. Additionally the record will be updated with member hosts, connection strings, etc.

Body parameters to create a TimescaleDB instance

Parameter Default Required Description
acls none false creates acls for instance on build
features none false To specify any additional instance features. Eg: addons.
features.addons none false To specify addons (see List addons).
name none true a name for the instance
plan none true a valid plan identifier (see List plans)
provider none true a valid cloud provider (see List cloud providers)
region none true a valid cloud region to deploy to, e.g. us-east-1 (see List regions)
service none true a valid service to use (see List services)
serviceSubtype none true a valid service subtype for TimescaleDB (see List service subtypes)
settings none false settings for instance like custom configurations
settings.datastoreConfigurations none false key-value pairs of custom TimescaleDB settings. For a valid list (see List configurations)
version none true a valid version of service (see List versions)

Example request: Create a TimescaleDB instance

{
    "plan": "Standard_20GB",
    "name": "timescaledb-test",
    "version": "12.3-tsdb-1.7.1",
    "region": "us-east-1",
    "provider": "AWS",
    "service": "TimescaleDB",
    "features": {},
    "settings": {},
    "serviceSubtype": "timescaledb_cluster"
}

Example request to create a TimescaleDB instance with custom configs

{
    "plan": "Standard_20GB",
    "name": "timescaledb-test",
    "version": "12.3-tsdb-1.7.1",
    "region": "us-east-1",
    "provider": "AWS",
    "service": "TimescaleDB",
    "features": {},
    "settings": {
      "datastoreConfigurations": {
        "max_connections": 50,
        "log_executor_stats": "on"
      }
    },
    "serviceSubtype": "timescaledb_cluster"
}

Example response

Success HTTP Status Code: 202 Accepted

{
  "id": "728edd1e-02c2-49a2-9859-58fdeac33df2",
  "transactionId": "74d8470e-d1f4-40b8-b089-86545b1c88dc"
}

Rename a TimescaleDB instance

PATCH /instances/timescaledb/<instance_id>/

Requests the instance be renamed to the specified value.

Body parameters to rename a TimescaleDB instance

Parameter Default Required Description
name none true a name for the instance

Success HTTP Status Code: 200 OK

Example request

{
    "name": "adifferentname"
}

Example response

{
  "id": "3d41d516-6d21-47f0-9360-2c78972b3c0d",
  "revision": "e07aab59ab5b7b760f9d8370c71518a6",
  "service": "TimescaleDB",
  "hosts": [
    {
      "id": "914d271c-09ed-4389-b288-c02a5570c7f9",
      "revision": "e07aab59ab5b7b760f9d8370c71518a6",
      "connectionUri": "postgres://<username>:<password>@192.168.99.101:3115/postgres?sslmode=require",
      "dtCreated": "2020-02-17T21:20:34.001000Z",
      "dtModified": "2020-02-17T21:20:34.001000Z",
      "dtDeleted": null,
      "role": "timescaledb",
      "fqdn": "192.168.99.101",
      "port": 3115,
      "cpu": "1.0",
      "memoryMb": 512,
      "diskSizeGb": 10,
      "iops": 1000,
      "metadata": {},
      "quantity": 1
    }
  ],
  "acls": [],
  "statusDisplay": "Ready",
  "serviceSubtype": "timescaledb_cluster",
  "dtCreated": "2020-02-17T21:20:34.001000Z",
  "dtModified": "2020-02-17T21:20:34.001000Z",
  "dtDeleted": null,
  "provider": "AWS",
  "name": "adifferentname",
  "version": "12.3-tsdb-1.7.1",
  "features": {},
  "settings": {},
  "metadata": {},
  "status": 1,
  "organization": "2b258bc1-5791-49ca-a6c3-988a68ef21d9",
  "region": "us-east-1",
  "connectionString": "postgres://USERNAME:PASSWORD@192.168.99.101:3115/postgres?sslmode=require"
}

Delete a TimescaleDB instance

DELETE /instances/timescaledb/<instance_id>/

Requests that a TimescaleDB instance be deleted.

This will set the instance to status 6 (Delete Requested). The status will be updated to 3 (Deleted) once the resources have been removed.

Delete requests currently return no body and a response code of 204.

Example response

Create a High-Availability TimescaleDB instance

Create an HA TimescaleDB instance

POST /instances/timescaledb/

Refer here for details on creating a TimescaleDB instance.

Additional body parameters to specify in order to create an HA TimescaleDB instance.

Parameter Default Required Description
features.addons.replicas_for_ha none false Number of replicas to configure instance for High-Availability. Minimum - 1, Maximum - 2.

Example request: Create a HA TimescaleDB instance

{
    "plan": "Standard_20GB",
    "name": "timescaledb-ha-test",
    "version": "12.3-tsdb-1.7.1",
    "region": "us-east-1",
    "provider": "AWS",
    "service": "TimescaleDB",
    "features": {
        "addons": {
            "replicas_for_ha": 2
        }
    },
    "settings": {},
    "serviceSubtype": "timescaledb_cluster"
}

Example response

Success HTTP Status Code: 202 Accepted

{
  "id": "728edd1e-02c2-49a2-9859-58fdeac33df2",
  "transactionId": "74d8470e-d1f4-40b8-b089-86545b1c88dc"
}

Restore TimescaleDB Instance from Backup

Restore a TimescaleDB instance from backup

POST /instances/timescaledb/

Refer here for details on creating a TimescaleDB instance.

Refer here for details on listing backups to find the requested backup.

Additional body parameters to restore a TimescaleDB instance

Parameter Default Required Description
settings none false To specify any create settings
settings.restoreFromBackup none false To specify restore specific settings
settings.restoreFromBackup.instanceId none true The id of the instance to restore from. Instances must be owned by the organization requesting the restore. When no backupId or restoreTimestamp is included, the new instance is restored to the latest state of the source instance's WAL archives
settings.restoreFromBackup.backupId none false The id of the backup to restore from. Backup must be from the instance specified by the instanceId (above)
settings.restoreFromBackup.restoreTimestamp none false The timestamp upto which the backup is to be restored, to support Point In Time Recovery (PITR). Accepted format - 'YYYY-MM-DDThh:mm:ssZ'. Example: 2019-07-26T23:00:00Z. The closest previous successful full backup and WAL archives until the specified timestamp will be used for restore

Note

  1. WAL archives are updated depending on volume of updates.
  2. Always specify an instanceId.
  3. Include either
    • no other field (full restore to the latest state of the source instance's WAL archives),
    • a backupID (to restore up till that backup),
    • a restoreTimestamp (to restore up till that time)
  4. If both backupId and restoreTimestamp are included, restoreTimestamp will be preferred.
  5. The provider, region, service, serviceSubtype, and version of the restored instance should be the same as the source instance of the backup, being specified for restore.
  6. The storage size of the plan should also be equal to or greater than the source instance storage size.
  7. The organization of the source instance should match that of the restored instance.

To use the latest available full backup of a specified instance: example request

{
    "plan": "Standard_20GB",
    "name": "timescaledb-test",
    "version": "12.3-tsdb-1.7.1",
    "region": "us-east-1",
    "provider": "AWS",
    "service": "TimescaleDB",
    "features": {},
    "settings": {
        "restoreFromBackup": {
            "instanceId": "bd31d011-446f-4e2d-9287-270dcbc9aa2f"
        }
    },
    "serviceSubtype": "timescaledb_cluster"
}

Example response

Success HTTP Status Code: 202 Accepted

{
  "id": "728edd1e-02c2-49a2-9859-58fdeac33df2",
  "transactionId": "74d8470e-d1f4-40b8-b089-86545b1c88dc"
}

To restore an instance using a backup Id: example request

{
    "plan": "Standard_20GB",
    "name": "timescaledb-test",
    "version": "12.3-tsdb-1.7.1",
    "region": "us-east-1",
    "provider": "AWS",
    "service": "TimescaleDB",
    "features": {},
    "settings": {
        "restoreFromBackup": {
            "instanceId": "bd31d011-446f-4e2d-9287-270dcbc9aa2f",
            "backupId": "84c50d7b-3aff-414e-8a9b-bb228c5ade72"
        }
    },
    "serviceSubtype": "timescaledb_cluster"
}

Example response

{
  "id": "728edd1e-02c2-49a2-9859-58fdeac33df2",
  "transactionId": "25ce6115-28fb-4f31-bd23-9fa051558861"
}

PITR of an instance: example request

{
    "plan": "Standard_20GB",
    "name": "timescaledb-test",
    "version": "12.3-tsdb-1.7.1",
    "region": "us-east-1",
    "provider": "AWS",
    "service": "TimescaleDB",
    "features": {},
    "settings": {
        "restoreFromBackup": {
            "instanceId": "bd31d011-446f-4e2d-9287-270dcbc9aa2f",
            "restoreTimestamp": "2019-07-26T23:00:00Z"
        }
    },
    "serviceSubtype": "timescaledb_cluster"
}

Example response

{
  "id": "728edd1e-02c2-49a2-9859-58fdeac33df2",
  "transactionId": "25ce6115-28fb-4f31-bd23-9fa051558861"
}

TimescaleDB Users

Create a user for a TimescaleDB instance

POST /instances/timescaledb/<instance_id>/users/

Creates a new user for the specified TimescaleDB instance (instance_id). TimescaleDB is implemented as an extension on PostgreSQL. Hence, all the concepts of PostgreSQL users/roles applies to TimescaleDB as well.

Note on usernames: pg_ or objectrocket_ cannot be used as prefixes to usernames as these prefixes are reserved for PostgreSQL built-in roles and ObjectRocket system users.

Body parameters to create a TimescaleDB user

Parameter Default Required Description
username none true Name of the user/PostgreSQL role. Avoid using pg_ or objectrocket_ as a user prefix since this naming convention is used for built-in roles and system users.
password none true Password of the user for password authentication.
roles none true List of user privileges. Refer below table for additional details.

PostgreSQL privileges assigned for a specific role included in roles parameter

Role PostgreSQL privilges assigned by system Description
admin LOGIN, CREATEROLE, CREATEDB This role can be used to create and manage permissions of other users/roles

Example request

{
    "username": "myadmin",
    "password": "myadminpswd",
    "roles": ["admin"]
}

Example response

Success HTTP Status Code: 201 Created

{
    "detail": "User successfully created for instance afa83127-f122-40a6-a7f7-b0a5e9a056cc"
}

List users for a TimescaleDB instance

GET /instances/timescaledb/<instance_id>/users/

Gets the user list for the specified TimescaleDB instance (instance_id).

This is meant to mimic the built-in \du query on a PostgreSQL instance. Like the standard \du query to list users, this endpoint does not return the default roles.

This endpoint will also return ObjectRocket-specific system users, which are used for replication, metrics, etc. These system users cannot be deleted or interacted with through the API and should not be deleted in the instance.

Example response

Success HTTP Status Code: 200 OK

[
  {
    "username":"cluster_admin_user"
  },
  {
    "username":"my_app"
  },
  {
    "username":"objectrocket_admin",
    "systemUser": true
  },
  {
    "username":"objectrocket_postgres_exporter",
    "systemUser": true
  },
  {
    "username":"objectrocket_replicationuser",
    "systemUser": true
  },
  {
    "username":"postgres",
    "systemUser": true
  }
]

Delete a user from a TimescaleDB instance

DELETE /instances/timescaledb/<instance_id>/users/

Deletes a user from the specified TimescaleDB instance (instance_id).

Built-in and system users cannot be deleted (see Create a user for a TimescaleDB instance).

Body parameters to delete a TimescaleDB user

Parameter Default Required Description
username none true Name of the user/PostgreSQL role.

Example request

{
    "username": "myadmin"
}

Success HTTP Status Code: 200 OK

Example response

{
  "detail": "User successfully deleted from instance afa83127-f122-40a6-a7f7-b0a5e9a056cc"
}

Update Configuration for TimescaleDB Instance

Update configuration for TimescaleDB Instance

PATCH /instances/timescaledb/<instance_id>/

This endpoint uses the JSON Merge Patch Strategy for applying settings.

Body parameters to update the configuration of a TimescaleDB instance

Parameter Default Required Description
settings.datastoreConfigurations none false To specify updated settings. Simply specify the TimescaleDB configuration setting as a key and the desired value. To remove a setting, set its value to "null". These settings will override any defaults. See List configurations for the configurable options, including defaults and allowable settings.

Max Connections

The maximum number of max_connections is based on plan size

Plan (Mem) Maximum max_connections
1GB 112
2GB 225
4GB 450
8GB 901
16GB 1802
24GB 2703

Example request to update the configuration of a TimescaleDB instance

{
  "settings": {
    "datastoreConfigurations": {
      "max_connections": 50,
      "log_executor_stats": "on"
    }
  }
}

Example response

Success HTTP Status Code: 202 Accepted

{
  "id": "3d41d516-6d21-47f0-9360-2c78972b3c0d",
  "revision": "e07aab59ab5b7b760f9d8370c71518a6",
  "service": "TimescaleDB",
  "hosts": [
    {
      "id": "914d271c-09ed-4389-b288-c02a5570c7f9",
      "revision": "e07aab59ab5b7b760f9d8370c71518a6",
      "connectionUri": "postgres://<username>:<password>@192.168.99.101:3115/postgres?sslmode=require",
      "dtCreated": "2020-02-17T21:20:34.001000Z",
      "dtModified": "2020-02-17T21:20:34.001000Z",
      "dtDeleted": null,
      "role": "timescaledb",
      "fqdn": "192.168.99.101",
      "port": 3115,
      "cpu": "1.0",
      "memoryMb": 512,
      "diskSizeGb": 10,
      "iops": 1000,
      "metadata": {},
      "quantity": 1
    }
  ],
  "acls": [],
  "statusDisplay": "Ready",
  "serviceSubtype": "timescaledb_cluster",
  "dtCreated": "2020-02-17T21:20:34.001000Z",
  "dtModified": "2020-02-17T21:20:34.001000Z",
  "dtDeleted": null,
  "provider": "AWS",
  "name": "ortest_timescaledb",
  "version": "12.3-tsdb-1.7.1",
  "features": {},
  "settings": {
    "datastoreConfigurations": {
      "maxReplicationSlots": 15,
      "maxWorkerProcesses": 10
    }
  },
  "metadata": {},
  "status": 1,
  "organization": "2b258bc1-5791-49ca-a6c3-988a68ef21d9",
  "region": "us-east-1",
  "connectionString": "postgres://USERNAME:PASSWORD@192.168.99.101:3115/postgres?sslmode=require"
}

TimescaleDB Certificate Instructions

Connecting to your database instance securely with TLS/SSL

TimescaleDB is implemented as an extension on PostgreSQL. Hence, PostgreSQL tls connection modes are applicable. Refer to the PostgreSQL SSL support documentation to understand various ssl modes. The below steps outline the process of CA cert retrieval, which can be used additionally to verify the server ('verify-ca' sslmode).

  1. List CA certificates for your TimescaleDB database instance as shown here: List certs.

  2. Retrieve CA certificate using the certificate id as shown here: Get cert. Pay close attention to the URL params type=intermediate and download=true, both of these params must be present to get the certificate.

  3. Copy the pem data (present on the "certificate" attribute of the response) into an empty file /path/to/certs/ca. Note that the newlines (\n) in the json output should be dereferenced correctly. Example: sed 's/\\n/\'$'\n''/g' /path/to/certs/ca > /path/to/certs/sslca.pem.

  4. Now, connect securely to your instance:

Example connection

psql 'postgres://myusername:mypassword@ingress.w98sujpz.launchpad.objectrocket.cloud:4097/postgres?sslmode=verify-ca&sslrootcert=/path/to/certs/sslca.pem'

TimescaleDB Certificates

CA - List all TimescaleDB instance certificates

GET instances/timescaledb/<instance_id>/certificates/?type=intermediate

Example response

Success HTTP Status Code: 200 OK

[
  {
    "id": "871f38e9-9c79-4de8-b79e-1cb8cf30d183",
    "clientCertificates": [],
    "dtCreated": "2019-09-04T15:11:24.791049Z",
    "dtModified": "2019-09-04T15:11:24.791080Z",
    "dtDeleted": null,
    "expiration": "2019-12-25T10:00:00.578000Z",
    "name": "instance_intermediate_ca",
    "primary": true,
    "instance": "f50ea96f-bd62-4195-a66a-d1c65aa4385a"
  }
]

CA - Get specific TimescaleDB instance certificate (by id)

GET /instances/timescaledb/<instance_id>/certificates/<ca_certificate_id>/?type=intermediate

Example response

Success HTTP Status Code: 200 OK

{
    "id": "871f38e9-9c79-4de8-b79e-1cb8cf30d183",
    "clientCertificates": [],
    "dtCreated": "2019-09-04T15:11:24.791049Z",
    "dtModified": "2019-09-04T15:11:24.791080Z",
    "dtDeleted": null,
    "expiration": "2019-12-25T10:00:00.578000Z",
    "name": "instance_intermediate_ca",
    "primary": true,
    "instance": "f50ea96f-bd62-4195-a66a-d1c65aa4385a"
}

CA - Get specific TimescaleDB instance certificate (by id) with PEM data

GET /instances/timescaledb/<instance_id>/certificates/<ca_certificate_id>/?type=intermediate&download=true

Example response

Success HTTP Status Code: 200 OK

{
   "id":"871f38e9-9c79-4de8-b79e-1cb8cf30d183",
   "clientCertificates":[],
   "dtCreated":"2019-09-04T15:11:24.791049Z",
   "dtModified":"2019-09-04T15:11:24.791080Z",
   "dtDeleted":null,
   "expiration":"2019-12-25T10:00:00.578000Z",
   "name":"instance_intermediate_ca",
   "primary":true,
   "instance":"f50ea96f-bd62-4195-a66a-d1c65aa4385a",
   "certificate":"-----BEGIN CERTIFICATE-----\nMIIDXTCCAkWgAwIBAgIQClXvAC05ndGrOtV0jjI/lTANBgkqhkiG9w0BAQsFADBE\nMRwwGgYDVQQKExNQb3N0Z3JlU1FMIE9wZXJhdG9yMSQwIgYDVQQDExtwb3N0Z3Jl\nc3FsLm9iamVjdHJvY2tldC5jb20wHhcNMTkwODE2MjAwNjA1WhcNMTkxMTE0MjAw\nNjA1WjBEMRwwGgYDVQQKExNQb3N0Z3JlU1FMIE9wZXJhdG9yMSQwIgYDVQQDExtw\nb3N0Z3Jlc3FsLm9iamVjdHJvY2tldC5jb20wggEiMA0GCSqGSIb3DQEBAQUAA4IB\nDwAwggEKAoIBAQDIEwhfZ6ymYd6WCpuwEWGc5g9nYIZDjQQKneB7U5OBeOGSC14F\nl2BGqZe89ndQ6qUj8znfokfbWFqUvRuTc15RgPmB31xy79lP/0LbzY6YOL9/Wk64\nw2FSB5rEF6q3eHeMas9MOtpchVZIhGoUndTl2ZNP0rhTxd9PTe5DVHsuhsGU/xgd\nnNAJYKpYpf3gyaMYV8RQqjtAlcr1xT+8Sfv4HO36IRzkU6D1oQFIRsGhhvAuEvra\n9ESRqxjAeDF1O6tgzOGo0TmlE4opBOgy/SIPkUl+gfJsZISyCCQr+Vtl24iTN03N\nxqT0hSrcugqCmz+OMHhzECs7xag58XgkC5lvAgMBAAGjSzBJMA4GA1UdDwEB/wQE\nAwICpDAPBgNVHRMBAf8EBTADAQH/MCYGA1UdEQQfMB2CG3Bvc3RncmVzcWwub2Jq\nZWN0cm9ja2V0LmNvbTANBgkqhkiG9w0BAQsFAAOCAQEArASbcFYtOV3AAgZthIa1\n43uOFPrD3PUW7LtoYwZqAuRqasB4v9tq4oCui1ZnrU2XdAIHB0ZORXqBpM+AE6kJ\nxEJDI5saXefJs5Df1GfYWZDheIEK3vMSUK7AegZjT98fno2RzhSJenXfkaJ2JOIX\n1tVF5Ik00DMybFbNdicgD+648kLlMGT3NYHE6XRg7bFoWufc/1+UDvWYx9l24m2P\nI1Iu/LCOF0K8wKg0mEHXRGRO2ian2hwi8e4IhMzdaNt1/DQmGrh2LiTfIprwfcw7\n1wrAy/hKwwnwtcFZ9zq2vc4KEX2nSUpHewRPB8D47mYKXdys48rZMUiRIY8T8E3N\nyQ==\n-----END CERTIFICATE-----"
}

Redis instances

Redis instances do not have the concept of users, passwords, or roles. A single password with superuser privileges grants access to any Redis instance.

List all Redis instances

GET /instances/redis/

Returns a list of all Redis instances with the password in the connectionString hidden.

GET /instances/redis/?showPassword=true

Returns a list of all Redis instances with the password in the connectionString visible.

Example response

Success HTTP Status Code: 200 OK

[
    {
        "id": "bcf9442b-7482-49f8-89d8-732013dcb81f",
        "name": "ortest_redis",
        "service": "Redis",
        "hosts": [],
        "features": {},
        "settings": {},
        "acls": [
            {
                "id": "ca628b71-d427-4af7-a557-3a4971c328b5",
                "cidr": "0.0.0.0/32",
                "instance": "bcf9442b-7482-49f8-89d8-732013dcb81f",
                "kind": 1,
                "dtCreated": "2019-11-10T06:11:46.595642Z",
                "dtModified": "2019-11-10T06:11:46.595683Z",
                "dtDeleted": null,
                "name": "everyone"
            }
        ],
        "statusDisplay": "Ready",
        "metadata": {},
        "serviceSubtype": "redis_ha",
        "dtCreated": "2017-03-20T21:20:34.001000Z",
        "dtModified": "2017-03-20T21:20:34.001000Z",
        "dtDeleted": null,
        "provider": "AWS",
        "version": "4.0.14",
        "status": 1,
        "organization": "c31d87bc-6db9-48e6-ad41-6b01e4c0f9c1",
        "region": "us-east-1",
        "connectionString": "rediss://<password>@192.168.0.1:6379/0"
    }
]

Example response

Success HTTP Status Code: 200 OK

[
    {
        "id": "bcf9442b-7482-49f8-89d8-732013dcb81f",
        "name": "ortest_redis",
        "service": "Redis",
        "hosts": [],
        "features": {},
        "settings": {},
        "acls": [
            {
                "id": "ca628b71-d427-4af7-a557-3a4971c328b5",
                "cidr": "0.0.0.0/32",
                "instance": "bcf9442b-7482-49f8-89d8-732013dcb81f",
                "kind": 1,
                "dtCreated": "2019-11-10T06:11:46.595642Z",
                "dtModified": "2019-11-10T06:11:46.595683Z",
                "dtDeleted": null,
                "name": "everyone"
            }
        ],
        "statusDisplay": "Ready",
        "metadata": {},
        "serviceSubtype": "redis_ha",
        "dtCreated": "2017-03-20T21:20:34.001000Z",
        "dtModified": "2017-03-20T21:20:34.001000Z",
        "dtDeleted": null,
        "provider": "AWS",
        "version": "4.0.14",
        "status": 1,
        "organization": "c31d87bc-6db9-48e6-ad41-6b01e4c0f9c1",
        "region": "us-east-1",
        "connectionString": "rediss://instance_admin_password@192.168.0.1:6379/0"
    }
]

Get specific Redis instance by id

GET /instances/redis/<instance_id>/

Returns a specific Redis instance with the password in the connectionString hidden.

GET /instances/redis/<instance_id>/?showPassword=true

Returns a specific Redis instance with the password in the connectionString visible.

Example response

Success HTTP Status Code: 200 OK

{
    "id": "bcf9442b-7482-49f8-89d8-732013dcb81f",
    "name": "ortest_redis",
    "service": "Redis",
    "hosts": [],
    "features": {},
    "settings": {},
    "acls": [
        {
            "id": "ca628b71-d427-4af7-a557-3a4971c328b5",
            "cidr": "0.0.0.0/32",
            "instance": "bcf9442b-7482-49f8-89d8-732013dcb81f",
            "kind": 1,
            "dtCreated": "2019-11-10T06:11:46.595642Z",
            "dtModified": "2019-11-10T06:11:46.595683Z",
            "dtDeleted": null,
            "name": "everyone"
        }
    ],
    "statusDisplay": "Ready",
    "metadata": {},
    "serviceSubtype": "redis_ha",
    "dtCreated": "2017-03-20T21:20:34.001000Z",
    "dtModified": "2017-03-20T21:20:34.001000Z",
    "dtDeleted": null,
    "provider": "AWS",
    "version": "4.0.14",
    "status": 1,
    "organization": "c31d87bc-6db9-48e6-ad41-6b01e4c0f9c1",
    "region": "us-east-1",
    "connectionString": "rediss://<password>@192.168.0.1:6379/0"
}

Example response

Success HTTP Status Code: 200 OK

{
    "id": "bcf9442b-7482-49f8-89d8-732013dcb81f",
    "name": "ortest_redis",
    "service": "Redis",
    "hosts": [],
    "features": {},
    "settings": {},
    "acls": [
        {
            "id": "ca628b71-d427-4af7-a557-3a4971c328b5",
            "cidr": "0.0.0.0/32",
            "instance": "bcf9442b-7482-49f8-89d8-732013dcb81f",
            "kind": 1,
            "dtCreated": "2019-11-10T06:11:46.595642Z",
            "dtModified": "2019-11-10T06:11:46.595683Z",
            "dtDeleted": null,
            "name": "everyone"
        }
    ],
    "statusDisplay": "Ready",
    "metadata": {},
    "serviceSubtype": "redis_ha",
    "dtCreated": "2017-03-20T21:20:34.001000Z",
    "dtModified": "2017-03-20T21:20:34.001000Z",
    "dtDeleted": null,
    "provider": "AWS",
    "version": "4.0.14",
    "status": 1,
    "organization": "c31d87bc-6db9-48e6-ad41-6b01e4c0f9c1",
    "region": "us-east-1",
    "connectionString": "rediss://instance_admin_password@192.168.0.1:6379/0"
}

Create a Redis instance

POST /instances/redis/

Requests that the build system create a Redis instance.

A successful request returns HTTP 202. The instance begins with a status of 4 and status_display of Create Requested. The instance should eventually transition to a status of 7 and status_display of Building. Once the instance is fully built, it will update to a status of 1 and status_display of Ready. When instance is built, the record also shows member hosts, connection strings, etc.

Body parameters to create a Redis instance

Parameter Default Required Description
acls none false creates acls for instance on build
name none true a name for the instance
plan none true a valid plan identifier (see List plans)
provider none true currently only AWS (see List cloud providers)
region none true the cloud region to deploy the instance, e.g. us-east-1 (see List regions)
service none true the requested service (see List services)
serviceSubtype none true a valid service subtype for Redis (see List service subtypes)
version none true the requested version of service (see List versions)

Example request

{
    "plan": "Standard_20GB",
    "name": "redis-test",
    "version": "4.0.14",
    "region": "us-east-1",
    "provider": "AWS",
    "service": "Redis",
    "features": {},
    "settings": {},
    "serviceSubtype": "redis_ha"
}

Example response

Success HTTP Status Code: 202 Accepted

{
  "id": "728edd1e-02c2-49a2-9859-58fdeac33df2",
  "transactionId": "74d8470e-d1f4-40b8-b089-86545b1c88dc"
}

Rename a Redis instance

PATCH /instances/redis/<instance_id>/

Requests to rename the instance to the specified value.

Body parameters to rename a Redis instance

Parameter Default Required Description
name none true a name for the instance

Example request

{
    "name": "adifferentname"
}

Example response

Success HTTP Status Code: 200 OK

{
    "id": "bcf9442b-7482-49f8-89d8-732013dcb81f",
    "name": "adifferentname",
    "service": "Redis",
    "hosts": [],
    "features": {},
    "settings": {},
    "acls": [
        {
            "id": "ca628b71-d427-4af7-a557-3a4971c328b5",
            "cidr": "0.0.0.0/32",
            "instance": "bcf9442b-7482-49f8-89d8-732013dcb81f",
            "kind": 1,
            "dtCreated": "2019-11-10T06:11:46.595642Z",
            "dtModified": "2019-11-10T06:11:46.595683Z",
            "dtDeleted": null,
            "name": "everyone"
        }
    ],
    "statusDisplay": "Ready",
    "metadata": {},
    "serviceSubtype": "redis_ha",
    "dtCreated": "2017-03-20T21:20:34.001000Z",
    "dtModified": "2017-03-20T21:20:34.001000Z",
    "dtDeleted": null,
    "provider": "AWS",
    "version": "4.0.14",
    "status": 1,
    "organization": "c31d87bc-6db9-48e6-ad41-6b01e4c0f9c1",
    "region": "us-east-1",
    "connectionString": "rediss://instance_admin_password@192.168.0.1:6379/0"
}

Delete a Redis instance

DELETE /instances/redis/<instance_id>/

Requests that a Redis instance be deleted.

This sets the instance's status to 6 (Delete Requested). The status updates to 3 (Deleted) once the resources are removed.

Delete requests currently return no body and a response code of 204.

Example response

Instance Stats

List available instance metrics (by ID)

GET /stats/instances/<instance_id>/

Returns a list of metrics available for the chosen instance. Each metric dict contains the name of the metric along with the instance URL for requesting those stats.

Example response

Success HTTP Stats Code: 200 OK

[
    {
        "spaceusage": "http://api.objectrocket.cloud/stats/instances/<INSTANCE_ID>/spaceusage/",
    }
]

Get instance metric (by ID and metric name)

GET /stats/instances/<instance_id>/<METRIC_NAME>/

Returns the instance stats for a given metric

Spaceusage

GET /stats/instances/<instance_id>/spaceusage/

Example response

Success HTTP Status Code: 200 OK

{
    "unit": "byte",
    "sampleTime": 1564602519.018594,
    "spaceTotal": 51508150272,
    "spaceAvailable": 51406172160,
    "spaceUsed": 101978112,
    "nodes": [
        {
            "name": "elasticsearch-1",
            "nodeid": "jIngWe1TRc6MqOjyi_a79A",
            "spaceAvailable": 17135390720,
            "spaceTotal": 17169383424,
            "spaceUsed": 33992704
        },
        {
            "name": "elasticsearch-0",
            "nodeid": "qzyw-QFoTj2CCgsu9l3uEA",
            "spaceAvailable": 17135390720,
            "spaceTotal": 17169383424,
            "spaceUsed": 33992704
        },
        {
            "name": "elasticsearch-2",
            "nodeid": "Q8jlmuMhSHGfSOBdQjlySg",
            "spaceAvailable": 17135390720,
            "spaceTotal": 17169383424,
            "spaceUsed": 33992704
        }
    ]
}

Send Prometheus query directly through proxy

GET /stats/proxy/?query=<PROMETHEUS_QUERY>

Send a Prometheus query through a proxy endpoint

NB: You cannot return metrics for an instance_id or namespace ID that you don't have permission to view

Example response

Success HTTP Status Code: 200 OK

{
  "jsonrpc": "2.0",
  "status": "success",
  "data": {
    "resultType": "vector",
    "result": [
      {
        "metric": {
          "__name__": "elasticsearch_filesystem_data_available_bytes",
          "cluster": "elasticsearch",
          "endpoint": "http",
          "instance": "172.16.152.12:9200",
          "instanceId": "dd9cf27c-9c76-4788-904f-41830fd5131a",
          "job": "elasticsearch",
          "namespace": "dd9cf27c-9c76-4788-904f-41830fd5131a",
          "node": "elasticsearch-1",
          "nodeid": "jIngWe1TRc6MqOjyi_a79A",
          "pod": "elasticsearch-1",
          "product": "elasticsearch",
          "service": "elasticsearch"
        },
        "value": [
          1564603363.758,
          "17135390720"
        ]
      },
      {
        "metric": {
          "__name__": "elasticsearch_filesystem_data_available_bytes",
          "cluster": "elasticsearch",
          "endpoint": "http",
          "instance": "172.16.216.14:9200",
          "instanceId": "dd9cf27c-9c76-4788-904f-41830fd5131a",
          "job": "elasticsearch",
          "namespace": "dd9cf27c-9c76-4788-904f-41830fd5131a",
          "node": "elasticsearch-0",
          "nodeid": "qzyw-QFoTj2CCgsu9l3uEA",
          "pod": "elasticsearch-0",
          "product": "elasticsearch",
          "service": "elasticsearch"
        },
        "value": [
          1564603363.758,
          "17135390720"
        ]
      },
      {
        "metric": {
          "__name__": "elasticsearch_filesystem_data_available_bytes",
          "cluster": "elasticsearch",
          "endpoint": "http",
          "instance": "172.16.8.13:9200",
          "instanceId": "dd9cf27c-9c76-4788-904f-41830fd5131a",
          "job": "elasticsearch",
          "namespace": "dd9cf27c-9c76-4788-904f-41830fd5131a",
          "node": "elasticsearch-2",
          "nodeid": "Q8jlmuMhSHGfSOBdQjlySg",
          "pod": "elasticsearch-2",
          "product": "elasticsearch",
          "service": "elasticsearch"
        },
        "value": [
          1564603363.758,
          "17135390720"
        ]
      },
      {
        "metric": {
          "__name__": "elasticsearch_filesystem_data_free_bytes",
          "cluster": "elasticsearch",
          "endpoint": "http",
          "instance": "172.16.152.12:9200",
          "instanceId": "dd9cf27c-9c76-4788-904f-41830fd5131a",
          "job": "elasticsearch",
          "namespace": "dd9cf27c-9c76-4788-904f-41830fd5131a",
          "node": "elasticsearch-1",
          "nodeid": "jIngWe1TRc6MqOjyi_a79A",
          "pod": "elasticsearch-1",
          "product": "elasticsearch",
          "service": "elasticsearch"
        },
        "value": [
          1564603363.758,
          "17135390720"
        ]
      },
      {
        "metric": {
          "__name__": "elasticsearch_filesystem_data_free_bytes",
          "cluster": "elasticsearch",
          "endpoint": "http",
          "instance": "172.16.216.14:9200",
          "instanceId": "dd9cf27c-9c76-4788-904f-41830fd5131a",
          "job": "elasticsearch",
          "namespace": "dd9cf27c-9c76-4788-904f-41830fd5131a",
          "node": "elasticsearch-0",
          "nodeid": "qzyw-QFoTj2CCgsu9l3uEA",
          "pod": "elasticsearch-0",
          "product": "elasticsearch",
          "service": "elasticsearch"
        },
        "value": [
          1564603363.758,
          "17135390720"
        ]
      },
      {
        "metric": {
          "__name__": "elasticsearch_filesystem_data_free_bytes",
          "cluster": "elasticsearch",
          "endpoint": "http",
          "instance": "172.16.8.13:9200",
          "instanceId": "dd9cf27c-9c76-4788-904f-41830fd5131a",
          "job": "elasticsearch",
          "namespace": "dd9cf27c-9c76-4788-904f-41830fd5131a",
          "node": "elasticsearch-2",
          "nodeid": "Q8jlmuMhSHGfSOBdQjlySg",
          "pod": "elasticsearch-2",
          "product": "elasticsearch",
          "service": "elasticsearch"
        },
        "value": [
          1564603363.758,
          "17135390720"
        ]
      },
      {
        "metric": {
          "__name__": "elasticsearch_filesystem_data_size_bytes",
          "cluster": "elasticsearch",
          "endpoint": "http",
          "instance": "172.16.152.12:9200",
          "instanceId": "dd9cf27c-9c76-4788-904f-41830fd5131a",
          "job": "elasticsearch",
          "namespace": "dd9cf27c-9c76-4788-904f-41830fd5131a",
          "node": "elasticsearch-1",
          "nodeid": "jIngWe1TRc6MqOjyi_a79A",
          "pod": "elasticsearch-1",
          "product": "elasticsearch",
          "service": "elasticsearch"
        },
        "value": [
          1564603363.758,
          "17169383424"
        ]
      },
      {
        "metric": {
          "__name__": "elasticsearch_filesystem_data_size_bytes",
          "cluster": "elasticsearch",
          "endpoint": "http",
          "instance": "172.16.216.14:9200",
          "instanceId": "dd9cf27c-9c76-4788-904f-41830fd5131a",
          "job": "elasticsearch",
          "namespace": "dd9cf27c-9c76-4788-904f-41830fd5131a",
          "node": "elasticsearch-0",
          "nodeid": "qzyw-QFoTj2CCgsu9l3uEA",
          "pod": "elasticsearch-0",
          "product": "elasticsearch",
          "service": "elasticsearch"
        },
        "value": [
          1564603363.758,
          "17169383424"
        ]
      },
      {
        "metric": {
          "__name__": "elasticsearch_filesystem_data_size_bytes",
          "cluster": "elasticsearch",
          "endpoint": "http",
          "instance": "172.16.8.13:9200",
          "instanceId": "dd9cf27c-9c76-4788-904f-41830fd5131a",
          "job": "elasticsearch",
          "namespace": "dd9cf27c-9c76-4788-904f-41830fd5131a",
          "node": "elasticsearch-2",
          "nodeid": "Q8jlmuMhSHGfSOBdQjlySg",
          "pod": "elasticsearch-2",
          "product": "elasticsearch",
          "service": "elasticsearch"
        },
        "value": [
          1564603363.758,
          "17169383424"
        ]
      }
    ]
  }
}

MFA (Multi-Factor Authentication)

Create MFA Enrollment Ticket

POST /mfa/

Creates a multi-factor authentication enrollment ticket for a user.

A successful request will return a 200 as well as a ticket id and a URL to the ticket.

Body parameters to creat an MFA ticket

Parameter Default Required Description
user_id none true A user's Auth0 user ID. In the /users/ list, this is returned as the username.
send_mail false false If true, the user will be sent an email with a URL to click to enroll in MFA.

Example request

{
  "user_id": "auth0|5d81385734b6760034a03148",
  "send_mail": true
}

Example response

{
  "ticketId": "7rwXR3yTRVKFq697f52Hvw5lfO6qQKoy",
  "ticketUrl": "https://objectrocket-dev.guardian.auth0.com/enrollment?ticket_id=7rwXR3yTRVKFq697f52Hvw5lfO6qQKoy"
}

Delete MFA Enrollment

DELETE /mfa/<username>/enrollments/<enrollment_id>/

Deletes a user's MFA enrollment. <username> is the APIV username from the /users/ end point. <enrollment_id> is the id of the user's enrollment.

A successful DELETE returns an empty body and a 204 status.

List MFA Enrollments for a user

GET /mfa/<username>/enrollments/

List the enrollments for a specific user. <username> is the APIV username from the /users/ end point.

Example Response

[
  {
    "id": "totp|dev_yAUYRZWs10ZCMg2I",
    "status": "confirmed",
    "enrolledAt": "2019-10-05T03:38:44.000Z",
    "lastAuth": "2019-10-05T03:38:44.000Z",
    "type": "authenticator",
    "authMethod": "authenticator"
  }
]