Enforce Default Custom Module Usage Via Resource Override Policies

This guide provides step-by-step instructions on using the StackGen Command-Line Interface (CLI) to sideload custom policies onto the StackGen platform. Sideloading allows you to extend StackGen's functionality with policies tailored to your requirements.

Overview

The Resource Override Policy allows you to replace specific cloud provider resource types with custom resource types. This is useful for enforcing compliance, standardization, or other organizational requirements in Terraform state management.

The policy consists of the following fields:

• Name: The descriptive name of the policy has to be unique.
• OverrideResourceTypeDetails: Defines the mappings of cloud provider resource types to custom resource types.
  • Each entry within this section represents a cloud provider resource type that should be overridden.
  • The details for each overridden resource include:
    • OverrideType: The custom resource type replacing the cloud provider resource.
    • Locked: can be ignored.
    • TemplateID: The identifier of the template associated with the custom resource type. Has to be a valid UUID.

Example: Below is a policy framework that helps enforce consistency in Terraform state management by allowing controlled resource type overrides. Before applying overrides, validate all template IDs and verify resource mappings..

[
  {
    "Name": "Resource Override Policy - Replace Compute and IAM Roles with Custom Versions",
    "OverrideResourceTypeDetails": {
      "cloud_storage_bucket": {
        "OverrideType": "custom_storage_bucket",
        "Locked": true,
        "TemplateID": "c7aedaa8-cc51-469a-9fc2-f14c57033b52"
      },
      "cloud_iam_role": {
        "OverrideType": "custom_iam_role",
        "Locked": true,
        "TemplateID": "402abbd3-0501-4be1-b683-04418a5ded84"
      }
    }
  }
]

Understanding Resource Override Mapping Policies in StackGen

Click to view

• Override Policies & Drag-and-Drop: The override mapping policy does not affect the drag-and-drop functionality of resources in StackGen. It only swaps or replaces resources when importing configurations (such as Terraform state files) or using Infrastructure as Code (IaC) exports.

• How Overrides Work During Import: When you import a Terraform state (tfstate) file, StackGen maps the resources to built-in or data source templates.

  • Even if a custom resource module was deployed already, StackGen-supported resources will still be created.
  • If a mapping policy exists, StackGen will automatically replace these built-in or data source resources with your custom module.

• Restricting Resource Usage: To prevent users from deploying a generic S3 bucket, define a resource restriction policy. These policies specify a list of allowed templates, which can include both custom templates/modules and built-in templates maintained by StackGen. Any resources not included in the policy will be disabled from the drag-and-drop interface.

  important

  This restriction affects the tfstate import and Cloud-to-Code processes differently. If no mapping policy is defined, restricted resources will still appear in the topology view, but IaC export will be disabled.

• Handling Variable Inputs: StackGen swaps the built-in or data source resource with your custom module when a custom resource is deployed and later re-imported. However, there is currently no built-in support for automatically passing variables (such as tfvars) back into the custom module.

Governance Rules

Click to view

We’ve listed the conditions for defining rules for managing your governance configurations, policies, and permissions within a multi-level structure.

• Ownership: Governance configurations can be owned at either the Enterprise or Team levels. Governance Configurations at the enterprise level can only be comprised of policies that are also owned at the enterprise level.
• Access and Scope: To create a governance configuration at the Enterprise level, a user must have the relevant scope assigned.
  • To create a governance configuration at the Team level, a user must have a team-level role or scope.
  • You can create a Governance configuration only if you are a StackGen DevOps or Administratior user.
• Policy Inheritance and Restrictions: A governance configuration at the Team level must contain policies that are also owned by the Team.
  • Policies created at the Enterprise level can be inherited by teams.
  • Policies created at the Team level cannot be accessed by other Teams.
• Policy Application Conditions:
  • If a governance configuration is applied to a Team, it overrides any configuration at the Enterprise level.
  • If a governance configuration is applied at an appStack level, it takes precedence over the Team level governance configuration.
  • An appStack automatically applies the governance configuration of the team it belongs to at the time of creation.
• Custom Resource and Security Conditions:
  • A custom resource template can be created at the User or Team level, but not at the Enterprise level.
  • A governance configuration applied at the Enterprise level must only use policies and resources that exist at the Enterprise level.
• Governance configurations are visible based on user Roles and Permissions.
• Secret storage must indicate which Teams have access and prevent unauthorized deletions.

Prerequisites

Click to view

Before you begin, ensure you have the following:

• StackGen CLI installed and configured: Follow the StackGen CLI documentation to install and set up the CLI on your system.
• Custom policy files: Ensure that your policy files are correctly formatted and ready for sideloading. Example policy format is present under CLI help command stackgen upload resource-override-policy --help.

Important Considerations

Click to view

