{"id":13505788,"url":"https://github.com/uber/astro","last_synced_at":"2025-06-11T17:40:18.635Z","repository":{"id":41407138,"uuid":"149765255","full_name":"uber/astro","owner":"uber","description":"Astro is a tool for managing multiple Terraform executions as a single command","archived":false,"fork":false,"pushed_at":"2023-03-19T22:42:53.000Z","size":202,"stargazers_count":431,"open_issues_count":23,"forks_count":32,"subscribers_count":1524,"default_branch":"master","last_synced_at":"2024-05-23T02:31:26.050Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":"","language":"Go","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"apache-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/uber.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","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}},"created_at":"2018-09-21T13:10:19.000Z","updated_at":"2024-04-26T01:18:48.000Z","dependencies_parsed_at":"2024-01-03T02:28:15.052Z","dependency_job_id":"d71248a3-a15c-44b2-94eb-c9d664a7fa41","html_url":"https://github.com/uber/astro","commit_stats":null,"previous_names":[],"tags_count":4,"template":false,"template_full_name":null,"purl":"pkg:github/uber/astro","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/uber%2Fastro","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/uber%2Fastro/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/uber%2Fastro/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/uber%2Fastro/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/uber","download_url":"https://codeload.github.com/uber/astro/tar.gz/refs/heads/master","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/uber%2Fastro/sbom","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":259308163,"owners_count":22837974,"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":[],"created_at":"2024-08-01T00:01:13.792Z","updated_at":"2025-06-11T17:40:18.610Z","avatar_url":"https://github.com/uber.png","language":"Go","readme":"# Astro\n\nAstro is a tool for managing multiple Terraform executions as a single command.\n\nFeatures:\n\n* Declarative configuration for modules to execute\n* Dependencies between modules\n* Fast, concurrent executions of Terraform operations\n* Safe Terraform upgrades and state file migrations\n\nNOTE: Astro is currently experimental.\n\n## Getting started\n\n**Installation**\n\nInstall Astro using go get (Go \u003e1.12 required):\n\n```\nGO111MODULE=on go get github.com/uber/astro/astro/cli/astro\n```\n\nThis will install a binary called `astro` in your `$GOPATH/bin`.\n\nAlternatively, you can download precompiled binaries from the [Github releases page](https://github.com/uber/astro/releases).\n\nNote that from version 0.6.0 `tvm`, a tool to download and install specific versions of Terraform for your platforms,\nis packaged together with astro.\n\n**Configuration**\n\nAstro looks for a configuration file called `astro.yaml` in the current or parent directories. It is recommended to place this file in the same top-level directory of your project where the Terraform code exists (e.g. `terraform/astro.yaml`).\n\nAn example astro configuration could look like:\n\n```\n---\n\nterraform:\n  version: 0.11.7\n\nhooks:\n  startup:\n    - command: assume-role --role terraform\n      set_env: true\n\nmodules:\n  - name: app\n    path: core/app\n    deps:\n      - module: users\n      - module: vpc\n    remote:\n      backend_config:\n        bucket: acme-terraform-states\n        key: \"{{.aws_region}}/app-{{.environment}}.tfstate\"\n        region: us-east-1\n    variables:\n      - name: region\n      - name: environment\n        values: [dev, prod]\n\n  - name: database\n    path: core/database\n    remote:\n      backend_config:\n        bucket: acme-terraform-states\n        key: \"{{.aws_region}}/database-{{.environment}}.tfstate\"\n        region: us-east-1\n    variables:\n      - name: region\n      - name: environment\n        values: [dev, prod]\n\n  - name: mgmt\n    path: core/mgmt\n    deps:\n      - module: vpc\n        variables:\n          environment: mgmt  # depends on vpc/mgmt\n    remote:\n      backend_config:\n        bucket: acme-terraform-states\n        key: \"{{.aws_region}}/mgmt-{{.environment}}.tfstate\"\n        region: us-east-1\n    variables:\n      - name: region\n\n  - name: users\n    path: core/users\n    remote:\n      backend_config:\n        bucket: acme-terraform-states\n        key: global/users\n        region: us-east-1\n\n  - name: vpc\n    path: core/vpc\n    remote:\n      backend_config:\n        bucket: acme-terraform-states\n        key: \"{{.aws_region}}/vpc-{{.environment}}.tfstate\"\n        region: us-east-1\n    variables:\n      - name: region\n      - name: environment\n        values: [mgmt, dev, prod]\n```\n\n**Planning**\n\nYou can run a plan across all modules by doing:\n\n```\nastro plan --region us-east-1\n```\n\n`--region` in this example is one of the variables defined in the module configuration above with no predefined value, so it must be provided at the command line.\n\nAstro will show the results of the plan for each execution:\n\n\n```\n\u003e astro plan --region us-east-1\nusers: OK No changes (7s)\nvpc-mgmt-us-east-1: OK No changes (15s)\nvpc-dev-us-east-1: OK No changes (31s)\nvpc-prod-us-east-1: OK No changes (28s)\ndatabase-dev-us-east-1: OK No changes (9s)\ndatabase-prod-us-east-1: OK No changes (10s)\napp-dev-us-east-1: OK No changes (10s)\napp-prod-us-east-1: OK No changes (11s)\nmgmt-us-east-1: OK No changes (43s)\n\u003e\n```\n\nIf there is a change, the plan will be shown, e.g.:\n\n\n```\n\u003e astro plan --region us-east-1 --modules app\napp-dev-us-east-1: OK Changes (10s)\n\n  ~ module.app.aws_s3_bucket.app-data\n      versioning.0.enabled: \"false\" =\u003e \"true\"\n\napp-prod-us-east-1: OK Changes (11s)\n\n  ~ module.app.aws_s3_bucket.app-data\n      versioning.0.enabled: \"false\" =\u003e \"true\"\n\u003e\n```\n\n**Upgrading**\n\nUpgrading Terraform is as easy as changing the version in the config, e.g.:\n\n```\ndiff --git a/terraform/astro.yaml b/terraform/astro.yaml\nindex 5725a36d..c0ef720f 100644\n--- a/terraform/astro.yaml\n+++ b/terraform/astro.yaml\n@@ -1,7 +1,7 @@\n ---\n\n terraform:\n-  version: 0.10.5\n+  version: 0.11.7\n\n modules:\n  - name: app\n```\n\nAstro will automatically download the new version when it needs it next.\n\n**Detaching from the remote**\n\nOlder versions of Terraform had the ability to disable the remote state, which was useful for performing safe upgrades or migrations.\n\nAstro restores this ability using the `--detach` command to plan, e.g.:\n\n```\nastro plan --detach\n```\n\nThis will create a session directory with a sandbox containing a copy (hard links) of the Terraform code, along with a local copy of the state file:\n\n```\n\u003e ls terraform/.astro/01CGC80C81CJFPFCCM0F1FRKDJ/app/sandbox/core/app/terraform.tfstate\nterraform/.astro/01CGC80C81CJFPFCCM0F1FRKDJ/app/sandbox/core/app/terraform.tfstate\n```\n\nIf you need to test anything, you can change directory within the sandbox without affecting the remote.\n\n**Hooks**\n\nAstro can run run external commands both at startup or before the execution of a module. If `set_env` is `true`, Astro will parse command\noutput for `NAME=value` pairs, and set those as environment values.\n\nThis can be useful, for example, when using an `assume-role` script to assume an AWS role that requires MFA authentication. If the script outputs\n`AWS_ACCESS_KEY_ID`, `AWS_SECRET_ACCESS_KEY` and `AWS_SESSION_TOKEN` to standard output, then it can be used as a startup hook by Astro to\ntransparently change role before running Terraform.\n\n## Use cases\n\n### Dynamic environments\n\nWhen running a `terraform plan` or `terraform apply`, you can specify custom variables at the command line (using `-var foo=bar`). This can be used to dynamically deploy to a particular environment, or region, for example.\n\nAstro allows you to specify these variables at runtime, or filter a set of predefined ones.\n\nIn the example configuration above, the \"app\" and \"database\" modules are deployed to two different environments (\"dev\" and \"prod\") by invoking Terraform with different `-var environment=\u003cvalue\u003e` flags set.\n\nWhat is happening behind the scenes is the module configuration generates a list of \"executions\", which is a Cartesian product of each set of possible variable values, plus the user-provided values at run time.\n\nEach execution is then run in parallel, taking into considerations dependencies that modules may have on one another.\n\n### Targeted deploys\n\nGiven a list of predefined environments, the user can \"filter\" which executions are run. For example, the following would run only the executions with enviroment=dev:\n\n```\nastro plan --enviroment dev\n```\n\nThe result would be:\n\n```\n\u003e astro plan --region us-east-1 --environment dev\nvpc-dev-us-east-1: OK No changes (31s)\ndatabase-dev-us-east-1: OK No changes (9s)\napp-dev-us-east-1: OK No changes (10s)\n\u003e\n```\n\n#### Remapping CLI flags\n\nAstro is meant to be used every day by operators. If your Terraform variable names are long-winded to type at the CLI, you can remap them to something simpler. For example, instead of typing `--environment dev`, you may wish to shorten this to `--env dev`.\n\nYou can specify a `flags:` block in your project configuration, like:\n\n```\nflags:\n  environment:\n    name: env\n    description: Environment to deploy to\n```\n\nThis will remap the \"environment\" Terraform variable to `--env` on the astro command line. You can also specify a description that will show up in the `--help` text.\n","funding_links":[],"categories":["Go"],"sub_categories":[],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fuber%2Fastro","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fuber%2Fastro","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fuber%2Fastro/lists"}