Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Jump to bottom

DEV-2465: add stack locking #85

Draft
wants to merge 2 commits into
base: main
Choose a base branch
from
Draft

DEV-2465: add stack locking #85

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
9cbdacf
add stack locking
mcalhoun Aug 20, 2024
babe437
update duplicate id
mcalhoun Aug 20, 2024
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
59 changes: 40 additions & 19 deletions README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -27,7 +27,7 @@

-->

This Github Action is used to run Terraform plan for a single, Atmos-supported component and save the given planfile to S3 and DynamoDB.
This Github Action is used to run Terraform plan for a single, Atmos-supported component and save the given plan file to S3 and DynamoDB.


> [!TIP]
Expand All @@ -44,9 +44,11 @@ This Github Action is used to run Terraform plan for a single, Atmos-supported c

## Introduction

This Github Action is used to run Terraform plan for a single, Atmos-supported component and save the given planfile to S3 and DynamoDB.
This Github Action is used to run Terraform plan for a single, Atmos-supported component and save the given plan file
to S3 and DynamoDB.

After running this action, apply Terraform with the companion action, [github-action-atmos-terraform-apply](https://github.com/cloudposse/github-action-atmos-terraform-apply)
After running this action, apply Terraform with the companion action,
[github-action-atmos-terraform-apply](https://github.com/cloudposse/github-action-atmos-terraform-apply)



Expand All @@ -55,14 +57,30 @@ After running this action, apply Terraform with the companion action, [github-ac

### Prerequisites

This GitHub Action requires AWS access for two different purposes. This action will attempt to first run `terraform plan` against a given component and
then will use another role to save that given Terraform Plan to an S3 Bucket with metadata in a DynamoDB table. We recommend configuring
[OpenID Connect with AWS](https://docs.github.com/en/actions/deployment/security-hardening-your-deployments/configuring-openid-connect-in-amazon-web-services)
to allow GitHub to assume roles in AWS and then deploying both a Terraform Plan role and a Terraform State role.
For Cloud Posse documentation on setting up GitHub OIDC, see our [`github-oidc-provider` component](https://docs.cloudposse.com/components/library/aws/github-oidc-provider/).
This GitHub Action requires AWS access for two different purposes. This action will attempt to first run `terraform
plan` against a given component and then will use another role to save that given Terraform Plan to an S3 Bucket with
metadata in a DynamoDB table. We recommend configuring [OpenID Connect with
AWS](https://docs.github.com/en/actions/deployment/security-hardening-your-deployments/configuring-openid-connect-in-amazon-web-services)
to allow GitHub to assume roles in AWS and then deploying both a Terraform Plan role and a Terraform State role. For
Cloud Posse documentation on setting up GitHub OIDC, see our [`github-oidc-provider`
component](https://docs.cloudposse.com/components/library/aws/github-oidc-provider/).

In order to store Terraform State, we configure an S3 Bucket to store plan files and a DynamoDB table to track plan
metadata. Both will need to be deployed before running this action. For more on setting up those components, see the
`gitops` component (__documentation pending__). This action will then use the
[github-action-terraform-plan-storage](https://github.com/cloudposse/github-action-terraform-plan-storage) action to
update these resources.

### Atmos Pro

If you are using the stack locking feature of this action (setting `lock-stack` to `true`), you will need to sign up
for an [Atmos Pro](https://app.cloudposse.com) account and generate an API key. You can then set the `atmos-pro-token`
input variable to the value of your API key. If you are an enterprise customer and using a dedicated Atmos Pro
instance, you should also set the `atmos-pro-base-url` input variable to the base URL of your Atmos Pro instance.

> [!IMPORTANT] > **Please note!** If you are using stack locking, this GitHub Action only works with `atmos >=
1.XX.0`. If you are using `atmos < 1.XX.0` stack locking will not work..

In order to store Terraform State, we configure an S3 Bucket to store plan files and a DynamoDB table to track plan metadata. Both will need to be deployed before running
this action. For more on setting up those components, see the `gitops` component (__documentation pending__). This action will then use the [github-action-terraform-plan-storage](https://github.com/cloudposse/github-action-terraform-plan-storage) action to update these resources.

### Config

Expand All @@ -89,8 +107,8 @@ integrations:
group-by: .stack_slug | split("-") | [.[0], .[2]] | join("-")
```

> [!IMPORTANT]
> **Please note!** This GitHub Action only works with `atmos >= 1.63.0`. If you are using `atmos < 1.63.0` please use `v1` version of this action.
> [!IMPORTANT] > **Please note!** This GitHub Action only works with `atmos >= 1.63.0`. If you are using `atmos <
1.63.0` please use `v1` version of this action.

### Support OpenTofu

Expand Down Expand Up @@ -120,7 +138,7 @@ integrations:
opentofu-version: 1.7.3
...
```

### Workflow example

```yaml
Expand Down Expand Up @@ -170,11 +188,11 @@ The following configuration fields now moved to GitHub action inputs with the sa
| `atmos-config-path` |


The following configuration fields moved to the `atmos.yaml` configuration file.
The following configuration fields moved to the `atmos.yaml` configuration file.

| name | YAML path in `atmos.yaml` |
|--------------------------|-------------------------------------------------|
| `aws-region` | `integrations.github.gitops.artifact-storage.region` |
| `aws-region` | `integrations.github.gitops.artifact-storage.region` |
| `terraform-state-bucket` | `integrations.github.gitops.artifact-storage.bucket` |
| `terraform-state-table` | `integrations.github.gitops.artifact-storage.table` |
| `terraform-state-role` | `integrations.github.gitops.artifact-storage.role` |
Expand All @@ -186,7 +204,7 @@ The following configuration fields moved to the `atmos.yaml` configuration file.
| `group-by` | `integrations.github.gitops.matrix.group-by` |


For example, to migrate from `v1` to `v2`, you should have something similar to the following in your `atmos.yaml`:
For example, to migrate from `v1` to `v2`, you should have something similar to the following in your `atmos.yaml`:

`./.github/config/atmos.yaml`
```yaml
Expand Down Expand Up @@ -219,7 +237,7 @@ integrations:
stack: "plat-ue2-sandbox"
atmos-config-path: ./rootfs/usr/local/etc/atmos/
atmos-version: 1.63.0
```
```

This corresponds to the `v1` configuration (deprecated) below.

Expand All @@ -236,7 +254,7 @@ terraform-version: 1.5.2
aws-region: us-east-2
enable-infracost: false
sort-by: .stack_slug
group-by: .stack_slug | split("-") | [.[0], .[2]] | join("-")
group-by: .stack_slug | split("-") | [.[0], .[2]] | join("-")
```

And the `v1` GitHub Action Workflow looked like this.
Expand All @@ -250,7 +268,7 @@ And the `v1` GitHub Action Workflow looked like this.
stack: "plat-ue2-sandbox"
atmos-gitops-config-path: ./.github/config/atmos-gitops.yaml
```

### Migrating from `v1` to `v2`

1. `v2` drops the `component-path` variable and instead fetches if directly from the [`atmos.yaml` file](https://atmos.tools/cli/configuration/) automatically. Simply remove the `component-path` argument from your invocations of the `cloudposse/github-action-atmos-terraform-plan` action.
Expand Down Expand Up @@ -316,13 +334,16 @@ Which would produce the same behavior as in `v1`, doing this:
| Name | Description | Default | Required |
|------|-------------|---------|----------|
| atmos-config-path | The path to the atmos.yaml file | N/A | true |
| atmos-pro-base-url | The base URL for Atmos Pro | https://app.cloudposse.com | false |
| atmos-pro-token | Your API key for Atmos Pro | N/A | false |
| atmos-version | The version of atmos to install | >= 1.63.0 | false |
| branding-logo-image | Branding logo image url | https://cloudposse.com/logo-300x69.svg | false |
| branding-logo-url | Branding logo url | https://cloudposse.com/ | false |
| component | The name of the component to plan. | N/A | true |
| debug | Enable action debug mode. Default: 'false' | false | false |
| drift-detection-mode-enabled | Indicate whether this action is used in drift detection workflow. | false | true |
| infracost-api-key | Infracost API key | N/A | false |
| lock-stack | Flag to indicate if Atmos Pro stack locking should be used | false | true |
| metadata-retention-days | Infracost API key | 1 | false |
| sha | Commit SHA to plan. Default: github.sha | ${{ github.event.pull\_request.head.sha }} | true |
| stack | The stack name for the given component. | N/A | true |
Expand Down
Loading
Loading