Deployment Manager API

Use the Deployment Manager API to manage the Instabase platform infrastructure. This handles operations such as initializing the database and managing configurations. See the Deployment Manager documentation for more details.

Table of Contents

Info

Deployment Manager was previously called the Instabase control plane. Some backend elements, such as Deployment Manager API endpoints, variables, and files, still reference this name.

Note

For installation-related API documentation, see the Installer API page. For upgrade-related API documentation, see the Upgrade API page. These endpoints are documented separately to allow for additional context.

Conventions and authentication

For this API, api_root defines where to route API requests for your Instabase instance.

Note

During the initial Instabase installation, this should access Deployment Manager directly, either by port-forwarding the Deployment Manager port (9500) or by creating a temporary ingress.

In this document api_root defines where to route API requests for your Instabase instance and includes the stem of the API path.

import json, requests

api_root = 'https://www.instabase.com/api/v1/control_plane'

In this document token defines the Deployment Manager token. All API requests must include your valid Deployment Manager token to authenticate the request. The Deployment Manager API Token is created in the cluster with a default, changeable value when the Deployment Manager YAML is applied.

To fetch the Deployment Manager API token, run the following command in the command line, where $IB_NS is your Instabase namespace:

export TOKEN=$(kubectl -n $IB_NS get \
secret/control-plane-metadata \
--template={{.data.api_token}} | base64 -d)

You can then reference the token in your calls using $TOKEN in place of token.

Set up Deployment Manager

Method	Syntax
GET	`api_root/setup`

Description

Use this API to set up the Instabase deployment manager for an existing installation. This initializes the Deployment Manager metadata in your database.

Examples

Request

Example (Python):

url = api_root + '/setup'
headers = {
  'Token': token,
}
resp = requests.get(url, headers=headers).json()

Response

If successful:

HTTP STATUS CODE 200

# body
{
  "status": "OK"
}

Deployment Manager set up status

Method	Syntax
POST	`api_root/setup/status`

Description

Use this API to check if the necessary database tables and default resource label bindings for Deployment Manager are created.

Response schema

All keys are returned in the response by default, unless marked as optional.

Key	Type	Description	Value
`isSetup`	boolean	Whether the database tables are setup.	`true` or `false`

Examples

Request

Example (Python):

url = api_root + '/setup/status'
headers = {
  'Token': token,
}
resp = requests.get(url, headers=headers).json()

Response

The response body is a JSON object:

{
  "isSetup": "true"
}

Database initialization

Method	Syntax
POST	api_root/database/setup

Description

Use this API to initialize the Instabase database by creating all the necessary Instabase tables. Use this API for a new installation.

Request parameters

The request body must be a JSON object with these parameters. Parameters are required unless marked as optional.

Name	Type	Description	Values
`create_admin_account`	boolean	Whether or not to create an admin account during database initialization.	`true`, `false`
`admin_email`	string	Optional if `create_admin_account` is true. Admin email with which to create the admin account.	Email address
`admin_username`	string	Optional. Admin username with which to create the admin account.	Default: `admin`
`enable_control_plane`	boolean	Optional. Whether or not to create the Deployment Manager database models.	`true`, `false`. Default: `false`
`enable_key_service`	boolean	Optional. Whether or not to create the key service database models.	`true`, `false`. Default: `false`
`enable_ml_studio`	boolean	Optional. Whether or not to create the model training database models.	`true`, `false`. Default: `false`
`enable_model_registry_pv`	boolean	Optional. Whether or not to create model registry database models.	`true`, `false`. Default: `false`
`enable_repo_projects`	boolean	Optional. Whether or not to enable the database schema change to support Solution Builder projects.	`true`, `false`. Default: `false`

Response schema

All keys are returned in the response by default, unless marked as optional.

Key	Description	Value
`status`	Whether or not the operation was successful.	`"OK"`
`error`	A string explaining what went wrong.	A message, such as `Tables have already been set up` or `Invalid parameters`.

Examples

Request

Python example:

url = api_root + '/database/setup'

data = dict(
  create_admin_account = "true",
  admin_email = "admin@email.com", # optional (only if 'create_admin_account' is true)
  admin_username = "admin", # optional (default: 'admin')
  enable_control_plane = "false", # optional (default: 'false')
  enable_key_service = "false", # optional (default: 'false')
  enable_models = "false" # optional (default: 'false')
)

headers = {
  'Token': token,
}
resp = requests.post(url, headers=headers, data=json.dumps(data)).json()

Response

If successful:

HTTP STATUS CODE 200

# body
{
  "status": "OK"
}

Database mock DDL for initialization

Method	Syntax
POST	api_root/database/mock_ddl

Description

Use this API to get a mock DDL that initializes the Instabase database.

Request parameters

The request body must be a JSON object with these parameters. Parameters are required unless marked as optional.

Name	Type	Description	Values
`create_admin_account`	boolean	Whether or not to create an admin account during database initialization.	`true`, `false`
`admin_email`	string	Optional if `create_admin_account` is true. Admin email with which to create the admin account.	Email address
`admin_username`	string	Optional. Admin username with which to create the admin account.	Default: `admin`
`enable_control_plane`	boolean	Optional. Whether or not to create the Deployment Manager database models.	`true`, `false`. Default: `false`
`enable_key_service`	boolean	Optional. Whether or not to create the key service database models.	`true`, `false`. Default: `false`
`enable_ml_studio`	boolean	Optional. Whether or not to create the model training database models.	`true`, `false`. Default: `false`
`enable_model_registry_pv`	boolean	Optional. Whether or not to create model registry database models.	`true`, `false`. Default: `false`
`enable_repo_projects`	boolean	Optional. Whether or not to enable the database schema change to support Solution Builder projects.	`true`, `false`. Default: `false`

Response schema

The response is a JSON object. All keys are returned in the response by default, unless marked as optional.

Key	Description	Value
`ddls`	A list of DDL strings that would be used for database initialization.	[“DDL1…”, “DDL2…”,…]

Examples

Request

POST api_root/database/mock_ddl

# body
{
  "create_admin_account": "true",
  "admin_email": "admin@email.com", # optional (only if 'create_admin_account' is true)
  "admin_username": "admin", # optional (default: 'admin')
  "enable_control_plane": "false", # optional (default: 'false')
  "enable_key_service": "false", # optional (default: 'false')
  "enable_ml_studio": "false", # optional (default: 'false')
  "enable_model_registry_pv": "false" # optional (default: 'false')
}

Example (Python):

url = api_root + '/database/mock_ddl'

data = dict(
  create_admin_account = "true",
  admin_email = "admin@email.com", # optional (only if 'create_admin_account' is true)
  admin_username = "admin", # optional (default: 'admin')
  enable_control_plane = "false", # optional (default: 'false')
  enable_key_service = "false", # optional (default: 'false')
  enable_models = "false" # optional (default: 'false')
)

headers = {
  'Token': token,
}
resp = requests.post(url, headers=headers, data=json.dumps(data)).json()

Response

If successful:

HTTP STATUS CODE 200

# body
{
  "ddls": [
    ..., <string: the DDL strings>
  ]
}

If error:

HTTP STATUS CODE 400
HTTP STATUS CODE 500

Test database connection

Method	Syntax
GET	api_root/database/connection

Description

Use this API to test the connection to the Instabase DB.

Examples

Request

GET api_root/database/connection

Example (Python):

url = api_root + '/database/connection'

headers = {
  'Token': token,
}
resp = requests.get(url, headers=headers).json()

Response

If successful:

HTTP STATUS CODE 200

If error:

HTTP STATUS CODE 500

Create base configs

Method	Syntax
POST	`api_root/base_configs`

Description

Info

Using this API to update your base configs for version upgrades is no longer supported, but will continue to function until release 24.01. To complete a version upgrade by API, follow the upgrades API documentation.

Use this API to create or update the base configs in Deployment Manager. You can also use this API to perform updates to Instabase, by supplying a new set of base configs corresponding to a new version of the platform. There are two ways to upload new base configs, either as text or as a compressed archive to upload many base configs at once. Multiple configurations may be uploaded together, by separating each block with the Kubernetes config delimiter (---). Your Instabase representative may provide a new set of base configurations for a new version of Instabase as a zip or tar archive; this can be uploaded directly.

