Skip to main content

Building Block

Building blocks are a granular and standardized asset of automation provided by platform teams via the platform builder. If you often set up the same infrastructure or configurations, meshstack's building blocks can save you time and effort. Building blocks definitions are offered via the marketplace and can be provisioned as building blocks by application teams in self-service.

Use the meshStack Hub

The meshStack Hub is your go-to place for discovering ready to use building blocks without the need to create them from scratch.

Building Block Definition​

A building block definition is a reusable template for automating resource provisioning. Building blocks are instances of building block definitions. Platform teams create and manage these definitions in the platform builder.

Building Block Types​

Workspace Building Blocks​

A workspace building block is created under a workspace and is globally available to all projects within that workspace. Use this type when the service does not need to be tied to a specific environment (project) for example project tooling or a central service used by multiple environments. Workspace building blocks don't have prerequisites such as platform type, platform, landing zone or a tenant. They have an individual life cycle linked only to the workspace.

Tenant Building Blocks​

A tenant building block is tied directly to a specific tenant, such as a virtual network or database within an AWS Account or Azure Subscription. When the tenant is deleted, the building block must also be deleted beforehand. Tenant building blocks can have a price setup for them that is added to the tenant usage report and chargeback statement.

Building Block Dependencies​

Building blocks can have dependencies on other building blocks. This allows for complex setups where one building block relies on another to function correctly. An example would be an Azure VM building block requiring a vnet building block. Dependencies are defined in the building block definition and are resolved during provisioning.

Building Block Implementation Types​

Building blocks can be implemented using different methods, depending on your automation needs and existing workflows. The available implementation types are:

Manual Implementation​

Manual building blocks are ideal if you want start standardizing without having the automation in place yet. Platform Engineers can offer manual building blocks via the marketplace to application teams. Whenever the building block is added to a tenant or workspace the Platform Engineers complete the work manually. This helps platform engineers to see the demand for this type of offering and prioritize the implementation of automated building blocks.

OpenTofu Implementation​

If you are a Platform Engineer with HashiCorp Terraform modules (supported until 1.5) or OpenTofu Modules in place you can easily integrate them into meshStack to completely automate provisioning from the request to deployment. The building block definition includes OpenTofu modules, which are executed automatically during provisioning. This approach enables consistent, repeatable, and scalable infrastructure deployment.

Logs When an OpenTofu Building Block is added to a project, logs are generated detailing the provisioning process and any errors. Admins and platform builder users can access these logs via the Building Block overview. Selecting a specific Building Block instance and its "Run" allows inspection of the related OpenTofu logs.

GitHub Actions Workflow Implementation​

GitHub Actions building blocks use GitHub Actions workflows to automate resource provisioning or configuration tasks. The building block definition references a workflow file, which is triggered and executed as part of the provisioning process. This method is ideal for teams already leveraging GitHub for source control and automation.

GitLab CI/CD Implementation​

GitLab CI/CD building blocks utilize GitLab's pipeline capabilities to automate provisioning steps. The building block definition specifies a .gitlab-ci.yml configuration, which runs jobs and scripts to set up resources. This approach integrates seamlessly with GitLab-based development and deployment workflows.

Azure DevOps Pipelines Implementation​

Azure DevOps Pipelines building blocks leverage Azure DevOps pipeline capabilities to automate provisioning and configuration tasks. The building block definition references a pipeline in Azure DevOps, which is triggered and executed as part of the provisioning process. This approach integrates seamlessly with teams using Azure DevOps for source control and automation workflows.

Building Block Inputs​

Building Blocks work on the principle of collecting input parameters from various sources to customize the provisioning process.

There are many input types available which you can chose from. You can also decide to encrypt sensitive inputs.

With OpenTofu building blocks you are also able to generate the inputs automatically from the OpenTofu module.

We are in the process of adding more input sources and types. If you have a specific request, please let us know via Canny.

User Permissions Input​

This input type is useful for granting users access to specific resources within a platform. This make sense if you are handling a platform that is not natively supported by meshStack or you want to handle user authorization on your own. It provides the Building Block with a list of user objects in the following JSON structure:

