Stack Overview

The term Stack refers to an opinionated structure built from versioned InfraWeave Modules, which serve as its foundational building blocks. Stacks are designed to simplify the user experience by providing a streamlined configuration with fewer options.

This makes them ideal for users who prioritize a solution that “just works” out of the box while being fully supported by the platform team. It also removes the need for end users to learn Terraform.

By grouping Modules into Stacks, the platform team can:

• Define a suite of tests to ensure the reliability of the entire Stack.
• Enforce constraints and best practices across all included Modules.
• Minimize the number of inputs required from end-users.
• Maintain and upgrade Stacks efficiently, ensuring smooth transitions between versions.

This approach allows the platform team to focus on upgrading a single Stack version rather than managing individual Modules or tracking their compatibility. It ensures that the building blocks (Modules) work cohesively, making updates seamless and consistent, while providing end-users with a dependable and easy-to-use solution.

Defining Stacks

InfraWeave allows you to define stack in a manifest file. Instead of having this file together with .tf-files, you reuse your existing Modules and put it together with one or more .yaml deployment-claims.

All variables and outputs are inherited from the child modules, except if you create dependencies between modules.

Stack Definition

Below is an example of a stack definition.

webpage-runner/stack.yaml

apiVersion: infraweave.io/v1
kind: Stack
metadata:
  name: webpagerunner # The id of the stack you define, must match lowercase of stackName
spec:
  stackName: WebpageRunner # The name of the stack you define
  version: 0.2.1 # The released version to use
  reference: https://github.com/your-org/webpage-runner # The URL to the module's source code
  description: |
    This is a stack consisting of a VPC, EC2-instance and an S3-bucket.

Put it in the same folder as your claims

• Directorywebpage-runner/

  • ec2-instance.yaml
  • s3bucket.yaml
  • stack.yaml
  • vpc.yaml

Here is an example of the claims used to define the WebpageRunner stack.

Note

It is assumed that you have the following module versions already published.

S3Bucket

This module has a required variable bucketName which is not set, so this will be required when deploying the Stack later.

webpage-runner/s3bucket.yaml

apiVersion: infraweave.io/v1
kind: S3Bucket
metadata:
  name: s3bucket # Reference to this claim
spec:
  moduleVersion: 0.0.11
  region: N/A
  variables: {} # Leaving required values will pass them to be required in the stack

Note

The metadata.name has to be a lowercase alphanumeric name, e.g. “s3bucket” or “bucket”, but not “s3-bucket” or “s3_bucket”.

VPC

This module has a required variable cidrSize which is not set, so this will be required when deploying the Stack later.

webpage-runner/vpc.yaml

apiVersion: infraweave.io/v1
kind: VPC
metadata:
  name: vpc # Reference to this claim
spec:
  moduleVersion: 0.4.3
  region: N/A
  variables:
    enableDnsSupport: true  # Setting a value will remove it as input to the stack

EC2Instance

The EC2 requires the VPC to be set up first, so the resulting id can be passed into vpcId (given the VPC tf-module has a defined output called id)

webpage-runner/ec2-instance.yaml

apiVersion: infraweave.io/v1
kind: EC2Instance
metadata:
  name: ec2 # Reference to this claim
spec:
  moduleVersion: 0.2.7
  region: N/A
  variables:
    vpcId: {{ VPC::vpc::id }} # Setting a value will remove it as input to the stack

Caution

The region parameter is required in all Module deployment claims but is overriden since the resulting Stack deployment claim region takes precedence.

You need to set it to the placeholder value N/A.

Result

All documentation will be generated automatically based on the used modules.

As an example, the stack can be deployed with the following claim:

manifests/claims/webpage-runner-test-1.yaml

apiVersion: infraweave.io/v1
kind: WebpageRunner
metadata:
  name: webpage-runner-test-1
spec:
  stackVersion: 0.2.1 # The released version to use, must match the version in the stack.yaml
  region: us-west-2
  variables:
    s3bucket:
      bucketName: my-bucket-name-here
      encryptionAtRest: true
    vpc:
      vpcName: testvpc-1
      cidrSize: 26
    ec2:
      instanceName: instance-name-abc

Examples

This can then (similar to in Modules) also be extended with examples that will make it easy for users to get started quickly.

Deep dive

A common question is why this shouldn’t simply be built into a single, large Terraform module. There are several reasons for this approach:

• Maintaining a dynamic and flexible module that fits multiple usage scenarios is challenging.
• Testing a large module with many inputs can become complex and time-consuming.