Request parameters

Parameters are required unless marked as optional. Valid content types are application/x-www-form-urlencoded and multipart/form-data.

Name	Type	Description	Values
release_version	string	The release version of the base configs	A valid release version, such as `21.0.12`
base_config	string	The base configuration. Multiple configurations may be uploaded together, by separating each block with the Kubernetes config delimiter (`---`). Only exists when content-type is `application/x-www-form-urlencoded` .	Valid Kubernetes configs.
file	file	The base configs in a compressed archive. Only exists when content-type is `multipart/form-data`.	`.zip`, `.tar.gz`

Examples

Request

Shell:

curl -i -X POST -H "Content-Type: multipart/form-data" -H 'Token: token' \
-F "file=@configs.zip" -F "release_version=21.x.0" api_root/base_configs

Python:

url = api_root + '/base_configs'

data = dict(
  release_version = "21.x.0", # release version of the base configs
  base_config = "...", # the configuration
)

headers = {
  'Token': token,
  'Content-type': contentType,
}
resp = requests.post(url, headers=headers, data=json.dumps(data)).json()

Response

If successful:

HTTP STATUS CODE 200

{
  "data": {
    "successful_apply": [
      <string: the names of the objects that were successfully updated in the cluster>
    ]
  },
  "statusCode": 200
}

If failure:

HTTP STATUS CODE 500

{
  "data": {
    "successful_apply": [
      <string: the names of the objects that were successfully updated in the cluster>
    ],
    "failed_to_apply": [
      <string: the names of the objects that failed to get updated in the cluster>
    ],
  },
  "statusCode": <number: the status code of the response>,
  "error": <string: the reason for the failure>
}

Get all base configuration versions

Method	Syntax
GET	api_root/base_configs/versions

Description

Use this API to fetch details of all base configurations stored in Deployment Manager.

Response schema

All keys are returned in the response by default, unless marked as optional.

Key	Description	Value
`baseConfigVersions`	The list of base configs to versions.	A list of objects where each object contains the below keys for a base config object and its versions.
`baseConfigVersions/objectName`	The object name of the base config.	A string, such as `objectName`.
`baseConfigVersions/Versions`	The list of version strings for a given object name.	A list of strings, such as `["release-1", "release2"]`.

Examples

Example (Python):

url = api_root + '/base_configs/versions'

headers = {
  'Token': token,
}
resp = requests.get(url, headers=headers).json()

Request

GET api_root/base_configs/versions

Response

If successful:

HTTP STATUS CODE 200

# body
{
  "baseConfigVersions": [
    {
      "objectName": <string: the Kubernetes object name>,
      "Versions": <list of strings: the release versions of the object stored in Deployment Manager>
    },
    ...
  ]
}

If error:

HTTP STATUS CODE 500

Get base configuration versions of object

Method	Syntax
GET	api_root/base_configs/OBJECT_NAME/versions

Description

Use this API to fetch details of the base configurations for a specific Kubernetes object stored in Deployment Manager.

Request parameters

Name	Type	Description	Values
`OBJECT_NAME`	string	The name of the Kubernetes object.	The name of any valid Kubernetes object.

Response schema

Key	Description	Value
`versions`	A list of strings.	Each release version of the object stored in Deployment Manager.
`error`	A string explaining what went wrong.	An error message, such as “Could not get base config history.”

Examples

Request

Python example:

url = api_root + '/base_configs/' + object_name + '/versions'

headers = {
  'Token': token,
}
resp = requests.get(url, headers=headers).json()

Response

If successful:

HTTP STATUS CODE 200

# body
{
  "versions": [
    <string: each release version of the object stored in Deployment Manager>,
    ...
  ]
}

Update base config image

Method	Syntax
POST	api_root/base_configs/image

Description

Use this API to update the image of an object’s base configuration.

Request parameters

Parameters are required unless marked as optional. Valid content types are application/x-www-form-urlencoded.

Name	Type	Description	Values
image	string	The new image value.	A valid image. For example, `gcr.io/instabase-public/image:tag`.
object	string	The name of the object to update the image for.	A valid object name. For example, `deployment-core-platform-service`.
comment	string	The comment to indicate the change this image provides.	A comment on the update. For example,`numpy-package-update`. Valid characters are `a-zA-z0-9-_` with a 40 character limit.
container	string	The name of the container to update the image for. Some objects may have more than one container.	A valid container name. For example, `container1`. If left blank, defaults to first container in the list.

Examples

Request

Shell:

curl -i -X POST -H "Content-Type: application/x-www-form-urlencoded" -H 'Token: token' \
--data-urlencode 'image=imageValue' --data-urlencode 'object=deployment-core-platform-service' --data-urlencode 'comment=numpy-package-update' api_root/patches/apply api_root/base_configs/image

Python:

url = api_root + '/base_configs/image'

data = dict(
  image = "...", 
  object = "...",
  comment = "...",
  container = "..."
)

headers = {
  'Token': token,
  'Content-Type': 'application/x-www-form-urlencoded',
}
resp = requests.post(url, headers=headers, data=json.dumps(data)).json()

Response

If successful:

HTTP STATUS CODE 200

{
  "data": {
    "successful_apply": [
      <string: the names of the object that were successfully updated in the cluster>
    ]
  },
  "statusCode": 200
}

If not successful:

HTTP STATUS CODE 500

{
  "data": {
    "successful_apply": [
      <string: the names of the object that were successfully updated in the cluster>
    ],
    "failed_to_apply": [
      <string: the names of the object that failed to get updated in the cluster>
    ],
  },
  "statusCode": <number: the status code of the response>,
  "error": <string: the reason for the failure>
}

Get all base configs

Method	Syntax
GET	api_root/base_configs

Description

Use this API to get all base configs in the system, optionally filtered by version and object. If no version or object is supplied, it returns all base config and their versions.

Request

GET api_root/base_configs

Request parameters

Name	Type	Description	Values
`version`	string	The base config version.	The base config version that you want to fetch (such as 23.07.3)
`object`	string	The name of the Kubernetes object.	The name of any valid Kubernetes object.

Response

If successful:

HTTP STATUS CODE 200

# body
{
  "data": {
    "baseConfigs": [
      {
        "object_name": "name of the  bae config object",
        "version": "version of the base config",
        "previous_version": "previous version of the base config",
        "state": "state of the base config",
        "config": "config contents itself",
        "metadata": "any metadata of the base config"
      },
      ...
    ]
  },
  "statusCode": 200
}

Apply patch

Method	Syntax
POST	`api_root/patches/apply`

Description

Use this API to apply a patch config to objects or labels in Deployment Manager.

For more information on how to create labels, see the create resource label bindings API.

Request parameters

Parameters are required unless marked as optional. Valid content-types are application/x-www-form-urlencoded and multipart/form-data.

Name	Type	Description	Values
patch	string	The configuration patch to be applied as text. This can either be in YAML or JSON format. Only exists when content-type is `application/x-www-form-urlencoded`.	Any valid YAML string or marshalled JSON string.
file	file	The patch as a file, or compressed archive of configuration patches. Only exists when content-type is `multipart/form-data`.	`.yml`, `.yaml`, `.json`, `.zip`, or `.tar.gz` file
description	string	Optional. The description of why the patch is needed.	Any valid string.
dry_run	boolean	Optional. Set to true to see the new materialized config after a patch is applied without writing to database.	`true` or `false`

Examples

Request

curl -i -X POST -H "Content-Type: application/x-www-form-urlencoded" -H 'Token: token' \
--data-urlencode 'patch=patchText' api_root/patches/apply

JSON patch

JSON patches are used in Deployment Manager when you need finer control over array elements within a config (for example ports in a NetworkPolicies). They use their own format, which is defined below:

Key	Description	Value
`kind`	The kind of the object the patch is targeting.	Any valid Kubernetes resource kind.
`target`	Optional. The object or label the patch is going to be applied to.	string
`comment`	Comment about what the patch is doing.	string
`patch`	The actual patch that will be applied. This is an array of operations. More information about this can be found in the JSON patch page.	array
`patch/op`	The operation to be applied by this item.	`add, copy, remove, replace, move`
`patch/from`	Optional. Used for copy and move operations.	string
`patch/path`	The target for the operation.	string
`patch/value`	Optional. The new value for the field. Used for add operations.	`map, array, string, number`

