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:
- SSO: click
Continue with Google.
- 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.
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.
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 an entity
Create an entity that represents your data plane system. In this case, your entity describes a MySQL database running on AWS. Click
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
This did two important things:
- Added an entity named
DBto your workspace. End customers who sign up to your SaaS will be able to manage those MySQL databases.
- Auto-generated an OpenAPI spec and REST APIs for CRUD operations on the
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.
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, 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.
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,
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.
Add a user.
Enter an email and password of your liking, and then click
The new user now shows up in the workspace's list of users.
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
When prompted, enter the email of the user you just created (in this example:
firstname.lastname@example.org) and click
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.
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
All fields (
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.
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.
DB entity instance was created, it generated a
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
From this events screen, you can clear, replay, or listen for new events.
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
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
Update event and then view the new event below the text editor.
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
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.
From the dashboard, click
Workspaceand select the
Create an access tokenand enter a label and optional description for this new access token. Click
Createto generate it.
Copy the token and keep it safe, you will not be able to see the token again.
ACCESS TOKENStab now shows an entry that represents your new token.
Follow instructions in examples on where to set it so your application picks it up.
Now you can explore:
- Connect a data plane to this control plane with Pulumi and kubernetes examples
- Run an example webapp for your SaaS application so that users can self-serve and see metrics for their usage.
- Run other examples for additional use-cases
Read more about Nile concepts:
- Explore our REST API or our JS SDK.
- Learn more about Nile control plane concepts: entities, users, organizations, custom entities and events.