Onboard an Application

Introduction

This tutorial platform engineers. It guides you through the steps to perform the onboarding of an Application into a Humanitec Organization.

“Onboarding” involves all the steps required so that can Application can receive Workload deployments using the Humanitec Platform Orchestrator.

Assigning the proper permissions to developers for the onboarded Application is part of the follow-up tutorial Onboard developers .

You will learn how to:

Create an Application
Ensure cluster connectivity
Prepare a Service User to setup CI/CD
Prepare required Resources

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
The Application name
Knowledge of the target Kubernetes cluster for the Application Workloads to run on
This cluster connected to the Platform Orchestrator. If you do not have it connected yet, these are your options:

Options to connect your Kubernetes cluster

Five-minute-IDP	Bring your own cluster	Reference architecture
Set up a local demo cluster following the Five-minute IDP Duration: 5 min No need to deploy the demo Workload, just perform the setup Ephemeral (throw-away) setup for demo purposes	Connect an existing cluster by following the Quickstart up to “Connect your cluster” (guided), or using the instructions in Kubernetes (self-guided) Duration: 15-30 min One-time effort per cluster, can be re-used going forward	Set up the reference architecture Duration: 15-30 min Creates a new cluster plus supporting cloud infrastructure, and connects it to the Platform Orchestrator

Five-minute-IDP

Bring your own cluster

Reference architecture

Set up a local demo cluster following the Five-minute IDP

Duration: 5 min

No need to deploy the demo Workload, just perform the setup

Ephemeral (throw-away) setup for demo purposes

Connect an existing cluster by following the Quickstart

up to “Connect your cluster” (guided), or using the instructions in Kubernetes

(self-guided)

Duration: 15-30 min

One-time effort per cluster, can be re-used going forward

Set up the reference architecture

Duration: 15-30 min

Creates a new cluster plus supporting cloud infrastructure, and connects it to the Platform Orchestrator

To provide a sample Resource Definition:
- The Terraform CLI installed locally

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 this environment variable to the Humanitec Organization ID:

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

humctl login

Create the Application

A Humanitec Appplication is like a Project where Developers will deploy their Workloads into its Environments. It is a purely logical entity, not an actual Workload.

You need to have the Administrator or Manager Organization level role to create an Application.

Derive the Application ID from the Application name. The ID must be made up of lowercase letters, digits, and “-” characters only. E.g. for an Application with the human-friendly name “My App”, you would derive an ID of my-app.

The Application ID cannot be changed later. It must be unique in your Humanitec Organization.

Create the Application:

export APP_ID=<application-id>

humctl create app ${APP_ID}

See the humanitec_application Terraform resource for more details.

variable app_id {}

resource "humanitec_application" "app" {
  id   = var.app_id
  name = var.app_id
}

This command will also create the first empty Application Environment named development. If you want to customize this first Environment, use these commands instead:

export APP_ID=<application-id>
export ENV_ID=<first-environment-id>

humctl api post /orgs/${HUMANITEC_ORG}/apps \
  -d '{
  "env": {
    "id": "'${ENV_ID}'",
    "name": "'${ENV_ID}'",
    "type": "development"
  },
  "id": "'${APP_ID}'",
  "name": "'${APP_ID}'"
  }'

variable app_id {}
variable env_id {}

resource "humanitec_application" "app" {
  id   = var.app_id
  name = var.app_id

  env = {
    id   = var.env_id
    name = var.env_id
    type = "development"
  }
}

Create a service user for CI/CD setup

For the CI/CD pipelines of the developers to deploy Workloads into their Application, they will need a Humanitec Service User .

You will now create a service user that is able to deploy into the development type Environments of the Application. You will then generate an API token for that user which you can incorporate into pipelines for continuous deployment.

Tip: Create as many Service Users as you need going forward and be as granular as you want to be. E.g. you can provide a separate service user with Deployer rights per Application/Environment Type combination.

Create the service user with the Member role on the Organization level:

export SERVICE_USER_NAME=<your-service-user-name>

humctl api post /orgs/${HUMANITEC_ORG}/users \
  -d '{
  "name": "'${SERVICE_USER_NAME}'",
  "role": "member",
  "type": "service"
  }'

See the humanitec_user Terraform resource for more details.

variable user_name {}

resource "humanitec_user" "member" {
  name = var.user_name
  role = "member"
  type = "service"
}

Assign the Developer role to this service user on the Application:

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

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

See the humanitec_application_user Terraform resource for more details.

resource "humanitec_application_user" "developer" {
  app_id  = humanitec_application.app.id
  user_id = humanitec_user.member.id
  role    = "developer"
}

In order to have this service user deploy the Workloads from the CI/CD pipelines of your developers, you need to assign it the Deployer role on the Environment Type(s) you want it to cover.

export ENVIRONMENT_TYPE=development

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

