NAV Navbar

Introduction

Getting Started

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

1) Create an Account

Sign up for ObjectRocket.

2) Verify your Email

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

3) Create an Organization

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

4) Billing Information

Enter in your billing information.

Authentication

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

This will generate a token to use against our api.

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

Api-Token: <Your api token here>

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

Insomnia Template

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

Catalog

List cloud providers

GET /cloudproviders/

Returns a list of cloud providers.

Example response

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

List regions

GET /regions/

GET /regions/?provider=aws

Returns a list of regions

Example response

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

Query parameters to list regions

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

List services

GET /services/

Returns a list of services.

Example response

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

List service subtypes

GET /servicesubtypes/

GET /servicesubtypes/?service=9a33f633-9d46-4211-ab4b-fbe3b7ccdabb

Returns a list of service subtypes.

Example response

[
  {
    "id": "85413ec3-bf8c-4d4d-9a71-55cd64113692",
    "dtCreated": "2019-01-22T19:24:05.433306Z",
    "dtModified": "2019-03-06T17:26:06.406818Z",
    "name": "elasticsearch_cluster",
    "description": "Elasticsearch Cluster where all nodes share all roles",
    "service": "9a33f633-9d46-4211-ab4b-fbe3b7ccdabb"
  },
  {
    "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"
  },
  {
    "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"
  }
]

Query parameters to list service subtypes

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

List versions

GET /versions/

GET /versions/?service=Elasticsearch

GET /versions/?serviceSubtype=elasticsearch_cluster

Returns a list of versions

Example response

[
  {
    "id": "46515c66-1c98-4e18-a037-db7dcec7993c",
    "dtCreated": "2019-02-20T21:43:21.956540Z",
    "dtModified": "2019-02-20T21:43:21.956566Z",
    "name": "6.4.0",
    "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.5.3",
    "serviceSubtype": "85413ec3-bf8c-4d4d-9a71-55cd64113692",
    "serviceSubtypeName": "elasticsearch_cluster",
    "serviceName": "Elasticsearch"
  }
]

Query parameters to list versions

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

List flavors

GET /flavors/

GET /flavors/?service=Elasticsearch

GET /flavors/?serviceSubtype=elasticsearch_cluster

Returns a list of flavors

Example response

[
  {
    "id": "9920dd84-c5fe-497d-a117-3724a1a35b89",
    "dtCreated": "2019-03-04T15:47:18.627318Z",
    "dtModified": "2019-03-04T15:47:18.627348Z",
    "name": "Standard",
    "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"
  }
]

Query parameters to list flavors

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

List plans

GET /plans/

GET /plans/?service=Elasticsearch

GET /plans/?serviceSubtype=elasticsearch_cluster

GET /plans/?flavor=standard

Returns a list of plans.

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

Example response

