{"id":20857412,"url":"https://github.com/unbounce/iidy","last_synced_at":"2025-05-12T07:32:58.969Z","repository":{"id":38104805,"uuid":"99076603","full_name":"unbounce/iidy","owner":"unbounce","description":"iidy (Is it done yet?) -- CloudFormation with Confidence","archived":false,"fork":false,"pushed_at":"2024-06-21T21:20:17.000Z","size":1403,"stargazers_count":52,"open_issues_count":13,"forks_count":7,"subscribers_count":27,"default_branch":"master","last_synced_at":"2024-06-23T12:20:44.860Z","etag":null,"topics":["cli","cloudformation","ops","owner-platform-services","tools"],"latest_commit_sha":null,"homepage":"","language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/unbounce.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":"CODE_OF_CONDUCT.md","threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2017-08-02T05:42:54.000Z","updated_at":"2024-06-21T21:20:20.000Z","dependencies_parsed_at":"2024-06-22T12:18:04.483Z","dependency_job_id":"f2488016-b2cb-42f3-b192-4c0875eda12e","html_url":"https://github.com/unbounce/iidy","commit_stats":null,"previous_names":[],"tags_count":32,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/unbounce%2Fiidy","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/unbounce%2Fiidy/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/unbounce%2Fiidy/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/unbounce%2Fiidy/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/unbounce","download_url":"https://codeload.github.com/unbounce/iidy/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":225130130,"owners_count":17425475,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["cli","cloudformation","ops","owner-platform-services","tools"],"created_at":"2024-11-18T04:38:44.095Z","updated_at":"2024-11-18T04:38:44.732Z","avatar_url":"https://github.com/unbounce.png","language":"TypeScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# iidy (Is it done yet?) -- a CloudFormation CLI tool\n\niidy improves the developer experience with CloudFormation and\nCloudFormation templates.\n\n* It provides immediate, readable feedback about what CloudFormation is doing\n  and any errors it encounters.\n* It is simple to learn, understand, and use. There are fewer moving parts and\n  its commands map directly to CloudFormation's.\n* It has simple, reliable support for AWS profiles.\n* It supports the full range of CloudFormation operations, including\n  _changesets_ without requiring any code beyond what is required to create a\n  stack.\n* It does some template validation, guards against common issues, and will be\n  extended over time to validate our best practices and security policies.\n* It provides seamless integration with AWS Parameter Store.\n* It includes an optional YAML pre-processor which allows CloudFormation\n  templates to be abstracted and simplified in ways not possible with vanilla\n  CloudFormation templates. The pre-processor language supports importing data\n  from a variety of external sources and this allows a better separation of\n  concerns than is possible with stock CloudFormation without resorting to\n  Lambda-backed custom resources. See the [pre-processor documentation\n  below](#yaml-pre-processing) for more details.\n* It has bash command completion support.\n\n## Table of Contents\n\n- [Pronunciation](#pronunciation)\n- [Demo](#demo)\n- [Installation](#installation)\n    - [Binary Install for macOS via Homebrew](#binary-install-for-macos-via-homebrew)\n    - [Binary Installation on Other Platforms](#binary-installation-on-other-platforms)\n    - [Installation from Source](#installation-from-source)\n    - [Docker Image](#docker-image)\n- [Usage](#usage)\n    - [Help](#help)\n    - [The Args File](#the-args-file)\n        - [Required Properties](#required-properties)\n        - [Optional Properties](#optional-properties)\n        - [Example](#example)\n        - [Importing Data](#importing-data)\n        - [Implicit Variables](#implicit-variables)\n        - [Defining Variables](#defining-variables)\n    - [AWS IAM Settings](#aws-iam-settings)\n    - [Environment Variables](#environment-variables)\n- [Examples](#examples)\n- [Development](#development)\n- [License](#license)\n- [Releasing](#releasing)\n- [Converting Existing CloudFormation Stacks to iidy](docs/converting-existing-cloudformation-stacks-to-iidy.md)\n- [Custom Resource Templates](docs/custom-resource-templates.md)\n- [Using Parameter Store](docs/using-parameter-store.md)\n- [Working with Non-CloudFormation YAML](docs/working-with-non-cloudformation-yaml.md)\n- [Working with StackSets](docs/working-with-stacksets.md)\n- [YAML Processing](docs/yaml-preprocessing.md)\n- [Extracting Data From Templates](docs/extracting-data-from-templates.md)\n\n## Pronunciation\n\niidy is pronounced \"eye-dee\", like the audience's response to Cab Calloway in\n[Minnie the Moocher](https://www.youtube.com/watch?v=8mq4UT4VnbE\u0026feature=youtu.be\u0026t=50s).\n\n## Demo\n\n[![asciicast](https://asciinema.org/a/8rzW1WyoDxMdVJpvpYf2mHm8E.png)](https://asciinema.org/a/8rzW1WyoDxMdVJpvpYf2mHm8E)\n\n## Installation\n\niidy is distributed as a self-contained executable (via [pkg](https://github.com/zeit/pkg)).\n\n### Binary Install for macOS via Homebrew\n\nUse Unbounce's custom Homebrew Tap to install iidy. This is the preferred method for macOS.\n\n```shell\nbrew tap unbounce/homebrew-taps\nbrew update\nbrew install iidy\n```\n\n### Binary Installation on Other Platforms\n\n```shell\n# Grab the appropriate binary from the releases page.\nwget https://github.com/unbounce/iidy/releases/download/v1.6.7/iidy-linux-amd64.zip\n# or wget https://github.com/unbounce/iidy/releases/download/v1.6.7/iidy-macos-amd64.zip\nunzip iidy*.zip\nchmod +x iidy\nmv iidy /usr/local/bin/ # or somewhere more appropriate\n```\n\n### Installation from Source\n\nCounter-intuitively, this requires more disk space than the binary\ninstall. You need Node 7+ and npm 4+ installed.\n\n```shell\ngit clone git@github.com:unbounce/iidy.git\ncd iidy\nnpm install \u0026\u0026 npm run build # to compile our source first\nln -s $(pwd)/bin/iidy /usr/local/bin/\n# or npm install -g .\n```\n\n## Usage\n\n### Help\n\n```\n$ iidy help\niidy - CloudFormation with Confidence                    An acronym for \"Is it done yet?\"\n\nCommands:\n  iidy create-stack     \u003cargsfile\u003e                            create a cfn stack based on stack-args.yaml\n  iidy update-stack     \u003cargsfile\u003e                            update a cfn stack based on stack-args.yaml\n  iidy create-or-update \u003cargsfile\u003e                            create or update a cfn stack based on stack-args.yaml\n  iidy estimate-cost    \u003cargsfile\u003e                            estimate aws costs based on stack-args.yaml\n\n  iidy create-changeset           \u003cargsfile\u003e [changesetName]  create a cfn changeset based on stack-args.yaml\n  iidy exec-changeset             \u003cargsfile\u003e \u003cchangesetName\u003e  execute a cfn changeset based on stack-args.yaml\n\n  iidy describe-stack      \u003cstackname\u003e                        describe a stack\n  iidy watch-stack         \u003cstackname\u003e                        watch a stack that is already being created or updated\n  iidy describe-stack-drift \u003cstackname\u003e                       describe stack drift\n  iidy delete-stack        \u003cstackname\u003e                        delete a stack (after confirmation)\n  iidy get-stack-template  \u003cstackname\u003e                        download the template of a live stack\n  iidy get-stack-instances \u003cstackname\u003e                        list the ec2 instances of a live stack\n  iidy list-stacks                                            list all stacks within a region\n\n  iidy param                                                  sub commands for working with AWS SSM Parameter Store\n\n  iidy template-approval                                      sub commands for template approval\n\n  iidy render \u003ctemplate\u003e                                      pre-process and render yaml template\n  iidy get-import \u003cimport\u003e                                    retrieve and print an $import value directly\n  iidy demo   \u003cdemoscript\u003e                                    run a demo script\n  iidy lint-template   \u003cargsfile\u003e                             lint a CloudFormation template\n  iidy convert-stack-to-iidy \u003cstackname\u003e \u003coutputDir\u003e          create an iidy project directory from an existing CFN stack\n  iidy init-stack-args                                        initialize stack-args.yaml and cfn-template.yaml\n\n  iidy completion                                             generate bash completion script. To use: \"source \u003c(iidy completion)\"\n\nAWS Options:\n  --client-request-token  a unique, case-sensitive string of up to 64 ASCII characters used to ensure idempotent retries.         [string] [default: null]\n  --region                AWS region. Can also be set via --environment \u0026 stack-args.yaml:Region.                                 [string] [default: null]\n  --profile               AWS profile. Can also be set via --environment \u0026 stack-args.yaml:Profile. Use --profile=no-profile to override values in\n                          stack-args.yaml and use AWS_* env vars.                                                                 [string] [default: null]\n  --assume-role-arn       AWS role. Can also be set via --environment \u0026 stack-args.yaml:AssumeRoleArn. This is mutually exclusive with --profile. Use\n                          --assume-role-arn=no-role to override values in stack-args.yaml and use AWS_* env vars.                 [string] [default: null]\n\nOptions:\n  --environment, -e  used to load environment based settings: AWS Profile, Region, etc.                                  [string] [default: \"development\"]\n  --debug            log debug information to stderr.                                                                           [boolean] [default: false]\n  --log-full-error   log full error information to stderr.                                                                      [boolean] [default: false]\n  -v, --version      show version information                                                                                                    [boolean]\n  -h, --help         show help                                                                                                                   [boolean]\n\nStatus Codes:\n  Success (0)       Command successfully completed\n  Error (1)         An error was encountered while executing command\n  Cancelled (130)   User responded 'No' to iidy prompt or interrupt (CTRL-C) was received\n```\n\n### The Args File\n\nMetadata for a CloudFormation stack is kept in a file called the \"argsfile\"\n(typically called `stack-args.yaml`). This file is a parameter for commands like\n`iidy create-or-update` or `iidy create-changeset` and is the main source of\ndata for creating or updating a CloudFormation stack.\n\n#### Required Properties\n\n| Property | Description | Example |\n|----------|-------------|---------|\n| StackName | CloudFormation stack name | `my-stack` |\n| Template | Local, `https` or `s3` location of CloudFormation template | `cfn-template.yaml` |\n\n#### Optional Properties\n\n| Property | Description | Example |\n|----------|-------------|---------|\n| Region | AWS Region to use, overridden by `--region` and `AWS_REGION` | `us-east-1` |\n| Profile | [AWS profile](https://docs.aws.amazon.com/cli/latest/userguide/cli-configure-profiles.html) to use, overridden by `--profile` and `AWS_PROFILE` |\n| AssumeRoleARN | IAM Role ARN to assume | `arn:aws:iam::1234567890:role/my-role` |\n| ServiceRoleARN | [CloudFormation Service Role](https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/using-iam-servicerole.html) to use |\n| Tags | Tags to assign to CloudFormation stack | `{ service: my-app }` |\n| Parameters | [CloudFormation stack parameters](https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/parameters-section-structure.html) to use |\n| Capabilities | List of [CloudFormation capabilities to use](https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/using-iam-template.html#using-iam-capabilities) | `CAPABILITY_NAMED_IAM` |\n| NotificationARNs | List of [SNS Topic ARNs to send CloudFormation notifications to] | `arn:aws:sns:us-east-1:123467890:my-topic` |\n| TimeoutInMinutes | Number of minutes to provide as [timeout to the CloudFormation service](https://docs.aws.amazon.com/AWSCloudFormation/latest/APIReference/API_CreateStack.html) | `10` |\n| OnFailure | options: `ROLLBACK`, `DELETE`, `DO_NOTHING`, default `ROLLBACK` | `DELETE`\n| DisableRollback | [boolean defaulting to false](https://docs.aws.amazon.com/AWSCloudFormation/latest/APIReference/API_CreateStack.html)\n| EnableTerminationProtection | [boolean defaulting to false](https://docs.aws.amazon.com/AWSCloudFormation/latest/APIReference/API_CreateStack.html)\n| StackPolicy | Location, `https`, or `s3` location of CloudFormation policy document | `policy.json` |\n| ResourceTypes | List of [allowed resource types to create in CloudFormation stack](https://docs.aws.amazon.com/AWSCloudFormation/latest/APIReference/API_CreateStack.html) | `['AWS::EC2::*']` |\n| CommandsBefore | List of commands to run before `create-` and `update-stack` commands | `['make build']` |\n| UsePreviousTemplate | for updates, [boolean defaulting to false](https://docs.aws.amazon.com/AWSCloudFormation/latest/APIReference/API_UpdateStack.html)\n| UsePreviousParameterValues | list of parameter names for updates, [equivalent to UsePreviousValue](https://docs.aws.amazon.com/AWSCloudFormation/latest/APIReference/API_Parameter.html)\n\n#### Example\n\n```yaml\nStackName: my-stack\n\nTemplate: cfn-template.yaml\n\nTags:\n  project: iidy-docs\n\nParameters:\n  Param1: value1\n  Param2: value2\n\nCapabilities:\n  - CAPABILITY_IAM\n  - CAPABILITY_NAMED_IAM\n\nTimeoutInMinutes: 10\n\nOnFailure: DELETE\n\nStackPolicy: policy.json\n\nCommandsBefore:\n  # a list of shell commands to run prior the cfn stack operation\n  # /bin/bash is used if found.\n  # handlebars templates in the command strings are preprocessed prior to execution.\n\n  # E.g.\n  - make build\n```\n\n#### Importing Data\n\nData can be imported into the stack args file using the `$imports:` block.\n\n| Import Type | Description | Example |\n|-------------|-------------|---------|\n| `file` | Load a local file, JSON and YAML files will be parsed into a data structure | `vars.yaml` |\n| `filehash` | Compute a SHA 256 hash of a file's contents | `filehash:path`, `filehash:?filepath` (`?` prefix allows file to be empty)\n| `filehash-base64` | Compute a SHA 256 hash of a file's contents, returns Base64 encoded hash | `filehash-base64:path`, `filehash-base64:?filepath` (`?` prefix allows file to be empty)\n| `s3` | Fetch an object from S3, JSON and YAML files will be parsed into a data structure | `s3://bucket-name/path/to/file` |\n| `cfn:export` | Fetch a [CloudFormation Export](https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/using-cfn-stack-exports.html) | `cfn:export:export-name`, `cfn:export:export-name?region=us-east-1` |\n| `cfn:output` | Fetch the [Output of a CloudFormation stack](https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/outputs-section-structure.html) | `cfn:export:stack-name`, `cfn:export:stack-name?region=us-east-1` |\n| `cfn:parameter` | Fetch the value of a parameter of a CloudFormation stack | `cfn:parameter:stack-name/parameter-name`, `cfn:parameter:stack-name/parameter-name?region=us-east-1` |\n| `cfn:tag` | Fetch the value of a tag of a CloudFormation stack | `cfn:tag:stack-name/tag-name`, `cfn:tag:stack-name/tag-name?region=us-east-1` |\n| `cfn:resource` | Fetch a resource of a CloudFormation stack | `cfn:resource:stack-name/resource-name`, `cfn:resource:stack-name/resource-name?region=us-east-1` |\n| `cfn:stack` | Fetch all data of a CloudFormation stack | `cfn:stack:stack-name`, `cfn:stack:stack-name?region=us-east-1` |\n| `http` | Fetch a file over HTTP. JSON and YAML files will be parsed into a data structure | `https://example.com/vars.yaml` |\n| `env` | Fetch value from environment variable | `env:VERSION`, `env:VERSION:default-value` |\n| `git:branch` | Get current git branch name (via `git rev-parse --abbrev-ref HEAD`) | `git:branch` |\n| `git:describe` | Get current git description (via `git describe --dirty --tags`) | `git:describe` |\n| `git:sha` | Get current git sha name (via `git rev-parse HEAD`) | `git:sha` |\n| `random:dashed-name` | Generate a random dashed name, for example: `'uptight-guitar'` | `random:dashed-name` |\n| `random:name` | Generate a random dashed name, for example: `'uptightguitar'` | `random:name` |\n| `random:int` | Generate a random integer, between 1 and 1000 | `random:int` |\n| `ssm` | Fetch a SSM Parameter Store value | `ssm:/path/to/param` |\n| `ssm-path` | Fetch all SSM Parameter Store values at a given path | `ssm-path:/path/to/params` |\n\niidy imports can be accessed using the `!$` YAML tag or using Handlebars\ntemplating. `!$` will insert the data assigned to that variable. Handlebars\ntemplated strings can be used to interpolate values into a string.\n\niidy parses `.yaml` or `.json` imports and makes them available as a map. It\nuses either the file extension or the mime-type of remote files to detect these\nfile types.\n\n```yaml\n$imports:\n  params: ssm-path:/my-services/config\n\nParameters:\n  Timeout: $! params.Timeout\n\nTags:\n  StackName: 'my-service'\n```\n\n#### Implicit Variables\n\nSome data is automatically set by iidy.\n\n| Variable | Description |\n|----------|-------------|\n| `iidy.region` | The current AWS region in use |\n| `iidy.environment` | Value of the `--environment` flag |\n\n```yaml\nStackName: 'my-service-{{ iidy.environment }}'\n```\n\n#### Defining Variables\n\nLocal variables with file can be specified using the `$defs` block.\n\n```yaml\n$defs:\n  serviceName: my-service\n\nStackName: '{{ serviceName }}-{{ iidy.environment }}'\n```\n\n### AWS IAM Settings\n\niidy supports loading AWS IAM credentials/profiles from a) the cli\noptions shown above, b) `Region` and `Profile` or `AssumeRoleArn`\nsettings in `stack-args.yaml`, or c) the standard AWS environment\nvariables. You will also need the correct level of IAM permissions for\niidy to perform CloudFormation API calls. This information can be provided in a\nnumber of different ways (ordered from highest to lowest precedence):\n\n- CLI options (see above)\n- `AWS_REGION` and `AWS_PROFILE` environment variables\n- standard [AWS environment variables](https://docs.aws.amazon.com/cli/latest/userguide/cli-configure-envvars.html)\n- `Region` and `Profile` or `AssumeRoleArn` in args file\n\nThese credentials are used to interact with the CloudFormation API and to\nperform and AWS-related imports.\n\nIf your profile requires an MFA token, iidy will prompt for it.\n\n```\n? MFA token for arn:aws:iam::001234567890:mfa/example.user: ____\n```\n\nIf you've assumed a profile prior to running iidy and want to it to ignore\nwhat's specified as `Profile` in `stack-args.yaml` and instead use `AWS_*`\nenvironment variables, set the CLI option `--profile no-profile`.\n\n### Environment Variables\n\nAny parameter used by iidy can be set using `IIDY_{{argname}}`. An example of\nthis would be changing the default environment from development to production.\n\n```shell\nexport IIDY_ENVIRONMENT=production\n```\n\n## Examples\n\nSee the [`examples/`](examples/) directory.\n\n## Development\n\niidy is coded in Typescript and compiles to ES2015 JavaScript using commonjs\nmodules (what Node uses). See the `Makefile` and the script commands in\n`package.json` for details about the build process.\n\nPlease format all files with `tsfmt` and remove extra whitespace before\nsubmitting a PR.\n\n### Releasing\n\n- Run `npm version minor|patch`\n- Run `git push --tags`\n- Run `make prepare_release`to generate the release artifacts for upload\n- Create a [GitHub release](https://github.com/unbounce/iidy/releases) following the template of previous releases\n- Update the [homebrew formula](https://github.com/unbounce/homebrew-taps/blob/master/iidy.rb) (double check the sha)\n\n## Global Configuration\n\nSome iidy features can be configured globally via [SSM Parameter\nStore](https://docs.aws.amazon.com/systems-manager/latest/userguide/systems-manager-parameter-store.html)\nconfigurations.\n\n| Parameter | Value |Description |\n|-----------|-------|------------|\n| `/iidy/default-notification-arn` | An ARN, eg. `\"arn:aws:sns:us-east-1:0123456789:mytopic\"` | Provides a value for `NotificationARNs` if it is not set |\n| `/iidy/disable-template-approval` | Must be the string `\"true\"` | Unsets `ApprovedTemplateLocation` to disable the template approval process |\n\n**Note** that SSM Parameter Store values are isolated to the AWS Account and Region they are set in.\n\n## License\n\nMIT.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Funbounce%2Fiidy","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Funbounce%2Fiidy","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Funbounce%2Fiidy/lists"}