How to Manage Building Block Definitions as Code

What is this guide about?

This guide explains how to manage building block definitions as infrastructure-as-code using the meshStack Terraform provider. You'll learn how to create, version, release, and maintain building block definitions through code, enabling version control, automation, and collaborative workflows for your platform engineering team.

Why Manage Building Block Definitions as Code?

Managing building block definitions as code provides several key benefits:

• Version Control: Track all changes to your building block definitions in Git, enabling rollback, history tracking, and code reviews
• Collaboration: Enable multiple platform engineers to work on building blocks simultaneously with proper merge workflows
• Automation: Integrate building block definition management into your CI/CD pipelines for automated testing and deployment
• Reproducibility: Ensure consistent deployment of building blocks
• Documentation: Your Terraform code serves as living documentation of your building block definitions

Prerequisites

Before you begin, ensure you have:

• meshStack Terraform Provider configured: A working OpenTofu/Terraform setup with the meshStack provider installed
• API key with appropriate permissions: An API key with permissions to create, read, and update building block definitions in your target workspace
• Basic Terraform knowledge: Familiarity with Terraform/OpenTofu resources, state management, and HCL syntax
• Git repository: A repository for storing your building block definition configurations
• Access to meshPanel: For initial setup and verification

Step by Step Guide

1. Set Up Your Terraform Configuration

Create a dedicated directory structure for your building block definitions:

mkdir -p building-blocks/definitions
cd building-blocks/definitions

Create a provider.tf file to configure the meshStack provider:

terraform {
  required_providers {
    meshstack = {
      source  = "meshcloud/meshstack"
    }
  }
}

provider "meshstack" {
  # Authentication is automatically configured via:
  # - MESHSTACK_API_KEY environment variable
  # - MESHSTACK_API_SECRET environment variable
  # - MESHSTACK_ENDPOINT environment variable (meshStack API URL)
  # These are shown when creating an API key in meshPanel
}

2. Create Your First Building Block Definition

Create a file s3-bucket.tf for a simple S3 bucket building block:

For a complete, production-ready example, see the S3 bucket example on meshstack-hub. That example also sets up the backplane needed for Workload Identity Federation (WIF) integration with the building block definition.

Below is a simplified version to illustrate the core concepts:

resource "meshstack_building_block_definition" "s3_bucket" {
  metadata = {
    # define workspace for definition
    owned_by_workspace = "my-platform-team"
  }

  spec = {
    display_name = "AWS S3 Bucket"
    description  = "Provisions an S3 bucket for application teams."
    target_type  = "WORKSPACE_LEVEL"
  }

  version_spec = {
    # first, setup the initial version in draft mode
    draft = true

    # define implementation details for the definition
    implementation = {
      terraform = {
        terraform_version = "1.9.0"
        repository_url    = "https://github.com/meshcloud/meshstack-hub.git"
        repository_path   = "modules/aws/s3_bucket/buildingblock"
        ref_name          = "main"
      }
    }

    # inputs for the definition
    # you can see two required ones for WIF here as well
    inputs = {
      bucket_name = {
        type            = "STRING"
        assignment_type = "USER_INPUT"
        display_name    = "S3 Bucket Name"
        description     = "The name of the S3 bucket"
      }
      AWS_ROLE_ARN = {
        type            = "STRING",
        display_name    = "AWS Role ARN",
        description     = "The ARN of the AWS role to assume for provisioning the S3 bucket",
        assignment_type = "STATIC",
        is_environment  = true
        argument        = jsonencode(module.backplane.workload_identity_federation_role)
      },
      AWS_WEB_IDENTITY_TOKEN_FILE = {
        type            = "STRING",
        assignment_type = "STATIC",
        display_name    = "AWS Web Identity Token File Path",
        description     = "The file path to the AWS web identity token for authentication",
        is_environment  = true
        argument        = jsonencode("/var/run/secrets/workload-identity/aws/token")
      }
    }

    outputs = {
      bucket_arn = {
        type            = "STRING"
        assignment_type = "NONE"
        display_name    = "S3 Bucket ARN"
      }
      # ...
    }
  }
}

3. Initialize and Apply Your Configuration

Initialize OpenTofu and create the building block definition:

# Initialize OpenTofu
tofu init

# Review the plan
tofu plan

# Apply the configuration
tofu apply

The building block definition is now created in meshStack as a draft. You can verify this in meshPanel under "Platform Builder > Building Blocks > Definitions".

