Manager API overview

The Imply Cloud Manager API allows you to deploy and manage Imply clusters through a secure, public-facing API. You can use the Cloud Manager API to integrate cluster and user management into your infrastructure automation frameworks. The Cloud Manager API is a secure, scalable approach to automate your Imply Cloud workflows.

This document is intended for Imply Cloud customers, specifically those who have the ManageClusters permission to manage the infrastructure of Imply users across a customer organization. It is assumed that you are familiar with the Imply Manager for managing and monitoring an Imply deployment.

Access the Imply Cloud Manager API through the same custom domain through which you access your Imply Cloud deployment, e.g., https://{vanity_domain}.implycloud.com.

Authorizing requests

The Cloud Manager API uses the OAuth 2.0 protocol for authentication and authorization.

To send authorized requests to the Cloud Manager API, complete the following steps:

  1. Enable SSO for your Imply Cloud account. SSO is disabled by default. Please contact your Imply account representative to enable Imply Cloud Auth. For more details, see Imply Cloud SSO auth.

  2. Configure OAuth-based authentication. Refer to OAuth client authentication for how to configure access through a custom OAuth client. Create a client for each external application that connects to your Imply Cloud clusters. In the OAuth client configuration, select the environment for the intended cluster and assign the manage-clusters role in the Service Account Roles tab.

After you have enabled and configured Imply Cloud Auth, you should be able to make requests to the Cloud Manager API using the access token provided when you created your OAuth client. When making an API call, supply the token in the HTTP Authorization request header using the Bearer authentication scheme.

Getting started

The following examples demonstrate common tasks performed with the Cloud Manager API. Before continuing, ensure that you have an OAuth access token as described in Authorizing requests.

Create a cluster

To create a new cluster, send a POST request with a request body containing the cluster configuration.

POST /clusters

Request body example:

{
    "metadata": {
        "name": "test-1"
    },
    "spec": {
        "version": "2021.06",
        "awsInstanceRole": "imply-instance",
        "awsTags": [],
        "encryptVolumes": true,
        "commonRuntimeProperties": [],
        "master": {
            "replicas": 1,
            "instanceType": "t2.small",
            "coordinatorRuntimeProperties": [],
            "overlordRuntimeProperties": []
        },
        "query": {
            "replicas": 3,
            "instanceType": "t2.small",
            "brokerRuntimeProperties": [],
            "routerRuntimeProperties": []
        },
        "data": {
            "historicalRuntimeProperties": [],
            "middleManagerRuntimeProperties": [],
            "tier1": {
                "replicas": 1,
                "instanceType": "t2.small",
                "historicalRuntimeProperties": [],
                "middleManagerRuntimeProperties": []
            }
        },
        "metadataStore": {
            "instanceType": "db.t3.small",
            "diskSize": 27,
            "backupRetention": 14,
            "encrypt": true
        },
        "pivot": {
            "accessMode": "PROXIED"
        },
        "deepStorage": {
            "path": "s3://my-bucket/prefix",
            "encrypt": true
        },
        "druidExtensions": [],
        "featureFlags": [],
        "customFiles": []
    }
}

Stop a cluster

To stop a cluster, send a PATCH request, specifying the ID of the cluster to be stopped and passing the request body below.

PATCH /clusters/{clusterId}
Content-Type: application/merge-patch+json

Request body:

{
  "spec": {
    "desiredState": "STOPPED"
  }
}

Delete a cluster

To delete a cluster, send a DELETE request, specifying the ID of the cluster to be removed.

DELETE /clusters/{clusterId}

Using Imply Manager API in your GitOps workflow

The Cloud Manager API provides for interoperability of Imply Cloud management with CI/CD tools. For instance, the Cloud Manager API is well suited for continuous deployment via a GitOps pipeline. With this setup, infrastructure configurations are stored in Git as the single source of truth, and the version-controlled code repository automatically updates production applications and infrastructure.

The following steps below present a high level overview of how you may employ the Cloud Manager API in a GitOps scenario.

  1. Define your desired cluster configuration in the form of a Cluster object in JSON format.
  2. Establish a Git repository which will store the declarative descriptions of the cluster.
  3. Create a workflow for your continuous deployment process, which, for example, deploys a cluster update when a cluster configuration file passes review and is merged into the main branch.
  4. To make a change to a cluster, update the configuration file in the Git repository and trigger your workflow to run.

Known issues

A PUT request made to overwrite a cluster configuration results in a 500 Server Error when the accessMode property of the Pivot configuration is missing. You can create a cluster without the Pivot configuration, as Pivot accessMode is set to PROXIED by default. However, the Pivot configuration is required for overwriting a cluster configuration.

Learn more

See the Manager API tutorial for an example of using the Cloud Manager API across a cluster lifecycle.

Manager API tutorial →