Deploy your Application

Introduction

This tutorial guides you through the process of deploying your first Application using the Humanitec Platform Orchestrator. You will learn how to

  • Create an Application
  • Connect the Orchestrator to a Kubernetes cluster
  • Deploy a Workload to your cluster
  • Modify the Workload
  • Use both the Portal as well as Score and the humctl CLI

Prerequisites

To get started you’ll need:

  • A Humanitec Organization. If you do not have one, sign up here for a free trial
  • (optional) A Kubernetes cluster to deploy your Workload onto. Its API server should be publicly accessible for the cloud-based Platform Orchestrator. If you do not have a cluster ready, not a problem - we will provide a simple way to spin one up along the way
  • (optional) The humctl CLI installed

Log in

To begin, navigate to the Portal login page and choose your preferred authentication option.

If it was you who created the Humanitec Organization, select the same option you used for that creation to log back in again.

After logging in, you start out on the “Applications” screen. This screen showcases all the Applications you can access within your Organization.

Execute this command and follow the on-screen instructions:

humctl login

Connect your Kubernetes cluster

The Platform Orchestrator always needs a target Kubernetes cluster to deploy your Workload into.

Available clusters are configured in the Resource Management section in the Portal. Click on that item in the main navigation on the left. You will see a list of Platform Orchestrator Resource Definitions. They instruct the Orchestrator how to handle a particular Resource your Workloads require, including the Kubernetes clusters.

If you are just starting out with the Orchestrator, you will see a number of “Default” items only. If you or another member of your Organization has already configured Resource Definitions, they will show up in this list.

Enter k8s-cluster into the Filter resources field at the top. This will show Kubernetes cluster Resource Definitions only. For new Organizations, this list will be empty.

You have these options to proceed:

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

For new starters, our recommendation is to go for the “Five-minute-IDP” option first and then diving in deeper into a more permanent setup using your own cluster and/or setting up the Reference architecture.

Choose and execute one option. As an outcome, you will now see a new k8s-cluster in the list of Resource Definitions in Resource Management.

Match your Application to the cluster

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

You will add matching criteria for an Application ID of demo-app. You will create an Application with this ID in the next step.

  1. Navigate to the Resource Management menu and select your target Kubernetes cluster
  2. Select Matching criteria
  3. Select + Add new criteria
  4. Enter Application ID is demo-app
  5. Click Save

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 Platform Orchestrator UI.

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

Also set your Humanitec Organization ID (must be all lowercase):

export HUMANITEC_ORG=<your-org-id>

Create the matching criteria and capture their ID for later use:

export CRITERIA_ID=$(humctl api post /orgs/${HUMANITEC_ORG}/resources/defs/${K8S_RESDEF}/criteria \
  -d '{
    "app_id": "demo-app"
    }' | jq --raw-output '.id' )
echo $CRITERIA_ID

Your target cluster is now finally ready to be deployed to. Let’s dive in and create your first Application.

Create your Application

  1. From the Applications screen, select Create new application
  2. Enter demo-app as the name for your Application and select Create new application to continue

Following this, you’ll land on your Application’s Status page. Here, you can find Application level settings, like Shared Values & Secrets or access management, and a list of Environments. The development Environment has been created by default.

To add Workloads or Shared Resources to your Application, click on the development Environment and continue to create a new Workload.

humctl create app demo-app

Create a new workload

  1. Click on the Create draft delta button in the top right corner. This will create a new draft Deployment where you can make changes
  2. Click the edit icon next to the “Untitled draft” title and give your draft the name Adding sample-service
  3. To add your first workload, select + Create new workload
  4. Enter sample-service as the name for your workload , then select Create workload
  1. Click on the sample-service link to navigate to the Workload details page

On the Workload details page, you have the ability to:

  • Add a container image
  • Add resource dependencies
  • Add DNS resources
  • Specify a service account
  • Add ports, and more

Next, add a container image to your Workload.

Create a Score file that describes your Workload. You will use that file for the upcoming deployment.

cat <<EOF > score.yaml
apiVersion: score.dev/v1b1
metadata:
  name: sample-service
containers:
  busybox:
    image: busybox:latest
    command: ["/bin/sh"]
    args: ["-c", "while true; do printenv && sleep 10; done"]
    variables:
      SAMPLE_VARIABLE: Sample value
      CURRENT_ENV: \${context.env.id}
EOF

This Score file describes a Workload named sample-service having a single container named busybox, using the image busybox:latest.

Add container image to workload

  1. Click on + Add container
  2. Scroll to the bottom and enter the image name busybox:latest
  3. Click on Add image and then Create to add the container to your Workload

