{"id":13682616,"url":"https://github.com/realestate-com-au/stackup","last_synced_at":"2025-05-15T18:05:16.241Z","repository":{"id":37677660,"uuid":"42434589","full_name":"realestate-com-au/stackup","owner":"realestate-com-au","description":"a simple CLI and Ruby API for AWS CloudFormation","archived":false,"fork":false,"pushed_at":"2025-02-27T07:07:39.000Z","size":411,"stargazers_count":98,"open_issues_count":11,"forks_count":33,"subscribers_count":19,"default_branch":"main","last_synced_at":"2025-04-11T23:58:02.901Z","etag":null,"topics":["aws-cloudformation","cli","docker-image","ruby-api","ruby-gem"],"latest_commit_sha":null,"homepage":"","language":"Ruby","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/realestate-com-au.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGES.md","contributing":null,"funding":null,"license":"LICENSE.md","code_of_conduct":null,"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,"zenodo":null}},"created_at":"2015-09-14T07:45:12.000Z","updated_at":"2025-02-27T06:54:46.000Z","dependencies_parsed_at":"2024-06-19T03:52:56.087Z","dependency_job_id":"1038dffc-de36-46e4-a4b6-f5af3294e4e5","html_url":"https://github.com/realestate-com-au/stackup","commit_stats":{"total_commits":414,"total_committers":30,"mean_commits":13.8,"dds":"0.33574879227053145","last_synced_commit":"bea0d602a3cd5e8f10290cc60cef7b549561515b"},"previous_names":[],"tags_count":58,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/realestate-com-au%2Fstackup","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/realestate-com-au%2Fstackup/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/realestate-com-au%2Fstackup/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/realestate-com-au%2Fstackup/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/realestate-com-au","download_url":"https://codeload.github.com/realestate-com-au/stackup/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":253755762,"owners_count":21959078,"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":["aws-cloudformation","cli","docker-image","ruby-api","ruby-gem"],"created_at":"2024-08-02T13:01:49.729Z","updated_at":"2025-05-15T18:05:16.183Z","avatar_url":"https://github.com/realestate-com-au.png","language":"Ruby","readme":"# stackup\n\n[![Gem Version](https://badge.fury.io/rb/stackup.png)](http://badge.fury.io/rb/stackup)\n[![Build Status](https://travis-ci.com/realestate-com-au/stackup.svg?branch=main)](https://travis-ci.com/realestate-com-au/stackup)\n\nStackup provides a CLI and a simplified Ruby API for dealing with\nAWS CloudFormation stacks.\n\n\u003c!-- TOC depthFrom:2 depthTo:6 withLinks:1 updateOnSave:1 orderedList:0 --\u003e\n\n- [Why?](#why)\n- [Installation](#installation)\n- [Command-line usage](#command-line-usage)\n\t- [Stack create/update](#stack-createupdate)\n\t- [Specifying parameters](#specifying-parameters)\n\t- [YAML support](#yaml-support)\n\t- [AWS credentials](#aws-credentials)\n\t- [Using URLs as inputs](#using-urls-as-inputs)\n\t- [Stack deletion](#stack-deletion)\n\t- [Stack inspection](#stack-inspection)\n\t- [Change-set support](#change-set-support)\n- [Programmatic usage](#programmatic-usage)\n- [Rake integration](#rake-integration)\n- [Docker image](#docker-image)\n- [Releasing](#releasing)\n\n\u003c!-- /TOC --\u003e\n\n## Why?\n\nStackup provides some advantages over using `awscli` or `aws-sdk` directly:\n\n  - It treats stack changes as synchronous, streaming stack events until the\n    stack reaches a stable state.\n\n  - A `Stack#up` facade for `create`/`update` frees you from having to know\n    whether your stack already exists or not.\n\n  - Changes are (mostly) idempotent: \"no-op\" operations - e.g. deleting a\n    stack that doesn't exist, or updating without a template change - are\n    handled gracefully (i.e. without error).\n\n## Installation\n\n    $ gem install stackup\n\n## Command-line usage\n\nThe entry-point is the \"stackup\" command.\n\nMost commands operate in the context of a named stack:\n\n    $ stackup STACK-NAME ...\n\nCalled with `--list`, it will list stacks:\n\n    $ stackup --list\n    foo-bar-test\n    zzz-production\n\n### Stack create/update\n\nUse sub-command \"up\" to create or update a stack, as appropriate:\n\n    $ stackup myapp-test up -t template.json\n\nThis will:\n\n  * update (or create) the named CloudFormation stack, using the specified template\n  * monitor events until the stack update is complete\n\nRequests will retry 3 times by default. After this limit is exceeded, `ERROR: Rate exceeded` failures will be logged.\nYou can increase the limit using the `--retry-limit` option, or by setting the `$AWS_API_RETRY_LIMIT` environment variable.\n\nFor more details on usage, see\n\n    $ stackup STACK up --help\n\n### Specifying parameters\n\nStack parameters can be read from a file, e.g.\n\n    $ stackup myapp-test up -t template.json -p parameters.json\n\nThese files can be either JSON or YAML format, see [YAML support](#yaml-support) for more information.\n\nParameters can be specified as simple key-value pairs:\n\n```json\n{\n  \"IndexDoc\": \"index.html\"\n}\n```\n\nbut also supports the [extended JSON format used by the AWS CLI](http://docs.aws.amazon.com/cli/latest/reference/cloudformation/create-stack.html):\n\n\n```json\n[\n  {\n    \"ParameterKey\": \"IndexDoc\",\n    \"ParameterValue\": \"index.html\",\n    \"UsePreviousValue\": false\n  }\n]\n```\n\nYou may specify `-p` multiple times; `stackup` will read and merge all the files:\n\n    $ stackup myapp-test up -t template.json \\\n      -p defaults.json \\\n      -p overrides.json\n\nOr, you can specify one or more override parameters on the command-line, using `-o` with `-p`:\n\n    $ stackup myapp-test up -t template.json \\\n      -p defaults.json \\\n      -o IndexDoc=index-override.html\n      -o ContentDoc=content-override.html\n\n### Specifying tags\n\nStack tags can be read from a file, e.g.\n\n    $ stackup myapp-test up -t template.json --tags tags.json\n\nThese files can be either JSON or YAML format, see [YAML support](#yaml-support) for more information.\n\nTags are specified as simple key-value pairs:\n\n```json\n{\n  \"environment\": \"dev\"\n}\n```\n\n### Acknowledging Capabilities\n\nCloudFormation requires that some stacks explicitly acknowledge certain capabilities before creation. This helps to prevent the creation of stacks with unintended privileges.\n\nIf your stack includes IAM resources, you must specify either the `CAPABILITY_IAM` capability, or the `CAPABILITY_NAMED_IAM` capability if they have custom names.\n\nIf your stack template contains macros or nested stacks, you must specify the `CAPABILITY_AUTO_EXPAND` capability.\n\nCapabilities can be provided via the `--capability` CLI option.\n\n    $ stackup myapp-test up -t template.json \\\n      --capability CAPABILITY_NAMED_IAM \\\n      --capability CAPABILITY_AUTO_EXPAND\n\n`stackup` includes defaults to including `CAPABILITY_NAMED_IAM` capability if, and only if, no capabilities are specified.\nThis is to provide backwards compatibility with previously deployed stacks and may be removed in a future release.\n\n### YAML support\n\n`stackup` supports input files (template, parameters, tags) in YAML format, as well as JSON.\n\nIt also supports the [abbreviated YAML syntax for Cloudformation functions](https://aws.amazon.com/blogs/aws/aws-cloudformation-update-yaml-cross-stack-references-simplified-substitution/), though unlike the [AWS CLI](https://aws.amazon.com/cli/), Stackup (by default) normalises YAML input to JSON before invoking CloudFormation APIs.\n\nIf you don't want normalisation of the YAML input to JSON, then use the `--preserve-template-formatting` flag to the `up` or `change-set create` commands.\n\nNote: normalisation of S3 / HTTP URL stored templates is never done, as Cloudformation collects these directly.\n\n### AWS credentials\n\nThe stackup command-line looks for AWS credentials in the [standard environment variables](https://blogs.aws.amazon.com/security/post/Tx3D6U6WSFGOK2H/A-New-and-Standardized-Way-to-Manage-Credentials-in-the-AWS-SDKs).\n\nYou can also use the `--with-role` option to temporarily assume a different IAM role, for stack operations:\n\n    $ stackup myapp-test up -t template.json \\\n      --with-role arn:aws:iam::862905684840:role/deployment\n\nYou can use the `--service-role-arn` option to pass a specific IAM service role for CloudFormation to use for stack\noperations:\n\n    $ stackup myapp-test up -t template.json \\\n\t    --service-role-arn arn:aws:iam::862905684840:role/cloudformation-role\n\n\n(for more information on CloudFormation service roles, see [AWS' documentation](https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/using-iam-servicerole.html)).\n\n### Using URLs as inputs\n\nYou can use either local files, or HTTP URLs, to specify inputs; stack template, parameters, etc.\n\n    $ stackup mystack up \\\n      -t https://s3.amazonaws.com/mybucket/stack-template.json\n\nWhere a template URL references an object in S3, `stackup` leverages [CloudFormation's native support](http://docs.aws.amazon.com/AWSCloudFormation/latest/APIReference/API_CreateStack.html) for such URLs, enabling use of much larger templates.\n\nNon-S3 URLs are also supported, though in that case `stackup` must fetch the content itself:\n\n    $ stackup mystack up \\\n      -t https://raw.githubusercontent.com/realestate-com-au/stackup/main/examples/template.yml\n\n### Stack deletion\n\nSub-command \"delete\" deletes the stack.\n\n### Stack inspection\n\nInspect details of a stack with:\n\n    $ stackup myapp-test status\n    $ stackup myapp-test resources\n    $ stackup myapp-test outputs\n\n### Change-set support\n\nYou can also create, list, inspect, apply and delete [change sets](http://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/using-cfn-updating-stacks-changesets.html) using `stackup`.\n\n    $ stackup myapp-test change-sets\n    $ stackup myapp-test change-set create -t template.json\n    $ stackup myapp-test change-set inspect\n    $ stackup myapp-test change-set apply\n\nThe change-set name defaults to \"pending\", but can be overridden using `--name`.\n\nThe `change-set create` subcommand, like the `up` command, supports `--service-role-arn` to specify a service role.\n\nIt is impossible to create a change set with no changes. By default, stackup will only return successfully if a change set was actually created, and will otherwise fail. If the `--no-fail-on-empty-change-set` option is provided, stackup will return successfully if a change set was created _or_ if no change set was created because no changes were needed.\n\n## Programmatic usage\n\nGet a handle to a `Stack` object as follows:\n\n    stack = Stackup.stack(\"my-stack\")\n\nYou can pass an `Aws::CloudFormation::Client`, or client config,\nto `Stackup`, e.g.\n\n    stack = Stackup(credentials).stack(\"my-stack\")\n\nSee {Stackup::Stack} for more details.\n\n## Rake integration\n\nStackup integrates with Rake to generate handy tasks for managing a stack, e.g.\n\n    require \"stackup/rake_tasks\"\n\n    Stackup::RakeTasks.new(\"app\") do |t|\n      t.stack = \"my-app\"\n      t.template = \"app-template.json\"\n    end\n\nproviding tasks:\n\n    rake app:diff       # Show pending changes to my-app stack\n    rake app:down       # Delete my-app stack\n    rake app:inspect    # Show my-app stack outputs and resources\n    rake app:up         # Update my-app stack\n\nParameters and tags may be specified via files, or as a Hash, e.g.\n\n    Stackup::RakeTasks.new(\"app\") do |t|\n      t.stack = \"my-app\"\n      t.template = \"app-template.json\"\n      t.parameters = \"production-params.json\"\n      t.tags = { \"environment\" =\u003e \"production\" }\n    end\n\n## Docker image\n\nStackup is also published as a Docker image. Basic usage is:\n\n    docker run --rm \\\n        -v \"`pwd`:/cwd\" \\\n        -e AWS_ACCESS_KEY_ID -e AWS_SECRET_ACCESS_KEY -e AWS_SESSION_TOKEN \\\n        -e AWS_DEFAULT_REGION \\\n        realestate/stackup:latest ...\n\nIf you're sensible, you'll replace \"latest\", with a specific [version](https://rubygems.org/gems/stackup/versions).\n\nThe default working-directory within the container is `/cwd`;\nhence the volume mount to make files available from the host system.\n\n## IAM Permissions\n\n### up\n\nThis policy grants the principal all actions required by `stackup up` for any cloudformation stack:\n\n```\n{\n    \"Version\": \"2012-10-17\",\n    \"Statement\": [\n        {\n            \"Effect\": \"Allow\",\n            \"Action\": [\n                \"cloudformation:CreateStack\",\n                \"cloudformation:DeleteStack\",\n                \"cloudformation:DescribeStackEvents\",\n                \"cloudformation:DescribeStackResource\",\n                \"cloudformation:DescribeStacks\",\n                \"cloudformation:SetStackPolicy\",\n                \"cloudformation:UpdateStack\"\n            ],\n            \"Resource\": [\n                \"*\"\n            ]\n        }\n    ]\n}\n```\n\n## Development\n\n### Running tests\n\n`auto/test` will run the tests in a Docker container.\n`auto/lint` will run the linter in a Docker container.\n\n### Releasing\n\nReleasing is done mostly by CI. The automated process will push tags to GitHub, push the docker images to DockerHub. It won't yet push the gem to `rubygems.org`, but we're working ok it..\n\nPrerequisites:\n\n* You must have a rubygems account with permission to push to the `stackup` gem. (`auto/release-gem` will ask for your username and password)\n* You have bumped the version number in `lib/stackup/version.rb`.\n* You have checked the `CHANGES.md` file to make sure it is reasonable and has the changes for this new version.\n\nTo release the rubygem.\n1. `auto/release-gem`\n2. On REA's internal CI tool of choice, find the build for `stackup-ci` and trigger a new build from `HEAD`. This will always grab the latest code from here and release the rest of the parts.\n","funding_links":[],"categories":["CLI Tools","Ruby"],"sub_categories":["Hooks"],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Frealestate-com-au%2Fstackup","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Frealestate-com-au%2Fstackup","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Frealestate-com-au%2Fstackup/lists"}