Module Contracts

Each Nullstone module has a contract that describes the module and where it can be used or connected. The contract is the combination of three properties on the module.

1. Category - describes what kind of infrastructure is provisioned
2. Cloud Provider(s) - describes which cloud provider(s) the module targets
3. Platform - describes which technology, framework, or implementation

One example might be:

datastore/aws/postgres:rds

This is the contract name for an RDS Postgres datastore specific to AWS. Because it has a Category of datastore, Nullstone will list this module as an option when creating a Datastore in the UI. Since it has a Cloud Provider of AWS, Nullstone will list this module if your Nullstone stack is connected to AWS.

Connections

The contract allows us to define which modules are allowed to connect to one another. Developers connect these modules through the use of a ns_connection data source with a contract attribute.

In the following example, the module defines a connection to any postgres datastore configured on aws. The outputs of the postgres module are extracted into local variables that the module can use to configure connectivity.

data "ns_connection" "postgres" {
  name     = "postgres"
  contract = "datastore/aws/postgres:*"
}

locals {
  db_endpoint          = data.ns_connection.postgres.outputs.db_endpoint
  db_security_group_id = data.ns_connection.postgres.outputs.db_security_group_id
}

Application Contracts

Application Contracts are specific contracts defined by Nullstone to manage the full lifecycle of an application. Any infrastructure that is created from a module with these contracts will automatically be treated as an application.

To learn more about Application contracts, check out Applications category.

To dive deeper, check out existing Application contracts:

• app/aws/ecs
• app/aws/lambda:zip
• app/aws/lambda:container
• app/aws/s3
• app/aws/ec2

Matching

In some cases, it is useful for module creators to make a connection to any class of modules. To do this, we use the wildcard symbol * in each contract component to match any module.

In the Connections section, we matched any postgres running on aws. This is because the module can use postgres hosted any way running on AWS: using RDS, using Aurora, self-hosted, or a third-party provider. If you want to match a specific subplatform, it's possible to do this explicitly:

data "ns_connection" "postgres" {
  name     = "postgres"
  contract = "datastore/aws/postgres:rds"
}

While it is most common to wildcard match any subplatform, it is also valuable to wildcard match other contract components. Nullstone offers the ability to wildcard match each of the contract components independently. Here are some examples to illustrate different patterns.

Contract	Category	Cloud Provider	Platform
datastore/aws/postgres	datastore	aws	postgres (any subplatform)
datastore/aws/postgres:*	datastore	aws	postgres (any subplatform)
datastore/aws/postgres:rds	datastore	aws	postgres (only rds)
datastore/*/postgres	datastore	any	postgres (any subplatform)
datastore/*/postgres	datastore	any	any
*/aws/*	any	aws	any