Getting started

This tutorial takes a new platform from the first sign-in to a boundary with a cluster and its first users, in the order the portal's first-run wizard asks for them.

Sign in

Open the portal at https://portal.example.com and sign in. Sign-in is handled by the platform's identity provider at https://auth.example.com.

The administrator named when the platform was installed holds the Platform Owner role, and is the person this tutorial is written for. Everyone else has exactly the access they are granted or invited to.

As long as no boundary is selected in your browser, the portal opens Welcome to Stackship:

• when there is no boundary you can see, it starts the wizard with Create your first Boundary;
• when there are boundaries, it shows Select a Boundary: pick one and choose Continue, or choose Create new Boundary to run the wizard.

Note

The wizard creates a boundary, which Platform Owner and Platform Contributor can do, and then registers a cluster, which only a Platform Owner can do. A Platform Contributor therefore gets through step 1 and is refused at step 2 with Could not connect Cluster; reload the portal, pick the new boundary under Select a Boundary, and project it onto a registered cluster — see Add a projection. If the wizard opens for you and you hold no platform role, you have no role on any boundary yet, and Create Boundary fails with Could not create Boundary. Ask the owner of the boundary you should work in to invite you.

What you are setting up

• A boundary is the top-level scope on the platform. Resources, members and permissions all belong to one; environments, teams or business units each get their own. Every new boundary also starts as a tenant of its own — the group of people who sign in to work in it.
• A cluster is a Kubernetes cluster the platform places resources on — usually the cluster the platform itself runs in. A boundary's resources can only be placed on clusters it is projected onto.
• An invitation is an e-mail with a single-use link. Whoever accepts it gets the role it names, at the scope it names.

Step 1: Create a boundary

1. Under Create your first Boundary, enter a Display name, for example Production or Acme Corp.
2. Choose Create Boundary.

The platform derives the boundary's slug — its name in addresses and in Kubernetes — from the display name: accents are removed, letters are lowercased, and every other run of characters becomes a hyphen, so Svensk Fågel becomes svensk-fagel. The Slug field is only a preview; what you type into it is not used. A display name whose slug is already taken is refused.

Create Boundary stays disabled until the Slug field holds 3 to 63 lowercase letters, digits and hyphens, starting and ending with a letter or digit. A short display name such as QA fills it with too little: type a longer value into the field to enable the button. The boundary still gets the slug derived from its display name.

Creating a boundary needs boundaries/create at the platform root, which Platform Owner and Platform Contributor hold. More about boundaries: Create a boundary.

Step 2: Connect a cluster

1. Under Connect your first Cluster, enter a Cluster name, unique on the platform, and a Region.
2. Answer Where is this cluster?:
   • The cluster Stackship runs in — the default — needs nothing more.
   • A remote cluster needs the API URL of its Kubernetes API server and its Cluster certificate: the CA certificate, base64-encoded. The platform forwards your own sign-in token to that API server, so it must trust the platform's identity provider.
3. Choose Connect Cluster.

Connect Cluster does two things: it registers the cluster and then projects your new boundary onto it. If the second part fails, the cluster stays registered and trying again with the same name is refused — project the boundary onto the registered cluster from the boundary instead, see Add a projection.

This step needs kernel/clusters/write and boundaries/projections/manage at the platform root. Only Platform Owner holds both — Platform Contributor has boundaries/projections/manage but not kernel/clusters/write — and the step cannot be skipped. The wizard always registers a cluster reached directly; clusters reached through an agent, and every later cluster, are registered under Settings → Platform Settings — see Connect a cluster.

Step 3: Invite users

This step is optional; you can invite people at any time later.

1. Choose Invite a user.
2. Enter the person's Email address.
3. Pick the Role they get. The common choices:
   • Owner — everything in the boundary, including managing members and inviting others;
   • Contributor — everything except managing members, inviting and assigning roles;
   • Reader — read-only access, including logs.
4. Pick the Scope: the whole boundary (the default), one resource group, or one resource.
5. Choose Send invitation.

Each invitation sent is listed in the step. People get their role when they accept the invitation, not before; how that works is in Invite a user.

Choose Finish setup. The portal selects your new boundary and opens it.

Tip

Once you have moved past a step, do not go back to it and submit it again: that creates a second boundary or cluster.

Next steps

• Create a resource group
• Assign a role
• Connect a deployment source