Onboard developers

Introduction #

This tutorial guides you through the steps to perform as a platform engineer to onboard Developers into your Humanitec Organization and their Application.

“Onboarding” involves all the steps required so that a developer start performing Workload deployments into their Application using the Humanitec Platform Orchestrator.

This tutorial is explicitly designed to prepare the platform engineering prerequisites for the Deploy your Workload developer starter tutorial.

You will learn how to:

• Invite developers to your Humanitec Organization
• Assign proper permissions to allow developers to deploy into their Application

Prerequisites #

To get started with this tutorial, you’ll need:

• A Humanitec Organization
• Your own user having the Administrator role in the Organization
• The humctl CLI installed locally
• (recommended) SSO/SAML set up for your Organization to use your own identity provider
  • If you plan to set up SSO, but have not configured it yet, wait until that is completed before onboarding any users
• The e-mail address of the developer to be onboarded
• The target Application onboarded into the Platform Orchestrator. You will need the Application ID
  • If you still need to onboard this Application, complete the Onboard an Application tutorial first

Throughout this tutorial, you will find the “Terraform” option for various commands. They are meant to be used with the Humanitec Terraform Provider which lets you manage your estate of Platform Orchestrator objects through Terraform. If you are just starting out, it is fine to take the first steps just using the CLI commands.

Prepare your local environment #

Set these environment variables for the Humanitec Organization ID and the Application ID:

export HUMANITEC_ORG=<your-humanitec-org-id>
export APP_ID=<your-application-id>

Login to the Platform Orchestrator:

humctl login

Invite developer to join the Humanitec Organization #

Your developer needs a user account (an “ Organization Member ”) that you can assign the required roles to in your Humanitec Organization. Prepare all actions by setting this variable to the user’s email address:

export MEMBER_EMAIL=<email-address>

Check if the Organization Member for this user already exists:

• Open the Humanitec Portal at https://app.humanitec.io
• Select Organization Members from the left menu
• Locate the user by their email address. You can use the search field to help you

If the Organization member already exists, you can proceed to granting access .

Otherwise, create the account now by submitting an invitation, assigning the Member role on the Organization level:

humctl api post /orgs/${HUMANITEC_ORG}/invitations \
  -d '{
  "email": "'${MEMBER_EMAIL}'",
  "role": "member"
  }'

You can work with the Organization Member account already going forward, specifically assign roles to it, even while the invitation is still pending.

Grant Application access to developer #

The level of access for your developers is a choice your organization has to make. Access is implemented by granting the proper RBAC roles to the developers’ Humanitec user accounts ( Organization Members ).

These are some viable setups using different combinations of role assignments for the developer Organization Members:

This tutorial will follow the Balanced setup.

All advanced operations, i.e. anything not permitted for the developers’ Organization Member users, should be automated through your CI/CD systems using service users and API tokens issued to them. That includes deploying to non-development and in particular into production Environments.

Assign the Application level Developer role to the developer’s Organization Member user:

• CLI
• Terraform

export DEVELOPER_APP_ROLE=developer # Adjust for granting a different role

export MEMBER_ID=$(humctl api get /orgs/${HUMANITEC_ORG}/users \
  | jq '. | map(. | select(.email=="'${MEMBER_EMAIL}'")) | .[0].id' \
  | tr -d "\"")

humctl api post /orgs/${HUMANITEC_ORG}/apps/${APP_ID}/users \
  -d '{
  "id": "'${MEMBER_ID}'",
  "role": "'${DEVELOPER_APP_ROLE}'"
  }'

variable user_email {}
variable application_role {}

data "humanitec_users" "user" {
  filter = {
    email = var.user_email
  }
}

resource "humanitec_application_user" "developer" {
  app_id  = humanitec_application.app.id
  user_id = data.humanitec_users.user.id
  role    = var.application_role
}

Assign the Environment type level Deployer role to the developer’s Organization Member user:

• CLI
• Terraform

export DEVELOPER_ENV_TYPE_ROLE=deployer

humctl api post /orgs/${HUMANITEC_ORG}/env-types/${ENVIRONMENT_TYPE}/users \
  -d '{
  "id": "'${MEMBER_ID}'",
  "role": "deployer"
  }'

variable env_type_id {}

resource "humanitec_environment_type_user" "deployer" {
  env_type_id = var.env_type_id
  user_id     = data.humanitec_users.user.id
  role        = "deployer"
}

Share information with developer #

You are now ready to share this information with your developer:

printf "\n---\nOrganization ID: "${HUMANITEC_ORG}"\n\
Application ID: "${APP_ID}"\n\
Onboarded Organization Member: "${MEMBER_EMAIL}"\n\
Application role assigned: "${DEVELOPER_APP_ROLE}"\n\
Deployer for Environment Type: "${ENVIRONMENT_TYPE}"\n"

Depending on what Resource Definition(s) you prepared earlier, e.g. through the Onboard an Application tutorial, also share the Resource Type(s) your developer can now use in their Score files.

Recap #

Congratulations! You have onboarded a developer and their Application onto the Platform Orchestrator. You learned how to:

• ✅ Invite users into your Organization
• ✅ Manage Application access for developers using roles and the RBAC system

Next steps #

Using the information shared with them, your developer is now ready to start the Deploy your Workload tutorial.

To onboard additional members of the Application team, repeat the steps to invite them and to grant them access.

For the purpose of this tutorial you have performed all steps manually. You may naturally consider automating them using a tooling of your choice which can execute the same commands. In particular, if you are planning to manage your estate of Platform Orchestrator objects through Terraform, start integrating the Terraform portions shown throughout this tutorial.