Deploy resources

[djgrant]

Context

Notation turns application code into a graph of cloud infrastructure services. These need to be deployed. This RFC explores the concerns around a basic deployment. Issues such as deployment state, drift detection, concurrency etc. are out of scope.

Challenges

1. Choosing the right services to make the deployment e.g. SDK, CDK, an IaC provider
2. Topological sorting of the Notation resource graph defined in Build orchestration graph #5
3. Parallelism
4. Ability to extend to other cloud providers
5. Keeping up-to-date with cloud provider changes
6. Speed to create new Notation modules
7. Avoiding getting lock in to other platforms
8. Ease of adoption for users
9. Propagating resource specification into Notation

Approaches

For now, I'll just consider AWS.

Providers

AWS CDK does not map well to the Notation model. The CDK provides templates that are configured with trees of data, whereas our model is compositional, producing a granular orchestration graph. The CDK model would not necessarily be available for other cloud providers. There are also concerns in the community about CDK implementing cloud formation.

IaC tools such as Terraform/OpenTofu and Pulumi map to Notation's orchestration graph. Terraform uses a DSL so it is not an ideal target, nor is it straight forward to resource types out of Terraform and into TypeScript. There is a more involved piece of work that could lean on Terraform's providers without buying into the platform wholesale. Pulumi does this and brings Terraform's providers into TypeScript. It however requires the user to have a binary installed and locks them into Pulumi's platform. I'd be open to using OpenTofu as a target, but it would require some work. There is a small ecosystem of tools for Terraform which may be useful to be able to interop with.

AWS SDK provides TypeScript modules for each of its service, making it a good candidate building type-safe modules on top of it. It's operations are limited to create/update/delete so this leaves deployment management a large but not impossible problem for Notation to implement.

Graph Traversal

As described in #5, the Notation orchestration graph is an adjacency list that is, by default, in topological order. Iterating down this list and deploying each resource described in sequential order will produce a successful deployment. However, this can be sped up by deploying resources in parallel. This would require the directed acyclic graph to be restructured into a layered graph.

Proposal

Use the AWS SDK to create a light IaC layer for Notation. These IaC modules will be the building blocks for the developer-facing abstraction.

The layers of abstraction will be organised into NPM packages:

@notation/aws – modules that can be used to create a Notation app (one Notation resource = multiple AWS resources)
@notation/aws.iac – modules that represent AWS resources and can be deployed by Notation.
@notation/core – utilities that can be used to create an IaC resource

Levels of Abstraction

To make it easier for the Notation team to work with the IaC modules, some domain knowledge of the underlying platform should be embedded into the IaC resources.

1. Pre-configuring resources for different use-cases

An IAM role resource is not particularly useful. It needs to be configured with policies that require several minutes of google searching to find. A pre-configured lambda IAM role resource is useful.

2. Enforcing Dependencies

An IaC resource should require that any dependent resources are passed explicitly. The whole resource should be passed, as opposed to referencing it by ID. This is because the identifiers used to reference resources is not consistently named in the SDK output. In some cases, dependencies are into ARNs that, again, require several minutes of googling to find e.g. arn:aws:apigateway:eu-west-1:lambda:path/2015-03-31/functions/123456/invocations.

The pre-configured resources mentioned above ensure that resources can require dependencies that are correctly configured.

const lambdaRole = new aws.Lambda.ExecutionRole();

const lambda = new aws.Lambda.Function({ 
  config: { memory: 1024 },
  dependencies: { lambdaRole }
})

The IaC abstractions are designed only to reduce the set of configurations that produce a broken deployment.

Any abstractions over architecture and functional configuration should be handled at the Notation SDK level e.g. in @noation/aws.

[djgrant]

Initial implementation in #8.

[djgrant]

Interesting related reading from the Crossplane team when they were considering how to build providers for their platform: https://github.com/crossplane/crossplane/blob/master/design/design-doc-terrajet.md#why-not-build-on-top-of-existing-effort.

One counterpoint to this is that Notation may not ever wish to support the same breadth of services as IaC tools. Certainly in the beginning, the time needed to integrate Terraform may outweigh the time needed to implement and maintain a handful of services.