Imply Cloud Manager API (1.0.0)

To use this API, you need the ManageClusters permission to create, modify, and remove clusters across a customer organization.

Familiarize yourself with the Imply Manager for managing and monitoring an Imply deployment.

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. Contact your Imply account representative if you need 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.

When you create your OAuth client, Imply provides you an access token. Use this access token to make requests to the Cloud Manager API. Supply the token in the HTTP Authorization request header using the Bearer authentication scheme.

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

The following examples demonstrate common tasks performed with the Cloud Manager API.

To create a new cluster, send a POST request to the Clusters API. Submit the cluster configuration in the request body.

POST /clusters

The following example shows the request body:

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

To stop a cluster, send a PATCH request to the Clusters API. Specify the cluster ID in the path and the desired cluster state in the request body.

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

The following example shows the request body:

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

To delete a cluster, send a DELETE request to the Clusters API. Specify the ID of the cluster in the path.

DELETE /clusters/{clusterId}

The Imply Cloud Manager API returns standard HTTP status codes. Common error cases and example responses are listed below.

An HTTP/1.1 400 Bad Request error is raised due to invalid user input.

The following example shows a response body for a 400 Bad Request error due to a missing cluster name and an incorrect path for AWS S3 deep storage:

{
  "error": {
    "code": "BadArgument",
    "message": "Request contains invalid arguments",
    "details": [
      {
        "code": "NullValue",
        "target": "metadata.name",
        "message": "Cluster name must not be null"
      },
      {
        "code": "MalformedValue",
        "target": "spec.deepStorage.path",
        "message": "Path is not a valid s3 path"
      }
    ]
  }
}

An HTTP/1.1 401 Unauthorized error is raised when authentication credentials have not been provided.

The following example shows a response body for a 401 Unauthorized error:

{
  "error": {
    "code": "Unauthorized",
    "message": "Provided user does not have permissions to complete this request"
  }
}

An HTTP/1.1 403 Forbidden error is raised when the attempted action has not been authorized by the user.

The following example shows a response body for a 403 Forbidden error:

{
  "error": {
    "code": "Unauthorized",
    "message": "Provided user does not have permissions to complete this request"
  }
}

An HTTP/1.1 409 Conflict error is raised when an action is attempted on a cluster that is currently being updated. A cluster can apply only one update at a time.

The following example shows a response body for a 409 Conflict error:

{
  "error": {
    "code": "StateConflict",
    "message": "Cluster [e9e1e18f-a9e8-4dd7-8a18-768039c57f22] cannot transition from [UPDATING] to [STOPPED]"
  }
}

A PUT request to overwrite a cluster configuration returns a 500 Server Error when you don't specify spec.pivot.accessMode. While this parameter isn't required to create a cluster, you must supply it when overwriting a cluster configuration.

Use the Clusters API to create and manage Imply clusters. To overwrite a cluster, provide a complete cluster configuration to replace the existing cluster. To update a cluster, provide a partial configuration with only the properties you want to modify.

Use the Clusters Historical API to obtain a previous configuration for a cluster. The cluster version number increments when the cluster configuration changes. You can access cluster information from past cluster states using its version number.