4. The Draft and Release Process

Building block definitions follow a draft → release workflow to ensure safe changes:

Understanding Draft Status

When draft = true, the building block definition is in development mode:

• ✅ Can be freely modified
• ✅ Not visible in the marketplace to end users
• ✅ Can be tested by platform team members
• ❌ Cannot be used by application teams

Releasing a Building Block Definition

To release your building block definition and make it available in the marketplace:

1. Update the draft status in your Terraform configuration:

resource "meshstack_building_block_definition" "s3_bucket" {
  # ... metadata and spec ...
  
  version_spec = {
    draft = false  # Change from true to false
    # ... rest of version_spec ...
  }
}

2. Apply the change:

tofu plan  # Review the change
tofu apply # Release the definition

Important

Once released (draft = false), the building block definition becomes available in the marketplace. If you created the building block definition from a workspace (not as an admin), it will first need to be approved by an admin before becoming visible in the marketplace.

Ensure you've thoroughly tested it before releasing.

5. Creating New Versions (Updating Released Definitions)

When you need to update a released building block definition, follow this process:

1. Create a new draft version by setting draft = true and making your changes:

resource "meshstack_building_block_definition" "s3_bucket" {
  metadata = {
    owned_by_workspace = "platform-team"
  }

  spec = {
    display_name = "S3 Bucket"
    description  = "Provisions an S3 bucket with best practice security settings (Updated)"
    # ... rest of spec ...
  }

  version_spec = {
    draft = true  # Create new draft version
    # ... rest of version_spec ...
  }
}

2. Apply to create the draft version:

tofu apply

3. Test the draft version using meshPanel or API

4. Release the new version by changing draft = false:

version_spec = {
  draft = false  # Release the new version
  # ... rest of version_spec ...
}

5. Apply to release:

tofu apply

note

If your first version of the building block definition has already been approved and you manage this from a workspace, subsequent releases no longer require approval and will be directly visible in the marketplace.

Version Number Management

meshStack automatically manages version numbers for you:

• When you create a new draft, meshStack increments the version number
• When you release a draft, that version becomes the latest published version
• Existing building block instances continue using their assigned version until manually upgraded by the platform team

6. Common Operations

Adding Dependencies Between Building Blocks

Define dependencies to ensure building blocks are provisioned in the correct order:

resource "meshstack_building_block_definition" "app_vm" {
  # ... metadata and spec ...
  
  version_spec = {
    # ... other config ...
    
    dependencies = [
      {
        ref = {
          uuid = meshstack_building_block_definition.s3_bucket.metadata.uuid
          kind = "meshBuildingBlockDefinition"
        }
      }
    ]
    # ... rest of version_spec ...
  }
}

Configuring Ephemeral API Keys

Enable building blocks to interact with the meshStack API:

resource "meshstack_building_block_definition" "composition" {
  # ... metadata and spec ...
  
  version_spec = {
    # ... other config ...
    
    permissions = [
      "BUILDINGBLOCK_LIST",
      "BUILDINGBLOCK_SAVE",
      "PROJECT_LIST",
      "TENANT_LIST"
    ]
    # ... rest of version_spec ...
  }
}

Adding Tags for Compliance

Use tags to implement access control and compliance rules:

resource "meshstack_building_block_definition" "secure_bucket" {
  metadata = {
    owned_by_workspace = "platform-team"
    tags = {
      SecurityLevel = ["high"]
      Compliance    = ["example", "demo"]
      Environment   = ["production"]
    }
  }
  # ... rest of definition ...
}

Configuring Multiple Platform Support

Allow a building block to work across multiple cloud platforms:

version_spec = {
  # ... other config ...
  
  supported_platform_types = [
    "AWS",
    "AZURE",
    "GCP"
  ]
  # ... rest of version_spec ...
}

Related Resources

Concepts

• Building Block - Understanding building blocks and building block definitions
• Marketplace - How building blocks appear in the marketplace

Guides

• How to Import an Existing Building Block Definition - Import existing definitions into Terraform
• How to Launch a New OpenTofu Building Block - Creating building blocks through the UI
• How to Manage a Building Block Definition - General management practices
• How to Use Ephemeral API Keys in Building Blocks - Configure building blocks to use the meshStack API

External Resources

• meshStack Terraform Provider Documentation - Complete provider reference
• meshStack Terraform Provider - Building Block Definition Resource - Resource documentation