Example JSON Patch:

{
  "comment": "Open new egress port for external service",
  "kind": "NetworkPolicy",
  "target": "some-network-policy",
  "patch": [
    {
      "op": "add",
      "path": "/spec/egress/1/ports/-",
      "value": {
        "protocol": "TCP",
        "port": 9999
      }
    }
  ]
}

Set patch targets

Every patch (file or string) must include a target tag before the patch body:

# target: targetName
apiVersion: v1
kind: Deployment
...

Every .yml in a compressed archive can have a different target.

String patch example (Python):

url = api_root + '/patches/apply'

data = dict(
  patch = "...", # body of the patch - include target tag at beginning of string
  description = "This patch updates the number of replicas for the given service",
)

headers = {
  'Token': token,
  'Content-Type': 'application/x-www-form-urlencoded',
}

resp = requests.post(url, headers=headers, data=data).json()

File patch example (Python):

url = api_root + '/patches/apply'

files=[
  ('file',('patch.yml',open('patch.yml','rb'),'application/octet-stream'))
]

data = {
    "description" : "..."
}

headers = {
    'Token': token
}

resp = requests.post(url, headers=headers, files=files, data=data).json()

File patch example (Curl):

curl --location 'api_root/patches/apply' \
--header 'token: your_token' \
--form 'file=@"patch.yml"' \
--form 'description="This patch updates the number of replicas for the given service"'

Response

When dry_run is not set or false:

If successful:

HTTP STATUS CODE 200

# body
{
  "data": {
    "successful_apply": [
      <string: the names of the objects that were successfully updated in the cluster>,
      ...
    ],
  },
  "statusCode": 200
}

If failure:

# body
{
  "data": {
    "successful_apply": [
      <string: the names of the objects that were successfully updated in the cluster>,
      ...
    ],
    "failed_to_apply": [
      <string: the names of the objects that failed to get updated in the cluster>,
      ...
    ],
  },
  "statusCode": <number: the status code of the response>,
  "error": <string: the reason for the failure>
}

Dry-run example response

When dry_run is true:

This is a dry-run patch response for two targets: object-1 and object-2. object-1 is an object with an existing base configuration. object-2 is a target with no associated objects.

# body
{
    "statusCode": 200,
    "data": {
        "dryRuns": [
            {
                "message": null,
                "dryRun": {
                    "objectName": "object-1",
                    "releaseVersion": "21.1.0",
                    "patchVersion": null,
                    "previousReleaseVersion": null,
                    "previousPatchVersion": null,
                    "state": null,
                    "config": "apiVersion: batch/v1\nkind: Deployment\nmetadata:\n  name: object-1\n  namespace:instabase",
                    "metadata": "{\"type\":\"Deployment\",\"isEncrypted\":false}",
                    "timestampMS": 1652116484052
                }
            },
            {
                "message": "Target 'object-2' is a nonexistent object. If you apply a patch to this target there will be no configuration file associated with it until an object called 'object-2' is created.",
                "dryRun": null
            }
        ]
    },
    "error": null
}

Get all patches

Method	Syntax
GET	api_root/patches

Description

Use this API to fetch all of the patches stored in Deployment Manager.

Response schema

All keys are returned in the response by default, unless marked as optional.

Name	Type	Description	Values
`data`	JSON object	An object containing the list of patches.	`{"patches" : []}`
`data/patches`	list of JSON objects	A list of json objects representing patches	`[{"version":...}, ...]`.
`data/patches[]/version`	integer	The version of the patch.	A patch version, such as `1658866352520`.
`data/patches[]/nextVersion`	integer	The version of the next patch.	A patch version, such as `1658866353683`.
`data/patches[]/target`	string	The target the patch was applied to.	`<targetName>`.
`data/patches[]/patch`	string	The body of the patch	A Kubernetes configuration patch.
`data/patches[]/metadata`	string	Metadata of the patch.	Patch metadata, such as `"{\"type\":\"Deployment\",\"isEncrypted\":false}"`.
`data/patches[]/description`	string	Description input by the user when creating the patch.	Description string, such as “Bumping up replica count”.
`statusCode`	integer	An HTTP status code.	Status code, such as `200`, `400`, or `500`.

Examples

Python

Request

url = api_root + '/patches'

headers = {
  'Token': token,
}
resp = requests.get(url, headers=headers).json()

Response

HTTP STATUS CODE 200
{
    "statusCode": 200,
    "data": {
        "patches": [
            {
                "version": 1658866352520,
                "nextVersion": 1658866353683,
                "target": "deployment-core-platform-service",
                "state": "NOT_GOLDEN",
                "patch": "apiVersion: apps/v1\nkind: Deployment\nspec:\n  template:\n    spec:\n      containers:\n        - name: CONTAINER_NAME\n          env:\n            - name: S3_SERVER_URL\n              value: \"test-server-url\"\n            - name: S3_SERVER_IS_SECURE\n              value: \"true\"\n            - name: S3_SERVER_CALLING_FORMAT\n              value: \"SubdomainCallingFormat\"\n            - name: AWS_ACCESS_KEY_ID\n              value: \"test-access-key\"\n            - name: AWS_SECRET_ACCESS_KEY\n              value: \"test-secret-key\"\n            - name: S3_AWS_REGION\n              value: \"us-east-1\"\n            - name: HOSTING_BUCKET\n              value: \"test-bucket-name\"\n            - name: INSTABASE_BUCKET\n              value: \"test-bucket-name\"\n            - name: HOSTED_STORAGE_TYPE\n              value: \"S3\"\n            - name: HOSTED_S3_ENCRYPTION_TYPE\n              value: \"aws_sse_s3\"\n            - name: USE_VIRTUAL_STYLE_URL\n              value: \"true\"",
                "metadata": "{\"type\":\"Deployment\",\"isEncrypted\":false,\"format\":\"YAML\",\"createdBy\":\"Installer\"}",
                "description": "Control Plane Installation Patch: s3_storage_patch"
            }
        ]
    },
    "error": null
}

Get all patches for object

Method	Syntax
GET	api_root/patches/OBJECT_NAME

Description

Use this API to fetch all of the patches stored in Deployment Manager for a specific object.

Request parameters

Parameters are required unless marked as optional.

Name	Type	Description	Values
`OBJECT_NAME`	string	The name of the Kubernetes object.	Any valid Kubernetes object name.

Response schema

You can add /list to the end of the URL to get just the version, target, and description parameters back in the response.

Name	Type	Description	Values
`data`	JSON object	An object containing the list of patches.	`{"patches" : []}`
`data/patches`	list of JSON objects	A list of JSON objects representing patches.	`[{"version":...}, ...]`
`data/patches[]/version`	integer	The version of the patch.	A patch version, such as `1658866352520`.
`data/patches[]/nextVersion`	integer	The version of the next patch.	A patch version, such as `1658866353683`.
`data/patches[]/target`	string	The target the patch was applied to.	`<targetName>`.
`data/patches[]/patch`	string	The body of the patch.	A Kubernetes configuration patch.
`data/patches[]/metadata`	string	Metadata of the patch.	Patch metadata, such as `"{\"type\":\"Deployment\",\"isEncrypted\":false}"`.
`data/patches[]/description`	string	Description input by the user when creating the patch.	Description string such as “Bumping up replica count”.
`statusCode`	integer	An HTTP status code.	Status code, such as `200`, `400`, or `500`.

Examples

Request

Python example:

url = api_root + '/patches/deployment-core-platform-service'

headers = {
  'Token': token,
}
resp = requests.get(url, headers=headers).json()

Response

