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.

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 can be uploaded 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; 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 can 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. Allows overriding the image registry specified in the Installer. This change persists until a new base config is applied for the specified service.

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