You’re good! The Score file already contains the container image.

Add container commands and arguments

The newly added container needs some additional commands to run properly.

  1. In the “Containers” section, click on the busybox container
  2. Scroll down to “Command overrides” and click Edit YAML
  3. Place the cursor in the first line and enter this content:
- '/bin/sh'
  1. Click Save.

Supplement the command with additional arguments.

  1. Scroll down to “Argument overrides” and click Edit YAML
  2. Place the cursor in the first line and enter this content:
- '-c'
- 'while true; do printenv && sleep 10; done'
  1. Click Save.

You’re good! The Score file already contains the container command and args.

These instructions will have the container periodically log all of its environment variables.

Add environment variables to workloads

  1. Scroll up to the “Variables” section and select + Add Variables
  2. For “Key”, add SAMPLE_VARIABLE
  3. For “Value”, add Sample value
  4. Click Save

The Platform Orchestrator also lets you tap into the Workload’s runtime context by using specific Placeholders. Add another variable:

  1. For “Key”, add CURRENT_ENV
  2. For “Value”, add ${context.env.id}
  3. Click Save

You’re good! The Score file already contains the variables section.

While the SAMPLE_VARIABLE has a static value, the CURRENT_ENV variable will be populated with the ID of the Application Environment your Workload is running in.

Your sample Application is now ready to be deployed.

Deploy the Application

Ready to deploy your Application? Follow these steps:

  1. Scroll to the top of the screen and select Review and Deploy
  2. Should you have left the previous screen in the meantime, you can navigate back to the draft you have been preparing by going to the Applications menu and selecting the development environment of the demo-app. The select Draft deltas and the existing Delta named Adding sample-service. This is the one you configured earlier. Click Review & Deploy.
  3. Type a comment in the Comment field, then click Deploy again

You will see the Deployment being executed. Wait for the status to show “Succeeded”.

Click the link to the development Environment. The Status page is now populated with an overview of the last Deployment, its status, Workloads, and Shared resources that were provisioned along with them.

The Deployment status will display as Running.

Now inspect your workload’s output.

  1. Click on the sample-service Workload
  2. On the Workload screen, click on the busybox container

The container screen will show the container logs. You should see those lines included in the output:

2030-05-17T10:45:09Z CURRENT_ENV=development
2030-05-17T10:45:09Z SAMPLE_VARIABLE=Sample value

Perform the Deployment:

humctl score deploy -f score.yaml --app demo-app --env development --wait

The output will show Status: succeeded when finished.

Check the runtime status of the target Environment:

humctl api get /orgs/${HUMANITEC_ORG}/apps/demo-app/envs/development/runtime

The response will show "status": "Success" for the sample-service.

You can also access the container logs via the Platform Orchestrator:

humctl api get /orgs/${HUMANITEC_ORG}/apps/demo-app/envs/development/logs?workload_id=sample-service&container_id=busybox

You will see the payload values SAMPLE_VARIABLE=Sample value and CURRENT_ENV=development.

Quit the log display using Cmd+C or CTRL+C.

You have successfully deployed your first Application via the Humanitec Platform Orchestrator! The Application runs on the cluster you provided and has dynamic runtime information injected into the Workload.

Cleaning up

Remove your setup unless you want to keep working with it.

Deleting the Application will make the Platform Orchestrator un-deploy the Workload from the cluster.

From the Applications menu, click the trash icon for the demo-app and confirm the deletion.

Delete the matching criteria from the cluster Resource Definition:

  • Navigate to the Resource Management menu and select your target Kubernetes cluster
  • Select Matching criteria
  • Click the trash icon for the demo-app criteria

If you have been using the Five-minute IDP setup, execute the cleanup now.

Delete the Application:

humctl delete app demo-app

Delete the Score file:

rm score.yaml

Delete the matching criteria from the cluster:

humctl api delete /orgs/${HUMANITEC_ORG}/resources/defs/${K8S_RESDEF}/criteria/${CRITERIA_ID}

Switch interfaces

This tutorial offered both the Portal and the humctl CLI plus Score as alternative interfaces. If you have been using one and and would now like to experience the other, we invite you to go back to Matching your Application and follow the steps once more, using the alternative instructions.

Recap

Congratulations! You have successfully completed the tutorial and deployed your first Application. You learned how to:

  • Connect your Kubernetes cluster to the Platform Orchestrator
  • Create a new Application
  • Configure a Workload
  • Inject concext information into the Workload using Placeholders
  • Use either the Portal, humctl with Score, or both, to describe your Workload and manage Platform Orchestrator objects

Next steps

If you haven’t done so in the process:

Overview

Manage your Java application