HTTP STATUS CODE 200
{
    "statusCode": 200,
    "data": {
        "patches": [
            {
                "version": 1658866352520,
                "nextVersion": 1658866353683,
                "target": "deployment-core-platform-service",
                "state": "NOT_GOLDEN",
                "patch": "apiVersion: apps/v1\nkind: Deployment\nspec:\n  template:\n    spec:\n      containers:\n        - name: CONTAINER_NAME\n          env:\n            - name: S3_SERVER_URL\n              value: \"test-server-url\"\n            - name: S3_SERVER_IS_SECURE\n              value: \"true\"\n            - name: S3_SERVER_CALLING_FORMAT\n              value: \"SubdomainCallingFormat\"\n            - name: AWS_ACCESS_KEY_ID\n              value: \"test-access-key\"\n            - name: AWS_SECRET_ACCESS_KEY\n              value: \"test-secret-key\"\n            - name: S3_AWS_REGION\n              value: \"us-east-1\"\n            - name: HOSTING_BUCKET\n              value: \"test-bucket-name\"\n            - name: INSTABASE_BUCKET\n              value: \"test-bucket-name\"\n            - name: HOSTED_STORAGE_TYPE\n              value: \"S3\"\n            - name: HOSTED_S3_ENCRYPTION_TYPE\n              value: \"aws_sse_s3\"\n            - name: USE_VIRTUAL_STYLE_URL\n              value: \"true\"",
                "metadata": "{\"type\":\"Deployment\",\"isEncrypted\":false,\"format\":\"YAML\",\"createdBy\":\"Installer\"}",
                "description": "Control Plane Installation Patch: s3_storage_patch"
            }
        ]
    },
    "error": null
}

Delete patch

Method	Syntax
DELETE	api_root/patches/VERSION

Description

Use this API to forcibly remove a patch from Deployment Manager and regenerate the materialized configs affected by the patch.

Request parameters

Parameters are required unless marked as optional.

Name	Type	Description	Values
`VERSION`	string	Version of the patch to be deleted.	A string specifying an existing patch version.

Response schema

All keys are returned in the response by default, unless marked as optional.

Key	Type	Description	Value
`data`	JSON object	An object containing lists of objects.	`{"data": {"successful_apply": []}}`
`data/successful_apply`	list of strings	A list of objects successfully updated in the cluster.	`{"successful_apply": ["deployment-apps-server"]}`
`data/failed_to_apply`	list of strings	A list of objects failed to apply in the cluster.	`{"failed_to_apply": ["deployment-api-server"]}`
`statusCode`	integer	A HTTP status code.	Status code, such as `200`, `400`, or `500`.
`error`	string	If failed, reason for the failure.

Examples

Request

Example (Python):

url = api_root + '/patches/' + version

headers = {
  'Token': token,
}
resp = requests.delete(url, headers=headers)

Response

The response body is a JSON object.

If successful:

HTTP STATUS CODE 200

{
  "data": {
    "successful_apply": [
      <string: the names of the objects that were successfully updated in the cluster>
    ]
  },
  "statusCode": 200
}

If failure:

# body
{
  "data": {
    "successful_apply": [
      <string: the names of the objects that were successfully updated in the cluster>
    ],
    "failed_to_apply": [
      <string: the names of the objects that failed to get updated in the cluster>
    ],
  },
  "statusCode": <number: the status code of the response>,
  "error": <string: the reason for the failure>
}

Update namespace

Description

Method	Syntax
POST	api_root/patches/namespace

Use this API to update the namespace of all configs. Note that existing objects with the old namespace will not be deleted—these must be cleaned up manually.

Request parameters

The request body must be a JSON object with these parameters. Parameters are required unless marked as optional.

Name	Type	Description	Values
`namespace`	string	The new namespace.	A string specifying a valid namespace.

Response schema

All keys are returned in the response by default, unless marked as optional.

Key	Type	Description	Value
`data`	JSON Object	An object containing lists of objects.	`{"data": {"successful_apply": []}}`
`data/successful_apply`	List of string	A list of objects successfully updated in the cluster.	`{"successful_apply": ["deployment-apps-server"]}`
`data/failed_to_apply`	List of string	A list of objects failed to apply in the cluster.	`{"failed_to_apply": ["deployment-api-server"]}`
`statusCode`	Integer	A HTTP status code.	Status code, such as `200`, `400`, or `500`.
`error`	String	If failed, reason of the failure.

Examples

Request

Example (Python):

url = api_root + '/patches/namespace'
data = dict(
  namespace = "instabase", # the new namespace for Instabase to run in
  description = "The namespace for the new cluster.",
)
headers = {
  'Token': token,
}
resp = requests.post(url, headers=headers, data=json.dumps(data)).json()

Response

The response body is a JSON object.

If successful:

HTTP STATUS CODE 200
{
  "data": {
    "successful_apply": [
      <string: the names of the objects that were successfully updated in the cluster>
    ]
  },
  "statusCode": 200
}

If failure:

# body
{
  "data": {
    "successful_apply": [
      <string: the names of the objects that were successfully updated in the cluster>
    ],
    "failed_to_apply": [
      <string: the names of the objects that failed to get updated in the cluster>
    ],
  },
  "statusCode": <number: the status code of the response>,
  "error": <string: the reason for the failure>
}

Set image registry

Method	Syntax
POST	api_root/patches/registry

Description

Use this API to set the image registry of all configs.

Request parameters

The request body must be a JSON object with these parameters. Parameters are required unless marked as optional.

Param Type	Name	Type	Description	Values
Body	`registry`	string	The new image registry.	A string specifying a valid image registry.

Response schema

All keys are returned in the response by default, unless marked as optional.

Key	Type	Description	Value
`data`	JSON object	An object containing lists of objects.	`{"data": {"successful_apply": []}}`
`data/successful_apply`	list of strings	A list of objects successfully updated in the cluster.	`{"successful_apply": ["deployment-apps-server"]}`
`data/failed_to_apply`	list of strings	A list of objects failed to apply in the cluster.	`{"failed_to_apply": ["deployment-api-server"]}`
`statusCode`	integer	A HTTP status code.	Status code, such as `200`, `400`, or `500`.
`error`	string	If failed, reason for the failure.

Examples

Request

Example (Python):

url = api_root + '/patches/registry'

data = dict(
  registry = "gcr.io/instabase-public", # the new image registry to pull the Instabase docker images from
)

headers = {
  'Token': token,
}
resp = requests.post(url, headers=headers, data=json.dumps(data)).json()

Response

The response body is a JSON object.

If successful:

HTTP STATUS CODE 200

{
  "data": {
    "successful_apply": [
      <string: the names of the objects that were successfully updated in the cluster>
    ]
  },
  "statusCode": 200
}

If failure:

# body
{
  "data": {
    "successful_apply": [
      <string: the names of the objects that were successfully updated in the cluster>
    ],
    "failed_to_apply": [
      <string: the names of the objects that failed to get updated in the cluster>
    ],
  },
  "statusCode": <number: the status code of the response>,
  "error": <string: the reason for the failure>
}

Get all latest materialized configurations

Method	Syntax
GET	api_root/configs

Description

Use this API to fetch the latest materialized configuration for all resources.

Response schema

All keys are returned in the response by default, unless marked as optional.

Key	Description	Value
`configs`	A list of all materialized configurations.
`objectName`	The Kubernetes object name.
`releaseVersion`	The release version of the materialized configuration.
`patchVersion`	The patch version of the materialized configuration.
`previousReleaseVersion`	The release version of the previous materialized configuration.
`previousPatchVersion`	The patch version of the previous materialized configuration.
`state`	Whether the materialized configuration is currently active.	`IS_GOLDEN` if currently active, `NOT_GOLDEN` otherwise
`config`	The text of the materialized configuration.
`metadata`	Metadata of the materialized configuration.
`timestampMS`	Unix timestamp of the materialized configuration create time.

Examples

Request

Example (Python):

url = api_root + '/configs'

headers = {
  'Token': token,
}
resp = requests.get(url, headers=headers).json()

Response

If successful:

HTTP STATUS CODE 200

# body
{
  "configs": [
    {
      "objectName": <string>,
      "releaseVersion": <string>,
      "patchVersion": <integer>,
      "previousReleaseVersion": <string>,
      "previousPatchVersion": <integer>,
      "state": <string>,
      "config": <string>,
      "metadata": <string>,
      "timestampMS": <integer>
    }
    ...
  ]
}

Get materialized configuration of object

Method	Syntax
GET	api_root/configs/OBJECT_NAME

Description

Use this API to fetch the materialized configuration file of a single object.

Request parameters

Parameters are required unless marked as optional.

