Massdriver bundles wrap IaC tools like Terraform and Helm (more coming soon).
This guide will cover some of the key components and best practices for integrating your IaC module with the Massdriver UI and provisioning system.
A tl;dr full walkthrough on building an AWS SNS Topic bundle can be found here if you want to jump straight to the code.
For developing infrastructure bundles and applications you'll need the Massdriver CLI.
Where Are My Variable Files?
Let's generate a bundle:
mass bundle new
You'll notice that in your
./src directory there are no Terraform variable files. Massdriver uses JSON Schema to present a rich user interface to end-users and uses that interface to also generate Terraform and Helm variable files.
You can generate your variables by running:
mass bundle build
Building the Right-Sized Bundle
We recommend building single use-case scoped bundles rather than bundles that encapsulate an entire cloud service.
Complex infrastructure modules are confusing to end-users (S3 Buckets have over 90 attributes) and there are many fields in the cloud resource APIs that are incompatible with each other.
We've also seen how bloated general purpose modules can be. EKS modules
- AWS RDS - End-users are looking for a specific database type; there are many fields in RDS configs that only work for MySQL or Postgres.
- AWS S3 - As noted above, S3 has a lot of fields that may not apply to an end-user use case.
- AWS RDS MySQL
- AWS RDS Postgres
- AWS S3 CDN Bucket
- AWS S3 Logging Bucket
- AWS S3 Application Assets Bucket
Smaller scopes mean simpler use cases. This makes it easier for the user to configure and manage, while having simpler IAM policies that follow least privileges for their specific use case.
Massdriver bundles should do one thing and do it well.
Bundle Naming Guidelines
Massdriver recommends (and follows) the following naming convention for bundles:
Massdriver provides metadata to your IaC tool during provisioning. We publish a JSON Schema of the metadata and provide backwards compatibility in the data provided to your bundle.
The metadata will be a top-level value provided to your IaC tool.
For example, in Terraform:
There are various fields that your IaC tool can use to integrate with the Massdriver platform.
MD Metadata Properties:
name_prefix(string): Standardized cloud agnostic naming convention prefix to be used on all resources created by a bundle. The name prefix is the project slug, environment slug, manifest slug, and a random 4 character slug joined by hyphens. This should be the name/identifier of the primary resource in your bundle and used a prefix for other resources created. The name prefix also happens to be the Massdriver package name. Minimum:
default_tags(object): Default tags to be applied to all bundle resources.
managed-by(string): Provisioning tool managing the resource. Must be one of:
md-manifest(string): Massdriver manifest slug. Minimum:
md-package(string): Massdriver package name. Minimum:
md-project(string): Massdriver project slug. Minimum:
md-environment(string): Massdriver environment slug. Minimum:
environment(object): Environment metadata for this deployment.
contact_email(string): The email address of the contact for this environment. This email address may be used by services like Lets Encrypt or to validate AWS SES domains.
observability(object): Observability integration metadata for this deployment.
alarm_webhook_url(string): A webhook URL to process metrics from AWS SNS Notifications, GCP Notification Channels, and Azure Monitor Action Groups. This will be a Massdriver URL used to present alerts from cloud resources.
Example MD Metadata:
WIP : As identifier for primary resources, prefix for all other resource names/identifiers.
Integrated Monitoring & Alarms
WIP : Alarm integrations using TF modules
Params & Connections
WIP : How params and connections are routed to variable files. Using JSON Schema for rich validation.
Recommend Params Field Sets
Coming soon we will be releasing a UI visualizer for
Two files are useful for local development:
If you generated your bundle using
mass bundle new a
.gitignore file should have been created for you excluding all
.tfvars.json files from git.
terraform-provider-massdriver & Artifact Definitions
Local Provider Overrides
WIP - Definining useful presets using JSON Schema examples