Deployment Sets and Deltas

Deployment Set format

Deployment Sets are defined as JSON objects and so are commonly rendered as JSON or YAML. The Set has 2 top level properties: modules and shared representing a set of Workloads or Resources as key-value maps.

The Workload objects all have a profile representing the Workload Profile used by the workload and an associated spec that contains the parameters of that Workload Profile. Workloads can optionally declare a dependency on private Resources through externals.

Resources, whether under the top level shared property or the externals property of a workload have the same structure. They all have a type defining the Resource Type and an optional set of params to parameterise the resource.

Having an understanding of the structure of a Deployment Set is important as this structure is used for Placeholders that are used.

Example Deployment Set

Here is an example Deployment Set in YAML format. It defines an application made up of 2 workloads products and payments, each of which serve part of the same API. The products service has a dependency on a PostgreSQL database, the payments service references an environment specific value for an API Key.

NOTE: For historical reasons, workloads are called modules and private dependent resources are called externals in the Deployment Set.

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

Example

Here is an example Delta in YAML format that adds a new workload called offers, removes a workload called payments and 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

Algebra of Sets and Deltas

Given 2 Sets S₁ and S₂ and the Delta Δ, the following operations are true:

    S₁ + Δ  = S₂
and
    S₂ - S₁ = Δ

Deltas can be combined to create a new Delta that has the same combined effect of the two Deltas being applied in sequence.

If S₁ is the result of applying Δ₁ to Set S₀, S₂ is the result of applying Δ₂ to S₁, then the following is true:

if
    S₀ + Δ₁ = S₁
and
    S₁ + Δ₂ = S₂
and
    Δ₁ + Δ₂ = Δ₃
then
    S₀ + (Δ₁ + Δ₂) = S₀ + Δ₃ = S₂

Placeholders

Resource Types