Name	Type	Description	Values
`OBJECT_NAME`	string	The Kubernetes object name to fetch the materialized configuration file from.	A string specifying a valid name of a Kubernetes object.

Response schema

All keys are returned in the response by default, unless marked as optional.

Key	Description	Value
`objectName`	The Kubernetes object name.	A string of the object name.
`releaseVersion`	The release version of the materialized configuration.	A string of the release version.
`patchVersion`	The patch version of the materialized configuration.	An integer of the patch version.
`previousReleaseVersion`	The release version of the previous materialized configuration.	An integer of the previous release version.
`previousPatchVersion`	The patch version of the previous materialized configuration.	An integer of the previous patch version.
`state`	Whether the materialized configuration is currently active.	The string “IS_GOLDEN” if the materialized configuration is currently active, otherwise the string “NOT_GOLDEN”.
`config`	The text of the materialized configuration.	A string of the text of the materialized configuration.
`metadata`	Metadata of the materialized configuration.	A string of the metadata of the materialized configuration.
`timestampMS`	Unix timestamp of the materialized configuration creation time.	An integer of the unix timestamp.

Examples

Example (Python):

url = api_root + '/configs/service-victoriametrics'

headers = {
  'Token': token,
}
resp = requests.get(url, headers=headers).json()

Request

GET api_root/configs/service-victoriametrics

Response

{
    "objectName": "service-victoriametrics",
    "releaseVersion": "$RELEASE_VERSION",
    "patchVersion": 0,
    "previousReleaseVersion": "",
    "previousPatchVersion": 0,
    "state": "NOT_GOLDEN",
    "config": "apiVersion: v1\nkind: Service\nmetadata:\n  name: service-victoriametrics\n  namespace: instabase\n  labels:\n    app: 
victoriametrics\n  annotations:\n    monitoring/enabled: \"true\"\nspec:\n  selector:\n    app: victoriametrics\n  ports:\n    - name: http\n      
protocol: TCP\n      port: 8428\n      targetPort: http\n  clusterIP: None\n",
    "metadata": "{\"type\":\"Service\",\"isEncrypted\":false}",
    "timestampMS": 1656287479653
}

Push latest materialized configs to cluster

Method	Syntax
POST	api_root/deployment/update

Description

Use this API to push all the latest materialized configs to the Instabase cluster.

Response schema

All keys are returned in the response by default, unless marked as optional.

Key	Description	Value
`statusCode`	The status code of the request.	An integer of the status code.
`data`	The objects which have successfully updated their materialized configs.	An object with key “successful_apply”, which is a string. Value is an array of the object names that have successfully updated their materialized configs.
`error`	The error message, if an error had occurred.	A string of the error messsage, or null if successful.

Examples

Example (Python):

url = api_root + '/deployment/update'

headers = {
  'Token': token,
}
resp = requests.post(url, headers=headers, data=json.dumps(data)).json()

Request

POST api_root/deployment/update

Response

{
    "statusCode": 200,
    "data": {
        "successful_apply": [
           "alertmanager-egress",
           "api-server-apps-egress",
           "service-victoriametrics"
        ]
    },
    "error": null
}

Get all resource labels

Method	Syntax
GET	api_root/resource_labels

Description

Use this API to get a list of all the unique resource labels that exist. This can be used to help with targeting a patch to a label.

Response schema

All keys are returned in the response by default, unless marked as optional.

Key	Description	Value
`statusCode`	The status code of the request.	An integer of the status code.
`data`	Contains an object “labels”, which contains the names of the labels.	An object with key “labels”, which contains a string array of the names of the resource labels.
`error`	The error message, if an error had occurred.	A string of the error messsage, or null if successful.

Examples

Example (Python):

url = api_root + '/resource_labels'

headers = {
  'Token': token,
}
resp = requests.post(url, headers=headers, data=json.dumps(data)).json()

Request

POST api_root/deployment/update

Response

{
    "statusCode": 200,
    "data": {
        "labels": [
           "ConfigMap",
           "Deployment",
           "Job"
        ]
    },
    "error": null
}

Create resource label bindings

Method	Syntax
POST	api_root/resource_labels/binding

Description

Use this API to create the resource label bindings between objects and labels.

Request parameters

Parameters are required unless marked as optional. The request body must be a URL-encoded form with the parameters below.

When there are multiple labels or object names, the API generates all possible label-object pairs based on all given labels and object names, and creates a binding between each pair.

Name	Type	Description	Values
`label`	string	Can have multiple labels by sending duplicate “label” keys.	A string specifying a resource label.
`object_name`	string	Can have multiple object names by sending duplicate “object_name” keys. All the objects in object_names will be assigned all of the labels in label.	A string specifying the object name of the created resource label.

Response schema

All keys are returned in the response by default, unless marked as optional.

Key	Description	Value
`statusCode`	The status code of the request.	An integer of the status code.
`data`	Contains an object “successful_apply”, which contains the names of the objects successfully updated in the cluster with the new labels. Also contains an object “failed_to_apply” with the object names of unsuccessful updates.	An object with key “successful_apply” that contains a string array of the object names successfully updated in the cluster and with key “failed_to_apply” that contains a string array of the object names unsuccessfully updated.
`error`	The error message, if an error had occurred.	A string of the error messsage, or null if successful.

Request

Example (Python):

url = api_root + '/resource_labels/binding'

data = ("label=database"
        "&label=grpc"
        "&object_name=deployment-a-service"
        "&object_name=deployment-b-service"
        "&object_name=deployment-c-service")

headers = {
    'Token': token,
    'content-type': 'application/x-www-form-urlencoded'
}

resp = requests.post(url, headers=headers, data=data)

Response

{
    "statusCode": 200,
    "data": {
        "successful_apply": [
           "alertmanager-egress",
           "api-server-apps-egress",
           "service-victoriametrics"
        ]
    },
    "error": null
}

Get object names by label

Method	Syntax
GET	api_root/resource_labels/objects/LABEL?must_exist=false

Description

Use this API to fetch all object names that are bound to the label.

Request parameters

Parameters are required unless marked as optional.

Name	Type	Description	Values
`LABEL`	string	Required. The label to fetch the resource label bindings from.
`must_exist`	boolean	Optional. If true, fetches only objects that have associated base configs.	Default value is false.

Response schema

All keys are returned in the response by default, unless marked as optional.

Key	Description	Value
`objects`	List of Kubernetes object names.

Examples

Request

Get the object names that are bound to the label by sending a GET request to api_root/resource_labels/objects/LABEL?must_exist=BOOL, where:

GET api_root/resource_labels/objects/LABEL?must_exist=false

Example (Python):

url = api_root + '/resource_labels/objects/' + label

headers = {
  'Token': token,
}
resp = requests.get(url, headers=headers).json()

Response

If successful:

HTTP STATUS CODE 200

# body
{
  "objects": <list<string: Kubernetes object name>>
}

Get labels by object name

Method	Syntax
GET	api_root/resource_labels/labels/OBJECT_NAME

Description

Use this API to fetch all labels that are bound to the object.

Request parameters

Parameters are required unless marked as optional.

Name	Type	Description	Values
`OBJECT_NAME`	string	The Kubernetes object name to fetch the resource label bindings from.

Response schema

All keys are returned in the response by default, unless marked as optional.

Key	Description	Value
`labels`	List of label names.

Examples

Request

Get the labels that are bound to the object by sending a GET request to api_root/resource_labels/labels/OBJECT_NAME, where:

GET api_root/resource_labels/labels/OBJECT_NAME

Example (Python):

url = api_root + '/resource_labels/labels/' + object_name

headers = {
  'Token': token,
}
resp = requests.get(url, headers=headers).json()

Response

If successful:

HTTP STATUS CODE 200

# body
{
  "labels": <list<string: label name>>
}

Delete object bindings

Method	Syntax
DELETE	api_root/resource_labels/binding/OBJECT_NAME

Description

Use this API to delete all resource label bindings of an object. After using this API, the specified object will no longer have any label bindings associated with it.

Request parameters

Parameters are required unless marked as optional.

Name	Type	Description	Values
`OBJECT_NAME`	string	Kubernetes object name.

Examples

Request

Delete all resource label bindings of an object by sending a DELETE request to api_root/resource_labels/binding/OBJECT_NAME.

