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.

Let's say you want to offer a SaaS that provides self-service MySQL databases running on AWS. This quick start walks you through your first steps to build your SaaS on Nile (which you can later adapt for your use case). By the end of this quick start, you will have:

  • a workspace (your control plane)
  • an entity definition with a schema (the definition of your data plane that represents a MySQL database)
  • an organization (a tenant) with one user (end customer) in that organization
  • an entity instance (logical instance of the MySQL database) in that organization
  • ability to view events as they happen

For this quickstart, you will do all this manually in the UI, but in a real deployment most of these actions would be done programmatically using Nile's REST API and SDKs.


Navigate your web browser of choice to the Nile Admin Dashboard. You have two options for logging in:

  1. SSO: click Continue with Google.
  2. Username/password: if you haven't signed up to Nile yet, go to our website, enter your email address, and click Talk to us. Someone from Nile will contact you.

login screenshot

Create a workspace

Your SaaS application lives in a workspace, which represents your control plane. You probably already have a name for the SaaS application you'd like to build, so now you can create it. Click Create a workspace.

welcome to nile

In the textbox, enter the name of your workspace. A workspace name is globally unique, so you need to select a different name for your workspace, i.e., don't use quickstart100 as shown in screenshot below. create workspace

Create an entity

Create an entity that represents your data plane system. In this case, your entity describes a MySQL database running on AWS. Click Create entity.

create entity

On the create entity page, there is a dropdown of templates in the upper right of the screen. One of these templates is for your new entity (prepopulated here to make the quickstart easier). Select Example - DB (quickstart) from the dropdown and click Create entity.

select template dropdown

This did two important things:

  1. Added an entity named DB to your workspace. End customers who sign up to your SaaS will be able to manage those MySQL databases.
  2. Auto-generated an OpenAPI spec and REST APIs for CRUD operations on the DB entity.

You can see the newly created entity and further explore its fields by clicking on the arrow next to the entity on the left sidebar, or by clicking on the entity directly to see the schema and OpenAPI spec that was automatically generated for it.

view entity

Create an organization

In Nile, all the entity instances are scoped to an organization (i.e., tenant), so next you create a new organization. For this example, you create the organization manually, but in a real application these actions would be done programmatically by real end users.

create organization button

Click Create organization, and in the text box type in the organization name, e.g. "Colton Labs". Note that organization names must be unique inside of a workspace. Click Save.

create organization form

Create a user

End users exist inside of a workspace and can be part of any number of organizations. For this example, you create a user and then assign them to the organization you just created, Colton Labs.

Click the Users icon.

create user

As you can see, no users have been created yet. (note: you are a "developer" and are part of the workspace, but you won't show up here in the "user" list)

For this example, you add a user manually, but in a real application these actions would typically be done by real end users through your SaaS web application. Click Add a user. Enter an email and password of your liking, and then click Create.

create user form

The new user now shows up in the workspace's list of users.

add user index

You can now add the user to the organization. On the left icon navigation, click on the building Organization icon, then select Colton Labs from the list, and press add user.

create database button

When prompted, enter the email of the user you just created (in this example: shaun@colton.demo) and click Save.

add user form

Great job! So far you have created a workspace, entity, and organization with one user.

Create an entity instance within the organization

Let's say when your service is up and running, a user signs up to Colton Labs and wants to provision a MySQL database. On the Nile side, this means that a DB entity instance is added into the Colton Labs organization.

For this example, you are adding an entity instance manually, but in a real application these actions would typically be done programmatically.

Back on the Workspace page, you can see the DB entity that you created earlier but it is not being used in any organizations yet.

workspace index

From the left icon sidebar, select the building Organizations icon and drill down into Colton Labs. A list of entities will be there, select Db and then create DB.

create database button

All fields (dbName, cloud, environment, size, connection, status) can be configured for this instance, but the entity definition set the only required field to be dbName, so the textbox defaults to show only the dbName property. You can update the instance later, but for now enter just a name for the database, e.g. myFirstDB.

create database form

Click Create to add this instance into the organization.

Note that this is a representation of the end user's database, but it's still not hooked hooked up to a real data plane yet). You can learn how to connect a data plane to this control plan with our Pulumi and Kubernetes examples. Before you do that, it's important to understand how to stitch everything together. That's where events come in.

View events

When the DB entity instance was created, it generated a create event. If that entity changes, it generates another event. Nile handles all these change events automatically.

To see those events, go to the new entity instance and scroll all the way to the right to get to the events column. Click view.

instance list view event

From this events screen, you can clear, replay, or listen for new events.

event ui

In a real world scenario, you would run a listener that would consume these events and then take appropriate action in the data plane. To show how events work, you will manually create an event that simulates an agent running in a data plane telling Nile it has reached the Provisioning status. Click Generate event to open a text editor. Add a new "status" field (remember, you didn't set the status field when you created in the instance) and set its value to Provisioning.

"dbName": "myFirstDB",
"status": "Provisioning"

Click Update event and then view the new event below the text editor.

event created


You built a SaaS control plane on Nile! You have:

  • created a workspace (your control plane)
  • created an entity definition with a schema (your data plane definition that represents a MySQL database)
  • created an organization (a tenant) with one user (end customer) in that organization
  • created an entity instance (logical instance of the MySQL database) in that organization
  • viewed events as they happen

More examples

Now that you've built your control plane, you can run additional examples that build on top of it. In order for those examples or other applications to authenticate to Nile, get a workspace access token from the dashboard.

  1. From the dashboard, click Workspace and select the ACCESS TOKENS tab.

  2. Click Create an access token and enter a label and optional description for this new access token. Click Create to generate it.

  3. Copy the token and keep it safe, you will not be able to see the token again.

  4. The ACCESS TOKENS tab now shows an entry that represents your new token.

    workspace access tokens

  5. Follow instructions in examples on where to set it so your application picks it up.

Now you can explore:

Further reading

Read more about Nile concepts: