Add atmos describe affected CLI command. Update docs website

[Andriy Knysh (aknysh)]

what

• Add atmos describe affected CLI command
• Update docs website (https://pr-274.atmos-docs.ue2.dev.plat.cloudposse.org/cli/commands/describe/affected/)

why

• The command atmos describe affected produces a list of the affected Atmos components and stacks given two Git commits. The command compares the final component sections (after all imports and deep-merging) for all Atmos components in all stacks, and produces a list of affected (changed) components in the stacks. The command also checks the changed files b/w the two commits and checks if the Terraform/Helmfile component folders are changed.

For the first commit, the command assumes that the repo root is a Git checkout (and throws an error if the repo is not a Git repository, does not have .git folder).

The second commit is specified on the command line using the --ref and --sha flags.
The --ref flag supports all standard Git References (https://git-scm.com/book/en/v2/Git-Internals-Git-References).

the ref will be the default branch (e.g. main) and the commit SHA will point to the HEAD of the branch.

atmos describe affected  --verbose=true

Cloning repo 'https://github.com/cloudposse/atmos' into the temp dir '/var/folders/g5/lbvzy_ld2hx4mgrgyp19bvb00000gn/T/16710538942745756531'

Checking out the HEAD of the default branch

Enumerating objects: 4138, done.
Counting objects: 100% (1080/1080), done.
Compressing objects: 100% (538/538), done.
Total 4138 (delta 611), reused 854 (delta 482), pack-reused 3058

Checked out Git ref: refs/heads/master

examples

atmos describe affected
atmos describe affected --verbose=true
atmos describe affected --ref refs/heads/main
atmos describe affected --ref refs/heads/main --format json
atmos describe affected --ref refs/tags/v1.16.0 --file affected.yaml --format yaml
atmos describe affected --ref refs/heads/my-new-branch
atmos describe affected --sha 3a5eafeab90426bd82bf5899896b28cc0bab3073 --file affected.json
atmos describe affected --sha 3a5eafeab90426bd82bf5899896b28cc0bab3073

test

If the current local branch changes a component (vars or env section) in any YAML stack config files that defines configuration for the component (either inline or via imports), the command shows all the affected components/stacks and the affected section:

atmos describe affected --ref refs/heads/main

[
   {
      "stack": "tenant2-ue2-staging",
      "component_type": "terraform",
      "component": "test/test-component-override-3",
      "affected": "stack.vars"
   },
   {
      "stack": "tenant2-ue2-prod",
      "component_type": "terraform",
      "component": "test/test-component-override-3",
      "affected": "stack.vars"
   },
   {
      "stack": "tenant2-ue2-dev",
      "component_type": "terraform",
      "component": "test/test-component-override-3",
      "affected": "stack.vars"
   },
   {
      "stack": "tenant1-ue2-staging",
      "component_type": "terraform",
      "component": "test/test-component-override-3",
      "affected": "stack.vars"
   },
   {
      "stack": "tenant1-ue2-dev",
      "component_type": "terraform",
      "component": "test/test-component-override-3",
      "affected": "stack.vars"
   },
   {
      "stack": "tenant1-ue2-test-1",
      "component_type": "terraform",
      "component": "test/test-component-override-3",
      "affected": "stack.vars"
   },
   {
      "stack": "tenant1-ue2-prod",
      "component_type": "terraform",
      "component": "test/test-component-override-3",
      "affected": "stack.vars"
   }
]

If the current local branch changes any base component (including the abstract ones), the command shows all the affected real components including all the components derived from the changed base component. For example, if we changed the variables for the test/test-component (which is a base for many derived components), the command shows the affected base and all the derived components:

atmos describe affected --ref refs/heads/main

[
  {
      "stack": "tenant1-ue2-dev",
      "component_type": "terraform",
      "component": "test/test-component",
      "affected": "stack.vars"
   },
   {
      "stack": "tenant1-ue2-dev",
      "component_type": "terraform",
      "component": "test/test-component-override",
      "affected": "stack.vars"
   },
   {
      "stack": "tenant1-ue2-dev",
      "component_type": "terraform",
      "component": "test/test-component-override-2",
      "affected": "stack.vars"
   },
   {
      "stack": "tenant1-ue2-dev",
      "component_type": "terraform",
      "component": "test/test-component-override-3",
      "affected": "stack.vars"
   }
]

If the current local branch changes the env section (ENV vars) for any base or derived components, the command shows the affected real components with the affected_section: "env":

atmos describe affected --ref refs/heads/main

[
  {
      "stack": "tenant1-ue2-dev",
      "component_type": "terraform",
      "component": "test/test-component-override-3",
      "affected": "stack.env"
   },
   {
      "stack": "tenant2-ue2-dev",
      "component_type": "terraform",
      "component": "test/test-component-override-3",
      "affected": "stack.env"
   },
   {
      "stack": "tenant2-ue2-staging",
      "component_type": "terraform",
      "component": "test/test-component-override-3",
      "affected": "stack.env"
   },
   {
      "stack": "tenant1-ue2-staging",
      "component_type": "terraform",
      "component": "test/test-component-override-3",
      "affected": "stack.env"
   },
   {
      "stack": "tenant2-ue2-prod",
      "component_type": "terraform",
      "component": "test/test-component-override-3",
      "affected": "stack.env"
   },
   {
      "stack": "tenant1-ue2-prod",
      "component_type": "terraform",
      "component": "test/test-component-override-3",
      "affected": "stack.env"
   },
   {
      "stack": "tenant1-ue2-test-1",
      "component_type": "terraform",
      "component": "test/test-component-override-3",
      "affected": "stack.env"
   }
]

If the current local branch changes a Terraform or Helmfile component (in components/terraform and components/helmfile folders), the command shows all the affected Atmos components/stacks and in the affected attribute it shows "affected": "terraform" if the Terraform code for the component has been changed, or "affected": "helmfile" if the Helmfile code for the component has been changed. For example, if we change the examples/complete/components/terraform/infra/vpc/main.tffile, it will affect all the Atmos components that provision the thevpc` Terraform component:

atmos describe affected --verbose=true

Cloning repo 'https://github.com/cloudposse/atmos' into the temp dir '/var/folders/g5/lbvzy_ld2hx4mgrgyp19bvb00000gn/T/16710736261366892599'

Checking out the HEAD of the default branch

Enumerating objects: 4215, done.
Counting objects: 100% (1157/1157), done.
Compressing objects: 100% (576/576), done.
Total 4215 (delta 658), reused 911 (delta 511), pack-reused 3058

Checked out Git ref: refs/heads/master

Local repo HEAD: 7d37c1e890514479fae404d13841a2754be70cbf refs/heads/add-describe-affected-cli-command
Remote repo HEAD: 40210e8d365d3d88ac13c0778c0867b679bbba69 refs/heads/master

Changed files:
cmd/describe_affected.go
examples/complete/Dockerfile
examples/complete/components/terraform/infra/vpc/main.tf
go.mod
go.sum
internal/exec/describe_affected.go
internal/exec/describe_component.go
internal/exec/describe_stacks.go
internal/exec/utils.go
internal/exec/vendor_utils.go
pkg/config/schema.go
pkg/describe/describe_affected_test.go
website/.nvmrc
website/docs/cli/commands/describe/describe-affected.md

Affected components and stacks:

[
   {
      "stack": "tenant1-ue2-dev",
      "component_type": "terraform",
      "component": "infra/vpc",
      "affected": "component"
   },
   {
      "stack": "tenant1-ue2-dev",
      "component_type": "terraform",
      "component": "vpc",
      "affected": "component"
   },
   {
      "stack": "tenant1-ue2-dev",
      "component_type": "terraform",
      "component": "vpc/new",
      "affected": "component"
   },
   {
      "stack": "tenant1-ue2-test-1",
      "component_type": "terraform",
      "component": "infra/vpc",
      "affected": "component"
   },
   {
      "stack": "tenant1-ue2-test-1",
      "component_type": "terraform",
      "component": "vpc",
      "affected": "component"
   },
   {
      "stack": "tenant2-ue2-prod",
      "component_type": "terraform",
      "component": "infra/vpc",
      "affected": "component"
   },
   {
      "stack": "tenant2-ue2-prod",
      "component_type": "terraform",
      "component": "vpc",
      "affected": "component"
   },
   {
      "stack": "tenant1-ue2-prod",
      "component_type": "terraform",
      "component": "infra/vpc",
      "affected": "component"
   },
   {
      "stack": "tenant1-ue2-prod",
      "component_type": "terraform",
      "component": "vpc",
      "affected": "component"
   },
   {
      "stack": "tenant1-ue2-staging",
      "component_type": "terraform",
      "component": "vpc",
      "affected": "component"
   },
   {
      "stack": "tenant1-ue2-staging",
      "component_type": "terraform",
      "component": "infra/vpc",
      "affected": "component"
   },
   {
      "stack": "tenant2-ue2-dev",
      "component_type": "terraform",
      "component": "infra/vpc",
      "affected": "component"
   },
   {
      "stack": "tenant2-ue2-dev",
      "component_type": "terraform",
      "component": "vpc",
      "affected": "component"
   },
   {
      "stack": "tenant2-ue2-staging",
      "component_type": "terraform",
      "component": "vpc",
      "affected": "component"
   },
   {
      "stack": "tenant2-ue2-staging",
      "component_type": "terraform",
      "component": "infra/vpc",
      "affected": "component"
   }
]

[Matt Calhoun (mcalhoun)]

LGTM!

[Ben (Benbentwo)]

LGTM!