DELETE api_root/resource_labels/binding/OBJECT_NAME

Example (Python):

url = api_root + '/resource_labels/binding/' + object_name

headers = {
  'Token': token,
}
resp = requests.delete(url, headers=headers)

Response

If successful:

HTTP STATUS CODE 200

Update default resource labels

Method	Syntax
POST	api_root/resource_labels/update-defaults

Description

Use this API to keep your default resource labels up-to-date. It will check the default labels in Deployment Manager, and create the new ones if missing.

Examples

Request

Update the default resource labels by sending a POST request to api_root/resource_labels/update-defaults.

POST api_root/resource_labels/update-defaults

Example (Python):

url = api_root + '/resource_labels/update-defaults'

headers = {
  'Token': token,
}
resp = requests.post(url, headers=headers)

Response

If successful:

HTTP STATUS CODE 200

Update cluster size

Method	Syntax
POST	api_root/resourcing/cluster/:size:

Description

Use this API to update your Instabase cluster size configuration, using Instabase standard resourcing sizing. Based on the cluster size you choose, this API updates the replica count and resourcing for the underlying services to the latest configured values.

This API has no request parameters. Instead, you define the cluster size in the API URL path. The following preset cluster sizes are available:

standard: 64 CPU cores/256 GB RAM
large: 128 CPU cores/512 GB RAM
x-large: 256 CPU cores/1024 GB RAM

Select the option that meets but does not exceed your cluster size. After installation, you can use patches to manually adjust the Instabase cluster size configuration to more closely match your Kubernetes cluster size.

Examples

Request

Update the cluster size by sending a POST request to api_root/resourcing/cluster/:size:, where :size: can be standard, large, or x-large.

POST api_root/resourcing/cluster/:size:

Example (Python):

url = api_root + '/resourcing/cluster/standard'

headers = {
  'Token': token,
}
resp = requests.post(url, headers=headers)

Response

If successful:

{
    "statusCode": 200,
    "data": {
        "successful_apply": [
           "alertmanager-egress",
           "api-server-apps-egress",
           "service-victoriametrics"
        ]
    },
    "error": null
}

Pause autoscaling controllers

Method	Syntax
POST	api_root/autoscaling/controllers/pause

Description

Pause all active autoscaling controllers. Autoscaling controllers work behind the scenes to optimize infrastructure utilization based on platform specifications.

Examples

Request

Example (cURL):

curl -i -X POST -H 'Token: {token}' ${api_root}/autoscaling/controllers/pause

Response

If successful:

HTTP STATUS CODE 200

Resume autoscaling controllers

Method	Syntax
POST	api_root/autoscaling/controllers/resume

Description

Resume all paused autoscaling controllers.

Examples

Request

Example (cURL):

curl -i -X POST -H 'Token: {token}' ${api_root}/autoscaling/controllers/resume

Response

If successful:

HTTP STATUS CODE 200

Get autoscaling controller statuses

Method	Syntax
GET	api_root/autoscaling/controllers/status

Description

See the status of all autoscaling controllers to see which are running or paused.

Examples

Request

Example (cURL):

curl -i -X GET -H 'Token: {token}' ${api_root}/autoscaling/controllers/status

Response

If successful:

HTTP STATUS CODE 200

# body
{
  "binary-autoscaler": "running",
  "scale-down-to-zero": "paused"
}

Get all containers for resource

Method	Syntax
GET	api_root/base_configs/:object/containers

Description

Returns a list of the containers for the Kubernetes resource (:object) specified in the request URL.

Examples

Request

Example (cURL):

curl -i -X GET -H 'Token: token' ${api_root}/base_configs/deployment-api-server/containers

Response

If successful:

HTTP STATUS CODE 200

# body
{
    "statusCode": 200,
    "data": [
      "api-server",
      "stats-collector",
      "jaeger-agent"
    ],
    "error": null
}

If error:

HTTP STATUS CODE 500

# body
{
    "statusCode": 500,
    "error": "Reason for error"
}

Get all release versions for resource

Method	Syntax
GET	api_root/base_configs/:object/versions

Description

Returns a list of all release version numbers that include a base config for the object specified in the request URL.

Examples

Request

Example (cURL):

curl -i -X GET -H 'Token: token' ${api_root}/base_configs/deployment-api-server/versions

Response

If successful:

HTTP STATUS CODE 200

# body
{
    "versions": [
      "22.10.1",
      "22.10.2",
      "23.01.4",
      "23.01.5"
    ]
}

If error:

HTTP STATUS CODE 500

# body
"Reason for error"

Get upgrade history

Method	Syntax
GET	api_root/base_configs/history

Description

Get a list of all platform upgrades that have occurred, including which users uploaded base configs for the upgrade and timestamps for when the upgrade was created and last updated. Optionally supports pagination. Sorted by release version.

Examples

Request

GET api_root/base_configs/history?limit=<N>&offset=<K>

Example (cURL):

curl -i -X GET -H 'Token: token' ${api_root}/base_configs/history?limit=50&offset=10

Response

If successful:

HTTP STATUS CODE 200

# body
{
    "statusCode": 200,
    "data": {
        "upgrades": [
          {
            "version": "23.01.0",
            // Creators - all users who uploaded base configs for this version
            "creators": [
              "user1@mydomain.com",
              "user2@mydomain.com"
            ],
            "lastUpdatedTimestampMS": <int>,
            "createdAtTimestampMS": <int>
          },
          ...
        ]
    },
    "error": null
}

If error:

HTTP STATUS CODE 400
HTTP STATUS CODE 500

# body
{
    "statusCode": <status_code>,
    "error": "Reason for error"
}

Asynchronous base configs upload

Method	Syntax
POST	api_root/base_configs/upload

Description

Use this API to asynchronously create or update the base configs in Deployment Manager. You can also use this API to perform updates to Instabase, by supplying a new set of base configs corresponding to a new version of the platform.

Info

Asynchronous endpoints don’t return the result of the request in their response. Instead, an ID value is returned, which is used in a subsequent API call. Use the Get results of asynchronous base configs upload to see the status of an Asynchronous base configs upload request.

You can upload new base configs as either text or as a compressed archive to upload many base configs at once.

You can upload multiple configurations together by separating each block with the Kubernetes config delimiter (---). Your Instabase representative might provide a new set of base configurations for a new version of Instabase as a .zip or .tar archive; you can upload these base configs directly.

Request parameters

Parameters are required unless marked as optional. Valid content types are application/x-www-form-urlencoded and multipart/form-data.

