stackgen-modules

This repository holds StackGen custom modules: Terraform modules for AWS, Azure (azurerm), and GCP, each packaged so they can be ingested and used inside StackGen as reusable infrastructure templates.

The modules are the source of truth for cloud resource patterns (VPCs, storage, Kubernetes, databases, and many others). They are organized by provider and named consistently with the underlying Terraform resource or data source (for example, aws_s3, azurerm_linux_webapp, google_bigquery).

Terraform and provider versions (main branch)

The following are the required_version / required_providers constraints declared in each module’s versions.tf on the default branch. They are compatibility ranges (not pinned releases); Terraform selects provider versions that satisfy them.

Component	Constraint	Registry source
Terraform CLI	>= 1.0.0, < 2.0.0	—
AWS	~> 5.0	hashicorp/aws
Azure	~> 3.9	hashicorp/azurerm
Google Cloud	~> 6.0	hashicorp/google

Individual modules may occasionally diverge if a pull request updates constraints before the rest of the repo; the module’s own versions.tf is always authoritative. See Versioning and provider compatibility for how releases and tags relate to these constraints.

Repository layout

Path	Purpose
aws/	AWS modules (one directory per module)
azurerm/	Azure modules
gcp/	Google Cloud modules
tools/	Scripts and helpers to upload modules and maintain metadata — see Tools

Each module is a folder that typically contains:

• Terraform (.tf) and any supporting files for that resource or composite.
• .stackgen/stackgen.yaml — StackGen metadata: UI labels, variable definitions, controls, and representation hints used when the module is exposed in the product.

If you are publishing modules to StackGen or syncing this repo with an environment, use the tooling in Tools.

Tools

Utilities for uploading modules to StackGen via the CLI (stackgen upload custom-modules) and maintaining metadata in this repo.

upload_stackgen_modules.sh

Batch upload using the StackGen CLI with minimal required input (--token), optional --url / --project / --templates, and Git --repo-url / --branch (or --tag). Supports SCM_TYPE / SCM_TOKEN for GitHub-backed flows.

Basic upload

./tools/upload_stackgen_modules.sh \
  --token "YOUR STACKGEN TOKEN" \
  --url "https://main.dev.stackgen.com" \
  --repo-url "https://github.com/stackgenhq/stackgen-modules" \
  --branch "main"

Single-module upload

For a specific template, for example the azurerm_linux_webapp module:

STACKGEN_URL="https://main.dev.stackgen.com" \
STACKGEN_TOKEN="YOUR STACKGEN TOKEN" \
stackgen upload custom-modules ./azurerm/azurerm_linux_webapp \
  --provider azure \
  --name azurerm_linux_webapp \
  --repo-url "https://github.com/stackgenhq/stackgen-modules" \
  --branch main

Options

• --token (required): StackGen authentication token
• --url: Custom StackGen URL (defaults to configured URL)
• --project: Project ID to upload modules to
• --templates: Comma-separated list of template names to upload (e.g. aws_ec2,aws_s3)
• --repo-url: Repository URL for source tracking
• --branch or --tag: Branch or tag name (use only one)

Behavior

• Minimal input: Only --token is strictly required.
• Batch upload: Uploads all modules under aws/, azurerm/, and gcp/ unless limited by --templates.
• Template filtering: Upload specific templates with --templates.
• Skip existing: Skips modules when the version name already exists.
• Error handling: Continues processing even if individual uploads fail (unless it's a non-skip error).

Other files

• stackgen_yaml_schema.json — JSON Schema for .stackgen/stackgen.yaml (validation and editor support).
• dummy.yaml — Sample / fixture input for development.

Defaults (upload_stackgen_modules.sh)

The upload script commonly defaults to:

• Repository URL: https://github.com/stackgenhq/stackgen-modules
• Branch: main
• StackGen URL: https://main.dev.stackgen.com (override with --url where supported)

Adjust these for forks or other environments as needed.

Versioning and provider compatibility

This repository is a monorepo: Git tags (and branches) refer to a single commit for the entire tree, not per-module versions. Module sources that use Git typically pin a path and a ref, for example:

git::https://github.com/example/stackgen-modules.git//aws/aws_s3?ref=v1.2.3

Where compatibility is defined

Concern	Where it lives
Terraform and provider versions the module expects	Each module’s versions.tf (required_version, required_providers)
Which snapshot of the repo to use	Git tag or branch (ref=)

Tagging convention (semantic versioning)

Use tags of the form vMAJOR.MINOR.PATCH on the repository. Summarize user-facing and breaking changes per tag in CHANGELOG.md when you publish a release (especially provider baseline bumps and incompatible module API changes).

• MAJOR — Breaking changes, including raising the minimum major version of a cloud provider (for example moving AWS from ~> 5.0 to ~> 6.0 in required_providers), or incompatible input/output changes.
• MINOR — New modules, new optional variables, or backward-compatible behavior.
• PATCH — Bug fixes that preserve the module contract.

When the repo moves to a new provider major

If main raises a minimum provider version (for example AWS ~> 5.0 to ~> 6.0), stay on an older Git tag or branch until your root module can match the new required_providers in this repo. Tags apply to the whole monorepo; you pin ref to the snapshot you need. CHANGELOG.md and GitHub/Git release notes should call out provider baseline changes when new tags are cut.

Contributing

We welcome contributions. Please read CONTRIBUTING.md and CODE_OF_CONDUCT.md before opening issues or pull requests.

In short: keep Terraform and .stackgen/stackgen.yaml in sync, validate metadata against stackgen_yaml_schema.json, and use the tools under tools/ where appropriate.

License

This project is licensed under the Apache License 2.0 — see LICENSE.