[
  {
    "id": "276b71cd-7919-4a4c-a2e7-f9ff3322c8c6",
    "dtCreated": "2019-03-04T15:47:18.631074Z",
    "dtModified": "2019-03-04T15:47:18.631099Z",
    "name": "Standard_48GB",
    "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
flavor 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)
serviceSubtype none false the name of the service subtype the plan applies to (see List service subtypes)

List addons

GET /addons/

GET /addons/?serviceSubtype=elasticsearch_cluster

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

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

Example response

[
    {
        "id": "74c887d8-148b-45e1-9e78-e4aaff8ff10a",
        "name": "dedicated_masters",
        "displayName": "Dedicated Masters",
        "description": "Add 3 dedicated master nodes with xRAM/yGB to your ES cluster",
        "maturityLevel": 2,
        "displaySetting": 1,
        "dtCreated": "2019-02-13T20:31:36.439349Z",
        "dtModified": "2019-02-13T20:31:36.439370Z",
        "serviceSubtype": "2567567567776-413e-9554-9a2cf8b630fc",
        "default": false,
        "value": {
            "type": "string",
            "enum": "['2GB RAM/8GB Disk', '4GB RAM/16GB Disk', '8GB RAM/32GB Disk']"
        }
    },
    {
        "id": "291f7736-77d6-413e-9554-9a2cf8b630fc",
        "name": "kibana",
        "displayName": "Kibana",
        "description": "Track query loads and requests through the Elastic Stack",
        "maturityLevel": 1,
        "displaySetting": 1,
        "dtCreated": "2019-02-13T20:31:36.439349Z",
        "dtModified": "2019-02-13T20:31:36.439370Z",
        "serviceSubtype": "2567567567776-413e-9554-9a2cf8b630fc",
        "default": true,
        "value": {
            "type": "boolean",
            "default": "true"
        }
    },
    {
        "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",
        "default": false,
        "value": {
            "type": "integer",
            "min": 1,
            "max": 2,
            "default": 2
        }
    }
]

Query parameters to list addons

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

Pricing

Get pricing for an instance

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

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

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

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

Example response

{
    "priceInCents": 25000
}

Query parameters for pricing

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

Organization

List your organization

GET /organizations/

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

Example response

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

Get organization by id

GET /organizations/<organization_id>

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

Example response

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

Update organization

PATCH /organization/<organization_id>/

Updates an organization you are a member and owner of.

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

Body parameters to update an organization

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

Example request

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

Example response

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

Invoice

Get upcoming invoice

GET /invoices/upcoming/

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

Example response

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

Get past invoices

GET /invoices/past/

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

Example response

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

Users

List users

GET /users/

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

Example response

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

Get a specific user

GET /users/<user_id>/

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

Example response

{

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

}

Filter users by email

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

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

NB: only filtering by email is currently supported

Example response

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

Delete a specific user

DELETE /users/<user_id>/

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

Example response

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

Patch a specific user's role

PATCH /users/<user_id>/

Changes the role of a user in the organization you are a member and owner of.

Body Parameters

Parameter Default Required Description
role none true the new role for the user

Example request

{
    "role": "readonly user"
}

Example response

{

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

}

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

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

Returns a list of instances for your organization.

Example response

[
    {
    "id": "081df6db-2f18-4d82-89e7-f6af577a3847",
    "name": "arbiters_testing1",
    "service": "MongoDB",
    "serviceSubtype": "mongodb_sharded",
    "provider": "azure",
    "hosts": [
        {
        "id": "0d553f4c-6e1f-4722-988f-3bf05325d618",
        "role": "Mongod",
        "dtCreated": "2017-02-02T04:59:01.991751Z",
        "dtModified": "2017-02-02T04:59:01.991788Z",
        "fqdn": "104.210.159.176",
        "port": 27017,
        "klass": "Standard_DS1_v2",
        "replsetId": "568949b9-f81e-4fce-b5a3-dc20ed534195",
        "uuid": "3d298ed9-f0eb-4227-9455-e64cabca2a96"
        },
        {
        "id": "7cccb688-be5b-4649-ad79-4e8b4b8102cb",
        "role": "Mongos",
        "dtCreated": "2017-02-02T04:59:01.985157Z",
        "dtModified": "2017-02-02T04:59:01.985196Z",
        "fqdn": "40.84.238.253",
        "port": 27018,
        "klass": "Standard_DS1_v2",
        "replsetId": "f09c453e-971c-4176-976f-eb59b4169746",
        "uuid": "801a9488-ebaa-4623-a970-cda902b82f80"
        },
        {
        "id": "8b8c6461-603d-474d-ae5f-72f2cd2b8948",
        "role": "Mongos",
        "dtCreated": "2017-02-02T04:59:01.987340Z",
        "dtModified": "2017-02-02T04:59:01.987378Z",
        "fqdn": "40.84.233.175",
        "port": 27018,
        "klass": "Standard_DS1_v2",
        "replsetId": "f09c453e-971c-4176-976f-eb59b4169746",
        "uuid": "46ed84c5-a34b-4c58-960b-ddb4c5b967c1"
        },
        {
        "id": "8e92a493-13db-402d-8309-bc2821f35dcd",
        "role": "Mongod",
        "dtCreated": "2017-02-02T04:59:01.989493Z",
        "dtModified": "2017-02-02T04:59:01.989531Z",
        "fqdn": "104.210.158.110",
        "port": 27017,
        "klass": "Standard_DS1_v2",
        "replsetId": "568949b9-f81e-4fce-b5a3-dc20ed534195",
        "uuid": "a968dc15-fc03-455d-b1a1-7b68aebdc6d2"
        },
        {
        "id": "9d6a5ada-5e2c-41d3-8748-58444f8d5561",
        "role": "Arbiter",
        "dtCreated": "2017-02-02T04:59:01.993934Z",
        "dtModified": "2017-02-02T04:59:01.993971Z",
        "fqdn": "13.84.155.141",
        "port": 27017,
        "klass": "Basic_A0",
        "replsetId": "568949b9-f81e-4fce-b5a3-dc20ed534195",
        "uuid": "cc06433e-82cc-4984-8373-7f85b0ed5c98"
        },
        {
        "id": "c2d436c1-f2b3-4098-be3a-e304d12208c8",
        "role": "Mongos",
        "dtCreated": "2017-02-02T04:59:01.982429Z",
        "dtModified": "2017-02-02T04:59:01.982463Z",
        "fqdn": "40.84.235.245",
        "port": 27018,
        "klass": "Standard_DS1_v2",
        "replsetId": "f09c453e-971c-4176-976f-eb59b4169746",
        "uuid": "5b562edf-c8c1-4591-b1bb-14888df95863"
        }
    ],
    "plan": "20GB",
    "features": {
        "storageEngine": "wiredtiger"
    },
    "settings": {},
    "acls": [],
    "statusDisplay": "Ready",
    "connectionString": "104.210.158.110:27017,13.84.155.141:27017,40.84.233.175:27018,104.210.159.176:27017,40.84.238.253:27018,40.84.235.245:27018",
    "dtCreated": "2017-01-31T19:39:57.266995Z",
    "dtModified": "2017-02-02T04:59:01.978902Z",
    "version": "3.2.11",
    "region": "southcentralus",
    "status": 2,
    "completed": "2017-02-02T04:59:01.978662Z",
    "cidr": "10.0.10.0/24",
    "metadata": {"resourceGroup": "1a678566-53f2-4b00-9a08-9cce4669a8a3"},
    "vnetId": "1a678566-53f2-4b00-9a08-9cce4669a8a3"
    }
]

Query parameters to list instances

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

ACLs

ACLs are attached to instances of a particular product type.

Current product types:

List ACLs

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

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

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

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

Example response

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

Get a specific ACL

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

Returns an ACL for an instance of a product.

Example response

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

Create an instance ACL

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

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

Note: kind is required for ACLs for Elasticsearch (including Kibana and Cerebro), but not for other databases.

Body parameters to create an instance ACL

Parameter Default Required Description
cidr none true ip address or CIDR block to apply
kind 1 false a qualifier which identifies the kind of ACL, required for Elasticsearch. Valid options are 2 (for Elasticsearch), 4 (for Kibana), 5 (for Cerebro), 6 (for CockroachDB), 7 (for CockroachDB Admin), 8 (for PostgreSQL)
name none true a name for the ACL

Example request

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

Example response

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

Delete ACLs

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

Requests that an ACL be deleted.

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

Backups

Backups are created for instances of a particular product type.

Current product types:

List Backups

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

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

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

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

Example response

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

Get a specific Backup

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

Returns a Backup for an instance of a product.

Example response

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

Elasticsearch Instances

List all Elasticsearch instances

GET /instances/elasticsearch/

Returns a list of all Elasticsearch instances.

Example response

  [{
    "id": "081df6db-2f18-4d82-89e7-f6af577a3847",
    "name": "arbiters_testing1",
    "service": "Elasticsearch",
    "serviceSubtype": "elasticsearch_cluster",
    "provider": "AWS",
    "hosts": [],
    "plan": "Standard_48GB",
    "features": {
      "addons": {}
    },
    "settings": {},
    "acls": [
      {
        "id": "25ffae8c-cfbf-4252-a37e-3b64187ef55a",
        "cidr": "7.7.7.7/32",
        "kind": 4,
        "name": "our_app"
      },
    ],
    "statusDisplay": "Ready",
    "dtCreated": "2017-01-31T19:39:57.266995Z",
    "dtModified": "2017-02-02T04:59:01.978902Z",
    "version": "6.4.0",
    "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/<ID>/

Returns a specific Elasticsearch instance.

Example response

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

Create an Elasticsearch instance

POST /instances/elasticsearch/

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

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

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

Body parameters to create an Elasticsearch instance

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

Example request

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

Example response

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

Rename an Elasticsearch instance

PATCH /instances/elasticsearch/<ID>/

Requests the instance be renamed to the specified value.

Body parameters to rename an Elasticsearch instance

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

Example request

{
    "name": "adifferentname"
}

Example response

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

Delete an Elasticsearch instance

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

Elasticsearch Scaling

Scale nodes for an Elasticsearch instance

POST /instances/elasticsearch/<ID>/scale/

Requests that an Elasticsearch instance be scaled.

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. The minimum number of nodes is 3 and the maximum is 5.
role none true Name of node/host role to scale. The only valid option is "elasticsearch".

Example request

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

Success HTTP Status Code: 202 Accepted

Example response

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

Elasticsearch User Management

List Elasticsearch instance users

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

Returns a list of users for the specified Elasticsearch instance.

Example response

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

Get a specific Elasticsearch instance user (by id)

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

Returns the user specified for the specified Elasticsearch instance.

Example response

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

Create Elasticsearch instance user

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

Creates a new Elasticsearch user for an Elasticsearch instance.

Example request

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

Example response

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

Body parameters to create an Elasticsearch instance user

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

Update Elasticsearch instance user

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

Updates an existing Elasticsearch user for an Elasticsearch instance.

Example request

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

Example response

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

Body parameters to update an Elasticsearch instance user

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

Delete Elasticsearch instance user

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

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

Body parameters to delete an Elasticsearch user

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

Example request

{
    "username": "myadmin"
}

Success HTTP Status Code: 202 Accepted

Example response

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

CockroachDB Instances

List all CockroachDB instances

GET /instances/cockroachdb/

Returns a list of all CockroachDB instances.

Example response

[
  {
    "id": "081df6db-2f18-4d82-89e7-f6af577a3847",
    "name": "cockroachdb_testing1",
    "service": "CockroachDB",
    "serviceSubtype": "cockroachdb_singlecluster",
    "provider": "AWS",
    "hosts": [],
    "plan": "Alpha_30GB",
    "features": {
      "addons": {}
    },
    "settings": {},
    "acls": [
      {
        "id": "25ffae8c-cfbf-4252-a37e-3b64187ef55a",
        "cidr": "7.7.7.7/32",
        "kind": 6,
        "name": "our_app"
      },
    ],
    "statusDisplay": "Active",
    "dtCreated": "2017-01-31T19:39:57.266995Z",
    "dtModified": "2017-02-02T04:59:01.978902Z",
    "version": "19.1.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/<ID>/

Returns a specific CockroachDB instance.

Example response

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

Create a CockroachDB instance

POST /instances/cockroachdb/

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

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

Body Parameters

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

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

Example request

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

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

Example response

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

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

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

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

Example response

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

Rename a CockroachDB instance

PATCH /instances/cockroachdb/<ID>/

Requests the instance be renamed to the specified value.

Body Parameters

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

Example request

{
    "name": "adifferentname"
}

Example response

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

Delete a CockroachDB instance

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

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

Example response

Scale nodes for a CockroachDB instance

POST /instances/cockroachdb/<ID>/scale/

Requests that a CockroachDB instance be scaled out.

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

Body Parameters

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

Example request

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

Success HTTP Status Code: 202 Accepted

Example response

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

CockroachDB Databases

List databases for a CockroachDB instance

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

List databases on an instance.

Example response

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

Retrieve a database for a CockroachDB instance

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

Example response

{
  "name": "testdb"
}

Create a database for a CockroachDB instance

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

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

Example request

{
  "name": "exampledb",
}

Body parameters to create a database for a CockroachDB instance

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

Delete a database for a CockroachDB instance

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

A successful request will return HTTP 204.

CockroachDB Users

List users for a CockroachDB instance

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

List users on an instance.

Example response

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

Retrieve a user for a CockroachDB instance

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

Example response

{
  "username": "testuser"
}

Create a user for a CockroachDB instance

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

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

Example request

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

Body parameters to create a user for a CockroachDB instance

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

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

Delete a user for a CockroachDB instance

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

Body parameters to delete a CockroachDB user

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

Example request

{
    "username": "testuser"
}

Success HTTP Status Code: 200 OK

Example response

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

CockroachDB Certificates Instructions

Connecting to your database instance securely with SSL

Create a database user

  1. Create a database user as described here

Generate CSR (Certificate Signing Request)

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

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

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

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

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

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

Retrieve CA certificate bundle

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

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

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

Connect using certificates

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

Example connection - cockroach client

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

Example connection - psql client

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

Client Certificate Delete (Revoke) Process

Call the delete endpoint in API

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

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

Generate New Client Certificates

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

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

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

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

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

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

Rotate CA (Renewal) Process

Create a new CA

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

Call the delete endpoint in API

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

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

CockroachDB Certificates

CA - List all CockroachDB certificates

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

Returns a list of all CockroachDB Instance CA certificates.

Example response

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

CA - Get specific CockroachDB Certificate (by id)

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

Returns a specific CockroachDB instance CA certificate.

Example response

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

CA certificates with PEM data

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

Example response

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

CA - Create a CockroachDB certificate

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

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

Body Parameters

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

Example request

{
    "cert_type": "intermediate"
}

Example response

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

CA - Delete a CockroachDB certificate

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

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

Body Parameters

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

Example request

{
    "cert_type": "intermediate"
}

Success HTTP Status Code: 202 ACCEPTED

Example response

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

Client - List all CockroachDB certificates

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

Returns a list of all CockroachDB Instance client certificates.

Example response

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

Client - Get specific CockroachDB Certificate (by id)

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

Example response

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

Client certificates with PEM data

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

Example response

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

Client - Create a CockroachDB certificate

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

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

Body Parameters

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

Example request

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

Example response

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

Client - Delete a CockroachDB certificate

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

Body Parameters

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

Example request

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

Success HTTP Status Code: 202 ACCEPTED

Example response

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

PostgreSQL Instances

List all PostgreSQL instances

GET /instances/postgresql/

Returns a list of all PostgreSQL instances.

Example response

Success HTTP Status Code: 200 OK

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

Returns a specific PostgreSQL instance.

Example response

Success HTTP Status Code: 200 OK

{
  "id": "eb9add74-6663-4ad8-a4a9-c387900009db",
  "name": "pgsql-test1",
  "service": "PostgreSQL",
  "hosts": [
    {
      "id": "9b9a2ad1-5196-4c11-9b0e-db90997ab889",
      "connectionUri": "postgres://<username>:<password>@ingress.w98sujpz.launchpad.objectrocket.cloud:4115/postgres?sslmode=require",
      "dtCreated": "2019-07-01T15:50:31.023744Z",
      "dtModified": "2019-07-01T15:50:37.101465Z",
      "dtDeleted": null,
      "role": "postgresql",
      "fqdn": "ingress.w98sujpz.launchpad.objectrocket.cloud",
      "port": 4115,
      "cpu": "0.2",
      "memoryMb": 1024,
      "diskSizeGb": 20,
      "iops": 0,
      "metadata": null,
      "quantity": 1
    }
  ],
  "features": {},
  "settings": {},
  "acls": [
    {
      "id": "1de94e87-97b6-4f50-89f9-8920e5b4fea5",
      "cidr": "0.0.0.0/0",
      "instance": "eb9add74-6663-4ad8-a4a9-c387900009db",
      "kind": 8,
      "dtCreated": "2019-07-01T15:49:53.640199Z",
      "dtModified": "2019-07-01T15:49:53.640219Z",
      "dtDeleted": null,
      "name": "anyipacl"
    }
  ],
  "statusDisplay": "Ready",
  "metadata": {},
  "dtCreated": "2019-07-01T15:49:53.385027Z",
  "dtModified": "2019-07-01T15:49:53.385054Z",
  "dtDeleted": null,
  "provider": "AWS",
  "version": "11.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
name none true a name for the instance
plan none true a valid plan identifier (see List plans)
provider none true currently only AWS (see List cloud providers)
region none true which cloud region to deploy to, e.g. us-east-1 (see List regions)
service none true which service is requested (see List services)
serviceSubtype none true a valid service subtype for PostgreSQL (see List service subtypes)
version none true requested version of service (see List versions)

Example request

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

Example response

Success HTTP Status Code: 202 Accepted

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

Rename a PostgreSQL instance

PATCH /instances/postgresql/<ID>/

Requests the instance be renamed to the specified value.

Body parameters to rename a PostgreSQL instance

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

Example request

{
    "name": "adifferentname"
}

Example response

Success HTTP Status Code: 200 OK

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

Delete a PostgreSQL instance

DELETE /instances/postgresql/<ID>/

Requests that a PostgreSQL instance be deleted.

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

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

Example response

Create a High-Availability PostgreSQL instance

Create an HA PostgreSQL instance

POST /instances/postgresql/

Refer here for details on creating a PostgreSQL instance.

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

Parameter Default Required Description
features none false To specify any additional instance features
features.addons none false To specify addons (see List addons).
features.addons.replicas_for_ha none false Number of replicas to configure instance for High-Availability. Minimum - 1, Maximum - 2.

Example request

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

Example response

Success HTTP Status Code: 202 Accepted

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

PostgreSQL Users

Create a user for a PostgreSQL instance

POST /instances/postgresql/<ID>/users/

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

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

Body parameters to create a PostgreSQL user

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

PostgreSQL privileges assigned for a specific role included in roles parameter

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

Example request

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

Example response

Success HTTP Status Code: 201 Created

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

List users for a PostgreSQL instance

GET /instances/postgresql/<ID>/users/

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

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

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

Example response

Success HTTP Status Code: 200 OK

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

Delete a user from a PostgreSQL instance

DELETE /instances/postgresql/<ID>/users/

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

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

Body parameters to delete a PostgreSQL user

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

Example request

{
    "username": "myadmin"
}

Success HTTP Status Code: 200 OK

Example response

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

PostgreSQL Certificate Instructions

Connecting to your database instance securely with TLS/SSL

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

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

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

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

  4. Now, connect securely to your instance:

Example connection

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

PostgreSQL Certificates

CA - List all PostgreSQL instance certificates

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

Example response

Success HTTP Status Code: 200 OK

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

CA - Get specific PostgreSQL instance certificate (by id)

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

Example response

Success HTTP Status Code: 200 OK

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

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

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

Example response

Success HTTP Status Code: 200 OK

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

Instance Stats

List available instance metrics (by ID)

GET /stats/instances/<ID>/

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

Example response

Success HTTP Stats Code: 200 OK

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

Get instance metric (by ID and metric name)

GET /stats/instances/<ID>/<METRIC_NAME>/

Returns the instance stats for a given metric

Spaceusage

GET /stats/instances/<ID>/spaceusage/

Example response

Success HTTP Status Code: 200 OK

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

Send Prometheus query directly through proxy

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

Send a Prometheus query through a proxy endpoint

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

Example response

Success HTTP Status Code: 200 OK

{
  "jsonrpc": "2.0",
  "status": "success",
  "data": {
    "resultType": "vector",
    "result": [
      {
        "metric": {
          "__name__": "es_fs_total_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__": "es_fs_total_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__": "es_fs_total_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__": "es_fs_total_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__": "es_fs_total_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__": "es_fs_total_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__": "es_fs_total_total_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__": "es_fs_total_total_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__": "es_fs_total_total_bytes",
          "cluster": "elasticsearch",
          "endpoint": "http",
          "instance": "172.16.8.13:9200",
          "instanceId": "dd9cf27c-9c76-4788-904f-41830fd5131a",
          "job": "elasticsearch",
          "namespace": "dd9cf27c-9c76-4788-904f-41830fd5131a",
          "node": "elasticsearch-2",
          "nodeid": "Q8jlmuMhSHGfSOBdQjlySg",
          "pod": "elasticsearch-2",
          "product": "elasticsearch",
          "service": "elasticsearch"
        },
        "value": [
          1564603363.758,
          "17169383424"
        ]
      }
    ]
  }
}

MFA (Multi-Factor Authentication)

Create MFA Enrollment Ticket

POST /mfa/

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

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

Body parameters to creat an MFA ticket

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

Example request

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

Example response

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

Delete MFA Enrollment

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

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

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

List MFA Enrollments for a user

GET /mfa/<username>/enrollments/

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

Example Response

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