[
    {
        "meshIdentifier": "identifier1",
        "username": "johndoe",
        "firstName": "John",
        "lastName": "Doe",
        "email": "johndoe@test.com",
        "euid": "johndoe",
        "roles": ["reader"]
    },
    {
        "meshIdentifier": "identifier2",
        "username": "lisaluck",
        "firstName": "Lisa",
        "lastName": "Luck",
        "email": "lisaluck@test.com",
        "euid": "lisaluck",
        "roles": ["admin", "reader", "user"]
    }
]

Code Input​

The Code input type allows building blocks to accept complex, structured data that goes beyond simple strings, numbers, or boolean values. This input type is particularly useful for OpenTofu/Terraform building blocks that need to work with sophisticated data structures.

In the case of a OpenTofu Building Block, Code inputs accept HCL (HashiCorp Configuration Language) expressions, enabling you to pass:

  • Complex types: Lists of objects, maps, nested structures (e.g., list(object({name = string, value = number})))
  • Direct HCL expressions: Values that OpenTofu should evaluate as code rather than plain text

For file content like certificates or PEM files, use the File input type instead, which is specifically designed for file uploads.

When users provide Code inputs in meshPanel, they use a text editor interface designed for proper formatting of complex values. The OpenTofu runner parses these inputs as HCL expressions, ensuring type-safe handling of structured data. If parsing fails, the CODE input value is passed as a properly encoded string into the variable. This fallback allows passing in YAML structure which can then by decoded with yamldecode within OpenTofu. Note that any JSON is also a valid HCL expression, so this will only be passed as a string if the variable input is specified with type = string in OpenTofu.

Like other input types, Code inputs can be marked as sensitive for encryption, making them suitable for passing credentials.

Sensitive Inputs​

Sensitive inputs are a useful feature for passing secrets like API keys or tokens to your building blocks. However, you should be aware of their limitations. Before using sensitive inputs, Platform engineers should consider if their use case can be alternatively solved using Workload Identity Federation or an external key management system.

Sensitive inputs are encrypted at rest using asymmetric cryptography. Our API can technically never return plaintext secrets. Values are only decryptable by the building block runner assigned to the building block definition.

Changing Runners

When changing the runner or changing the runner's public key, inputs can no longer be decrypted.

  • For static inputs: You need to publish a new building block definition version and resubmit plaintext values to make the building block runnable again.
  • For user inputs: Users need to update input values on their building blocks.

Building block runners will decrypt sensitive inputs and have them accessible in their environment. Run logs are thus at risk of leaking these secrets, for example in GitHub Actions logs or Terraform logs. Platform engineers should carefully review their pipeline configuration to ensure they are not inadvertently exposing secrets.

meshStack does currently not support sensitive outputs.

Building Block Outputs​

Building Blocks can provide output values to both admins and users after provisioning. These outputs can include information such as resource IDs, connection strings, or other relevant data generated during automation.

For OpenTofu-based Building Blocks, you can automatically extract OpenTofu outputs into meshStack. This is helpful in two main scenarios:

  • Dependency Management: If a Building Block depends on another (e.g., a virtual machine requiring a VNET ID), you can output the required variable from one Building Block and use it as an input for the dependent Building Block.
  • User Visibility: Outputs that are important for end users, such as access credentials or resource endpoints, can be displayed in the tenant control plane, making them easily accessible to customer users.

Ephemeral API Keys​

Building blocks can receive temporary API keys to interact with the meshStack API during their execution. This enables self-service automation patterns where building blocks can create additional resources like other building blocks, tenants or other meshObjects within the consuming workspace without requiring admin permissions. Therefore Platform Teams can set the required permissions in self-service.

When you configure permissions on a building block definition, the system automatically provides authentication to the building block implementation through the following environment variable:

  • MESHSTACK_API_TOKEN: A short-lived bearer token with the configured permissions

Additionally, the input variable MESHSTACK_ENDPOINT contains the meshStack API URL and can be used to execute operations against the meshStack API.

The ephemeral API key is scoped to the workspace where the building block runs and has only the permissions you explicitly configured. Users see the required permissions in the marketplace before adding the building block, allowing them to make informed decisions about what access the building block will have.

Key Benefits​

  • Least Privilege: Building blocks only get the permissions they need, scoped to the workspace
  • Transparency: Application teams see required permissions before adding a building block
  • Automatic Credential Management: No manual API key rotation or secret management
  • Security: Keys are automatically deleted after the run completes or after a maximum of 6 hours

