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

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.

[
  {
    "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

[
  {
    "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.

[
  {
    "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

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

Returns a list of service subtypes.

[
  {
    "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

[
  {
    "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

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

Returns a list of flavors

[
  {
    "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]

[
  {
    "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.

[
    {
        "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.

[
    {
        "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.

GET pricing/?region=926118a9-5435-4e7e-8b82-1f193e7cdab3&plan=e2d9308a-bd0e-4e8e-a652-986c6b297b8b&addon=5334c426-877a-4a56-8b51-2b5cef5dc399_value_2&addon=105c0b52-bc71-4961-becb-f80a4c4e1278_value_Basic_MongoS&addon=359b9a3f-66b7-4087-a6b2-b6d6c6dd7098_value_Basic_Cfg

Returns the price in cents of a Sharded-MongoDB instance of the specified Shardsvr plan with MongoS, Configsvr as addons in the specified region.

{
    "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.

{
    "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.

{
    "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

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

{
    "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.

{
    "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.

{
    "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.

{
    "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.

{

    "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

{
    "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).

{
  "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

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

{  
    "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.

[
  {
    "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)
provider	none	false	instance provider (AWS, GCP, Azure)

Note: filters only work on List Instances - not individual product List Instances

To list by service and region: EX: {{api_url}}/instances/?all=true&service=MongoDB&region=eastus

To list by service and provider: EX: {{api_url}}/instances/?all=true&service=MongoDB&provider=AWS

*Can do more than 2 queries if necessary

ACLs

ACLs are attached to instances of a particular product type.

Current product types:

elasticsearch
cockroachdb
postgresql
redis
timescaledb
mongodb

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/.

[
  {
    "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.

{
  "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)
12	MongoDB	MongoDBMongos

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

{
  "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 automatically scheduled for an instance.

Currently supported product types for backups:

cockroachdb
elasticsearch
postgresql
mongodb

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/.

[
  {
    "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.

{
  "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"
    }
  }
}

CockroachDB Instances

List all CockroachDB instances

GET /instances/cockroachdb/

Returns a list of all CockroachDB instances.

[
  {
    "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.

{
  "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.

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

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

{
    "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"
}

{
  "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

{
    "name": "adifferentname"
}

{
  "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.

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

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

Success HTTP Status Code: 202 Accepted

{
  "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.

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

Retrieve a database for a CockroachDB instance

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

{
  "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.

{
  "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.

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

Retrieve a user for a CockroachDB instance

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

{
  "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.

{
  "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.

{
    "username": "testuser"
}

Success HTTP Status Code: 200 OK

{
  "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

Create a database user as described here

Generate CSR (Certificate Signing Request)

Make sure you have a ssl utility like openssl installed (openssl)
Generate a RSA private key file to create your CSR: openssl genrsa -out /path/to/certs/client.<username>.key 2048
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.
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
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.
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

Create an empty file called: /path/to/certs/ca.crt
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.
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

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

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'

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

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.
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.

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.
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.
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

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

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.
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.

[
  {
    "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.

{
  "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

{
  "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"

{
    "cert_type": "intermediate"
}

{
  "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"

{
    "cert_type": "intermediate"
}

Success HTTP Status Code: 202 ACCEPTED

{
    "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.

[
  {
    "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

{
  "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

{
  "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)

{
    "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-----"
}

{
  "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

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

Success HTTP Status Code: 202 ACCEPTED

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

Elasticsearch Instances

List all Elasticsearch instances

GET /instances/elasticsearch/

Returns a list of all Elasticsearch instances.

  [{
    "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.

{
  "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	a valid cloud provider identifier, e.g. `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

{
    "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"
}

{
    "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"
}

{
  "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

{
    "name": "adifferentname"
}

{
  "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

{
    "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"
}

{
  "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 or removing multirole/data nodes
- Instances without dedicated masters may not exceed 5 nodes
- Instances without dedicated masters may not be scaled to 2 nodes
- Multi-node instances (w/out masters) may not scale below 3 nodes
- Single node instances (w/out masters) must be scaled up to at least 3 nodes and may not be scaled back down
- Nodes may only be removed one at a time
- Nodes may not be removed from an instance with any closed indices
Adding dedicated masters to an instance that does not have them

Adding Dedicated Masters

A multirole cluster without dedicated masters can have them 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 3 and the maximum is 5 for multi/data nodes without dedicated masters. 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 options are "elasticsearch" and "dedicated_master"
desiredPerNodeMemoryMb	none	false	Memory in MB for new master nodes to be added with
desiredPerNodeDiskSizeGb	none	false	Disk size in GB for new master nodes to be added with

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

Success HTTP Status Code: 202 Accepted

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

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

Success HTTP Status Code: 202 Accepted

{
  "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.

[
    {
        "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.

{
    "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.

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

{
    "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.

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

{
    "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.

{
    "username": "myadmin"
}

Success HTTP Status Code: 202 Accepted

{
  "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)

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

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.

  [{
    "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"
  }
]

Compactions

A compaction will reduce the disk usage of your MongoDB instance by rewriting the data. This will cause an election. Currenly only ObjectRocket Support can trigger a manual compaction; contact support@objectrocket.com for assistance in triggering a compaction. See Compaction Schedules for regularly scheduled compactions.

List Compactions

GET /mongodb/<instance_id>/compactions/

Returns a list of all compactions for a MongoDB instance.

[
  {
    "instance": "21ef3572-a321-4b4e-9c88-5014ec499342",
    "dtCreated": "2020-09-11T18:50:41.238594Z",
    "dtModified": "2020-09-11T18:50:41.238644Z",
    "dtDeleted": null,
    "status": 1,
    "revision": "869cb2fbc92f1030b7b8f763d714b3dd",
    "statusDisplay": "Requested",
    "id": "4e9c39df-0d7c-47fd-921f-7fb7ee535cfb"
  }
]

Get a specific compaction

GET /mongodb/<instance_id>/compactions/<compaction_id>/

Returns a compaction for a MongoDB instance.

{
  "instance": "21ef3572-a321-4b4e-9c88-5014ec499342",
  "dtCreated": "2020-09-11T18:50:41.238594Z",
  "dtModified": "2020-09-11T18:50:41.238644Z",
  "dtDeleted": null,
  "status": 1,
  "revision": "869cb2fbc92f1030b7b8f763d714b3dd",
  "statusDisplay": "Requested",
  "id": "4e9c39df-0d7c-47fd-921f-7fb7ee535cfb"
}

Compaction Schedules

A compaction schedule will create a compaction according to the cron schedule provided. This operation is only available for MongoDB instances. A MongoDB instance can only have one compaction schedule active at a time.

Note: The compaction schedule runs according to UTC time.

List Compaction Schedules

GET /mongodb/<instance_id>/compactionschedules/

Returns a list of all compaction schedules for a MongoDB instance.

[
  {
    "instance": "21ef3572-a321-4b4e-9c88-5014ec499342",
    "dtCreated": "2020-09-11T18:25:09.585535Z",
    "dtModified": "2020-09-11T18:25:09.585565Z",
    "dtDeleted": null,
    "revision": "011ad2624912edef5a75a144cc85f577",
    "schedule": "0 0 * * *",
    "status": 1,
    "statusDisplay": "Requested",
    "name": "default_compaction_schedule",
    "id": "c048f75c-422b-49f2-b6e0-9d29e1ba8d1c"
  }
]

Get a specific compaction schedule

GET /mongodb/<instance_id>/compactionschedules/<compaction_schedule_id>/

Returns a compaction schedule for a MongoDB instance.

{
  "instance": "21ef3572-a321-4b4e-9c88-5014ec499342",
  "dtCreated": "2020-09-11T18:25:09.585535Z",
  "dtModified": "2020-09-11T18:25:09.585565Z",
  "dtDeleted": null,
  "revision": "011ad2624912edef5a75a144cc85f577",
  "schedule": "0 0 * * *",
  "status": 1,
  "statusDisplay": "Requested",
  "name": "default_compaction_schedule",
  "id": "c048f75c-422b-49f2-b6e0-9d29e1ba8d1c"
}

Create a compaction schedule

POST /mongodb/<instance_id>/compactionschedules/

Creates a compaction schedule. Only one compaction schedule can be active at a time.

Body parameters to create a compaction

Parameter	Default	Required	Description
name	none	false	name for the compaction schedule
schedule	none	true	cron formatted schedule that your instance will be compacted by

{
  "name": "Daily midnight UTC compactions",
  "schedule": "0 0 * * *"
}

{
  "instance": "21ef3572-a321-4b4e-9c88-5014ec499342",
  "dtCreated": "2020-09-11T18:47:55.064256Z",
  "dtModified": "2020-09-11T18:47:55.064974Z",
  "dtDeleted": null,
  "revision": "b64bb325f332617fb93e598e8777c17b",
  "schedule": "0 0 * * *",
  "status": 1,
  "statusDisplay": "Requested",
  "name": "Daily midnight UTC compactions",
  "id": "7cff27fa-5787-44be-bebf-bd6011d636d9"
}

Update a compaction schedule

Updates a compaction schedule.

Body parameters to update a compaction

Parameter	Default	Required	Description
name	none	false	name for the compaction schedule
schedule	none	false	cron schedule that the instance will compact at

PUT /mongodb/<instance_id>/compactionschedules/<compaction_schedule_id>/

{
  "instance": "21ef3572-a321-4b4e-9c88-5014ec499342",
  "dtCreated": "2020-09-11T18:47:55.064256Z",
  "dtModified": "2020-09-11T18:47:55.064974Z",
  "dtDeleted": null,
  "revision": "b64bb325f332617fb93e598e8777c17b",
  "schedule": "0 0 * * 6",
  "status": 1,
  "statusDisplay": "Requested",
  "name": "Saturday midnight UTC compactions",
  "id": "7cff27fa-5787-44be-bebf-bd6011d636d9"
}

{
  "instance": "21ef3572-a321-4b4e-9c88-5014ec499342",
  "dtCreated": "2020-09-11T18:47:55.064256Z",
  "dtModified": "2020-09-11T19:28:22.632886Z",
  "dtDeleted": null,
  "revision": "51b82025b082a7644331768e32837df9",
  "schedule": "0 0 * * 6",
  "status": 1,
  "statusDisplay": "Requested",
  "name": "Saturday midnight UTC compactions",
  "id": "7cff27fa-5787-44be-bebf-bd6011d636d9"
}

Delete a compaction schedule

Deletes a compaction schedule.

DELETE /mongodb/<instance_id>/compactionschedules/<compaction_schedule_id>/

MongoDB Instances

List MongoDB instances

GET /instances/mongodb/

Returns a list of instances for the current organization.

[
    {
    "id": "f1d1b736-ef2e-4578-b434-fb98041184a5",
    "service": "MongoDB",
    "hosts": [],
    "acls": [
      {
        "id": "1363203e-7b6b-4225-a46a-2a97139dc69e",
        "cidr": "7.7.7.7/32",
        "name": "mongodb_acl1",
        "kind": 1,
      }
    ],
    "statusDisplay": "Ready",
    "serviceSubtype": "mongodb",
    "dtCreated": "2017-03-20T21:20:34.001000Z",
    "dtModified": "2017-03-20T21:20:34.001000Z",
    "provider": "AWS",
    "name": "mongodb_testing1",
    "version": "3.6.17",
    "features": {
      "storageEngine": "wiredTiger"
    },
    "settings": {},
    "metadata": {},
    "status": 1,
    "region": "us-east-1",
  }
]

Get a MongoDB instance

GET /instances/mongodb/<instance_id>/

{
    "id": "f1d1b736-ef2e-4578-b434-fb98041184a5",
    "service": "MongoDB",
    "hosts": [],
    "acls": [
      {
        "id": "1363203e-7b6b-4225-a46a-2a97139dc69e",
        "cidr": "7.7.7.7/32",
        "name": "mongodb_acl1",
        "kind": 1,
      }
    ],
    "statusDisplay": "Ready",
    "serviceSubtype": "mongodb",
    "dtCreated": "2017-03-20T21:20:34.001000Z",
    "dtModified": "2017-03-20T21:20:34.001000Z",
    "provider": "AWS",
    "name": "mongodb_testing1",
    "version": "3.6.17",
    "features": {
      "storageEngine": "wiredTiger"
    },
    "settings": {},
    "metadata": {},
    "status": 1,
    "region": "us-east-1",
}

Request a MongoDB instance

POST /instances/mongodb/

This will request that a MongoDB instance be created by the build system.

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.

A requested MongoDB instance will be built as a 3 node replica set unless the appropriate features.addons are specified. See Create a Sharded MongoDB instance for details on how to build sharded MongoDB instances.

Body parameters to create a MongoDB instance

Parameter	Default	Required	Description
acls	none	false	creates acls for instance on build
features	none	true	instance features dependent on service
features.storageEngine	`wiredTiger`	false	currently only `wiredTiger`
features.addons	none	false	To specify addons (see List addons and Create a Sharded MongoDB instance)
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 identifier, e.g. `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. currently only `MongoDB` (see List services)
serviceSubtype	none	true	currently only `mongodb` for `MongoDB` (see List service subtypes)
settings	none	false	settings for instance like storage warning threshold
version	none	true	requested version of service (see List versions)

{
    "plan": "Basic_10GB",
    "name": "whatever",
    "version": "4.2.3",
    "region": "us-east-1",
    "service": "MongoDB",
    "features": {
      "storageEngine": "wiredTiger"
    },
    "acls": [
      {
        "name": "datacenter",
        "cidr": "127.0.0.1/32",
      }
    ],
    "settings": {},
    "provider": "AWS",
    "serviceSubtype": "mongodb"
}

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

Rename a MongoDB instance

PATCH /instances/mongodb/<instance_id>/

This changes the instance's name to the specified value.

Body parameters to rename a MongoDB instance

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

{
    "name": "adifferentname"
}

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

Delete a MongoDB instance

DELETE /instances/mongodb/<instance_id>

This will set the instance to status 6 (status_display Delete Requested). A successful request will return HTTP 204.

Create a Sharded MongoDB instance

For a general overview of the MongoDB sharded architecture, see here.

Create a MongoDB instance with MongoS, shards, and config servers

POST /instances/mongodb/

Refer here for details on creating a replicaset MongoDB instance.

Additional body parameters to create a Sharded MongoDB instance

To build a sharded MongoDB instance with the requested number of shards and MongoS nodes, add the following parameters to the features.addons field of the request. Note that each shard will consist of 3 MongoDB nodes in a replica set (e.g. 2 shards x 3 nodes/shard = 6 total nodes). All sharded MongoDB instances have 3 config servers deployed in a replica set.

Parameter	Default	Required	Description
mongos	none	true	number of mongoS nodes (min 2)
shards	none	true	number of shards (min 1; each consisting of 3x mongod nodes)
per_mongos	false	true	create connection strings for each mongoS node (for high concurrency applications)
mongos_plan	none	true	a valid mongoS plan identifier (see List addons)
configsvr_plan	none	true	a valid config server plan identifier (see List addons)

See List addons with serviceSubtypeName=mongodb for available mongos_plan and configsvr_plan identifiers, as well as accepted values for other parameters. See List plans for details on mongos_plan and configsvr_plan definitions.

{
  "plan": "Basic_10GB",
  "name": "whatever",
  "version": "4.2.3",
  "region": "us-east-1",
  "service": "MongoDB",
  "features": {
    "storageEngine": "wiredTiger",
    "addons": {
      "mongos": 3,
      "shards": 3,
      "per_mongos": false,
      "mongos_plan": "Basic_MongoS",
      "configsvr_plan": "Basic_Cfg"
    }
  },
  "acls": [
    {
      "name": "datacenter",
      "cidr": "127.0.0.1/32",
    }
  ],
  "settings": {},
  "provider": "AWS",
  "serviceSubtype": "mongodb"
}

Returns HTTP 202 on success

{
  "id": "99d17001-671a-406b-b67b-87ec53606feb",
  "revision": "27813d1a68973a2c07da4fdf26af726f"
}

MongoDB Databases

List databases for a MongoDB instance

GET /instances/mongodb/<instance_id>/databases/

List databases on an instance.

[
    {
        "db": "admin",
        "indexSize": 81920,
        "storageSize": 49152,
        "ok": 1,
        "avgObjSize": 248.25,
        "objects": 4,
        "indexes": 3,
        "numExtents": 0,
        "dataSize": 993,
        "collections": 2
    },
    {
        "db": "local",
        "indexSize": 16384,
        "storageSize": 16384,
        "ok": 1,
        "avgObjSize": 1325,
        "objects": 1,
        "indexes": 1,
        "numExtents": 0,
        "dataSize": 1325,
        "collections": 1
    },
    {
        "db": "exampledb",
        "indexSize": 16384,
        "storageSize": 16384,
        "ok": 1,
        "avgObjSize": 22,
        "objects": 234,
        "indexes": 15,
        "numExtents": 0,
        "dataSize": 22,
        "collections": 1
    }
]

Retrieve a database for a MongoDB instance

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

{
  "db": "exampledb",
  "indexSize": 16384,
  "storageSize": 16384,
  "ok": 1,
  "avgObjSize": 22,
  "objects": 234,
  "indexes": 15,
  "numExtents": 0,
  "dataSize": 22,
  "collections": 1
}

Create a database for a MongoDB instance

POST /instances/mongodb/<instance_id>/databases/

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

{
  "name": "exampledb"
}

Body parameters to create a database for a MongoDB instance

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

Delete a database for a MongoDB instance

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

A successful request will return HTTP 204.

MongoDB Users

Create a MongoDB user

POST /instances/mongodb/<instance_id>/users/

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

Note: Users created with a password will be able to login with that password; users that are created without a password will only be able to login with a certificate (see MongoDB Certificate Instructions)

{
  "username": "admin",
  "password": "H6CfqdHyhezRuW",
  "database": "mydatabase",
  "roles": ["read"]
}

{
  "username": "CN=admin",
  "database": "mydatabase",
  "roles": ["read"]
}

Body parameters to create a MongoDB user

Parameter	Default	Required	Description
password	none	false	password for the database user if not using certificate for authentication (see MongoDB Certificate Instructions)
roles	none	true	a roles list that determines what role to assign the user on the target database; choices are `read` or `readWrite`
database	false	true	name of the database to create user on
username	none	true	name of the database user to add

List MongoDB users

GET /instances/mongodb/<instance_id>/users/

GET /instances/mongodb/<instance_id>/users/?database=<database_name>

GET /instances/mongodb/<instance_id>/users/?database=$external

Note: This lists users according to the database they use to authenticate, not the database they are granted permissions on. Users created without a password use the $external database to authenticate and so will be listed on that database.

Query parameters to list MongoDB database users

Parameter	Default	Required	Description
database	none	false	name of the database to list the user(s)

List users in a database.

[
  {"username": "devuser", "database": "devdb"},
  {"username": "readonlyuser", "database": "devdb"}
]

Remove a MongoDB user

DELETE /instances/mongodb/<instance_id>/users/

Note: This deletes users according to the database they use to authenticate, not the database they are granted permissions on. Users created without a password use the $external database to authenticate and so should be deleted on that database.

Body parameters to delete a MongoDB user

Parameter	Default	Required	Description
username	none	true	Name of the MongoDB user.
database	none	true	Name of the MongoDB database to delete the user from.

{
    "username": "testuser",
    "database": "testdb"
}

Success HTTP Status Code: 200 OK

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

MongoDB Certificates Instructions

There are two ways to securely connect to MongoDB instances:

Connecting with a username/password and the CA certificate bundle
Connecting with a client certificate and the CA certificate bundle

Connecting to your MongoDB instance securely with a password

Create a MongoDB user with password

Create a database user with a password as described here

Retrieve CA certificate bundle

List the CA certificates for your MongoDB instance as shown here: list intermediate certs. Find the CA certificate for that instance.
Using the CA certificate ID found in the previous step, download the CA certificate that you just created as shown here: get ca certs. Pay close attention to the URL params type=intermediate and download=true -- this will return the PEM data in the certificate field.
Copy the PEM data you retrieved in the previous step into a new ca.pem file.

Connect using password and CA certificate

Retrieve the connectionString for your MongoDB instance (which can be found by listing instances) and get the address of your instance.

Example Connection String: mongodb+srv://<instance_id>.m.<cluster>.launchpad.objectrocket.cloud/DBNAME -u DBUSER -p DBPASS --sslCAFile=/PATH/TO/CA.bundle --ssl
Change the DBNAME of the above to the database that you wish to connect to.
Connect to your MongoDB instance securely using the username/password and the CA certificate file (the ca.pem file):

Note: SSL use is deprecated in the current MongoDB; TLS use is preferred.

Note: Currently the MongoDB client for Mac will not allow connection due to length of the connection string.

Connecting to your MongoDB instance securely with a client certificate

Create a MongoDB user without a password

Create a database user with no password as described here

Generate CSR (Certificate Signing Request)

Make sure you have a ssl utility like openssl installed
Generate a private key file:

openssl genrsa -out /path/to/certs/mongodb.<username>.key 2048
Generate the CSR file using your private key:

openssl req -new -key /path/to/certs/mongodb.<username>.key -out /path/to/certs/mongodb.<username>.csr -subj "/CN=<username>" -reqexts key_usage -config <(echo '[req]'; echo 'distinguished_name=req'; echo '[key_usage]'; echo 'keyUsage = digitalSignature'; echo 'extendedKeyUsage = clientAuth')

Make sure to include the username of the database user as the CN subject attribute. Leave every other subject attribute blank.

NOTE: You must include the the keyUsage and extendKeyUsage extensions. Use the example command above to avoid any potential issues during the client certificate create process.
(Optional) You can check your subject on the CSR by using this command:

openssl req -in /path/to/certs/mongodb.<username>.csr -inform PEM -subject

The above command will return a line with the username: subject=CN=<username>
Copy the data from mongodb.<username>.csr file created in the step 3. Make a call to create a client certificate for MongoDB using that data for the certificate_signing_request field.
List the client certificates for your MongoDB instance as shown here: list client certs. Find the certificate where the username matches the username created.
Using the client certificate ID found in the previous step, download the client certificate that you just created as shown here: get client certs. Pay close attention to the URL params type=client and download=true -- this will return the PEM data in the certificate field.
Create a new file with the name mongodb.<username>.pem and paste in:
1. the PEM data retrieved in the previous step; and
2. the contents of your private key file created in step 2.

Retrieve CA certificate bundle

List the CA certificates for your MongoDB instance as shown here: list intermediate certs. Find the CA certificate for that instance.
Using the CA certificate ID found in the previous step, download the CA certificate that you just created as shown here: get ca certs. Pay close attention to the URL params type=intermediate and download=true -- this will return the PEM data in the certificate field.
Copy the PEM data you retrieved in the previous step into a new ca.pem file.

Connect using client and CA certificates

Retrieve the connectionString for your MongoDB instance (which can be found by listing instances) and get the address of your instance.

Note that the connectionString assumes a username/password connection, but the address section is all we will need. For instance, given the following connectionString field

mongodb+srv://<instance_id>.m.<cluster>.launchpad.objectrocket.cloud/DBNAME -u DBUSER -p DBPASS --sslCAFile=/PATH/TO/CA.bundle --ssl

we will take just the address of the instance: mongodb+srv://<instance_id>.m.<cluster>.launchpad.objectrocket.cloud/DBNAME
Change the DBNAME of the above address to the database that you wish to connect to.
Connect to your MongoDB instance securely using the certificates files (the mongodb.<username>.pem file and the ca.pem file) and the following flags:

Note: SSL use is deprecated in the current MongoDB; TLS use is preferred.

Note: User without a password are authorized with the $external database and with the MONGODB-X509 mechanism, so we have to add the following flags to the connection command: --authenticationDatabase '$external' --authenticationMechanism MONGODB-X509

Note: Currently the MongoDB client for Mac will not allow connection due to length of the connection string.

MongoDB Client Certificate Delete (Revoke) Process

Call the delete endpoint in API

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.
The target certificate will then be revoked, because MongoDB 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 MongoDB Client Certificates

By calling delete on a client certificate you will now be presented with two CA certificates: 1. 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 MongoDB nodes until deleted.) 2. 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: MongoDB currently does not support CRLs, so every time you revoke a client certificate the instance CA will be rotated.

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 be 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.
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.
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.pem 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.

MongoDB Rotate CA (Renewal) Process

Create a new CA

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

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.
Follow the steps here for more information. Step 3 will complete the CA rotation process.

MongoDB Certificates

CA - List all MongoDB certificates

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

Returns a list of all MongoDB Instance CA certificates.

[
  {
    "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 MongoDB Certificate (by id)

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

Returns a specific MongoDB instance CA certificate.

{
  "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/mongodb/<instance_id>/certificates/<ca_certificate_id>/?type=intermediate&download=true

{
  "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 MongoDB certificate

POST /instances/mongodb/<instance_id>/certificates/

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

Body Parameters

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

{
    "cert_type": "intermediate"
}

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

CA - Delete a MongoDB certificate

DELETE /instances/mongodb/<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.

Body Parameters

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

{
    "cert_type": "intermediate"
}

Success HTTP Status Code: 202 ACCEPTED

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

Client - List all MongoDB certificates

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

Returns a list of all MongoDB Instance client certificates.

[
  {
    "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 MongoDB Certificate (by id)

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

{
  "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/mongodb/<instance_id>/certificates/<client_certificate_id>/?type=client&download=true

{
  "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 MongoDB certificate

POST /instances/mongodb/<instance_id>/certificates/

Create a new MongoDB 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)

{
    "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-----"
}

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

Client - Delete a MongoDB certificate

DELETE /instances/mongodb/<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

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

Success HTTP Status Code: 202 ACCEPTED

{
    "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.

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.

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	a valid cloud provider identifier, e.g. `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)

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

{
    "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"
}

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

{
    "name": "adifferentname"
}

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.

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.

{
    "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"
}

Success HTTP Status Code: 202 Accepted

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

PostgreSQL Scaling

Scale nodes for an PostgreSQL instance

POST /instances/postgresql/<instance_id>/scale/

Requests that a PostgreSQL instance be scaled.

This scales the instance memory and disk size to the specified value(s).

Note: PostgreSQL cannot currently be scaled on Azure.

Body Parameters

Parameter	Default	Required	Description
role	none	true	Name of node/host role to scale. The only valid option is "postgresql".
desiredPerNodeMemoryMb	none	true	Desired memory in MB for the new master and replica (if any) node(s)
desiredPerNodeDiskSizeGb	none	true	Desired disk size in GB for the new master and replica (if any) node(s)

Note: - Ratio desiredPerNodeDiskSizeGb:desiredPerNodeMemoryMb (Disk size converted to Mb) must be 20:1 - Refer to plans catalog to get potential desiredPerNodeDiskSizeGb and desiredPerNodeMemoryMb values - Storage (desiredPerNodeDiskSizeGb) scale down is not supported - The scale will work for both master and replicas if there are any

{
    "desiredPerNodeMemoryMb": 2048,
    "desiredPerNodeDiskSizeGb": 40,
    "role": "postgresql"
}

Success HTTP Status Code: 202 Accepted

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

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

WAL archives are updated depending on volume of updates.
Always specify an instanceId.
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)
If both backupId and restoreTimestamp are included, restoreTimestamp will be preferred.
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.
The storage size of the plan should also be equal to or greater than the source instance storage size.
The organization of the source instance should match that of the restored instance.

{
    "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"
}

Success HTTP Status Code: 202 Accepted

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

{
    "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"
}

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

{
    "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"
}

{
  "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

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

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.

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.

{
    "username": "myadmin"
}

Success HTTP Status Code: 200 OK

{
  "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

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

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).

List CA certificates for your PostgreSQL database instance as shown here: List certs.
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.
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.
Now, connect securely to your instance:

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

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

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

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-----"
}

CA - Create a PostgreSQL certificate

POST /instances/postgresql/<instance_id>/certificates/

Create a new PostgreSQL CA certificate. A successful request will return HTTP 201.

Body Parameters

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

{
    "cert_type": "intermediate"
}

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

TimescaleDB Instances

List all TimescaleDB instances

GET /instances/timescaledb/

Returns a list of all TimescaleDB instances.

Success HTTP Status Code: 200 OK

[
  {
    "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

{
  "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.

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)

{
    "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"
}

{
    "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"
}

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

{
    "name": "adifferentname"
}

{
  "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.

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.

{
    "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"
}

Success HTTP Status Code: 202 Accepted

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

TimescaleDB Scaling

Scale nodes for an TimescaleDB instance

POST /instances/timescaledb/<instance_id>/scale/

Requests that a TimescaleDB instance be scaled.

This scales the instance memory and disk size to the specified value(s).

Note: TimescaleDB cannot currently be scaled on Azure.

Body Parameters

Parameter	Default	Required	Description
role	none	true	Name of node/host role to scale. The only valid option is "timescaledb".
desiredPerNodeMemoryMb	none	true	Desired memory in MB for the new master and replica (if any) node(s)
desiredPerNodeDiskSizeGb	none	true	Desired disk size in GB for the new master and replica (if any) node(s)

{
    "desiredPerNodeMemoryMb": 2048,
    "desiredPerNodeDiskSizeGb": 40,
    "role": "timescaledb"
}

Success HTTP Status Code: 202 Accepted

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

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

WAL archives are updated depending on volume of updates.
Always specify an instanceId.
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)
If both backupId and restoreTimestamp are included, restoreTimestamp will be preferred.
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.
The storage size of the plan should also be equal to or greater than the source instance storage size.
The organization of the source instance should match that of the restored instance.

{
    "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"
}

Success HTTP Status Code: 202 Accepted

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

{
    "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"
}

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

{
    "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"
}

{
  "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

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

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.

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.

{
    "username": "myadmin"
}

Success HTTP Status Code: 200 OK

{
  "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

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

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).

List CA certificates for your TimescaleDB database instance as shown here: List certs.
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.
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.
Now, connect securely to your instance:

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

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

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

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.

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"
    }
]

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.

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"
}

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	a valid cloud provider identifier, e.g. `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)

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

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

{
    "name": "adifferentname"
}

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.

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.

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/

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

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.

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

{
  "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.

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