• Policy format: Your custom policy files must adhere to the format specified by StackGen. Incorrect formatting may cause errors during the upload.
• Policy conflicts: Be mindful of potential conflicts between your custom and existing StackGen policies. Carefully review your custom policies to avoid unintended behaviour.
• Version control: Consider using version control for your custom policy files. This will help you track changes and revert to previous versions if needed.
• Testing: Thoroughly test your custom policies in a controlled environment before applying them to production workloads.
• Resource Name Matching: The resource type specified in OverrideResourceTypeDetails must exactly match the Terraform state resource type. Example: Overriding cloud_function with custom_function works only if the incoming Terraform state contains cloud_function.
• Template ID Verification: The TemplateID must belong to a custom resource type accessible to the team applying the policy.

  • The TemplateID must correspond to the same resource type as the one being overridden.

  • Before creating a resource override policy, ensure the TemplateID is listed using the command:

    stackgen resource type --pattern custom_storage_bucket -c true --team teamId

Process Workflow

To sideload custom policies onto the StackGen platform, you’ll need to:

1. Create a new Custom Resource
2. Initialize the StackGen CLI
3. Create a custom policy.json file
4. Upload the Policy via StackGen CLI
5. Create a Governance Configurationtemplate that lets you enforce this policy on Teams

Let’s go through each step in detail.

Create a New Custom Resource

Click to view

1. Navigate to the Team workspace: In StackGen, policies are enforced at the team level. Make sure you are in the desired Team’s workspace where you want to set up the custom module enforcement policy, then collect the Team ID from the browser URL.
2. Create a new Custom Resource:

   1. In the appStack view, click New Resource on the bottom left.

      

   2. Click the + icon at the top of the list next to the Custom Resources section.

      

   3. Link the custom module from your git repository.

Initialize StackGen CLI

Click to view

1. Set the following three environment variables in your shell to point StackGen CLI to the right environment:

   1. Refer to the PAT documentation to create a Token and run:

      export STACKGEN_TOKEN=<TOKEN>

   2. Follow these steps to retrieve your Team ID:

      1. Select the team from the Teams dropdown.

      2. Copy your Team ID from the browser address bar.

         

      3. Run the following:

         `Export STACKGEN_TEAM=<Team ID from step 1>`

   3. Copy the URL for your StackGen Cloud and run the following:

      export STACKGEN_URL=<URL>

2. Run the following command to list available resource types:

   stackgen resource type -c true

   Before creating a resource override policy, ensure the TemplateID is listed using the command:

   stackgen resource type --pattern custom_storage_bucket -c true --team teamId

   3. Find your custom module on the list and copy its UUID.

Create a Custom policy.json File

Click to view

The example below defines a Hardened S3 Substitution Policy policy that automatically replaces any S3 resources in an Appstack with a custom S3 module. Copy and modify the example into the policy.json file.

[
  {
    "Name": "Hardened S3 Substitution Policy",
    "OverrideResourceTypeDetails": {
      "aws_s3": {
        "OverrideType": "aws_s3_bucket",
        "Locked": true,
        "TemplateID": "{CUSTOM_MODULE_UUID_HERE}"
      }
    }
  }
]

Upload the Policy via StackGen CLI

Click to view

1. Navigate to the policy directory: Use the cd command to navigate to the directory containing your custom policy files.

2. Upload the policy via CLI: Use the stackgen upload command followed by the path to your policy file.

   For example:

   stackgen upload resource-override-policy -p path/to/your/policy.json

3. Verify successful External Policy loading: The StackGen CLI will provide feedback on the sideloading process. Look for messages indicating success or any potential errors.

Create Governance Configuration

Click to view

​​Ensure that the overridden resource type aligns with the organizational policies and infrastructure requirements.From the StackGen home page, click Governance Configurations (from your team’s workspace) to create a new governance configuration.

Examples

We’ve listed examples of custom policies you could use to ensure consistency, security, and compliance when provisioning your resources on various clouds.

AWS

• Replace all generic S3 buckets and RDS templates with hardened custom modules.

  [
  {
      "Name": "Enforce S3 Encryption",
      "OverrideResourceTypeDetails": {
      "aws_s3_bucket": {
          "OverrideType": "aws_s3_bucket",
          "Locked": true,
          "TemplateID": "s3-encryption-template"        
      },
  "aws_rds_cluster": {
          "OverrideType": "aws_rds",
          "Locked": true,
          "TemplateID": "rds-hardend-template-id"        
      }
      }
  }
  ]

• Mandate the use of a custom storage account module instead of a generic storage account template.

  [
  {
      "Name": "Require Azure Storage Account Encryption",
      "OverrideResourceTypeDetails": {
      "azurerm_storage_account": {
          "OverrideType": "azurerm_storage_account",
          "Locked": true,
          "TemplateID": "azure-storage-template-id"
      }
      }
  }
  ]

Google Cloud (GCP)

• Ensure the use of a custom Cloud Storage Bucket template instead of a default configuration.

  [
  {
      "Name": "Require GCP Storage Encryption",
      "OverrideResourceTypeDetails": {
      "google_storage_bucket": {
          "OverrideType": "google_storage_bucket",
          "Locked": true,
          "TemplateID": "gcp-storage-template-id"
      }
      }
  }
  ]