Module Overview

Modules are global, reusable, and composable Terraform configurations, essential for building modular and maintainable infrastructure.

Every Module turns existing terraform code to be available for deployment in InfraWeave.

A Module is published using the cli, and will enable to provisioning infrastructure using that module.

Note

Try to keep on a relatively small level and reuse using stacks, avoid built-in logic.

Defining Modules

You define a Module in a manifest file. Below is an example of a module definition.

modules/s3bucket.yaml

apiVersion: infraweave.io/v1
kind: Module
metadata:
  name: s3bucket # The name of the module you define, must match lowercase of moduleName
spec:
  moduleName: S3Bucket # The name of the module you define
  version: 0.1.4 # The released version to use
  reference: https://github.com/your-org/s3bucket # The URL to the module's source code
  description: | # Description; supports markdown
    # About
    Amazon S3 is an object storage service that stores data as objects
    within buckets.
    ## Usage
    Store files and make them available to other files
    > Don't forget to use versioning if you want to keep old versions

Put it in the same directory as your terraform files (including the lockfile .terraform.lock.hcl)

• Directorysrc/

  • .terraform.lock.hcl
  • data.tf
  • main.tf
  • module.yaml
  • variables.tf
  • Directoryother_files

    • example.txt

Caution

Do not set region in your provider block unless you have a very specific use-case. When deploying the Module it should instead be set by the user with region in the deployment claim.

(if you set region in the provider block this will take precedence whatever the user sets in the deployment claim)

Examples

Module can be extended with examples to show a working implementation.

This allows to provide guidance of how it can be used, and serves as templates in Backstage. It can also serve as test cases for the python module to prevent broken examples.

modules/s3bucket.yaml

...
spec:
  ...
  examples:
    - name: simple-bucket
      variables:
        bucket_name: mybucket-14923
      description: |
        # Simple Bucket

        This example ...
    - name: advanced-bucket
      variables:
        bucket_name: mybucket-14923
        resource_policy:
          Actions:
            - s3:GetObject
            - s3:PutObject
            - s3:ListBucket
            - s3:DeleteObject
          Resources:
            - arn:aws:s3:::mybucket-14923
            - arn:aws:s3:::mybucket-14923/*
          Principal:
            AWS: arn:aws:iam::123456789012:role/my-role-name
          Effect: Allow
      description: |
        # Advanced Bucket

        This example ...

Runtime Context Variables

It is possible to create variables that will automatically be set during runtime, e.g. which deployment_id, who committed, which repo etc, by adding this to a module:

...

variable "INFRAWEAVE_GIT_COMMITTER_EMAIL" {
  type    = string
  default = ""
}

variable "INFRAWEAVE_REFERENCE"  {
  type    = string
  default = ""
}

Any variable starting with INFRAWEAVE_ is reserved for this feature and will not be exposed to user as a regular variable. It is mandatory to set type=string and default="", you can optionally set a description.

Usecase

This is commonly used for tags, e.g.:

provider "aws" {
  default_tags {
    tags = merge(
      var.tags,
      {
        INFRAWEAVE_GIT_COMMITTER_EMAIL = var.INFRAWEAVE_GIT_COMMITTER_EMAIL
        INFRAWEAVE_REFERENCE = var.INFRAWEAVE_REFERENCE
      }
    )
  }
}

Available Options

Generic (always available)

These will always set a value if you decide to include it

INFRAWEAVE_DEPLOYMENT_ID
INFRAWEAVE_ENVIRONMENT
INFRAWEAVE_REFERENCE
INFRAWEAVE_MODULE_VERSION
INFRAWEAVE_MODULE_TYPE
INFRAWEAVE_MODULE_TRACK
INFRAWEAVE_DRIFT_DETECTION
INFRAWEAVE_DRIFT_DETECTION_INTERVAL

GitHub Webhook Specific

Will only be set when pushing to a GitHub repository, otherwise it will be "" (empty string)

INFRAWEAVE_GIT_COMMITTER_EMAIL
INFRAWEAVE_GIT_COMMITTER_NAME
INFRAWEAVE_GIT_ACTOR_USERNAME
INFRAWEAVE_GIT_ACTOR_PROFILE_URL
INFRAWEAVE_GIT_REPOSITORY_NAME
INFRAWEAVE_GIT_REPOSITORY_PATH
INFRAWEAVE_GIT_COMMIT_SHA

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 1vCPU and 4GB for the runner:

modules/s3bucket.yaml

apiVersion: infraweave.io/v1
kind: Module
metadata:
  name: s3bucket
spec:
  moduleName: S3Bucket
  version: 0.1.4
  reference: https://github.com/your-org/s3bucket
  cpu: "1024"      # See table below for valid CPU values
  memory: "4096"   # See table below for valid memory values
  description: |
    # About
    Amazon S3 is an object storage service that stores data as objects

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 Module resource.

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

• kind: [Required] Should always be Module.

• metadata

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

• spec

  • moduleName: [Required] The name of your module

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

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

  • description: [Required] A description of the module 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 module can be deployed

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

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

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