Deploy your first Application

Use humctl to create an App

Now that you have a cluster, it would be great to deploy something. You will use a demo app made by one of Humanitec’s developers for this. It is excellent for demoing things and also for this Quickstart - you can take a look at the sources and, of course, modify and build on your own, but it comes pre-built and ready to use as well. Let’s get it deployed!

You need to have an Application first, so let’s create on using humctl:

humctl create app $HUMANITEC_APP

The Application is an empty shell yet having a default “development” Environment and nothing more. You can check for Environments in the Application defined via $HUMANITEC_APP anytime like this:

Test cluster connectivity

Now that you have created your application and the default “development” environment is there, you can check the connectivity of the k8s cluster according to the cluster Resource Definition you created.

humctl resources check-connectivity --app $HUMANITEC_APP --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.

Create a workload specification using Score

The next thing you need is a Score file. Score is a workload specification designed to simplify development for cloud-native developers. The spec enables you to describe your workload’s configuration in a vendor-neutral way, eliminating the need for tooling-specific syntax from platforms such as Docker or Kubernetes. That means setting configuration parameters and requesting the required backing infrastructure, such as a database.

If you want to learn more about Score, you can visit score.dev to explore on your own.

You can quickly generate a starter Score file using humctl:

humctl score init

Modify the created score.yaml using your editor of choice:

  • Change the name to quickstart
  • Change the targetPort to 8080
  • Change the image to ghcr.io/astromechza/demo-app:latest

The sample Score file contains some elements we do not (yet) need, such as a number of variables and resources. Apply these modifications to the Score file:

  • Remove the entire resources section
  • Remove all of the variables and add this one:
variables:
  OVERRIDE_MOTD: "Hello, Quickstart!"

If you want to check for correctness of your edits or skip the self-editing, you can find a preconfigured file in the solutions subdirectory. To use it, execute:

cp solutions/first_deployment_score.yaml score.yaml

Perform your first Deployment

You can now deploy the application for the first time. It’s a simple command:

humctl score deploy --wait

The command uses the Score file named score.yaml by default that you created earlier. It also uses the HUMANITEC_ORG, HUMANITEC_APP and HUMANITEC_ENV environment variables from the environment setup. The optional --wait flag displays the output of the deployment pipeline that is triggered in the Platform Orchestrator, and waits for it to complete.

Go and check what you achieved in the Orchestrator’s portal.

  • Navigate to the Applications menu
  • In the “quickstart” Application, select the “development” Environment. You will see the overview of the most recent Deployment.
  • Wait for the Deployment status to show “Running” and the Workload status to be “Healthy”
  • Select the “quickstart” Workload
  • Select the “hello-world” container. You will see an initial log output of the demo application

The Platform Orchestrator has created a new Kubernetes namespace on your cluster for the Application. You can see its name by going back to the “development” Environment overview, and expanding the “k8s-namespace” Resource. Execute this command to extract the information using humctl:

export NAMESPACE_DEVELOPMENT=$(humctl get active-resource \
  /orgs/${HUMANITEC_ORG}/apps/${HUMANITEC_APP}/envs/${HUMANITEC_ENV}/resources \
  -oyaml \
  | yq -r '.[] | select (.metadata.type == "k8s-namespace") | .status.resource.namespace')

echo $NAMESPACE_DEVELOPMENT

Inspect the Kubernetes objects in that namespace:

kubectl get all -n $NAMESPACE_DEVELOPMENT

Based on your Score file, the Platform Orchestrator has created a Deployment, resulting in a Pod, and a Service object. Use the Service to access the demo application UI:

kubectl port-forward service/${HUMANITEC_APP} 8080:8080 \
  -n ${NAMESPACE_DEVELOPMENT}

Open this URL: http://localhost:8080/

You should see the message “Hello, Quickstart!” served to you by demo application. That message is taken from the OVERRIDE_MOTD variable you set in your Score file.

Quit the port forwarding via Cmd-C or Ctrl-C.

Recap

And that concludes this chapter. You have:

  • ✅ Created an Application in the Platform Orchestrator
  • ✅ Prepared a workload specification using Score
  • ✅ Deployed a workload using Score and humctl
  • ✅ Verified the result on the Kubernetes end

Your setup now looks like this:

%%{ init: { 'flowchart': { 'curve': 'linear' } } }%%
flowchart LR
  subgraph scoreFile[Score file]
    scoreWorkload(Workload)
  end
  subgraph platformOrchestrator[Platform Orchestrator]
    cloudAccount(Cloud Account)
    resDefCluster(Resource Definition\nCluster)
    subgraph application[Application]
        envDevelopment(Environment\n"development")
    end
  end
  subgraph cloudInfrastructure[Cloud Infrastructure]
    subgraph k8sCluster[Kubernetes Cluster]
      subgraph namespace[Namespace]
        workload(Workload)
      end
    end
  end
  scoreFile -->|humctl score deploy| envDevelopment
  resDefCluster -.- k8sCluster
  envDevelopment --> namespace

  %% Using the predefined styles
  class application,k8sCluster nested
  class scoreWorkload,workload highlight

Continue to apply some further customizations.

Connect your cluster

Customize your namespace