Skip to main content

Control Plane in 5 minutes

Nile is a platform that makes it easy to build a reliable, multi-tenant control plane.

This quickstart will walk you through Nile's REST APIs and the first steps of using Nile. In the next 5 minutes, you'll create an entity to represent your data plane and then use Nile's APIs to sign up tenant and manage data plane instances as that tenant.

Prerequisites

Before getting started, you will need access to Nile Platform. This includes URL of Nile backend and Nile Developer login details. You'll also want to invent a name for your first Nile workspace.

You can follow the tutorial using either curl or ts-node with Nile's Javascript SDK. We start by setting up the environment:

export NILE_URL=https://prod.thenile.dev:443
export NILE_WORKSPACE_ID=clustify
export NILE_DEVELOPER_EMAIL=nora@clustify.com
export NILE_DEVELOPER_PASSWORD=verysecret

Login to Nile as a developer

First, lets get a developer identification token that will allow us to create entities in Nile:

curl -X POST "$NILE_URL/auth/login" \
--header 'Content-Type: application/json' \
--data-raw '{
"email": "'$NILE_DEVELOPER_EMAIL'",
"password": "'$NILE_DEVELOPER_PASSWORD'"
}'

the result will be something like:

{"token" : "eyJhbGciOiJIUzI1NiJ9...9Q64"}

Save the token to an environment variable, since we'll be using it a lot:

export NILE_DEVELOPER_TOKEN=eyJhbGciOiJIUzI1NiJ9...9Q64

Create your workspace

Workspace is how Nile represents your control plane. This is where entities and tenants are created. You already picked a name for it, so now we just need to ask Nile to create it:

curl -X POST "$NILE_URL/workspaces" \
--header 'Content-Type: application/json' \
--header "Authorization: Bearer $NILE_DEVELOPER_TOKEN" \
--data-raw '{
"name": "'$NILE_WORKSPACE_ID'"
}'

Create your first custom entity

It is typical to start by creating an entity that represents your data plane system. In this case, we'll describe a MySQL cluster, running on AWS.

  1. Create a file named clusters.json and populate it with the entity schema:
{
"name": "clusters",
"schema": {
"type": "object",
"properties": {
"cluster_name": { "type": "string" },
"status": { "type": "string" },
"ARN": { "type": "string" },
"Endpoint": { "type": "string" }
},
"required": ["cluster_name"]
}
}
  1. Now update Nile with the new entity:
curl -X POST "$NILE_URL/workspaces/$NILE_WORKSPACE_ID/entities" \
--header "Authorization: Bearer $NILE_DEVELOPER_TOKEN" \
--header 'Content-Type: application/json' \
-d @clusters.json

This did two important things:

  1. Added an entity names clusters to your workspace. Users who sign up to your control plane will be able to manage clusters.
  2. Auto-generated OpenAPI spec and REST APIs for CRUD operations on the cluster entity.

Sign up as a tenant

Lets make up an imaginary user of our control plane. We'll call him Shaun.

export NILE_TENANT_EMAIL=shaun@colton.demo
export NILE_TENANT_PASSWORD=mycatname

Sign up as the user:

curl -X POST "$NILE_URL/workspaces/$NILE_WORKSPACE_ID/users" \
--header 'Content-Type: application/json' \
--data-raw '{
"email": "'$NILE_TENANT_EMAIL'",
"password": "'$NILE_TENANT_PASSWORD'"
}'

And lets log in as Shaun. The rest of the quickstart will be done from Shaun's POV as a user of Clustify:

curl -X POST "$NILE_URL/workspaces/$NILE_WORKSPACE_ID/auth/login" \
--header 'Content-Type: application/json' \
--data-raw '{
"email": "'$NILE_TENANT_EMAIL'",
"password": "'$NILE_TENANT_PASSWORD'"
}'

If successful, you should get a token as a result. Once again, we'll save it for reuse:

export NILE_TENANT_TOKEN=eyJhbGciOiJIUzI1NiJ9...9Q64

In Nile, everything happens in tenant organizations, so lets create a tenant for Shaun and his colleagues.

curl -X POST "$NILE_URL/workspaces/$NILE_WORKSPACE_ID/orgs" \
--header "Authorization: Bearer $NILE_TENANT_TOKEN" \
--header 'Content-Type: application/json' \
--data-raw '{
"name": "Colton Labs"
}'

If all went well, you will see something like this:

{"id":3,"type":"organization","name":"Colton Labs"}

Save the organization id because the user can only manage clusters in organizations they are a member of.

export NILE_TENANT_ORG=3

Manage clusters

Time for Shaun to manage some clusters.

But wait, you may be thinking, I don't have a control plane yet! How can Shaun manage clusters? Truth is, you actually kinda already have a control plane. At least parts of it.

Lets have Shaun create his first cluster:

curl -X POST "$NILE_URL/workspaces/$NILE_WORKSPACE_ID/orgs/$NILE_TENANT_ORG/instances/clusters" \
--header "Authorization: Bearer $NILE_TENANT_TOKEN" \
--header 'Content-Type: application/json' \
--data-raw '{
"cluster_name": "MyFirstCluster"
}'

If all went well, the response will be something like this:

{
"id": 35,
"type": "clusters",
"properties": {
"cluster_name": "MyFirstCluster"
}
}

and if you now try to list the clusters:

curl -X GET "$NILE_URL/workspaces/$NILE_WORKSPACE_ID/orgs/$NILE_TENANT_ORG/instances/clusters" \
--header "Authorization: Bearer $NILE_TENANT_TOKEN"

You should see:

[
{
"id": 35,
"type": "clusters",
"properties": {
"cluster_name": "MyFirstCluster"
}
}
]

Try to create a few more! Perhaps with more than just the required field. You can also update the cluster with PUT or delete it with DELETE.

Congratulations!

You took the first few steps toward using Nile to build a SaaS control plane.

What's next?