See the humanitec_environment_type_user Terraform resource for more details.

var env_type_id {}

resource "humanitec_environment_type_user" "deployer" {
  env_type_id = var.env_type_id
  user_id     = humanitec_user.member.id
  role        = "deployer"
}

Finally, generate an API token for this service user. Set the expiration (can be none) according to your organization guidelines.

humctl api post /users/${SERVICE_USER_ID}/tokens \
  -d '{
  "description": "Your service user token",
  "expires_at": "2030-04-30T19:47:01Z",
  "id": "your-service-user-token",
  "type": "static"
  }'

See the humanitec_service_user_token Terraform resource for more details.

resource "humanitec_service_user_token" "token" {
  id          = "your-service-user-token"
  user_id     = humanitec_user.member.id
  description = "Your service user token"
  expires_at  = "2030-04-23T21:59:59.999Z"
}

Anyone with knowledge of this token will be able to impersonate the service user and execute actions within the limits of the user’s role assignments. Once generated, store the token in a safe place and share it only with those entitled to perform these actions.

The primary purpose of this API token will be its use in CI/CD automation, e.g. to be placed as a repository or project secret available to a pipeline using the mechanisms of your specific CI/CD tooling. Depending on the processes in your organization, you can either register it there or share it with your developers to do the same.

This step concludes the basic user and permissions setup for the new Application. Now proceed the Application onboarding by connecting the Application to its target Kubernetes cluster.

Match the Application to your cluster

To make the Platform Orchestrator pick the right cluster for your Application, you need to proper add Matching Criteria to the cluster’s Resource Definition.

Choose the Resource Definition of the target Kubernetes cluster. You can use humctl get resource-definition to get a list of available Resource Definitions, or go to the “Resource Management” section in the Portal.

Make that Resource Definition match your Application:

export K8S_RESDEF=<my-k8s-cluster-resource-definition-id>

humctl api post /orgs/${HUMANITEC_ORG}/resources/defs/${K8S_RESDEF}/criteria \
  -d '{
    "app_id": "'${APP_ID}'"
    }'

See the humanitec_resource_definition_criteria Terraform resource for more details.

variable k8s_resdef_id {}

resource "humanitec_resource_definition_criteria" "example" {
  resource_definition_id = var.k8s_resdef_id
  app_id                 = humanitec_application.app.id
}

Test cluster connectivity

Now that you have created your Application with the default “development” Environment and matched it to your Kubernetes cluster, you can check the connectivity to that cluster for the Platform Orchestrator.

humctl resources check-connectivity --app $APP_ID --env development

This command does not perform any Deployment but checks the ability for the Platform Orchestrator to connect to the cluster for a given Environment.

If everything is set up properly, the command will return a successful result and provide details about your setup.

Provide a Resource Definition

Providing Resource Definitions is a Platform Engineer’s task enabling developers to then easily request Resources for their Workloads through Score.

For this tutorial, you will use on the Humanitec Resource Packs to provide a Resource Definition of type redis to provision an in-cluster Redis cache.

Open the In-cluster Redis Resource Pack page and follow the instructions to deploy the example.

You need the Terraform CLI to install Resource Packs.

Once that is done, you will see a new Resource Definition of type redis in this list:

humctl get resource-definitions | grep redis

Just like for the Kubernetes cluster Resource Definition, add Matching Criteria to the Redis one to match your Application:

export REDIS_RESDEF=<my-redis-cluster-resource-definition-id>

humctl api post /orgs/${HUMANITEC_ORG}/resources/defs/${REDIS_RESDEF}/criteria \
  -d '{
    "app_id": "'${APP_ID}'"
    }'

See the humanitec_resource_definition_criteria Terraform resource for more details.

variable redis_resdef_id {}

resource "humanitec_resource_definition_criteria" "example" {
  resource_definition_id = var.redis_resdef_id
  app_id                 = humanitec_application.app.id
}

Reflect on Application access

At this point, developers in your organization will not yet have the required permissions to actually perform deployments into the new Application if you are following a least privilege approach. Assigning those permissions is covered in the follow-up tutorial named in the next steps .

Recap

Congratulations! You have onboarded an Application onto the Platform Orchestrator. You learned how to:

✅ Create Applications and Environments
✅ Match the Aüplication to the target Kubernetes cluster
✅ Create service users and issue API tokens
✅ Create new Resource Definitions using the Resource Packs
✅ Match Resource Definitions to an Application

Next steps

Proceed to Onboard developers so that they can start deploying into their Application.

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.

Onboard an Application

Introduction #

Prerequisites #

Prepare your local environment #

Create the Application #

Create a service user for CI/CD setup #

Match the Application to your cluster #

Test cluster connectivity #

Provide a Resource Definition #

Reflect on Application access #

Recap #

Next steps #