Tutorial: Update Resource Definitions for related Applications

Introduction

Using the Platform Orchestrator helps organizations achieve standardization by design. This tutorial will show you how platform engineering teams maintain those standards through the process of updating Resource Definitions which are in active use by already running Applications. You’ll deploy a demo setup and analyze which Applications are using which Resources, using different tools and interfaces. By updating Resource Definitions and re-deploying Applications in sequence, you’ll be able to observe how the Platform Orchestrator handles each situation and keeps Applications on the “golden path”.

These steps take place at the intersection of platform engineering and development teams, and are recommended reading for both groups. You learn how to

  • Create Resource Definitions and Applications
  • Deploy Applications using Score
  • Analyze active Resources
  • Update Resource Definitions
  • Update Applications with active Resources

Prerequisites

To get started you’ll need:

  • A Humanitec Organization. If you do not have one, sign up here for a free trial
  • The humctl Humanitec CLI
  • A Kubernetes cluster connected to the Platform Orchestrator for Workload deployments. If you do not have one 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

Create Resource Definitions and Applications

You’ll first create a number of objects in your Humanitec Organization:

Clone our sample Git repository:

git clone https://github.com/humanitec-tutorials/update-resdef-for-related-apps
cd update-resdef-for-related-apps

This tutorial uses Terraform and the Humanitec Terraform Provider to manage all of the objects listed above.

Prepare the required variables to access your Organization:

cd terraform && cp terraform.tfvars.example terraform.tfvars

Edit the resulting terraform.tfvars file, provide the required values, and save the file.

Initialize Terraform and have it create all required objects:

terraform init
terraform apply -auto-approve

Let’s check the result by opening the Platform Orchestrator UI at https://app.humanitec.io/orgs/<your-org-id>

Select Applications from the left-hand menu. You should see Applications named “app1”, “app2”, and “app3” in the list, each with a single environment named “development” and the note “No deployments have been made within this application”. You’ll deploy actual Workloads into the Applications in the next step.

Select Resource Management from the left-hand menu. You should see Resource Definitions named “bucket”, “postgres”, and “redis” in the list, each with the driver “humanitec/terraform”. If you select any one of those entries and switch to the “Configuration” tab, you will see the Terraform code that will effectively be executed by the Terraform Driver whenever a Resource is provisioned based on this Resource Definition.

Select the “bucket” Resource Definition and switch to the “Matching criteria” tab. You’ll find a criteria definition saying “Application ID is app2”. This will later make the Platform Orchestrator select this Resource Definition when performing Resource matching for our Deployment of “app2”.

Likewise, the other Resource Definitions “postgres” and “redis” have their own matching criteria, which can be more than one. This is the resulting setup:

Matching criteria app1 app2 app3
bucket ✅
postgres ✅
redis ✅ ✅

Deploy Applications

Prepare your Environment for the Application Deployment. Set these Environment variables:

export HUMANITEC_ORG=<your-org-id>
export HUMANITEC_TOKEN=<a Humanitec API token> # Only required for using curl instead of humctl

where:

Login to humctl. Follow the instructions given by the CLI:

humctl login

Change into the directory holding the sample Score files:

cd ../score

Execute the Deployments using the humctl CLI:

humctl score deploy --app app1 --env development -f score-app1.yaml

humctl score deploy --app app2 --env development -f score-app2.yaml

humctl score deploy --app app3 --env development -f score-app3.yaml

The output of these commands will be the ID of a Deployment Delta which is derived from the Score file by the the Platform Orchestrator, representing the changes to be applied to the target Application. The output also shows the ID of a Pipeline run executing those changes.

Taking a quick look the Score files, we can see that they request the types of Resources shown in the matrix above in their resources section, e.g. for score-app2.yaml:

resources:
  "redis":
    type: redis
  "s3":
      type: s3

Analyze active Resources

Verify that all three Applications now have a Deployment with active Resources in their “development” environment. There are different ways to obtain this information: top-down via the Deployment (“which Resources have been provisioned for a this Application Deployment?”), or bottom-up via the Resource Definitions (“for which Application Deployments has a Resource of this type been provisioned?”).

Via the Application Deployment

Here’s how you can see active Resources for an Application Deployment in the Platform Orchestrator UI (“top-down”):

  • Select Applications from the left-hand navigation.
  • You should see the message “Last change deployed <today>” for “app1”, “app2”, and “app3”.
  • Select the “development” environment for “app1”.
  • Select the “app1” workload.
  • Expand the “Resource dependencies”.

You should find an active Resource of type redis with an instance_type of cache.t3.micro. This is the default value set in our Terraform code.

