{"id":21834493,"url":"https://github.com/molecule-man/stack-assembly","last_synced_at":"2025-04-14T08:44:13.319Z","repository":{"id":57561778,"uuid":"166577353","full_name":"molecule-man/stack-assembly","owner":"molecule-man","description":"Command line tool to configure and deploy aws cloudformation stacks","archived":false,"fork":false,"pushed_at":"2023-08-30T14:06:16.000Z","size":1615,"stargazers_count":39,"open_issues_count":1,"forks_count":2,"subscribers_count":2,"default_branch":"master","last_synced_at":"2025-03-27T22:22:03.607Z","etag":null,"topics":["aws","cli","cloudformation","configuration","deployment","go","golang"],"latest_commit_sha":null,"homepage":null,"language":"Go","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/molecule-man.png","metadata":{"files":{"readme":"README.rst","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","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}},"created_at":"2019-01-19T18:03:59.000Z","updated_at":"2023-06-14T00:13:25.000Z","dependencies_parsed_at":"2024-06-20T02:46:45.818Z","dependency_job_id":"1fbda8de-2822-403c-b8fe-76d90236a459","html_url":"https://github.com/molecule-man/stack-assembly","commit_stats":null,"previous_names":[],"tags_count":8,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/molecule-man%2Fstack-assembly","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/molecule-man%2Fstack-assembly/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/molecule-man%2Fstack-assembly/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/molecule-man%2Fstack-assembly/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/molecule-man","download_url":"https://codeload.github.com/molecule-man/stack-assembly/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":248850408,"owners_count":21171746,"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","cli","cloudformation","configuration","deployment","go","golang"],"created_at":"2024-11-27T20:11:32.348Z","updated_at":"2025-04-14T08:44:13.296Z","avatar_url":"https://github.com/molecule-man.png","language":"Go","funding_links":[],"categories":[],"sub_categories":[],"readme":"Stack-Assembly\n##############\n\nStack-Assembly is a command line tool to configure and deploy AWS Cloudformation\nstacks in a safe way. The safety aspect is enabled by utilizing Cloudformation\n`Changesets\n\u003chttps://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/using-cfn-updating-stacks-changesets.html\u003e`_\nand letting the user to view and confirm changes to be deployed.\n\n.. class:: no-web\n\n    |build|\n\n\n.. class:: no-web\n\n    .. image:: demo.gif\n        :alt: stack-assembly in action\n        :width: 100%\n        :align: center\n\n\n.. contents::\n\n.. section-numbering::\n\nMain features\n=============\n\n* No dependencies (NodeJS, Python interpreter, aws cli etc.) - Stack-Assembly is\n  a single statically linked binary\n* Configuration powered by `Golang Templates \u003chttps://golang.org/pkg/text/template/\u003e`_\n* Interactive interface which enables user to view, diff and confirm changes to\n  be deployed\n* Colorized terminal output\n* Documentation\n* Test coverage\n\n\nInstallation\n============\n\nThe pre-compiled binaries can be downloaded from `the release page\n\u003chttps://github.com/molecule-man/stack-assembly/releases\u003e`_. The following OSs\nare supported:\n\n* Windows amd64/386\n* Linux amd64/386\n* Darwin amd64/386\n\nBuild it yourself\n-----------------\n\nThis requires go 1.11 to be installed\n\n.. code-block:: bash\n\n    $ git clone git@github.com:molecule-man/stack-assembly.git\n    $ cd stack-assembly\n    $ make build\n\nThis will build binary inside ``bin`` folder.\n\nQuick start example\n===================\n\nFor demonstration purposes it is assumed that there exists file\n``./path/to/cf-tpls/sqs.yaml`` containing cloudformation template you\nwant to deploy. For example:\n\n.. code-block:: yaml\n\n    AWSTemplateFormatVersion: \"2010-09-09\"\n    Parameters:\n      QueueName:\n        Type: String\n      VisibilityTimeout:\n        Type: Number\n    Resources:\n      MyQueue:\n        Type: AWS::SQS::Queue\n        Properties:\n          QueueName: !Ref QueueName\n          VisibilityTimeout: !Ref VisibilityTimeout\n\nThen create Stack-Assembly configuration file in the root folder of your project\n``stack-assembly.yaml``:\n\n.. code-block:: yaml\n\n    # In this simple example two stacks are configured. Both stacks use the same\n    # cloudformation template\n    stacks:\n      # tpl1 is the id of the stack. This id has meaning only inside this\n      # config. You can use this id to deploy a particular stack instead of\n      # deploying all stacks as it's done by default. You can do it by running\n      # `stas sync tpl1`\n      tpl1:\n        name: demo-tpl1\n        path: path/to/cf-tpls/sqs.yaml\n        # parameters is a key-value map where values are strings. Numeric\n        # parameters have to be defined as strings as you can see in the example\n        # of VisibilityTimeout parameter\n        parameters:\n          QueueName: demo1\n          VisibilityTimeout: \"10\"\n      tpl2:\n        name: demo-tpl2\n        path: path/to/cf-tpls/sqs.yaml\n        parameters:\n          QueueName: demo2\n          VisibilityTimeout: \"20\"\n\nAssuming you have configured `AWS credentials`_ then you can deploy your stacks\nby running:\n\n.. code-block:: bash\n\n    $ stas sync\n\nBy default Stack-Assembly is executed in interactive mode. During the deployment\nit shows the changes that are about to be deployed and asks user's confirmation\nto proceed with deployment.\n\nUsage\n=====\n\n.. code-block::\n\n    $ stas help sync\n    Creates or updates stacks specified in the config file(s).\n\n    By default sync command deploys all the stacks described in the config file(s).\n    To deploy a particular stack, ID argument has to be provided. ID is an\n    identifier of a stack within the config file. For example, ID is tpl1 in the\n    following yaml config:\n\n        stacks:\n          tpl1: # \u003c--- this is ID\n            name: mystack\n            path: path/to/tpl.json\n\n    The config can be nested:\n        stacks:\n          parent_tpl:\n            name: my-parent-stack\n            path: path/to/tpl.json\n            stacks:\n              child_tpl: # \u003c--- this is ID of the stack we want to deploy\n                name: my-child-stack\n                path: path/to/tpl.json\n\n    In this case specifying ID of only wanted stack is not enough all the parent IDs\n    have to be specified as well:\n\n      stas sync parent_tpl child_tpl\n\n    Usage:\n      stas sync [\u003cID\u003e [\u003cID\u003e ...]] [flags]\n\n    Aliases:\n      sync, deploy\n\n    Flags:\n      -h, --help   help for sync\n\n    Global Flags:\n      -c, --configs strings            Alternative config file(s). Default: stack-assembly.yaml\n      -n, --no-interaction             Do not ask any interactive questions\n          --nocolor                    Disables color output\n      -p, --profile string             AWS named profile (default \"default\")\n      -r, --region string              AWS region\n      -v, --var -v myParam=someValue   Additional variables to use as parameters in config.\n                                       Example: -v myParam=someValue\n\n\nSpecifying multiple config files\n--------------------------------\n\nYou can supply multiple ``-c`` configuration files. When you supply multiple\nfiles, Stack-Assembly combines them into a single configuration. Subsequent\nfiles override and add to their predecessors.\n\nFor example, consider this command line:\n\n.. code-block:: bash\n\n    $ stas sync -c stack-assembly.yml -c stack-assembly.staging.yml\n\nThe ``stack-assembly.yml`` file might look like this:\n\n.. code-block:: yaml\n\n    stacks:\n      ec2machine:\n        name: ec2machine-dev\n        path: cf-tpls/ec2machine.yml\n        parameters:\n          Size: t2.micro\n          ImageID: ami-rt34fu\n\nAnd the ``stack-assembly.staging.yml`` file might look like this:\n\n.. code-block:: yaml\n\n    stacks:\n      ec2machine:\n        name: ec2machine-staging\n        parameters:\n          Size: t2.medium\n        tags:\n          ENV: staging\n\nStack-Assembly will apply configuration from ``stack-assembly.staging.yml`` on\ntop of ``stack-assembly.yml`` and the result configuration will look like this:\n\n.. code-block:: yaml\n\n    stacks:\n      ec2machine:\n        name: ec2machine-staging\n        path: cf-tpls/ec2machine.yml\n        parameters:\n          Size: t2.medium\n          ImageID: ami-rt34fu\n        tags:\n          ENV: staging\n\nConfiguration\n=============\n\nStack-Assembly uses simple yet powerful config file that can be in one of these\nthree formats: ``yaml``, ``toml``, ``json``. The next sections will use ``yaml``\nas a format.\n\nConfig file location\n--------------------\n\nStack-Assembly will firstly try to use file ``stack-assembly.yaml`` in your\nproject directory. If it's not found then Stack-Assembly will try to use\n``stack-assembly.yml``, ``stack-assembly.toml``, ``stack-assembly.json``.\n\nConfig file structure\n---------------------\n\nExample of Stack-Assembly config file:\n\n.. code-block:: yaml\n\n    settings:\n      aws:\n        # aws named profile. See the following link for more information\n        # https://docs.aws.amazon.com/cli/latest/userguide/cli-configure-profiles.html\n        # This configuration option can be overriden by env variable AWS_PROFILE.\n        # Or by command line parameter `--profile`\n        profile: default\n\n        # aws region. This configuration option can be overriden by env variable\n        # AWS_REGION. Or by command line parameter `--region`\n        region: us-west-2\n\n    # cloudformation parameters that are global for all stacks\n    parameters:\n      Env: dev\n      ServiceName: myservice\n\n    stacks:\n      db:\n        # cloudformation stack's name. It's possible to use golang templating\n        # inside `name`\n        name: \"{{ .Params.DbName }}\"\n\n        # path to cloudformation template.\n        # Either `path` or `body` has to be provided\n        path: cf-tpls/rds.yml\n\n        # cloudformation stack's parameters\n        parameters:\n          Type: db.t2.medium\n          # it's possible to use golang templating inside parameter value\n          DbName: \"{{ .Params.ServiceName }}-{{ .Params.Env }}\"\n\n        # cloudformation stack's tags. It's also possible to use golang\n        # templating inside tag value\n        tags:\n          ENV: \"{{ .Params.Env }}\"\n\n        # it's possible to create a stack policy that will disallow to `update`\n        # or `delete` certain stack resources. In this case the policy will be\n        # applied to stack resource with `LogicalResourceId` equal to\n        # `DbInstance`. See the following link for more information:\n        # https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/protect-stack-resources.html\n        blocked:\n          - DbInstance\n\n      ec2app:\n        name: \"{{ .Params.ServiceName }}-{{ .Params.Env }}-ec2app\"\n        parameters:\n          Type: t2.micro\n\n        # `path` is not the only way to specify cloudformation template. It's\n        # possible to specify the whole template body inside the config. It\n        # might be especially useful when template generating tool (as e.g.\n        # troposphere) is used.\n        # In this example, given that `Env` is equal to \"dev\", body will have\n        # contents of the output produced by executing\n        # `python terraform_tpls/ec2.py dev`\n        body: |\n          {{ .Params.Env | Exec \"python\" \"terraform_tpls/ec2.py\" }}\n\n        # dependsOn instruction tells Stack-Assembly that this stack should be\n        # deployed after `db` stack is deployed\n        dependsOn:\n          - db\n\n        # In some cases, you must explicity acknowledge that your stack template\n        # contains certain capabilities in order for AWS CloudFormation to\n        # create the stack. For more information, see\n        # https://docs.aws.amazon.com/AWSCloudFormation/latest/APIReference/API_CreateStack.html\n        capabilities:\n          - CAPABILITY_IAM\n\n        # Rollback triggers enable you to have AWS CloudFormation monitor the\n        # state of your application during stack creation and updating, and to\n        # roll back that operation if the application breaches the threshold of\n        # any of the alarms you've specified.\n        # For more information, see\n        # https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/using-cfn-rollback-triggers.html\n        rollbackConfiguration:\n          monitoringTimeInMinutes: 1\n          rollbackTriggers:\n            - arn: arn:aws:cloudwatch:{{ .AWS.Region }}:{{ .AWS.AccountID }}:alarm:{{ .Params.ServiceName }}-errors\n              type: AWS::CloudWatch::Alarm\n\nConfig nesting\n--------------\n\nEvery stack in stack-assembly config can contain nested stacks. This enables\npossibility to deploy subgroup (subtree) of stacks.\n\n.. code-block:: yaml\n\n    stacks:\n      staging:\n\n        # settings, as well as parameters, are propagated down the tree.\n        # All the child stacks of `staging` inherit settings and parameters\n        # defined at `staging` level\n        settings:\n          aws:\n            region: eu-west-1\n        parameters:\n          Env: staging\n\n        stacks:\n          db:\n            name: \"db-staging\"\n            path: cf-tpls/rds.yml\n          app:\n            name: \"app-staging\"\n            path: cf-tpls/app.yml\n\n      production:\n\n        settings:\n          aws:\n            region: us-east-1\n        parameters:\n          Env: production\n\n        stacks:\n          db:\n            name: \"db-production\"\n            path: cf-tpls/rds.yml\n          app:\n            name: \"app-production\"\n            path: cf-tpls/app.yml\n\nHaving this config one can deploy all the stacks under ``production`` by\nrunning:\n\n.. code-block:: bash\n\n    stas sync production\n\nOr, if one needs to deploy ``db`` stack under ``staging``, one can use the\nfollowing command:\n\n.. code-block:: bash\n\n    stas sync staging db\n\nReuse\n-----\n\nWhen writing complex config, it's almost inevitable to have duplication in the\nconfig. This section describes how stack-assembly helps to avoid\ncopying-and-pasting.\n\nLet's say we have a stack we want to deploy multiple times in different\nenvironments. Each environment is different from each other only by handful of\nparameters. Then we put the reused stack under the ``definitions`` in the root\nof the config. And then we can (re)use this stack in the config by referencing\nthis stack with ``$basedOn`` field in the config:\n\n.. code-block:: yaml\n\n    stacks:\n      staging:\n        \"$basedOn\": reused_stack\n        parameters:\n          Env: staging\n\n      production:\n        \"$basedOn\": reused_stack\n        parameters:\n          Env: production\n\n    definitions:\n      reused_stack:\n        name: \"reused-stack-{{ .Params.Env }}\"\n        path: cf-tpls/stack.yml\n\nAWS credentials\n===============\n\nIf you've ever used awscli or similar tool you probably already know about aws\ncredentials file. Stack-Assembly also uses this file to read credentials. The\ndefault location of this file is ``$HOME/.aws/credentials``. You can find more\ninformation in `AWS documentation\n\u003chttps://docs.aws.amazon.com/cli/latest/userguide/cli-configure-files.html\u003e`_.\n\nFor the sake of example let's consider that you have configured aws credentials\nand now have this files in your home folder:\n\n**~/.aws/credentials**\n\n::\n\n    [default]\n    aws_access_key_id=AKIAIOSFODNN7EXAMPLE\n    aws_secret_access_key=wJalrXUtnFEMI/K7MDENG/bPxRfiCYEXAMPLEKEY\n\n**~/.aws/config**\n\n::\n\n    [default]\n    region=us-west-2\n\nNow you have couple of options:\n\n1. Specify profile and region in the config file. See `Config file structure`_:\n\n.. code-block:: yaml\n\n    settings:\n      aws:\n        profile: default\n        region: eu-west-1\n\n2. Use environmental variables:\n\n.. code-block:: bash\n\n    $ export AWS_PROFILE=default\n    $ export AWS_REGION=eu-west-1\n    $ stas sync\n\n3. Use command line flags:\n\n.. code-block:: bash\n\n    $ stas sync --profile default --region eu-west-1\n\nOther commands\n==============\n\nApart from `sync` command there are also couple of handy other commands you can\nuse:\n\n.. code-block:: bash\n\n    $ stas help\n    Usage:\n      stas [command]\n\n    Available Commands:\n      delete      Deletes deployed stacks\n      diff        Show diff of the stacks to be deployed\n      dump-config Dump loaded config into stdout\n      help        Help about any command\n      info        Show info about the stack\n      sync        Synchronize (deploy) stacks\n\nDrop-in replacement of cloudformation commands of aws-cli\n---------------------------------------------------------\n\nStack-assembly provides a possibility to enhance\n`aws-cli \u003chttps://github.com/aws/aws-cli\u003e`_ by replacing\n`create-stack \u003chttps://docs.aws.amazon.com/cli/latest/reference/cloudformation/create-stack.html\u003e`_,\n`update-stack \u003chttps://docs.aws.amazon.com/cli/latest/reference/cloudformation/update-stack.html\u003e`_\nand\n`deploy \u003chttps://docs.aws.amazon.com/cli/latest/reference/cloudformation/deploy.html\u003e`_ commands with improved versions of those commands. More info can be found `here \u003chttps://github.com/molecule-man/stack-assembly/blob/master/docs/aws-drop-in.md\u003e`_\n\nTODO\n====\n\n* Enable user to unblock the blocked resource (interactively).\n* Github support.\n* Add possibility to introspect aws resources??\n\n.. |build| image:: https://circleci.com/gh/molecule-man/stack-assembly.svg?style=svg\n    :target: https://circleci.com/gh/molecule-man/stack-assembly\n    :alt: Build status of the master branch\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmolecule-man%2Fstack-assembly","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fmolecule-man%2Fstack-assembly","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmolecule-man%2Fstack-assembly/lists"}