Partner Teams

This guide is for a company that installs and runs DevZero for its own customers. With partner teams, your DevZero team starts a separate DevZero team for each customer. The customer's team belongs to the customer and is billed to them. Your people join it in the role they hold in your team and switch to it from the team switcher, like any other team they belong to.

You can start a customer team in the console or with Terraform. For a customer that already has a DevZero team, you give your service account access to that team instead.

Turning it on

DevZero turns partner teams on for each team. No team can turn it on for itself. To ask for it, contact support@devzero.io with your Team ID, from Settings > Organization Settings > Account.

Until it is on, starting a team fails with:

only a DevZero partner team can start teams or let its service accounts into other teams; contact support@devzero.io

Who can do what

Every customer team needs a person who is an Admin of your team. That person joins it as Admin and can invite the customer's people and rename the team.

Start a customer team in the console

Every team started from yours is listed under Settings > Organization Settings > Customer Teams, with who started it, when, and how many members it has. Open one you are a member of to switch to it.

Start a customer team with Terraform

Terraform starts the team with the devzero_team resource and registers clusters in it with team_id, on devzero_cluster or on the devzero-inc/cluster/devzero module. This needs provider 0.3.0 or later and module 0.2.0 or later. The pipeline runs as a service account, with nobody signed in.

One-time setup

An Admin of your team:

1. Creates a service account under Settings > Organization Settings > Service Accounts > Create service account. The default role, Developer, is enough. A service account with the Viewer role cannot start teams.
2. Creates its token with Manage tokens > Create token on the account. The Expiration is 30 days, 90 days (the default), 180 days, 1 year, or No expiration. The token starts with dzs- and is shown once.
3. Copies your Team ID from Settings > Organization Settings > Account. This is the provider's team_id.

Keep the token in your pipeline's secret store. It keeps working when people leave your team, and stops when it expires or you Revoke it.

Per customer

terraform {
  required_providers {
    devzero = {
      source  = "devzero-inc/devzero"
      version = ">= 0.3.0"
    }
  }
}

variable "partner_team_id" {
  type = string
}

variable "partner_service_account_token" {
  type      = string
  sensitive = true
}

provider "devzero" {
  team_id = var.partner_team_id
  token   = var.partner_service_account_token
}

resource "devzero_team" "acme" {
  name                = "Acme"
  member_emails       = ["alice@partner.example"]
  admin_invite_emails = ["admin@acme.example"]
}

module "acme_prod" {
  source  = "devzero-inc/cluster/devzero"
  version = "~> 0.2"

  cluster_name = "acme-prod"
  team_id      = devzero_team.acme.id
}

• member_emails names people of your team. At least one must be an Admin there. Each joins in the role they hold in your team.
• admin_invite_emails invites the customer's admins as Admin.
• The module registers the cluster in the customer's team and installs DevZero's agents in the cluster with that cluster's token. It needs the helm and kubernetes providers configured for the customer's cluster, which are not shown here.
• To install the charts yourself, use devzero_cluster with the same team_id and pass its token to them.

The service account joins each team it starts as a Developer. There it can register, rename and delete clusters and reset their tokens. It is never an Admin outside your team, so it cannot invite people to a customer's team or rename it.

A customer that already has a DevZero team

Use this when the customer already has a DevZero team, or when the customer's team was started in the console.

In another team, a service account holds Developer or Viewer, never Admin. Registering clusters needs Developer. The customer's Admins see your service account under Settings > Organization Settings > Service Accounts > From other teams, where they can lower it to Viewer or remove it. Either one stops your Terraform from registering or deleting clusters in their team.

Limits and billing

• A customer team is billed to the customer, not to you.
• A started team begins on the default tier of 2 clusters. DevZero sets each customer team's tier and billing terms. To raise a team's limit, contact support@devzero.io.
• When Terraform registers a cluster in a team started from yours, every cluster in that team counts against the limit, including one whose agents never reported. Past the limit, the registration fails with "cluster limit for this account has been reached". Delete a cluster you do not use to free its place.
• A customer's existing team keeps its own tier and billing terms.

Invites

• One start invites at most 10 customer admins. A service account or person can create at most 20 invites per hour, counted across every team they start.
• An invite is valid for 7 days.
• Terraform sends invites only when it starts a team. If an email could not be sent, invites_not_sent lists the address, and applying again does not send it. An Admin of the customer's team re-sends it under Settings > Organization Settings > User and Role Management with Resend invite, or sends the link from Copy invite link.
• Later invites come from Invite team member on the same page.

Things to know

• Start values are used once. A devzero_team's name, member_emails and admin_invite_emails are used only when the team starts, and a later change is refused at plan. The team's Admins manage its name and people in the console.
• A cluster's team is fixed. team_id is set when a cluster is registered, and a plan that changes it is refused. Terraform never moves a cluster to another team. A cluster registered with a provider release before 0.3.0 stays in your own team. To have it in a customer's team, register a new devzero_cluster there and run the agents with its token.
• Renaming a resource address needs a moved block. Without one, a renamed devzero_team starts a second team, sends its invites again, and takes your service account out of the first. A renamed devzero_cluster is deleted in DevZero and registered again with a new token, and counts against the limit.
• Destroying. Destroying a devzero_cluster deletes the cluster in DevZero. Destroying a devzero_team with the service account's token takes the service account out of the team, and the team and its people stay. With a person's token it is that person's leave: a last member's leave deletes the team, unless DevZero refuses it, as it does once a cluster in the team has reported. To stop managing a customer without deleting anything, see Teams.
• A team or cluster that cannot be read. If the customer removes your service account, or the team or a cluster is gone, the refresh fails and Terraform keeps it in state rather than starting a new team or registering a new cluster. Remove it from configuration as well as from state to go on.
• Regions. DevZero's regions share nothing. A team started from yours is in your team's region, and your service account cannot reach a customer's team in another region.