Skip to content

Commit

Permalink
chore: address PR feedback
Browse files Browse the repository at this point in the history
  • Loading branch information
@gberenice
gberenice committed Oct 29, 2024
1 parent 4d367d9 commit ae4fe7c
Show file tree
Hide file tree
Showing 4 changed files with 132 additions and 49 deletions.
64 changes: 40 additions & 24 deletions modules/spacelift-automation/README.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -2,7 +2,7 @@

[![Release](https://img.shields.io/github/release/masterpointio/terraform-spacelift-automation.svg)](https://github.com/masterpointio/terraform-spacelift-automation/releases/latest)

This Terraform root module provides infrastructure automation for projects in [Spacelift](https://docs.spacelift.io/).
This Terraform child module provides infrastructure automation for projects in [Spacelift](https://docs.spacelift.io/).

## Overview

Expand All @@ -17,14 +17,12 @@ It automates the creation of "child" stacks and all the required accompanying Sp
3. [Spacelift AWS Integration Attachment](https://docs.spacelift.io/integrations/cloud-providers/aws#lets-explain)
Associates a specific AWS IAM role with a stack to allow it to assume that role. The IAM role typically has permissions to manage specific AWS resources, and Spacelift assumes this role to run the operations required by the stack.
4. [Spacelift Initialization Hook](https://docs.spacelift.io/concepts/run#initializing)
Prepares your environment before executing infrastructure code. This custom script copies corresponding Terraform tfvars files into a working directory before either run or task, so it's automatically loaded into the OpenTofu/Terraform execution environment.

These files are automatically mounted and available during the Terraform plan and apply stages.
Prepares your environment before executing infrastructure code. This custom script copies corresponding Terraform tfvars files into a working directory before either run or task as a `spacelift.auto.tfvars` file. It's [automatically loaded](https://opentofu.org/docs/v1.7/language/values/variables/#variable-definitions-tfvars-files) into the OpenTofu/Terraform execution environment.

## Usage

Spacelift Automation logic is opinionated and heavily relies on the Git repository structure.
The root module `spacelift-automation` is configured to track all the files in the provided root module directory and create the stack based on the provided configuration (if any).
This module is configured to track all the files in the provided root module directory and create the stack based on the provided configuration (if any).

Structure requirements are:

Expand All @@ -48,6 +46,17 @@ Input repo structure:
│ │ │ └── stage.tfvars
│ │ ├── variables.tf
│ │ └── versions.tf
│ ├── k8s-cluster
│ │ ├── stacks
│ │ │ └── dev.yaml
│ │ │ └── prod.yaml
│ │ │ └── common.yaml
│ │ ├── tfvars
│ │ │ └── dev.tfvars
│ │ │ └── prod.tfvars
│ │ ├── variables.tf
│ │ ├── main.tf
│ │ └── versions.tf
...
```

Expand All @@ -74,24 +83,31 @@ The configuration above creates the following stacks:

These stacks have the following configuration:

- Stacks track changes in GitHub repo `github.com/masterpointio/terraform-spacelift-automation`, branch `main` (default one), and directrory `root-modules`.
- Stacks track changes in GitHub repo `github.com/masterpointio/terraform-spacelift-automation`, branch `main` (the default), and directrory `root-modules`.
- Common configuration is defined in `root-modules/spacelift-aws-role/stacks/common.yaml` and applied to both Stacks. However, if there is an override in a Stack config (e.g. `root-modules/spacelift-aws-role/stacks/dev.yaml`), it takes precedence over common configs.
- Corresponding Terraform variables are generated by [Initialization Hook](https://docs.spacelift.io/concepts/run#initializing) and placed in the root of each Stack's working directory during each run or task. For example, the content of the file `root-modules/spacelift-aws-role/tfvars/dev.tfvars` will be copied to working directory of the Stack `spacelift-aws-role-dev` as file `spacelift.auto.tfvars` allowing the OpenTofu/Terraform inputs to be automatically loaded.
- Corresponding Terraform variables are generated by an [Initialization Hook](https://docs.spacelift.io/concepts/run#initializing) and placed in the root of each Stack's working directory during each run or task. For example, the content of the file `root-modules/spacelift-aws-role/tfvars/dev.tfvars` will be copied to working directory of the Stack `spacelift-aws-role-dev` as file `spacelift.auto.tfvars` allowing the OpenTofu/Terraform inputs to be automatically loaded.

## FAQs

### Why are variable values provided separately in `tfvars/` and not in the `yaml` file?

This is to support easy local and outside-spacelift operations. Keeping variable values in a `tfvars` file per workspace allows you to simply pass that file to the relevant CLI command locally via the `-var-file` option so that you don't need to provide values individually.

## Can I create a Stack for Spacelift Automation?
### Can I create a Spacelift Stack for Spacelift Automation? (Recommended)

Spacelift Automation can manage itself as a Stack as well. Follow the next steps to achieve that:
Spacelift Automation can manage itself as a Stack as well and we recommend this so you can fully automate your Stack management on merge to your given branch. Follow these next steps to achieve that:

1. Create a vanilla OpenTofu/Terraform configuration for this module. In other words, a configuration that uses the default capabilities of either OpenTofu or Terraform without any customization, complex logic, or third-party modules or plugins.
1. Create Terraform workspace that will be used for your Automation configuration, e.g.:
1. Create a new vanilla OpenTofu/Terraform root module that consumes this child module and supplies the necessary configuration for your unique setup. In other words, it's a configuration that uses the default capabilities of either OpenTofu or Terraform without any customization, or third-party tools or plugins.
2. Optionally, Create Terraform workspace that will be used for your Automation configuration, e.g.:
```sh
tofu workspace new masterpoint
```
1. Apply the vanilla OpenTofu/Terraform configuration.
1. Move the Automation configs to the `<root-modules>/spacelift-automation/stacks` directory and push the changes to the tracked repo and branch.
1. From this moment Spacelift Automation is tracking the changes for its Stack configs and Terraform variables.
Remember, that Stack config and tfvars file name must be equal to the workspace, which can be `default`.
3. Apply the vanilla OpenTofu/Terraform configuration.
4. Move the Automation configs to the `<root-modules>/spacelift-automation/stacks` directory and push the changes to the tracked repo and branch.
5. From this moment Spacelift Automation is tracking the changes for its Stack configs and Terraform variables.

NOTE to Masterpoint team: We might want to create a small wrapper to automatize this using Taskit.
NOTE to Masterpoint team: We might want to create a small wrapper to automatize this using Taskit. On hold for now.

<!-- BEGINNING OF PRE-COMMIT-TERRAFORM DOCS HOOK -->

Expand All @@ -106,7 +122,7 @@ NOTE to Masterpoint team: We might want to create a small wrapper to automatize

| Name | Version |
| ------------------------------------------------------------------ | ------- |
| <a name="provider_spacelift"></a> [spacelift](#provider_spacelift) | >= 1.14 |
| <a name="provider_spacelift"></a> [spacelift](#provider_spacelift) | 1.16.1 |

## Modules

Expand All @@ -117,12 +133,12 @@ NOTE to Masterpoint team: We might want to create a small wrapper to automatize

## Resources

| Name | Type |
| ------------------------------------------------------------------------------------------------------------------------------------------------------------ | -------- |
| [spacelift_aws_integration_attachment.this](https://registry.terraform.io/providers/spacelift-io/spacelift/latest/docs/resources/aws_integration_attachment) | resource |
| [spacelift_drift_detection.this](https://registry.terraform.io/providers/spacelift-io/spacelift/latest/docs/resources/drift_detection) | resource |
| [spacelift_stack.this](https://registry.terraform.io/providers/spacelift-io/spacelift/latest/docs/resources/stack) | resource |
| [spacelift_stack_destructor.this](https://registry.terraform.io/providers/spacelift-io/spacelift/latest/docs/resources/stack_destructor) | resource |
| Name | Type |
| --------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------- |
| [spacelift_aws_integration_attachment.default](https://registry.terraform.io/providers/spacelift-io/spacelift/latest/docs/resources/aws_integration_attachment) | resource |
| [spacelift_drift_detection.default](https://registry.terraform.io/providers/spacelift-io/spacelift/latest/docs/resources/drift_detection) | resource |
| [spacelift_stack.default](https://registry.terraform.io/providers/spacelift-io/spacelift/latest/docs/resources/stack) | resource |
| [spacelift_stack_destructor.default](https://registry.terraform.io/providers/spacelift-io/spacelift/latest/docs/resources/stack_destructor) | resource |

## Inputs

Expand Down Expand Up @@ -180,8 +196,8 @@ NOTE to Masterpoint team: We might want to create a small wrapper to automatize
| <a name="input_tags"></a> [tags](#input_tags) | Additional tags (e.g. `{'BusinessUnit': 'XYZ'}`).<br>Neither the tag keys nor the tag values will be modified by this module. | `map(string)` | `{}` | no |
| <a name="input_tenant"></a> [tenant](#input_tenant) | ID element \_(Rarely used, not included by default)\_. A customer identifier, indicating who this instance of a resource is for | `string` | `null` | no |
| <a name="input_terraform_smart_sanitization"></a> [terraform_smart_sanitization](#input_terraform_smart_sanitization) | Indicates whether runs on this will use terraform's sensitive value system to sanitize<br>the outputs of Terraform state and plans in spacelift instead of sanitizing all fields. | `bool` | `false` | no |
| <a name="input_terraform_version"></a> [terraform_version](#input_terraform_version) | Terraform version to use. | `string` | `"1.7.2"` | no |
| <a name="input_terraform_workflow_tool"></a> [terraform_workflow_tool](#input_terraform_workflow_tool) | Defines the tool that will be used to execute the workflow.<br>This can be one of OPEN_TOFU, TERRAFORM_FOSS or CUSTOM. Defaults to TERRAFORM_FOSS. | `string` | `"OPEN_TOFU"` | no |
| <a name="input_terraform_workflow_tool"></a> [terraform_workflow_tool](#input_terraform_workflow_tool) | Defines the tool that will be used to execute the workflow.<br>This can be one of OPEN_TOFU, TERRAFORM_FOSS or CUSTOM. | `string` | `"OPEN_TOFU"` | no |
| <a name="input_tf_version"></a> [tf_version](#input_tf_version) | Terraform version to use. | `string` | `"1.7.2"` | no |
| <a name="input_worker_pool_id"></a> [worker_pool_id](#input_worker_pool_id) | ID of the worker pool to use.<br>NOTE: worker_pool_id is required when using a self-hosted instance of Spacelift. | `string` | `null` | no |

## Outputs
Expand Down
Loading

0 comments on commit ae4fe7c

Please sign in to comment.