{"id":26829440,"url":"https://github.com/stuartellis/copier-tf-tools","last_synced_at":"2025-03-30T13:16:41.759Z","repository":{"id":281422504,"uuid":"945213877","full_name":"stuartellis/copier-tf-tools","owner":"stuartellis","description":"Terraform and OpenTofu project template using the Copier tool","archived":false,"fork":false,"pushed_at":"2025-03-26T22:55:28.000Z","size":93,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":1,"default_branch":"main","last_synced_at":"2025-03-26T23:32:06.418Z","etag":null,"topics":["copier-template","opentofu","terraform"],"latest_commit_sha":null,"homepage":"","language":"Jinja","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/stuartellis.png","metadata":{"files":{"readme":"README.md","changelog":null,"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}},"created_at":"2025-03-08T23:06:17.000Z","updated_at":"2025-03-26T22:55:53.000Z","dependencies_parsed_at":"2025-03-09T01:25:24.679Z","dependency_job_id":"3ad5a4dd-2a77-4cdb-851e-4aabf35cc5f2","html_url":"https://github.com/stuartellis/copier-tf-tools","commit_stats":null,"previous_names":["stuartellis/copier-sve-tf","stuartellis/copier-tf-tools"],"tags_count":14,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/stuartellis%2Fcopier-tf-tools","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/stuartellis%2Fcopier-tf-tools/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/stuartellis%2Fcopier-tf-tools/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/stuartellis%2Fcopier-tf-tools/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/stuartellis","download_url":"https://codeload.github.com/stuartellis/copier-tf-tools/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":246320198,"owners_count":20758410,"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":["copier-template","opentofu","terraform"],"created_at":"2025-03-30T13:16:41.290Z","updated_at":"2025-03-30T13:16:41.750Z","avatar_url":"https://github.com/stuartellis.png","language":"Jinja","funding_links":[],"categories":[],"sub_categories":[],"readme":"\u003c!--\nSPDX-FileCopyrightText: 2025-present Stuart Ellis \u003cstuart@stuartellis.name\u003e\n\nSPDX-License-Identifier: MIT\n--\u003e\n\n# Copier Template for TF Tooling\n\n[![Copier](https://img.shields.io/endpoint?url=https://raw.githubusercontent.com/copier-org/copier/master/img/badge/badge-grayscale-inverted-border-orange.json)](https://github.com/copier-org/copier) [![standard-readme compliant](https://img.shields.io/badge/readme%20style-standard-brightgreen.svg?style=flat-square)](https://github.com/RichardLitt/standard-readme) [![pre-commit](https://img.shields.io/badge/pre--commit-enabled-brightgreen?logo=pre-commit)](https://github.com/pre-commit/pre-commit) [![styled with prettier](https://img.shields.io/badge/styled_with-prettier-ff69b4.svg)](https://github.com/prettier/prettier)\n\nThis [Copier](https://copier.readthedocs.io/en/stable/) template provides files for a [Terraform](https://www.terraform.io/) or [OpenTofu](https://opentofu.org/) project. It uses [Task](https://taskfile.dev) as the task runner for the template and the generated projects.\n\nThe tasks in the generated projects provide an opinionated set of tools for Terraform and OpenTofu. These tasks use built-in features to support:\n\n- Multiple TF components in the same repository\n- Multiple instances of the same TF component with different configurations\n- Temporary instances of a TF component for testing or development with [workspaces](https://opentofu.org/docs/language/state/workspaces/).\n\n\u003e This project always uses the identifier _TF_ or _tf_ where possible, rather than Terraform or OpenTofu. This enables you to use the same tasks and code with both tools.\n\n## How It Works\n\nFirst use Copier to either generate a new project, or add this tooling to an existing project. This tooling designed to avoid conflicts with other tools.\n\nOnce you have the tooling in a project, you can use it to develop and manage infrastructure with Terraform or OpenTofu. It enables you to work with separate sets of TF infrastructure code. Each set of infrastructure code is a separate component.\n\nEach of the infrastructure components in the project is a separate TF root module. This tooling refers to these TF root modules as _stacks_. The project puts TF stacks in the directory `tf/definitions/`.\n\nThis tooling uses _contexts_ to provide profiles for TF. Contexts enable you to deploy multiple instances of the same stack with different configurations. These instances may or may not be in different environments. Each context is a directory that contains a `context.json` file and one `.tfvars` file per stack. The `context.json` file specifies metadata and the settings for a TF remote backend.\n\n\u003e The directory `tf/contexts/all/` also contains one `.tfvars` file per stack. The `.tfvars` file for a stack in the `all` directory is always used along with `.tfvars` for the current context. This enables you to share common tfvars across all of the contexts for a stack.\n\nThe project structure also includes a `tf/modules/` directory to hold TF modules that are shared between stacks in the same project.\n\nBy design, this tooling does not specify or enforce any dependencies between infrastructure components. If you need to execute changes in a particular order, specify that order in whichever system you use to carry out deployments.\n\nThis tooling uses specific files and directories to avoid conflicts with other tools. It adds a `tf/` directory and the file `tasks/tf/Taskfile.yaml` to the project. It also adds a `Taskfile,yaml` to the root directory of the project if one does not already exist. Tasks generate a `tmp/tf/` directory for artifacts. It only changes the contents of the `tf/` and `tmp/tf/` directories.\n\n## Install\n\nYou need [Copier](https://copier.readthedocs.io/en/stable/) to add this template to a project. Use [uv](https://docs.astral.sh/uv/) or [pipx](https://pipx.pypa.io/) to run Copier. These tools enable you to use Copier without installing it.\n\nYou can either create a new project with this template or add the template to an existing project. Use the same _copy_ sub-command of Copier for both cases. Run Copier with the _uvx_ or _pipx run_ commands, which download and cache software packages as needed. For example:\n\n```shell\nuvx copier copy git+https://github.com/stuartellis/copier-tf-tools your-project-name\n```\n\nTo update a project again with this template, run these commands:\n\n```shell\ncd your-project-name\nuvx copier update -A -a .copier-answers-tf-tools.yaml .\n```\n\n\u003e Updates only currently only change the Taskfile `tasks/tf/Taskfile.yaml`. By design, the Copier configuration for this template does not change the contents of the `tf/` directory once it has been created.\n\n## Usage\n\nTo use the tasks in a generated project you need:\n\n- [Git](https://git-scm.com/)\n- A UNIX shell, such as Bash or Fish\n- [Task](https://taskfile.dev)\n- [Terraform](https://www.terraform.io/) or [OpenTofu](https://opentofu.org/)\n\nYou only need Python to create projects from this template. The tasks in the template do not use Python. This means that they can be run in a restricted environment, such as a continuous integration job.\n\nI recommend that you use a tool version manager to install copies of Terraform and OpenTofu. Consider using either [tenv](https://tofuutils.github.io/tenv/), which is specifically designed for TF tools, or the general-purpose [mise](https://mise.jdx.dev/) framework. The generated projects include a `.terraform-version` file so that your tool version manager can install the Terraform version that you specify.\n\nTo see a list of the available tasks in a project, enter _task_ in a terminal window:\n\n```shell\ntask\n```\n\nTasks for TF stacks use the namespace `tf`. For example, `tf:new` creates the directories and files for a new stack:\n\n```shell\nSTACK=example_app task tf:new\n```\n\nYou need to set these environment variables to work on a stack:\n\n- `CONTEXT` - The TF configuration to use\n- `STACK` - Name of stack\n\nSet these variables to override the defaults:\n\n- `PRODUCT_NAME` - The name of the project\n- `TF_CLI_EXE` - The Terraform or OpenTofu executable to use\n- `VARIANT` - The name of the active TF workspace\n- `TF_REMOTE_BACKEND` - Enables a remote TF backend\n\nBy default, this tooling uses a local TF state file. We set `TF_REMOTE_BACKEND` to `true` to use S3 as the remote backend for TF:\n\n```shell\nTF_REMOTE_BACKEND=true\n```\n\n\u003e This tooling currently only supports S3 as a remote TF backend.\n\nSpecify `CONTEXT` to create a deployment of the stack in the target CONTEXT:\n\n```shell\nCONTEXT=dev STACK=example_app task tf:plan\nCONTEXT=dev STACK=example_app task tf:apply\n```\n\n### Variants\n\nSpecify `VARIANT` to create an alternate deployment of the same stack with the same context:\n\n```shell\nCONTEXT=dev STACK=example_app VARIANT=feature1 task tf:plan\nCONTEXT=dev STACK=example_app VARIANT=feature1 task tf:apply\n```\n\nThe variant feature uses TF workspaces. It sets the value of the tfvar `variant` to the name of the variant. Use the `environment`, `stack` and `variant` tfvars to define resource names that are unique and do not conflict. The `tf:test` task generates random variant names that have the prefix `t-` to ensure that test copies of stacks do not conflict with other copies of the stack.\n\n### Available `tf` Tasks\n\n| Name         | Description                                                                                       |\n| ------------ | ------------------------------------------------------------------------------------------------- |\n| tf:apply     | _terraform apply_ for a stack                                                                     |\n| tf:check-fmt | Checks whether _terraform fmt_ would change the code for a stack                                  |\n| tf:clean     | Remove the generated files for a stack                                                            |\n| tf:console   | _terraform console_ for a stack                                                                   |\n| tf:destroy   | _terraform apply -destroy_ for a stack                                                            |\n| tf:fmt       | _terraform fmt_ for a stack                                                                       |\n| tf:init      | _terraform init_ for a stack                                                                      |\n| tf:new       | Add the source code for a new stack. Copies content from the _tf/definitions/template/_ directory |\n| tf:plan      | _terraform plan_ for a stack                                                                      |\n| tf:rm        | Delete the source code for a stack                                                                |\n| tf:test      | _terraform test_ for a stack                                                                      |\n| tf:validate  | _terraform validate_ for a stack                                                                  |\n\n### Available `tf:context` Tasks\n\n| Name            | Description                                                                  |\n| --------------- | ---------------------------------------------------------------------------- |\n| tf:context:list | List the contexts                                                            |\n| tf:context:new  | Add a new context. Copies content from the _tf/contexts/template/_ directory |\n| tf:context:rm   | Delete the directory for a context                                           |\n\n## Contributing\n\nThis project was built for my personal use. I will accept suggestions and consider Pull Requests, but may decline anything that makes it less useful for me.\n\nConfiguration files for this project template are provided by my [baseline](https://github.com/stuartellis/copier-sve-baseline) Copier template. To synchronize a copy of this project template with the baseline template, run these commands:\n\n```shell\ncd copier-sve-baseline\ncopier update -a .copier-answers-baseline.yaml .\n```\n\n## License\n\nMIT © 2025 Stuart Ellis\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fstuartellis%2Fcopier-tf-tools","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fstuartellis%2Fcopier-tf-tools","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fstuartellis%2Fcopier-tf-tools/lists"}