Glossary

Application

A Humanitec Application is collection of related Kubernetes workloads that run in the same Kubernetes namespace. You may prefer to think of them as projects, systems, or domains depending on your team’s internal conventions.

Application Configuration Set

Application Configuration (Set) refers to all the configuration details needed to deploy an App. It includes Environment variables, secrets, dependencies, volumes, and container configurations.

Baseline configuration

A platform team’s baseline configuration in the context of Humanitec refers to the default configurations that an organization maintains for running a dynamic setup. These configurations are typically centralized and maintained by platform teams or senior developers. They include:

  • Workload profiles: These are application configuration baselines that contain things like CPU minimum allocations, labels, and annotations. They carry the information necessary to create the final application configuration. They can be thought of as empty Helm charts.
  • Resource definitions: These are baselines on how to wire existing resources, or create new ones using Infrastructure as Code such as Terraform or Humanitec Drivers.
  • Available resources and their matching criteria: This determines what resource to create or match based on what context. The matching criteria may look like this: If the workload specification requires a database of type Postgres and the context matches the criteria “Environment Type = production or development” then use the Driver humanitec/postgres-cloudsql to wire the workload to an existing database in a CloudSql instance.

These baseline configurations are used by the Humanitec Platform Orchestrator to create application and infrastructure configurations with every git push, applying abstract requests (workload specifications) to these baseline configurations provided by the platform engineering team.

Definition

A Resource Definition defines how a Resource should be provisioned. It defines the Resource Driver and its inputs along with a set of Resource Matching Rules that defines when to select it.

Delta

A Delta describes changes that can be applied to an existing Set to generate a new Set. Deltas can be used to create new Sets from existing Sets. They can also be used to describe the difference between any two Sets.

When you create a Draft in the Humanitec UI, you are creating a Delta. The Delta collets all the changes that you make in the UI. When you deploy the Draft, the Delta is applied to the Set associated with the current active deployment. This generates a new Set for the new Deployment.

Unlike Sets, Deltas are mutable. They can be updated by combining them with other Deltas. This is how Drafts are updated in the UI.

Deployment

A Deployment represents an actual change to the state of an Environment. Humanitec keeps track of Deployments and the Application Configuration Set (Set) at the time of the deployment. Providing an audit history of an Environment enabling rolling-back and review.

The state of a Deployment is stored as a Set. Humanitec provides a rich set of tools for comparing and describing changes to Sets allowing for use cases such as:

  • Identifying the material differences between 2 Deployments in the same or different Environments
  • Applying consistent updates across different environments
  • Rolling-back an environment to a previously deployed state

Driver

Drivers are responsible for provisioning Resources.

Examples include:

  • Creating S3 buckets
  • Creating namespaces in a K8s cluster
  • Allocating Subdomains

Environment

An Environment is a space where an instance of an App can be deployed. It consists of a Kubernetes namespace and any Resources that Workloads in the App have dependencies on.

Environment Type

Environment Types are used to categorize Environments. Common types would be: development for all Environments developers are allowed to update directly, staging for Environments used to run verification and QA processes before deployment to production and production for Environments that are used by customers.

It is possible to control access to Environments based on their Environment Type. For example, developers may have permission to make manual deployments into environments of type development but not into environments of type production.

Ephemeral Environments

An Ephemeral Environment is a temporary, on-the-fly instance of an application or system. It’s built to mirror production settings but exists solely for the duration of a specific task, such as testing a feature or bug fix. Once the task is done, the environment is torn down, leaving no traces behind.

File

Files are templatable elements that are injected into the file-system of the Container at runtime. They are normally used to provide configuration files for processes that cannot be configured via Environment Variables.

Files differ from Volumes in that they cover specific files rather than directories. Files are also reset on every deployment. You should use Files for things related to configuration that might need to be changed by developers. You should use Volumes for things related to data that the Application creates or consumes.

Namespace

Kubernetes namespaces are used to organize Kubernetes objects within a Kubernetes cluster. In Humanitec, an Application is a collection of Workloads which run the same namespace, meaning that every Environment that’s created has its own namespace.

Matching

Matching Rules provide a way for Humanitec to select a Resource Definition in a given Environment. Each Resource Definition can have zero, or more, Matching Rules associated with it. Each Matching Rules defines zero, or more, parts of the context that must match in order for a Resource Definition to be selected. Matching Rules are selected via a “most specific first” process (similar to the longest-prefix-matching used in network routing). This means of all the Matching Rules potentially matching the context, the Matching Rules Rule with the most specific match is chosen.

Organization

Organizations are the “root” object in Humanitec. They are the basic unit of membership for developers and platform teams working in Humanitec. When you are invited to Humanitec, you are invited to an Organization.

Placeholders

Placeholders are template variables that will be replaced at deployment time. Using a syntax that is similar to template literals in JavaScript or variable substitution in shell scripts, they can be used in Variables, Files, and Driver Inputs. It should be noted, however, that some types of Placeholder have limitations on where they can be used.

Multiple placeholders can be used in a string, for example when specifying a connection string to a database:

postgresql://${shared.users-db.username}:${shared.users-db.password}@${shared.users-db.host}:${shared.users-db.port}/${shared.users-db.name}

Placeholders can only be used in certain fields. These fields are:

Profile

A Workload Profile defines the type of Kubernetes workload (deployment/job/cronjob), and can provide default values for the features supported by that workload type.

Each Workload in Humanitec has an associated Profile. This is defined via a dropdown in the creation modal dialog, or, if using the API, in a Set via the profiles property in the module object.

Resource

A Resource is something that is consumed or used by a Workload. Resources can either be Shared (available to all Workloads in an App) or Private (only available to a single Workload).

Examples of Resources include:

  • a PostgreSQL database used to store customer data,
  • a DNS name that a service is exposed to the internet with and
  • the Kubernetes Cluster the workload runs in.

Workload

Analogous to a Kubernetes workload; a Workload in Humanitec represents the code that runs in a Kubernetes cluster.

It is made up of one or more Containers alongside their configuration. In most cases, a Workload will be some kind of back-end service or a front-end of your App. For example, in a micro-service architecture, each service would be represented by a Workload in Humanitec.

Some parts of the API still use the term module to refer to a Workload. This is scheduled to change in the next major API version released (bumping the API from version 0.x.x to 1.x.x) - deprecating the term module prior to its removal at some point later.

Dynamic Configuration Management