Privilege Escalation Prevention​

If your building block creates nested building blocks that also require permissions, meshStack prevents privilege escalation. A nested building block creation fails if it requests more permissions than the parent building block has. This ensures that building blocks cannot grant themselves elevated access.

Supported Implementation Types​

Ephemeral API keys are supported for:

  • OpenTofu building blocks
  • GitLab CI/CD building blocks
  • Azure DevOps Pipelines building blocks

Note: Ephemeral API keys are not yet fully supported for GitHub Actions and Azure DevOps building blocks.

For OpenTofu building blocks, the meshStack Terraform provider automatically picks up MESHSTACK_API_TOKEN and MESHSTACK_ENDPOINT environment variables. No additional provider configuration needed.

For a step-by-step guide on setting up ephemeral API keys, see How to Use Ephemeral API Keys in Building Blocks.

Building Block Run Control​

Building Block Run Control configures who is allowed to create building block runs and review detailed logs of each run. Two options are available: Platform Team Only and Platform Team and Workspace Users.

Platform teams can always trigger new building block runs and view all logs of any building block they own the building block definition of.

When set to Platform Team Only workspace Users cannot manually trigger new building block runs except by updating inputs. Also, workspace users can only review building block run logs explicitly flagged as user messages.

Note: Building Blocks using the OpenTofu implementation type do not emit "user messages" at this time. Therefore, if you select the Platform Team Only option, workspace users will not see any logs for OpenTofu building blocks.

When set to Platform Team and Workspace Users workspace users can manually trigger new building block runs and view all logs. This option is useful for building blocks where users can be expected to troubleshoot and resolve issues on their own.

Pricing​

You can set up prices for Building Blocks when ordered via the marketplace. For more information please follow the How to Setup Prices guide.

Versioning and Rollout​

To update an existing Building Block, go to the Building Block definitions and select the desired Building Block. Click "Create draft" to start a new version. The definition will enter edit mode, allowing you to make and save changes.

Once your changes are complete, select "Release" to publish the new version. This version becomes the default for users ordering the Building Block from the Marketplace. Existing users continue to use the previous version unless an upgrade is performed.

If you need to upgrade existing instances to the latest version, navigate to the Admin Area and select "Marketplace > Building Blocks." Check the boxes next to the Building Blocks you want to upgrade, then click “Upgrade.” This action forces a new run of the selected Building Blocks, ensuring users receive the latest version.

The following diagram shows how a building block definition and its versions relate to building block instances, and how the platform team and app teams interact:

Building Block Execution Model​

Note: meshStack is transitioning to an improved execution model. The features described here are being rolled out gradually and may not be available in all environments yet.

Building blocks execute in isolated and ephemeral environments. Each run creates a temporary execution environment that is destroyed after completion.

Benefits:

  • Isolated Execution: Each run executes independently without sharing state or resources
  • Scoped WIF Tokens: Workload Identity Federation tokens are scoped to specific building block definitions
  • Parallel Execution: Multiple building blocks can run simultaneously without resource contention

Credentials Management (OpenTofu Only)​

In some cases, OpenTofu code requires credentials to provision infrastructure. For example, an OpenTofu building block for AWS typically needs access keys. A best practice is to use environment variables such as AWS_ACCESS_KEY_ID and AWS_SECRET_ACCESS_KEY. In this case, your OpenTofu AWS provider configuration can be as simple as:

provider "aws" {}

These environment variables must be provided to the OpenTofu runner. In meshStack, you can define these as input variables in the Building Block definition with the following settings:

  • Source: Static (if you want to use the same credentials for every run) or User input (to let users provide their own)
  • Input type: String
  • Provided as: Environment
  • Encryption: Enabled

This approach is not limited to AWS. Many OpenTofu providers support authentication via environment variables. For example, the Datadog provider uses DD_API_KEY and DD_APP_KEY as environment variables. For more details, see the Datadog Terraform provider documentation.

Cloud Provider Authentication Methods​

