Set and Deltas

A Deployment Set contains all the developer owned environment agnostic configuration for an Applications. It contains 2 sets of objects: Workloads and Resources shared by those workloads. Together, these describe the material things that should run or be provisioned in an Environment.

Use of Deployment Sets in Humanitec

Every deployment made by Humanitec has an associated Deployment Set.

The ID of the Deployment Set can be considered a robust identifier and can be used as part of an audit log for deployments. This is because Sets have the property that they are immutable and that their ID is a hash of the contents of the Set. This means that comparing 2 IDs is sufficient to tell if two deployment sets are identical.

A new Deployment Set can be created by applying a Deployment Delta to an existing Set. When deploying in Humanitec, you deploy a Deployment Delta which is then applied to the currently deployed Set in that Environment. The newly generated Set is then associated with the new deployment.

Example Deployment Set

The following is an example of an Application with two Workloads: products and payments.

The products service has a dependency on a PostgreSQL database, the payments service references an environment specific value for an API Key.

modules:
  products:
    profile: humanitec/default-module
    externals:
      "products":
        "type": "postgres"
    spec:
      containers:
        products:
          image: registry.example.com/shop/products-svc:1.3.2
          variables:
            PAGE_SIZE: 10
            CONNECTION_STRING: "postgresql://${externals.products.username}:${externals.products.password}@${externals.products.host}:${externals.products.port}/${externals.products.name}"
      ingress:
        shared.api:
          /products:
            path_type: Prefix
            port: 4001
  payments:
    profile: humanitec/default-module
    spec:
      containers:
        payments:
          image: registry.example.com/shop/payments-svc:2.1.6
          variables:
            API_KEY: ${values.STRIPE_API_KEY}
      ingress:
        shared.api:
          /payments:
            path_type: Prefix
            port: 8081
shared:
  api:
    type: dns

Deployment Deltas

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

Use of Deltas in Humanitec

When you diff two deployments, you are actually generating a Delta which describes the differences between the two Sets deployed in each deployment.

When you create a draft in the Humanitec UI, you are creating a Delta. The Delta collects 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 deployment. This generates a new Set for the new deployment.

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

Example Deployment Delta

The following example, adds a new Workload called offers and removes a Workload called payments. It also changes the PAGE_SIZE variable in the products Workload.

modules:
  add:
    offers:
      profile: humanitec/default-module
        spec:
          containers:
            image: registry.example.com/shop/offers-svc:0.9.2
  remove:
  - payments
  update:
    products:
    - op: replace
      path: /spec/containers/products/variables/PAGE_SIZE
      value: 20

Environments

Workloads