Name	Type	Description	Values
release_version	string	The release version of the base configs	A valid release version, such as `21.0.12`
base_config	string	The base configuration. You can upload multiple configurations by separating each block with the Kubernetes config delimiter (`---`). Only exists when content-type is `application/x-www-form-urlencoded` .	Valid Kubernetes configs.
file	file	The base configs in a compressed archive. Only exists when content-type is `multipart/form-data`.	`.zip`, `.tar.gz`	`

Examples

Request

curl -i -X POST -H "Content-Type: multipart/form-data" -H 'Token: token' \
-F "file=@configs.zip" -F "release_version=21.x.0" api_root/base_configs/upload

Response

If successful:

HTTP STATUS CODE 200

{
  "data": {
    "RequestID": <string: id of async task>
  },
  "status_code": 200
}

If failure:

HTTP STATUS CODE 400
HTTP STATUS CODE 500

# body
"Reason for error"

Get results of asynchronous base configs upload

Method	Syntax
GET	api_root/base_configs/upload/:request_id

Description

Use this API to check the status of a request made using the Asynchronous base configs upload API. Use the request URL to specify the ID of the Asynchronous base configs upload request.

Examples

Request

Example (cURL):

curl -i -X GET -H 'Token: token' api_root/base_configs/upload/1a2b3c

Response

If successful:

HTTP STATUS CODE 200

# body
{
    "statusCode": 200,
    "data": {
        "successful_apply": [
           "alertmanager-egress",
           "api-server-apps-egress",
           "service-victoriametrics"
        ]
    },
    "error": null
}

If error:

HTTP STATUS CODE 400
HTTP STATUS CODE 500

Find inconsistent resources

Method	Syntax
GET	api_root/configs/k8s-inconsistencies

Description

Find out which Kubernetes resources’ states have diverged between what is running in Kubernetes and what is running in the database.

Examples

Request

curl -i -X POST -H 'Token: token' ${api_root}/configs/k8s-inconsistencies

Response

If successful:

HTTP STATUS CODE 200

# body
{
  "numInconstencies": 1,
  "inconsistentResources": {
    "deployment-api-server":{
      "diffRows": [
        {
          "key": <string>,
          "expected": <string>,
          "got": <string>
        }
      ]
    },
    "consistentResources": [
      "deployment-1",
      "deployment-2",
      ...
    ],
    "skippedResources": {
      "deployment-some-service": {
        "code": <int: internal-status-code>,
        "readon": <string>
      }
    }
  }

NumInconsistencies int `json:"numInconsistencies"`
	// resources that are inconsistent with k8s
	InconsistentResources map[string]utils.Diff `json:"inconsistentResources"`
	// resources that are consistent
	ConsistentResources []string `json:"consistentResources"`
	// consistency check skipped for these resources
	SkippedResources map[string]ConsistencyCheckSkipReason `json:"skippedResources"`
}

If error:

HTTP STATUS CODE 500

"Reason for error"

Get Deployment Manager namespace

Method	Syntax
GET	api_root/deployments/namespace

Description

Get the namespace that Deployment Manager is currently running in.

Examples

Request

curl -i -X GET -H 'Token: token' api_root/deployments/namespace

Response

If successful:

HTTP STATUS CODE 200

# body
{
    "statusCode": 200,
    "data": {
       "namespace": "instabase"
    },
    "error": null
}

Download telemetry data

Method	Syntax
POST	api_root/obs/telescope/export

Description

Use this API to download Telescope telemetry data as a .zip file.

Request parameters

The request body must be a JSON object with these parameters. Parameters are required unless marked as optional.

Name	Type	Description
`services`	string[]	The list of services to be included in the report.
`data_sources`	string[]	The list of data sources to be included in the report. Options are `LOGS`, `STATS`, and `CONFIGS`.
`start`	string	An ISO-formatted timestamp representing the start of the data collection period.
`end`	string	An ISO-formatted timestamp representing the end of the data collection period.
`label`	string	A label to identify the generated Telescope file.

Examples

Request

Shell:

curl -H 'Token: token' api_root/obs/telescope/export -d <REQUEST_BODY>

Request Body

{
  "services": ["server-nginx"],
  "data_sources": ["LOGS"],
  "label": "any-label",
  "start": "2023-10-26T13.08.45.131Z",
  "end": "2023-10-26T14:08:45.131Z"
}

Response

If successful:

{
  "statusCode": 200,
  "data": {
    "id": "0b7e18e3-5e71-429a-8e6d-a8a467003e6d",
    "job_status": "WAITING",
    "request": {
      "services": ["server-nginx"],
      "data_sources": ["LOGS"],
      "start": "2023-10-26T13:08:45.131Z",
      "end": "2023-10-26T14:08:45.131Z",
      "label": "any-label-1698329335912"
    },
    "result": {
      "zip_file_path": ""
    }
  },
  "error": null
}

Check telemetry data status

Method	Syntax
GET	api_root/obs/telescope/export/:id/status

Description

Use this API to check the status of a Telescope telemetry data request. The ID should correspond to the ID received from the api_root/obs/telescope/export endpoint used to initiate the data request.

Examples

Request

Shell:

curl -H 'Token: token' api_root/obs/telescope/export/:id:/status

Response

If successful:

{
  "statusCode": 200,
  "data": {
    "id": "0b7e18e3-5e71-429a-8e6d-a8a467003e6d",
    "job_status": "SUCCESS",
    "request": {
      "services": ["server-nginx"],
      "data_sources": ["LOGS"],
      "start": "2023-10-26T13:08:45.131Z",
      "end": "2023-10-26T14:08:45.131Z",
      "label": "ommR0Z-25131-1698329335912"
    },
    "result": {
      "zip_file_path": "/tmp/telescope-2459079637/0b7e18e3-5e71-429a-8e6d-a8a467003e6d.zip"
    }
  },
  "error": null
}

Upload telemetry data

Method	Syntax
POST	api_root/obs/telescope/import

Description

Use this API to upload a previously exported telemetry .zip file, to access your data sources on Grafana.

Examples

Request

Shell:

curl -i -X POST -H "Content-Type: multipart/form-data" -H 'Token: token' \
-F "file=@telescope.zip"

Response

If successful:

{
  "statusCode": 200,
  "data": {
    "id": "bbd84cbe-50f8-4a98-a346-357fd1b07ebf",
    "job_status": "SUCCESS",
    "request": {
      "zip_file_path": "/tmp/telescope-3633448012/bbd84cbe-50f8-4a98-a346-357fd1b07ebf.zip"
    },
    "result": {
      "services": ["core-platform-service"],
      "data_sources": ["STATS"],
      "start": "2023-09-28T13:53:53.423Z",
      "end": "2023-09-28T14:53:53.423Z",
      "label": "Wh2Pe9-33423-1695912845006"
    }
  },
  "error": null
}

Download imported telemetry configs

Method	Syntax
GET	api_root/obs/telescope/import/:id/configs

Description

Use this API to download telemetry configs that were previously uploaded. Use the request URL to pass the ID value returned by a previous Upload telemetry data request.

Query parameters

Name	Type	Description
`id`	string	The ID of the uploaded import job.

Examples

Request

Shell:

curl -H 'Token: token' api_root/obs/telescope/import/:id:/configs

Response

If successful:

{
  "statusCode": 200,
  "data": {},
  "error": null
}

Check status of imported telemetry data

Method	Syntax
GET	api_root/obs/telescope/import/:id/status

Description

Use this API to check the status of previously uploaded telemetry data. Use the request URL to pass the ID value returned by a previous Upload telemetry data request.

Query parameters

Name	Type	Description
`id`	string	The ID of the uploaded import job.

Examples

Request

Shell:

curl -H 'Token: token' api_root/obs/telescope/import/:id:/status

Response

If successful:

{
  "statusCode": 200,
  "data": {},
  "error": null
}

Search patches by keyword

Method	Syntax
GET	api_root/patches/search

Description

Use this API to search through all patches for a specific keyword or phrase.

Query parameters

All parameters are required.

Name	Type	Description
`query`	string	The keyword or phrase you’re searching for.
`caseSensitive`	boolean	Whether to match the case of the query. Set to `true` to enforce case sensitivity.
`limit`	number	The maximum number of patches to return.

Examples

Request

Shell:

curl -H 'Token: token' api_root/patches/search?query=tracing&caseSensitive=false&limit=80

For queries with multiple words, encode spaces as the + character:

curl -H 'Token: token' api_root/patches/search?query=LOG_LEVEL:+ERROR&caseSensitive=true&limit=10

Response

If successful:

{
  "patches": [
    {
      "version": "1654815406062",
      "nextVersion": "1654815474632",
      "target": "hot-configs",
      "state": "NOT_GOLDEN",
      "patch": "apiVersion: v1\nkind: ConfigMap\nmetadata:\n  name: hot-configs\n  namespace: instabase-dogfood\n# __ib_label=scalar\ndata:\n  base-hot-config: |\n    ENABLE_TRACING: false\n    dummy_key: dummy_value\n    LOG_LEVEL: ERROR\n    STATS_ENABLE: true\n  deployment-core-platform-service: |\n    dummy_key: dummy_value\n    LOG_LEVEL: INFO\n  deployment-api-server: |\n    ENABLE_TRACING: true\n    dummy_key: dummy_value\n    LOG_LEVEL: INFO\n  deployment-api-server-apps: |\n    ENABLE_TRACING: true\n    dummy_key: dummy_value\n    LOG_LEVEL: INFO\n  deployment-apps-server: |\n    dummy_key: dummy_value\n    LOG_LEVEL: ERROR\n  deployment-webapp: |\n    dummy_key: dummy_value\n    LOG_LEVEL: INFO\n  deployment-file-service: |\n    dummy_key: dummy_value\n    LOG_LEVEL: INFO\n  deployment-license-service: |\n    dummy_key: dummy_value\n  deployment-job-service: |\n    dummy_key: dummy_value",
      "metadata": "{\"type\":\"ConfigMap\",\"isEncrypted\":false}",
      "description": ""
    }
  ]
}

Get platform status

Method	Syntax
GET	api_root/platform-status/components

Description

Use this API to get the current platform status. Like the Platform status tab available in Deployment Manager, this API returns a high-level overview of the health of various components in your deployment, such as the database and filesystem.

Examples

Request

Shell:

curl -H 'Token: token' api_root/platform-status/components

Response

If successful:

{
  "statusCode": 200,
  "data": {
    "database": {
      "last_updated_epoch_seconds": 1695914909,
      "health_checks_by_id": {
        "Database Connection": {
          "id": "Database Connection",
          "status": "healthy",
          "component_name": "database",
          "details": "Check Passed!",
          "tags": [
            "platform-status-dashboard",
            "upgrade"
          ],
          "is_critical": true,
          "contiguous_fails": 0,
          "first_check_started_at_epoch_seconds": 1695896294,
          "last_checked_at_epoch_seconds": 1695914813,
          "last_check_runtime_milliseconds": 249,
          "last_success_at_epoch_seconds": 1695914813
        },
        ...
      }
    },
    ...
  },
  "error": null
}

Get platform release version

Method	Syntax
GET	api_root/platform/version

Description

Use this API to get the current platform release version of your deployment.

Examples

Request

Shell:

curl -H 'Token: token' api_root/platform/version

Response

If successful:

{
  "statusCode": 200,
  "data": {
    "release_version": "23.07"
  },
  "error": null
}

Revive the Instabase platform

Method	Syntax
POST	api_root/deployment/revive

Description

Use this API to revive the Instabase platform from hibernation. This endpoint is primarily used by Instabase Cloud Console to manage SaaS deployments, and should only be directly used by advanced users.

Examples

Request

Shell:

curl -X POST -H 'Token: token' api_root/deployment/revive

Response

If successful:

{
  "statusCode": 200,
  "data": null,
  "error": null
}

Update all objects

Method	Syntax
POST	api_root/deployment/update

Description

Use this API to apply the current materialized configs for all objects to Kubernetes.

Examples

Request

Shell:

curl -X POST -H 'Token: token' api_root/deployment/update

Response

If successful:

{
  "statusCode": 200,
  "data": {
    "successful_apply": ["deployment-api-server", "deployment-webapp"],
    "failed_to_apply": {
      "deployment-loki-read": "reason"
    }
  },
  "error": null
}

Update an object

Method	Syntax
POST	api_root/deployment/update/:object

Description

Use this API to apply the current materialized config for a single object to Kubernetes. Use the request URL to pass the name of the object.

Examples

Request

Shell:

curl -X POST -H 'Token: token' api_root/deployment/update/deployment-api-server

Response

If successful:

{
  "statusCode": 200,
  "data": {
    "successful_apply": ["deployment-api-server"],
    "failed_to_apply": {}
  },
  "error": null
}

Get autoscaled resources

Method	Syntax
GET	api_root/resourcing/autoscaled

Description

Use this API to determine which resources in the cluster currently have autoscaling enabled.

This API has no request parameters.

Examples

Request

GET api_root/resourcing/autoscaled

Response

If successful:

{
    "statusCode": 200,
    "data": {
        "names": [
           "deployment-api-server",
            "deployment-apps-server",
            "deployment-celery-app-tasks",
            "deployment-conversion-service",
            "deployment-model-service"
        ]
    },
    "error": null
}

Get settings

Method	Syntax
GET	api_root/settings

Description

Use this API to determine some of the platform related settings and their values.

This API has no request parameters.

Examples

Request

GET api_root/settings

Response

If successful:

HTTP STATUS CODE 200

{
  "data": {
    "settings": {
        "isAIHubEnvironment": "false",
        "isDocsEnabled": "false",
        "isDocsFromWordpress": "true",
        "isDogfoodEnvironment": "true",
        "isProdEnvironment": "false",
        "isSaasEnvironment": "false",
        "isUATEnvironment": "false",
        "obsAlertEmailAppPassword": "",
        "obsAlertReceiverEmail": "",
        "obsAlertSenderEmail": "",
        "obsAlertSlackChannel": "",
        "obsAlertSlackUrl": "",
        "obsAlertSmtpServer": "",
        ...
    }
  },
  "statusCode": 200,
  "error": null
}

Update settings

Method	Syntax
POST	api_root/settings

Description

Use this API to update the some of platform settings and their values.

Examples

Request

POST api_root/settings

Request parameters

The request body must be a JSON object with the same structure as the GET settings endpoint above. It must be complete, ideally taken from the GET API.

HTTP STATUS CODE 200

{
  "data": {
    "settings": {
        "isAIHubEnvironment": "false",
        "isDocsEnabled": "false",
        "isDocsFromWordpress": "true",
        "isDogfoodEnvironment": "true",
        "isProdEnvironment": "false",
        "isSaasEnvironment": "false",
        "isUATEnvironment": "false",
        "obsAlertEmailAppPassword": "",
        "obsAlertReceiverEmail": "",
        "obsAlertSenderEmail": "",
        "obsAlertSlackChannel": "",
        "obsAlertSlackUrl": "",
        "obsAlertSmtpServer": "",
        ...
    }
  },
  "statusCode": 200,
  "error": null
}

Response

If successful:

{
   "updatedConfigs": {
      "successful_apply": [],
      "failed_to_apply": []
   }
}

Get previous and new config given a patch

Method	Syntax
GET	api_root/configs/previous/OBJECT_NAME/PATCH_VERSION

Description

Use this API to determine the config for a resource before and after a specific patch version has been applied to the resource’s configuration.

Examples

Request

GET api_root/configs/previous/OBJECT_NAME/PATCH_VERSION

Request parameters

Parameters are required unless marked as optional.

Name	Type	Description	Values
`OBJECT_NAME`	string	The name of the Kubernetes object.	Any valid Kubernetes object name.
`PATCH_VERSION`	string	The patch version of the targeted patch.	A patch version in numbers.

Response

If successful:

{
    "statusCode": 200,
    "data": {
        "prev_config": "config1",
        "new_config": "config1+patch"
    },
    "error": null
}

Hibernate cluster

Method	Syntax
POST	api_root/deployment/hibernate

Description

Use this API to hibernate the cluster. It scales all deployments and stateful sets down to 0 replicas.

Examples

Request

POST api_root/deployment/hibernate

Response

If successful:

HTTP STATUS CODE 200

{
  "data": null,
  "statusCode": 200,
  "error": null
}

Delete a Kubernetes Job

Method	Syntax
DELETE	api_root/kube/job/JOB_NAME

Description

Use this API to delete a specific Kubernetes job in the cluster.

Examples

Request

DELETE api_root/kube/job/JOB_NAME

Request parameters

Parameters are required unless marked as optional.

Name	Type	Description	Values
`JOB_NAME`	string	The name of the Kubernetes job.	A string name of the Kubernetes job.

Response

If successful:

HTTP STATUS CODE 200

{
  "data": null,
  "statusCode": 200,
  "error": null
}

Delete a Kubernetes pod

Method	Syntax
POST	api_root/kube/pod/delete

Description

Use this API to delete a specific Kubernetes pod in the cluster.

Examples

Request

POST api_root/kube/pod/delete

Request parameters

Parameters are required unless marked as optional. The request body must be a URL-encoded form with the parameters below.

Name	Type	Description	Values
`pod`	string	The pod ID)	A string specifying the pod ID.

Response

If successful:

HTTP STATUS CODE 200

{
  "data": null,
  "statusCode": 200,
  "error": null
}

Quarantine a Kubernetes pod

Method	Syntax
POST	api_root/kube/pod/quarantine

Description

Use this API to quarantine a specific Kubernetes pod in the cluster. This removes the pod from load balancer to be inspected, for debugging purposes.

Examples

Request

POST api_root/kube/pod/quarantine

Request parameters

Parameters are required unless marked as optional. The request body must be a URL-encoded form with the parameters below.

Name	Type	Description	Values
`pod`	string	The pod ID	A string specifying the pod ID.

Response

If successful:

HTTP STATUS CODE 200

{
  "data": null,
  "statusCode": 200,
  "error": null
}