Golden paths have become a popular approach, offering a set of well-tested and recommended configurations to help users get started quickly and reliably.

This approach simplifies the experience for end users who don’t need to understand the underlying details, while also providing a setup that can be thoroughly tested. This is particularly important given the vast number of possible configuration combinations.

A Stack is typically implemented by the platform team in collaboration with application teams to ensure the setup meets specific needs and use cases.

Additionally, Stacks can include a suite of automated tests, ensuring reliability and consistency across deployments.

Resource requests

It is possible to specify the required resources for a module. For example a small module might be sufficient with little cpu and memory making it cheap to use, meanwhile a large module or stack might require a lot of cpu or memory.

If you don’t specify anything, the default 1vCPU and 2GB is used.

Example

Here is an example of requesting 2vCPU and 6GB for the runner:

webpage-runner/stack.yaml

apiVersion: infraweave.io/v1
kind: Stack
metadata:
  name: webpage-runner # The id of the stack you define
spec:
  stackName: WebpageRunner # The name of the stack you define
  version: 0.2.1 # The released version to use
  reference: https://github.com/your-org/webpage-runner
  cpu: "2048"      # See table below for valid CPU values
  memory: "4096"   # See table below for valid memory values
  description: |
    # About
    This is a stack consisting of a VPC, EC2-instance and an S3-bucket.

Note

The values have to be in quotes

Useful Information

• terraform plan runs single-threaded.
• cloud provider may throttle API-calls
• is typically a good idea to provide minimum 1vCPU

Vendor Specifications

📒 Click here to expand table 📂

AWS

AWS - Allowed value combinations

Following table shows possible combinations that can be used.

CPU Value [milli-vCPUs]	Memory Value [MiB]
256 (.25 vCPU)	512, 1024, 2048
512 (.5 vCPU)	1024, 2048, 3072, 4096
1024 (1 vCPU)	2048, 3072, 4096, 5120, 6144, 7168, 8192
2048 (2 vCPU)	Between 4096 and 16384 in 1024 MiB increments
4096 (4 vCPU)	Between 8192 and 30720 in 1024 MiB increments

You can find the exact pricing here per region. (ARM)

It does not differ a lot between regions, for us-east-1 are as following:

Region	Resource	Price
us-east-1	Per vCPU per hour	$0.03238
us-east-1	Per GB per hour	$0.00356

As a pointer, if a task runs for 2 minutes this will have the following cost for these combinations:

CPU (vCPUs)	Memory (GB)	Runtime (Minutes)	Total Cost (USD)
0.5	0.5	2	$0.000599
0.5	1	2	$0.000658
1	2	2	$0.001316
2	4	2	$0.002633
3	6	2	$0.003950

Azure

This is currently being developed for Azure.

Azure - Allowed value combinations

Following table shows possible combinations that can be used.

CPU Value [vCPUs]	Memory Value [GiB]
1.0-4.0 vCPU	Between 1-16 GiB

You can find the exact pricing here per region. (AMD64)

It does not differ a lot between regions, for East US are as following:

Region	Resource	Price
East US	Per vCPU per hour	$0.04050
East US	Per GB per hour	$0.00445

As a pointer, if a task runs for 2 minutes this will have the following cost for these combinations:

CPU (vCPUs)	Memory (GB)	Runtime (Minutes)	Total Cost (USD)
0.5	0.5	2	$0,000749
0.5	1	2	$0,000823
1	2	2	$0,001646
2	4	2	$0,003293
3	6	2	$0,004940

GCP

This is not yet implemented in GCP.

Template Specification

Below is the specification for the Stack resource.

• apiVersion: [Required] Should always be infraweave.io/v1.

• kind: [Required] Should always be Stack.

• metadata

  • name: [Required] The name of the stack.

• spec

  • stackName: [Required] The name of your stack

  • version: [Required] The version of the stack to use.

  • reference: [Required] A link to the source code (location of this file)

  • description: [Required] A description of the stack to use, supports markdown.

  • cpu: [Optional] CPU for the terraform job. Check the vendor specific table above. (Default value is 1 vCPU equivalent)

  • memory: [Optional] Memory for the terraform job. Check the vendor specific table above. (Default value is 2 GiB equivalent)

  • examples: [Optional] List of examples of how this stack can be deployed

    • name: [Required] A name (id) for this example (e.g. “simple-bucket”)

    • variables: [Required] Map of variables in camelCase and their values

    • description: [Required] A description of this example, supports markdown.