meshStack simplifies credential management by offering preconfigured inputs for the three major cloud platforms (AWS, Azure, and GCP). When creating an OpenTofu building block, you can use the "Generate Inputs" menu to automatically add the necessary credential inputs based on your preferred authentication method:

  1. Traditional Credential-Based Authentication: Use long-lived credentials like access keys or service account keys. This method is straightforward but requires manual credential management and rotation.
  2. Workload Identity Federation (Recommended): Use short-lived OIDC tokens that meshStack automatically provides to building blocks. This method eliminates the need for long-lived credentials and enhances security by leveraging cloud-native identity federation features.

Traditional Credential-Based Authentication​

If you choose traditional credential-based authentication, meshStack can generate the necessary input variables for you. When defining your building block, under "Inputs", select the appropriate option from the "Generate Inputs" menu:

  • AWS: Select "Generate AWS auth inputs" to create inputs for access key authentication using AWS_ACCESS_KEY_ID and AWS_SECRET_ACCESS_KEY
  • Azure: Select "Generate Azure auth inputs" to create inputs for service principal authentication using client credentials
  • GCP: Select "Generate GCP auth inputs" to create inputs for service account key authentication

WIF lets building blocks access cloud resources without long-lived credentials. For each run, meshStack creates a Kubernetes Job that declares projected service account token volumes — one per cloud provider — mounted at well-known file paths inside the execution environment. Kubernetes issues these short-lived tokens (valid for 2 hours) automatically when the job starts, with provider-specific audience claims and a subject claim scoped to the building block definition. The cloud provider validates the token against a pre-configured trust relationship and issues temporary credentials.

WIF Configuration Values​

Each building block definition has a dedicated set of WIF values that identify it as a trusted OIDC principal to your cloud provider. You'll need these when configuring the cloud-side IAM trust relationship.

tip

Find these values in the Admin Area or Platform Builder → Implementation tab → Workload Identity Setup of your building block definition.

ValueToken claimDescription
Issuer URLissOIDC issuer of the runner's identity provider (for example, your Kubernetes cluster) — configure this as the trusted issuer in your cloud provider
SubjectsubScoped to this building block definition — target it exactly in your IAM trust policy
AudienceaudCloud-provider-specific value embedded in the token
Token path—File path inside the execution environment where the token is mounted

Getting Started​

The meshStack Hub provides ready-to-use building block examples for the most common cloud platforms. Each example combines a backplane module — which creates the cloud-side IAM trust relationship using the WIF values above — with the building block definition registration in meshStack, all in a single configuration.

OpenTofu and the meshStack Hub

The examples above use the meshStack OpenTofu provider and meshStack Hub modules to automate the full setup. If your team does not use OpenTofu, or if you need guidance on manual IAM configuration, reach out to support@meshcloud.io.

Self-Hosted Runners

Building block runners are currently operated by meshStack. If your organization requires self-hosted runners or wants to bring its own WIF configuration with full control over the OIDC issuer, token claims, and IAM trust policies, contact support@meshcloud.io to discuss available options.

Security Considerations

WIF grants cloud resource access to whatever code runs with the federated identity. Apply least-privilege IAM policies on the cloud side, and only configure WIF for building blocks fully controlled by your platform team. Avoid broad roles or reusing the same WIF setup across untrusted runners, as this can lead to unintended access.

Monitoring and Troubleshooting​

Building Block Execution Monitoring​

meshStack provides visibility into building block execution through run details and status information. Each building block instance shows its current state and execution history, helping you track provisioning progress and identify any issues.

Timeout Detection and Warning Messages​

Building blocks include enhanced timeout detection that provides better visibility into execution issues. When a building block run experiences timeouts, warning messages are displayed in the building block run details to help you understand what happened and why.

Building Block Timeout and Retry Behavior:

By default, building block runs have a timeout of 3 hours. When a timeout occurs, the system automatically retries the run indefinitely until one of the following happens:

  • The run reaches a final state (succeeded or failed)
  • The run is manually aborted by an operator
  • A new run is triggered for the same building block

This automatic retry mechanism helps resolve temporary issues that may cause timeouts, such as network connectivity problems or temporary platform unavailability. When the circumstances change (like a network issue being resolved), the retried run can complete successfully.

Important retry behavior: If a new run is triggered while an existing run is still being retried after timeouts, the system will stop retrying the old run and execute the new one instead. This ensures you always get the most current configuration applied.

Timeout warnings in the building block run details provide transparency into execution performance and help you understand when retries are occurring.

Concepts​

Guides​