Skip to content

update-mdyaml-resources-dependencies #218

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
chrisghill wants to merge 1 commit into
base: main
Choose a base branch
from
Open

update-mdyaml-resources-dependencies #218

Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
290 changes: 146 additions & 144 deletions docs/bundle-development/01-bundle-yaml-spec.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -95,13 +95,16 @@ steps:

# config (optional)
# Provisioner-specific configuration.
# Values can be static or JQ expressions referencing params/connections.
# Values can be static or JQ expressions referencing params/dependencies.
#
# JQ expressions start with "." and can reference:
# - .params.<field> - Bundle parameters
# - .connections.<name> - Connection resources
# - .connections.<name> - Dependency resources
# - .connections.<name>.data.<path> - Resource data
# - .connections.<name>.specs.<path> - Resource specs
#
# Note: dependencies are exposed at runtime under the legacy
# `connections` name, so JQ paths use .connections.<name>.
config:
# OpenTofu/Terraform config options:
# json: boolean - Enable JSON output (default: false)
Expand Down Expand Up @@ -265,7 +268,9 @@ params:
default: "15"

# dependencies (optional)
# Conditional logic: show fields based on other field values
# Conditional logic: show fields based on other field values.
# This is the JSON Schema `dependencies` keyword scoped to params —
# not the bundle's top-level `dependencies` block below.
dependencies:
high_availability:
oneOf:
Expand All @@ -284,107 +289,80 @@ params:
const: false

# =============================================================================
# CONNECTIONS (Input Resources)
# DEPENDENCIES (Input Resources)
# =============================================================================

# connections (required)
# JSON Schema defining resources this bundle consumes from other bundles.
# Connections enable type-safe infrastructure composition.
# dependencies (optional)
# Declares the resources this bundle consumes from other bundles.
# Dependencies enable type-safe infrastructure composition.
# Most bundles declare at least a cloud credential dependency.
#
# Each connection must reference a resource type using $ref.
connections:
# required (optional)
# List of connections that must be provided.
required:
- vpc
- credentials

# properties (required)
# Connection definitions.
properties:
# VPC connection - required network infrastructure
vpc:
# $ref (required for connections)
# Reference to a resource type.
#
# Formats:
# - resource-type-name - Resource type from your organization
# - other-org/resource-type-name - Resource type from another organization
$ref: aws-vpc
title: VPC
description: The VPC where the database will be deployed

# Cloud credentials connection
credentials:
$ref: aws-iam-role
title: AWS Credentials
description: IAM role for provisioning resources

# Optional connection (not in required list)
monitoring:
$ref: datadog-agent
title: Monitoring
description: Optional Datadog agent for metrics

# Constrained connection - only accepts resources matching additional criteria
# You can add `properties` alongside `$ref` to validate resource fields
# before allowing the connection.
database:
$ref: postgresql
title: PostgreSQL Database
description: Database connection (requires PostgreSQL 16)
# Only allow PostgreSQL 16 resources to connect
properties:
version:
const: "16"

# Another example: constrain by region using enum
# regional_cache:
# $ref: redis-cluster
# properties:
# region:
# enum: ["us-east-1", "us-west-2"]
# Each entry maps a dependency name to a resource type reference.
# Replaces the deprecated `connections` block (see Legacy Format below).
#
# Note: at deployment time, dependencies are still exposed to provisioners
# and JQ expressions under the legacy `connections` name
# (e.g. .connections.vpc.data.infrastructure.arn).
dependencies:
# VPC dependency - required network infrastructure
vpc:
# resource_type (required)
# The resource type this dependency accepts, with an optional
# version constraint after "@".
#
# Formats:
# - resource-type-name - Resource type from your organization
# - resource-type-name@1.2.3 - Exact version
# - resource-type-name@~1 - Any 1.x.x release
# - resource-type-name@~1.2 - Any 1.2.x release
# - resource-type-name@latest - Latest release
# - other-org/resource-type-name@~1 - Resource type from another organization
resource_type: aws-vpc@~1

# required (required)
# Whether this dependency must be connected before the bundle
# can be deployed.
required: true

