/gh-pages/README.md.dhall.html

<!DOCTYPE HTML><html><head><title>/README.md.dhall</title><link rel="stylesheet" type="text/css" href="index.css"><link rel="stylesheet" type="text/css" href="https://fonts.googleapis.com/css2?family=Fira+Code:wght@400;500;600;700&family=Lato:ital,wght@0,400;0,700;1,400&display=swap"><script type="text/javascript" src="index.js"></script><meta charset="UTF-8"></head><body><div class="nav-bar"><img class="dhall-icon" src="dhall-icon.svg">dhall-aws-cloudformation<div class="nav-bar-content-divider"></div><a id="switch-light-dark-mode" class="nav-option">Switch Light/Dark Mode</a></div><div class="main-container"><h2 class="doc-title">/<a href="index.html">dhall-aws-cloudformation</a>/README.md.dhall</h2><a class="copy-to-clipboard" data-path="https://raw.githubusercontent.com/jcouyang/dhall-aws-cloudformation/0.9.81/README.md.dhall">Copy path to clipboard</a> <div class="doc-contents"></div><h3>Source</h3><div class="source-code"><pre>let version = <a href="./version.dhall.html">./version.dhall</a> let config = <a href="./config.dhall.html">./config.dhall</a> let fold = <a href="https://github.com/dhall-lang/dhall-lang/raw/v20.0.0/Prelude/List/fold.dhall" target="_blank">https://github.com/dhall-lang/dhall-lang/raw/v20.0.0/Prelude/List/fold.dhall</a> let exampleText = <a href="./examples/readme.gen.dhall.html">./examples/readme.gen.dhall as Text</a> let exampleResult = <a href="./examples/readme.gen.json.html">./examples/readme.gen.json as Text</a> in '' # Dhall AWS CloudFormation `dhall-aws-cloudformation` contains [Dhall](https://github.com/dhall-lang/dhall-lang) bindings to AWS CloudFormation, so you can generate CloudFormation template from Dhall expressions. This will let you easily typecheck, template and modularize your CloudFormation definitions. ## :mag: [References](https://gh.1punch.dev/dhall-aws-cloudformation/package.dhall.html) ## :bulb: [Examples](https://gh.1punch.dev/dhall-aws-cloudformation/examples/index.html) ## :book: Usage ### Use resource schema AWS Cloudformation has massive amount of specifications, to load all dhall remotely will be very slow and impractical. One simply way to make import faster is by only importing just each resource you need #### Remote import resource ```dhall ${<a href="#var8-5" class="name-use" data-name="var8-5">exampleText</a>} ``` to convert to CloudFormation JSON file just ``` dhall-to-json < ./template.dhall > ./template.json ``` which generates ```json ${<a href="#var10-5" class="name-use" data-name="var10-5">exampleResult</a>} ``` Other way around is build the binary of subset of the resources using nix #### Build and load package.dhall binary to local cache Have something like `./examples/example0.nix`, and the dhall file you want to compile `./examples/example0.dhall` ```nix ${<a href="./examples/example0.dhall.html">./examples/example0.dhall as Text</a>} ``` Add all the resources you need to `cf-preset`, run nix-build, if the subset is not too large it will be very quick, and you will see something like: ``` ⚠ ─ If error occured, you may need to update the sha256 in your dhall file e.g. │ let aws = missing sha256:a04e4db67b092e40987639cca5cd845f452b3984ee7ec77172f815a31e830325 ``` Actually the first time it will fail since you can't guess the correct sha of the subset binary, now if you update example0.dhall with the correct sha, it should then be able to compile to `./result/example0.yaml` ```dhall let aws = missing sha256:a04e4db67b092e40987639cca5cd845f452b3984ee7ec77172f815a31e830325 let Function = aws.Cloudformation.`AWS::Lambda::Function` ``` ### Intrinsic Function The following intrinsic functions are implemented, you can find examples of using intrinsic function in [Fn.dhall document](https://oyanglul.us/dhall-aws-cloudformation/Fn.dhall.html) - [x] Fn::Base64 - [x] Fn::Cidr - [x] Condition functions - [x] Fn::FindInMap - [x] Fn::GetAtt - [x] Fn::GetAZs - [x] Fn::ImportValue - [x] Fn::Join - [x] Fn::Select - [x] Fn::Split - [x] Fn::Sub - [x] Fn::Transform - [x] Ref ### Type Safe `Fn::GetAttr` Instead of manually looking for AWS documents to make sure the resource has what attributes, we can just use `<Resource>.GetAttr.<attribute name>`: ```dhall render (Role.GetAttr.Arn "HelloWorldFunctionRole") ``` So the compiler can just help you find the correct attributes available. ### Sam Policy Templates Cloudformation's Policy document is loosy type as just JSON, it is hard to get the policy right and too many boilerplates to create a Dhall JSON data thanks to [AWS SAM](https://docs.aws.amazon.com/serverless-application-model/latest/developerguide/serverless-policy-templates.html) there are some common policy documents we can laverage these templates are translated into Dhall functions, so you don't need to use SAM to be able to use these policy documents. ```dhall let Policy = https://github.com/jcouyang/dhall-aws-cloudformation/raw/${<a href="#var1-5" class="name-use" data-name="var1-5">version</a>}/cloudformation/AWS::IAM::Role/Policy.dhall let Sam/Policy = https://github.com/jcouyang/dhall-aws-cloudformation/raw/${<a href="#var1-5" class="name-use" data-name="var1-5">version</a>}/sam/policy-template/package.dhall ... Policies = Some [Policy::{ , PolicyDocument = Sam/Policy.DynamoDBReadPolicy (Fn.String "DBName") , PolicyName = s "dynamo read only" }] ... ``` will generates ```json { "Policies": [ { "PolicyDocument": { "Statement": [ { "Action": [ "dynamodb:GetItem", "dynamodb:Scan", "dynamodb:Query", "dynamodb:BatchGetItem", "dynamodb:DescribeTable" ], "Effect": "Allow", "Resource": [ { "Fn::Sub": [ "arn:''${AWS::Partition}:dynamodb:''${AWS::Region}:''${AWS::AccountId}:table/''${tableName}", { "tableName": "DBName" } ] }, { "Fn::Sub": [ "arn:''${AWS::Partition}:dynamodb:''${AWS::Region}:''${AWS::AccountId}:table/''${tableName}/index/*", { "tableName": "DBName" } ] } ] } ] }, "PolicyName": "dynamo read only" } ] } ``` ## :coffee: Contribute ### Build and Test ``` > nix-shell $ cabal build $ cabal test ``` ### Generate Type Definitions e definitions are generated from config file `./config.dhall` which contains specifications used by [AWS CDK](https://github.com/aws/aws-cdk/blob/master/packages/%40aws-cdk/cfnspec/build-tools/update.sh) as well: ${<a href="#var5-5" class="name-use" data-name="var5-5">fold</a> { mapKey : Text, mapValue : Text } <a href="#var3-5" class="name-use" data-name="var3-5">config</a>.specifications Text ( λ(x : { mapKey : Text, mapValue : Text }) → λ(y : Text) → '' - [${<a href="#var167-9" class="name-use" data-name="var167-9">x</a>.<a href="#var167-15" class="name-use" data-name="var167-15">mapKey</a>}](${<a href="#var167-9" class="name-use" data-name="var167-9">x</a>.<a href="#var167-30" class="name-use" data-name="var167-30">mapValue</a>}) ${<a href="#var168-9" class="name-use" data-name="var168-9">y</a>}'' ) ""} regenerate types definition files, simply run ``` $ cabal run ``` if you just want to regenerate dhall files without setting up haskell dev environment, just ```sh docker run --rm -v $(pwd):/data -w /data ghcr.io/jcouyang/dhall-aws-cloudformation ``` ## :warning: Known Issue The following CloudFormation definitions will raise assertion error due to invalid type definition such as empty type or cyclic import ${<a href="#var5-5" class="name-use" data-name="var5-5">fold</a> Text <a href="#var3-5" class="name-use" data-name="var3-5">config</a>.excludes Text ( λ(x : Text) → λ(y : Text) → '' - `${<a href="#var188-9" class="name-use" data-name="var188-9">x</a>}` ${<a href="#var189-9" class="name-use" data-name="var189-9">y</a>}'' ) ""} '' </pre></div></div></body></html>

/dhall-aws-cloudformation/gh-pages/README.md.dhall.html

Source