Feel free to check the other Applications and Resource Definitions in the same way. You should find active Resources created according to the matrix shown earlier.

You can also query a Deployment’s active Resources programmatically via the Platform Orchestrator API.

For the “app1” Application:

You should get a result containing an element with "type": "redis".

For the “app2” Application:

You should get a result containing an element with "type": "redis" and one with "type": "s3".

For the “app3” Application:

You should get a result containing an element with "type": "postgres".

Via the Resource Definition

The Platform Orchestrator UI can also show active Resources from the perspective of the Resource Definitions (“bottom-up”):

  • In the Orchestrator UI, select Resource Management from the left-hand navigation.
  • Select “redis”.

You’ll find two active Resources have been created based on this Resource Definition, one each for “app1” and “app2”.

Check the UI likewise for the “bucket” and “postgres” Resource Definitions.

You can also query a Resource Definition’s active Resources programmatically via the Platform Orchestrator API.

For the “bucket” Resource Definition:

You should get a result for "app_id": "app2".

For the “postgres” Resource Definition:

You should get a result for "app_id": "app3".

For the “redis” Resource Definition:

You should get a result for "app_id": "app1" and "app_id": "app2".

Update the Resource Definition

Now that you’ve checked for active Resources in your Applications from different angles, let’s apply a change.

Perform another terraform apply to override the Redis instance type:

cd ../terraform && terraform apply -var='instance_type=t3.large' -auto-approve

The output should display this change to the “redis” Resource Definition:

  # humanitec_resource_definition.redis will be updated in-place
  ~ resource "humanitec_resource_definition" "redis" {
    [...]
                      ~ instance_type = "cache.t3.micro" -> "t3.large"
    [...]
    }

Verify the Resource Definition “redis” has indeed been updated using the Platform Orchestrator UI (check the “Input variables” on the “Configuration” tab) or this command:

You should get this result:

{
  "instance_type": "t3.large"
}

Verify that active Resources have not changed

You changed the Resource Definition for “redis”, but how did that affect existing active Resources previously provisioned for our Applications? We know that “app1” and “app2” are using “redis”. Take a look:

  • Via the UI (top-down via the Application): Select Applications - “app1” or “app2” - “development” - “Auto-deployment (SCORE)” - “app1” or “app2” - “Resource dependencies” - “redis”
  • Via the API (bottom-up via the Resource Definition):

You should get a result for "app_id": "app1" and "app_id": "app2"still showing the previous "instance_type": "cache.t3.micro".

Update one Application

So now you can see that active Resources have not changed by altering their Resource Definition. Let’s redeploy one Application (“app1”) and see what happens.

Change into the directory holding the sample Score files:

cd ../score

Re-deploy “app1”:

humctl score deploy --app app1 --env development -f score-app1.yaml

Verify that only the redeployed Application has been updated

Check what the current active “redis” Resources for “app1” and “app2” look like.

  • Via the UI (top-down via the Application): Select Applications - “app1” or “app2” - “development” - “Auto-deployment (SCORE)” - “app1” or “app2” - “Resource dependencies” - “redis”
  • Via the API (bottom-up via the Resource Definition):

You should get a result for "app_id": "app1" having the new "instance_type": "t3.large" and "app_id": "app2"" still showing the previous "instance_type": "cache.t3.micro".

Update the second Application

Re-deploy “app2”:

humctl score deploy --app app2 --env development -f score-app2.yaml

Verify that both Applications have been updated

Repeat the verification process from the previous step, using either the UI or API.

You’ll see that both Applications now have a “redis” type Resource with "instance_type": "t3.large".

Note that “app3” is unaffected by our changes as it uses one of type postgres instead of a Resource of type redis. It would therefore be affected in the same way if we started updating the “postgres” Resource Definition.

Troubleshooting

If you receive an error message containing “HTTP 401 - Unauthorized” in any of the command line actions, check whether the HUMANITEC_TOKEN is correctly set to a valid API token of the target Organization.

Cleaning up

Change back into the terraform directory and destroy the setup:

cd ../terraform && terraform destroy -auto-approve

Recap

Congratulations! You have successfully completed the tutorial and learned how to update Resource Definitions for related Applications. You learned how to:

  • Create Resource Definitions and Applications
  • Deploy Applications using Score
  • Analyze active Resources
  • Update Resource Definitions
  • Update Applications with active Resources

Next Steps

This tutorial has been using partially commented-out Terraform code snippets to demonstrate the use of Resource Definitions without actually provisioning cloud services.

There is another way of handling Resources that are managed outside of the Platform Orchestrator but still need to be consumed by Workloads using the Echo Driver .

Tutorial: Provision a Redis cluster on AWS using Terraform