# Cloud credentials dependency
credentials:
resource_type: aws-iam-role@~1
required: true

# Optional dependency (required: false)
monitoring:
resource_type: datadog-agent@~2
required: false

# =============================================================================
# RESOURCES (Outputs)
#
# The YAML key remains `artifacts:` for backwards compatibility, but
# semantically this block declares the resources the bundle produces.
# =============================================================================

# artifacts (required)
# JSON Schema defining resources this bundle produces. The key name
# `artifacts` is preserved from the original bundle spec.
# These outputs can be consumed as connections by other bundles.
#
# Each entry must reference a resource type using $ref.
artifacts:
# required (optional)
# List of resources that will always be produced.
required:
- database

# properties (required)
# Resource declarations.
properties:
database:
# $ref (required)
# Reference to the resource type schema.
$ref: postgresql-authentication
title: PostgreSQL Database
description: Connection details for the provisioned database

# Additional resource example
read_replica:
$ref: postgresql-authentication
title: Read Replica
description: Connection details for read replica (if enabled)
# resources (optional)
# Declares the resources this bundle produces. These outputs can be
# consumed as dependencies by other bundles.
# Replaces the deprecated `artifacts` block (see Legacy Format below).
resources:
database:
# resource_type (required)
# The resource type and version this bundle produces, in the form
# name@version (e.g. postgresql-authentication@1.0.0).
resource_type: postgresql-authentication@1.0.0

# required (required)
# Whether this resource is always created by the bundle.
required: true

# Conditionally-created resource (required: false)
read_replica:
resource_type: postgresql-authentication@1.0.0
required: false

# =============================================================================
# UI SCHEMA
# =============================================================================

# ui (optional)
# ui (required, may be empty: `ui: {}`)
# Controls how the configuration form renders in the Massdriver UI.
# Follows React JSON Schema Form (RJSF) UI Schema specification.
# See: https://react-jsonschema-form.readthedocs.io/en/docs/api-reference/uiSchema/
Expand Down Expand Up @@ -429,18 +407,19 @@ ui:
#
# The app block is processed by the terraform-massdriver-application module,
# which parses your massdriver.yaml and provides outputs for secrets,
# environment variables, connections, and policies.
# environment variables, dependencies, and policies.
#
# Module: https://github.com/massdriver-cloud/terraform-massdriver-application
# Registry: https://registry.terraform.io/modules/massdriver-cloud/application/massdriver
app:
# envs (optional)
# Map environment variable names to JQ expressions.
# Expressions can reference params and connections.
# Expressions can reference params and dependencies (dependencies are
# exposed at runtime under the legacy `connections` name).
#
# Variable names must match: ^[a-zA-Z_][a-zA-Z0-9_]*$
envs:
# Extract values from connections
# Extract values from dependencies
DATABASE_HOST: .connections.database.data.authentication.hostname
DATABASE_PORT: .connections.database.data.authentication.port | tostring
DATABASE_NAME: .connections.database.data.authentication.database
Expand Down Expand Up @@ -509,19 +488,17 @@ params:
title: Bucket Name
pattern: "^[a-z0-9][a-z0-9-]{1,61}[a-z0-9]$"

connections:
required:
- aws_credentials
properties:
aws_credentials:
$ref: aws-iam-role
dependencies:
aws_credentials:
resource_type: aws-iam-role@~1
required: true

artifacts:
required:
- bucket
properties:
bucket:
$ref: aws-s3-bucket
resources:
bucket:
resource_type: aws-s3-bucket@1.0.0
required: true

