Skip to content

example-workflows.mdx

Latest commit

 

History

History
131 lines (85 loc) · 8.71 KB

example-workflows.mdx

File metadata and controls

131 lines (85 loc) · 8.71 KB
title Example Workflows
sidebar_label Example Workflows
sidebar_position 2

import Intro from '@site/src/components/Intro'; import CodeBlock from '@theme/CodeBlock'; import CollapsibleText from '@site/src/components/CollapsibleText'; import PartialAtmosTerraformPlan from '@site/examples/legacy/snippets/.github/workflows/atmos-terraform-plan.yaml'; import PartialAtmosTerraformApply from '@site/examples/legacy/snippets/.github/workflows/atmos-terraform-apply.yaml'; import PartialAtmosTerraformDispatch from '@site/examples/legacy/snippets/.github/workflows/atmos-terraform-dispatch.yaml'; import PartialAtmosTerraformDriftDetection from '@site/examples/legacy/snippets/.github/workflows/atmos-terraform-drift-detection.yaml'; import PartialAtmosTerraformDriftRemediation from '@site/examples/legacy/snippets/.github/workflows/atmos-terraform-drift-remediation.yaml'; import PartialAtmosTerraformPlanMatrix from '@site/examples/legacy/snippets/.github/workflows/atmos-terraform-plan-matrix.yaml'; import PartialAtmosTerraformApplyMatrix from '@site/examples/legacy/snippets/.github/workflows/atmos-terraform-apply-matrix.yaml';

:::warning Deprecated These example workflows are for the legacy GitHub Actions GitOps approach.

For current examples using Atmos Native CI, see cloudposse-examples/atmos-native-ci and the Atmos CI documentation.

This content is preserved for users with existing GitHub Actions GitOps deployments. :::

Using GitHub Actions with Atmos and Terraform is fantastic because it gives you full control over the workflow. While we offer some opinionated implementations below, you are free to customize them entirely to suit your needs.

The following GitHub Workflows should be used as examples. These are created in a given Infrastructure repository and can be modified however best suites your needs. For example, the labels we've chosen for triggering or skipping workflows are noted here as "Conventions" but can be changed however you would prefer.

Atmos Terraform Plan

:::info Conventions

Use the no-plan label on a Pull Request to skip this workflow.

:::

The Atmos Terraform Plan workflow is triggered for every affected component from the Atmos Describe Affected workflow. This workflow takes a matrix of components and stacks and creates a plan for each, using the Atmos Terraform Plan composite action. For more on the Atmos Terraform Plan composite action, see the official atmos.tools documentation.

If an affected component is disabled with terraform.settings.github.actions_enabled, the component will show up as affected but all Terraform steps will be skipped. See Enabling or disabling components.

{PartialAtmosTerraformPlan}

Atmos Terraform Apply

:::info Conventions

  1. Use the auto-apply label on Pull Request to apply all plans on merge
  2. Use the no-apply label on a Pull Request to skip all workflows on merge
  3. If a Pull Request has neither label, run drift detection for only the affected components and stacks.

:::

The Atmos Terraform Apply workflow runs on merges into main. There are two different workflows that can be triggered based on the given labels.

If you attach the Apply label (typically auto-apply), this workflow will trigger the Atmos Terraform Apply composite action for every affected component in this Pull Request. For more on the Atmos Terraform Apply composite action, see the official atmos.tools documentation.

Alternatively, you can choose to merge the Pull Request without labels. If the "apply" label and the "skip" label are not added, this workflow will trigger the Atmos Drift Detection composite action for only the affected components in this Pull Request. That action will create a GitHub Issue for every affected component that has unapplied changes.

{PartialAtmosTerraformApply}

Atmos Terraform Drift Detection

:::info Max Opened Issues

Drift detection is configured to open a set number of Issues at a time. See max-opened-issues for the cloudposse/github-action-atmos-terraform-drift-detection composite action.

:::

The Atmos Terraform Drift Detection workflow runs on a schedule. This workflow will gather every component in every stack and run the Atmos Drift Detection composite action for each.

For every stack and component included with drift detection, the workflow first triggers an Atmos Terraform Plan.

  1. If there are changes, the workflow will then create or update a GitHub Issue for the given component and stack.
  2. If there are no changes, the workflow will check if there's an existing Issue. If there's an existing issue, the workflow will then mark that Issue as resolved.
{PartialAtmosTerraformDriftDetection}

Atmos Terraform Drift Remediation

:::info Conventions

Use the apply label to apply the plan for the given stack and component

:::

The Atmos Terraform Drift Remediation workflow is triggered from an open Github Issue when the remediation label is added to the Issue. This workflow will run the Atmos Terraform Drift Remediation composite action for the given component and stack in the Issue. This composite action will apply Terraform using the Atmos Terraform Apply composite action and close out the Issue if the changes are applied successfully.

The drift and remediated labels are added to Issues by the composite action directly. The drift is added to all Issues created by Atmos Terraform Drift Detection. Remediation will only run on Issues that have this label. Whereas the remediated label is added to any Issue that has been resolved by Atmos Terraform Drift Remediation.

{PartialAtmosTerraformDriftRemediation}

Atmos Terraform Dispatch

The Atmos Terraform Dispatch workflow is optionally included and is not required for any other workflow. This workflow can be triggered by workflow dispatch, will take a single stack and single component as arguments, and will run Atmos Terraform workflows for planning and applying for only the given target.

This workflow includes a boolean option for both "Terraform Plan" and "Terraform Apply":

  1. If only "Terraform Plan" is selected, the workflow will call the Atmos Terraform Plan Worker (./.github/workflows/atmos-terraform-plan-matrix.yaml) workflow to create a new planfile
  2. If only "Terraform Apply" is selected, the workflow will call the Atmos Terraform Apply Worker (./.github/workflows/atmos-terraform-apply-matrix.yaml) for the given branch. This action will take the latest planfile for the given stack, component, and branch and apply it.
  3. If both are selected, the workflow will run both actions. This means it will create a new planfile and then immediately apply it.
  4. If neither are selected, the workflow does nothing.
{PartialAtmosTerraformDispatch}

Atmos Terraform Plan Matrix (Reusable)

The Atmos Terraform Plan Matrix is reusable workflow that called by another workflows to create a terraform plan.

{PartialAtmosTerraformPlanMatrix}

Atmos Terraform Apply Matrix (Reusable)

The Atmos Terraform Apply Matrix is reusable workflow called by another workflow to apply an existing plan file.

{PartialAtmosTerraformApplyMatrix}