Background

Definitions

Concepts and definitions that appear in this documentation for CloudFormation and cfgen.

CloudFormation Concepts

• AWS CloudFormation is an AWS service used to manage the lifecycle of resources
• A CloudFormation Template is a JSON or YAML file defining the parameters, reosurces and outputs used to generate a CloudFormation Stack
• A CloudFormation Stack is the deployed (or instantiated) form of a template that is created in a particular AWS Account and Region. Multiple stacks can be created from the same template.
• Resources are instantiations of AWS service objects, defined in a template and created or destroyed by a stack through stack creation and updates.
• Deploying a CloudFormation template creates a stack. Updating or deleting the stack by either changing the values of its parameters or its template may cause resources to be added, updated or deleted.
• Parameters are values that can be used to customise a stack's deployment, defined in the template
• Outputs are values specified by a template that are made available to parent templates and via the CloudFormation Console and API. The may be optionalled exported into a global namespace for consumption by other stacks as inputs.
• Resource Properties define how a resource is configured. These values may be static or derived from other resource attributes or intrinsic functions
• Resource Attributes are outputs from the creation of a resource made available in a stack as inputs to the properties of other resources or for output values. Referencing attributes of resources in properties creates an implicit dependency order between those resources.
• Intrinsic Functions are used in CloudFormation stacks to retrieve resource attributes (such as Ref or Fn::GetAtt), manipulate strings, test conditions (such as Fn::If) or retrieve the exported values of other stacks (Fn::ImportValue). They are executed at deployment time.

cfgen Concepts

Templates

Cfgen.Template.t Template types represent a CloudFormation template under assembly.

Use the API functions in Cfgen.Template to add resources, parameters or outputs.

Constructs

Constructs are a higher level abstraction than CloudFormation resources. Borrowing from CDK terminology, we can define constructs through different levels of abstraction:

* L1 constructs are the generated CloudFormation resource types in Cfgen.BaseConstructs * L2 constructs are higher-level than L1 resources, usually centered on a primary resource type (like Lambda functions or API Gateway instances), but with helper functions to generate the "glue" resources that surround them (like IAM roles, Lambda Event Source Mappings, Event Bridge rules, etc). An L2 construct will typically generate more than one underlying CloudFormation resource * L3 constructs implement patterns designed to implement common tasks. They will combine multiple L2 and L1 constructs to achieve a common goal, like deploying a Lambda function to respond to an EventBridge Rule with the correct level of failure handling (like DLQs) and monitoring (like CloudWatch alarms). They typically cross service boundaries for this reason.

cfgen only provides L1 constructs at this time. You can achieve L2 and L3 constructs through standard composition and abstraction mechanisms in OCaml, e.g. functions and modules, but cfgen does not provide any special support for working with them (yet).

Tokens

Tokens are special strings or numbers that are substituted with CloudFormation intrinsic functions at template serialisation. They permit access to dynamic values, such as resource attributes, account or region variables, or imported values from other stack exports, when constructing resource properties or template outputs.