ui: {}
```

## Infrastructure Bundle Example
Expand Down Expand Up @@ -580,25 +557,18 @@ params:
title: Multi-AZ
default: false

connections:
required:
- vpc
- aws_authentication
properties:
vpc:
$ref: aws-vpc
title: VPC
aws_authentication:
$ref: aws-iam-role
title: AWS Credentials
dependencies:
vpc:
resource_type: aws-vpc@~1
required: true
aws_authentication:
resource_type: aws-iam-role@~1
required: true

artifacts:
required:
- database
properties:
database:
$ref: postgresql-authentication
title: PostgreSQL Database
resources:
database:
resource_type: postgresql-authentication@1.0.0
required: true

ui:
ui:order:
Expand Down Expand Up @@ -662,23 +632,18 @@ params:
title: Container Port
default: 8080

connections:
required:
- kubernetes_cluster
- database
properties:
kubernetes_cluster:
$ref: kubernetes-cluster
title: Kubernetes Cluster
database:
$ref: postgresql-authentication
title: PostgreSQL Database
dependencies:
kubernetes_cluster:
resource_type: kubernetes-cluster@~1
required: true
database:
resource_type: postgresql-authentication@~1
required: true

artifacts:
properties:
service:
$ref: kubernetes-service
title: Kubernetes Service
resources:
service:
resource_type: kubernetes-service@1.0.0
required: false

app:
envs:
Expand All @@ -704,6 +669,34 @@ ui:
- "*"
```

## Legacy Format: `connections` and `artifacts`

Older bundles declare inputs and outputs as JSON Schema blocks named `connections` and `artifacts`:

```yaml
connections:
required:
- vpc
properties:
vpc:
$ref: aws-vpc

artifacts:
required:
- database
properties:
database:
$ref: postgresql-authentication
```

This format is **deprecated**:

- The CLI prints a deprecation warning when it encounters `connections` or `artifacts` and will ask you to migrate to `dependencies` and `resources`.
- The legacy format does not support versioned resource types (`name@version`).
- A bundle cannot mix formats: setting both `connections` and `dependencies`, or both `artifacts` and `resources`, is an error.

To migrate, convert each `properties` entry into a named entry with `resource_type` (adding a version constraint), and convert the `required` list into per-entry `required: true`/`required: false` flags.

## Field Reference

### Required Fields
Expand All @@ -713,8 +706,7 @@ ui:
| `name` | `string` | Bundle identifier (3-53 chars, lowercase with hyphens) |
| `description` | `string` | Human-readable description (10-1024 chars) |
| `params` | `object` | JSON Schema for user parameters |
| `connections` | `object` | JSON Schema for input resources |
| `artifacts` | `object` | JSON Schema for output resources (YAML key kept for backwards compatibility) |
| `ui` | `object` | RJSF UI schema for form customization (may be empty: `ui: {}`) |

### Optional Fields

Expand All @@ -723,9 +715,19 @@ ui:
| `version` | `string` | `0.0.0` | Semantic version (MAJOR.MINOR.PATCH) |
| `source_url` | `string` | - | Link to source repository |
| `steps` | `array` | Single terraform step | Provisioning steps |
| `ui` | `object` | - | RJSF UI schema for form customization |
| `dependencies` | `object` | - | Resources this bundle depends on (replaces deprecated `connections`) |
| `resources` | `object` | - | Resources this bundle produces (replaces deprecated `artifacts`) |
| `app` | `object` | - | Application configuration (envs, secrets, policies) |

### Dependency and Resource Fields

Each entry in `dependencies` and `resources` is a named object with:

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `resource_type` | `string` | Yes | Resource type reference: `name`, `name@version`, or `org/name@version`. Dependencies accept version constraints (`@1.2.3`, `@~1`, `@~1.2`, `@latest`); resources pin the version they produce. |
| `required` | `boolean` | Yes | For dependencies: must be connected before deploying. For resources: always created by the bundle. |

### Step Fields

| Field | Type | Required | Description |
Expand All @@ -747,5 +749,5 @@ ui:
- [Bundles Concept](/concepts/bundles) - Understanding bundles
- [Provisioners Overview](/bundle-development/provisioners/overview) - Available provisioners
- [Massdriver Annotations](/bundle-development/schema-design/massdriver-annotations) - `$md.*` extensions
- [Resource Types](/concepts/resources-and-types) - Connection contracts
- [Resource Types](/concepts/resources-and-types) - Dependency contracts
- [Bundle Meta Schema](https://api.massdriver.cloud/json-schemas/bundle.json) - Validation schema