v1.67.0

Add Terraform Cloud backend. Add/update docs @aknysh (#572)

what

• Add Terraform Cloud backend
• Add docs:
  • Terraform Workspaces in Atmos
  • Terraform Backends. Describes how to configure backends for AWS S3, Azure Blob Storage, Google Cloud Storage, and Terraform Cloud

why

• Allow configuring and using the Terraform Cloud backend
• Document existing and new Atmos features

docs

Terraform Cloud backend uses a cloud block to specify which organization and workspace(s) to use.

To configure the Terraform Cloud backend in Atmos, add the following config to an Atmos manifest in _defaults.yaml:

terraform:
  backend_type: cloud
  backend:
    cloud:
      organization: "my-org"
      hostname: "app.terraform.io"
      workspaces:
        # Parameters for workspaces

For each component, you can optionally specify the workspaces.name parameter similar to the following:

components:
  terraform:
    my-component:
      # Optional backend configuration for the component
      backend:
        cloud:
          workspaces:
            name: "my-component-workspace"

If auto_generate_backend_file is set to true in the atmos.yaml CLI config file in the components.terraform section,
Atmos will deep-merge the backend configurations from the _defaults.yaml manifests and from the component itself, and will generate a backend config JSON file backend.tf.json in the component's folder, similar to the following example:

{
  "terraform": {
    "cloud": {
      "hostname": "app.terraform.io",
      "organization": "my-org",
      "workspaces": {
        "name": "my-component-workspace"
      }
    }
  }
}

Instead of specifying the workspaces.name parameter for each component in the component manifests, you can use
the {terraform_workspace} token in the cloud backend config in the _defaults.yaml manifest.
The token {terraform_workspace} will be automatically replaced by Atmos with the Terraform workspace for each component. This will make the entire configuration DRY.

terraform:
  backend_type: cloud
  backend:
    cloud:
      organization: "my-org"
      hostname: "app.terraform.io"
      workspaces:
        # The token `{terraform_workspace}` will be automatically replaced with the
        # Terraform workspace for each Atmos component
        name: "{terraform_workspace}"

v1.66.0

Add `stacks.name_template` section to `atmos.yaml`. Add `Go` templating to Atmos stack manifests @aknysh (#560)

what

• Add stacks.name_template section to atmos.yaml
• Add Go templating to Atmos stack manifests
• Update docs
  • https://atmos.tools/cli/configuration/#stacks
  • https://atmos.tools/core-concepts/stacks/templating/

why

• Add stacks.name_template section to atmos.yaml - stacks.name_template section allows greater flexibility in defining the naming convention for the top-level Atmos stacks

  • stacks.name_pattern configures the name pattern for the top-level Atmos stacks using the context variables namespace, tenant, environment and stage as the tokens. Depending on the structure of your organization, OUs, accounts and regions, set stacks.name_pattern to the following:

    • name_pattern: {stage} - if you use just one region and a few accounts (stages) in just one organization and one OU. In this case, the top-level Atmos stacks will use just the stage (account) in their names, and to provision the Atmos components in the top-level stacks, you will be executing Atmos commands like atmos terraform apply <component> --stack dev, atmos terraform apply <component> --stack staging and atmos terraform apply <component> --stack prod

    • name_pattern: {environment}-{stage} - if you have multiple regions and accounts (stages) in just one organization and one OU. In this case, the top-level Atmos stacks will use the environment (region) and stage (account) in their names, and to provision the Atmos components in the top-level stacks, you will be executing Atmos commands like atmos terraform apply <component> --stack ue2-dev, atmos terraform apply <component> --stack uw2-staging and atmos terraform apply <component> --stack ue1-prod. Note that the name_pattern can also be defined as {stage}-{environment}, in which case the Atmos commands will look like atmos terraform apply <component> --stack dev-ue2

    • name_pattern: {tenant}-{environment}-{stage} - if you have multiple regions, OUs (tenants) and accounts (stages) in just one organization. In this case, the top-level Atmos stacks will use the tenant, environment (region) and stage (account) in their names, and to provision the Atmos components in the top-level stacks, you will be executing Atmos commands like atmos terraform apply <component> --stack plat-ue2-dev, atmos terraform apply <component> --stack core-uw2-staging and atmos terraform apply <component> --stack plat-ue1-prod, where plat and core are the OUs/tenants in your organization

    • name_pattern: {namespace}-{tenant}-{environment}-{stage} - if you have a multi-org, multi-tenant, multi-account and multi-region architecture. In this case, the top-level Atmos stacks will use the namespace, tenant, environment (region) and stage (account) in their names, and to provision the Atmos components in the top-level stacks, you will be executing Atmos commands like atmos terraform apply <component> --stack org1-plat-ue2-dev, atmos terraform apply <component> --stack org2-core-uw2-staging and atmos terraform apply <component> --stack org2-plat-ue1-prod, where org1 and org2 are the organization names (defined as namespace in the corresponding _defaults.yaml config files for the organizations)

  • stacks.name_template serves the same purpose as stacks.name_pattern (defines the naming convention for the top-level Atmos stacks), but provides much more functionality. Instead of using the predefined context variables as tokens, it uses Go templates. Sprig Functions are supported as well

    • For the Go template tokens, and you can use any Atmos sections (e.g. vars, providers, settings)
      that the Atmos command atmos describe component <component> -s <stack> generates for a component in a stack.

    • name_template: "{{.vars.tenant}}-{{.vars.environment}}-{{.vars.stage}}" defines the same name pattern for the top-level Atmos stacks as name_pattern: "{tenant}-{environment}-{stage}" does

    • Since stacks.name_template allows using any variables form the vars section (and other sections), you can define
      your own naming convention for your organization or for different clouds (AWS, Azure, GCP). For example, in the
      corresponding _defaults.yaml stack manifests, you can use the following variables:

      • org instead of namespace
      • division instead of tenant
      • region instead of environment
      • account instead of stage

      Then define the following stacks.name_template in atmos.yaml:

      stacks:
        name_template: "{{.vars.division}}-{{.vars.account}}-{{.vars.region}}"

      You will be able to execute all Atmos commands using the newly defined naming convention:

      atmos terraform plan <component> -s <division-account-region>
      atmos terraform apply <component> -s <division-account-region>
      atmos describe component <component> -s <division-account-region>

      NOTE:
      Use either stacks.name_pattern or stacks.name_template to define the naming convention for the top-level Atmos stacks. stacks.name_template has higher priority. If stacks.name_template is specified, stacks.name_pattern will be ignored.

• Add Go templating to Atmos stack manifests

  Atmos supports Go templates in stack manifests. Sprig Functions are supported as well.

  You can use Go templates in the following Atmos section to refer to values in the same or other sections:

  • vars
  • settings
  • env
  • metadata
  • providers
  • overrides
  • backend
  • backend_type
  
  

  NOTE:
  In the template tokens, you can refer to any value in any section that the Atmos command atmos describe component <component> -s <stack>generates.

  For example, let's say we have the following component configuration using Go templates:

  component:
    terraform:
      vpc:
        settings:
          setting1: 1
          setting2: 2
          setting3: "{{ .vars.var3 }}"
          setting4: "{{ .settings.setting1 }}"
          component: vpc
          backend_type: s3
          region: "us-east-2"
          assume_role: "<role-arn>"
        backend_type: "{{ .settings.backend_type }}"
        metadata:
          component: "{{ .settings.component }}"
        providers:
          aws:
            region: "{{ .settings.region }}"
            assume_role: "{{ .settings.assume_role }}"
        env:
          ENV1: e1
          ENV2: "{{ .settings.setting1 }}-{{ .settings.setting2 }}"
        vars:
          var1: "{{ .settings.setting1 }}"
          var2: "{{ .settings.setting2 }}"
          var3: 3
          # Add the tags to all the resources provisioned by this Atmos component
          tags:
            atmos_component: "{{ .atmos_component }}"
            atmos_stack: "{{ .atmos_stack }}"
            atmos_manifest: "{{ .atmos_stack_file }}"
            region: "{{ .vars.region }}"
            terraform_workspace: "{{ .workspace }}"
            assumed_role: "{{ .providers.aws.assume_role }}"
            description: "{{ .atmos_component }} component provisioned in {{ .atmos_stack }} stack by assuming IAM role {{ .providers.aws.assume_role }}"
            # `provisioned_at` uses the Sprig functions
            # https://masterminds.github.io/sprig/date.html
            # https://pkg.go.dev/time#pkg-constants
            provisioned_at: '{{ dateInZone "2006-01-02T15:04:05Z07:00" (now) "UTC" }}'

  When executing Atmos commands like atmos describe component and atmos terraform plan/apply, Atmos processes all the template tokens in the manifest and generates the final configuration for the component in the stack:

  settings:
    setting1: 1
    setting2: 2
    setting3: 3
    setting4: 1
    component: vpc
    backend_type: s3
    region: us-east-2
    assume_role: <role-arn>
  backend_type: s3
  metadata:
    component: vpc
  providers:
    aws:
      region: us-east-2
      assume_role: <role-arn>
  env:
    ENV1: e1
    ENV2: 1-2
  vars:
    var1: 1
    var2: 2
    var3: 3
    tags:
      assumed_role: <role-arn>
      atmos_component: vpc
      atmos_manifest: orgs/acme/plat/dev/us-east-2
      atmos_stack: plat-ue2-dev
      description: vpc component provisioned in plat-ue2-dev stack by assuming IAM role <role-arn>
      provisioned_at: "2024-03-12T16:18:24Z"
      region: us-east-2
      terraform_workspace: plat-ue2-dev

  
  

  While Go templates in Atmos stack manifests offer great flexibility for various use-cases, one of the obvious use-cases
  is to add a standard set of tags to all the resources in the infrastructure.

  For example, by adding this configuration to the stacks/orgs/acme/_defaults.yaml Org-level stack manifest:

  terraform:
    vars:
      tags:
        atmos_component: "{{ .atmos_component }}"
        atmos_stack: "{{ .atmos_stack }}"
        atmos_manifest: "{{ .atmos_stack_file }}"
        terraform_workspace: "{{ .workspace }}"
        provisioned_at: '{{ dateInZone "2006-01-02T15:04:05Z07:00" (now) "UTC" }}'

  the tags will be processed and automatically added to all the resources provisioned in the infrastructure.

v1.65.0

Add `providers` section to Atmos manifests. Update docs @aknysh (#555)

what

• Add providers section to Atmos manifests
• Auto-generate the prefix attribute for Atmos components for Terraform backend gcs for GCP
• Update docs (https://atmos.tools/core-concepts/components/terraform-providers/)

why

Terraform utilizes plugins known as providers for communication with cloud providers, SaaS providers, and various APIs.

In order for Terraform to install these providers, the corresponding Terraform configurations need to explicitly state what providers are required. Furthermore, certain providers require additional configuration, such as specifying endpoint URLs or cloud regions, before they can be used.

Provider Configuration in Terraform

When working with Terraform, you specify provider configurations in your Terraform code. This involves declaring which providers your infrastructure requires and providing any necessary configuration parameters. These parameters may include endpoint URLs, cloud regions, access credentials, or any other provider-specific configuration parameters.

To declare a provider in Terraform, use a provider block within your Terraform configuration files, usually in a providers.tf file in the component (a.k.a. root module) directory. The provider block specifies the provider type and all the necessary configuration parameters.

Here's an AWS provider configuration example for a vpc component. The provider config is defined in the components/terraform/vpc/providers.tf file:

  provider "aws" {
    region = "us-east-2"
    assume_role = "IAM Role ARN"
  }

In this example, the aws provider block includes the region and IAM role required for Terraform to communicate with the AWS services.

By correctly defining provider configurations in your Terraform code, you ensure that Terraform can seamlessly install, configure, and use the necessary plugins to manage your infrastructure across various cloud and services.

Provider Configuration and Overrides in Atmos Manifests

Atmos allows you to define and override provider configurations using the providers section in Atmos stack manifests.
The section can be defined globally for the entire organization, OU/tenant, account, region, or per component.

For example, the providers section at the global scope can look like this:

terraform:
  providers:
    aws:
      region: "us-east-2"
      assume_role: "IAM Role ARN"

Similarly, it can be defined (or overridden) at the OU/tenant, account and region scopes in the corresponding _defaults.yaml stack manifests.

If you want to override a provider configuration for a specific component, use the component.terraform.<component>.providers section. For example, the following config can be used to override the assume_role parameter just for the vpc component:

components:
  terraform:
    vpc:
      providers:
        aws:
         assume_role: "IAM Role ARN for VPC"

You can include the providers sections in any Atmos stack manifest at any level of inheritance. Atmos will process, deep-merge and override all the providers configurations for a component in the following order:

• Global scopes (terraform.providers sections for the Org, OUs, accounts and regions)
• Base component scope (component.terraform.<base_component>.providers section)
• Current component scope (component.terraform.<component>.providers section)

Refer to Atmos Component Inheritance for more information on all types of component inheritance supported by Atmos.

When you define the providers sections, Atmos processes the inheritance chain for a component and generates a
file providers_override.tf.json in the component's folder with the final values for all the defined providers.

For example:

> atmos terraform plan vpc -s plat-ue2-prod --logs-level=Trace

Variables for the component 'vpc' in the stack 'plat-ue2-prod':
  environment: ue2
  max_subnet_count: 3
  name: common
  namespace: cp
  region: us-east-2
  stage: prod
  tenant: plat

Writing the variables to file:
components/terraform/vpc/plat-ue2-prod.terraform.tfvars.json

Writing the provider overrides to file:
components/terraform/vpc/providers_override.tf.json

The generated providers_override.tf.json file would look like this:

{
    "provider": {
      "aws": {
        "assume_role": "IAM Role ARN for VPC"
      }
    }
}

Terraform then uses the values in the generated providers_override.tf.json to override the parameters for all the providers in the file.

References

• Terraform Providers
• Terraform Override Files

v1.64.3

🚀 Enhancements

include some protection on the azurerm backend when global does not exist @aochsner (#548)

what

When using the azurerm backend, the logic assumes a global key is set and prepends that to the component key. However, when it doesn't exist it causes atmos to crash. This checks if a global key is set and if not, then don't prepend anything.

why

• don't require a global key

v1.64.2

Add Atmos CLI command aliases @aknysh (#547)

what

• Add Atmos CLI command aliases
• Update docs https://atmos.tools/cli/configuration/#aliases

why

An alias lets you create a shortcut name for an existing CLI command. Any CLI command can be aliased, including the Atmos native commands like terraform apply or describe stacks, as well as Atmos Custom Commands.

CLI command aliases are configured in the aliases section in the atmos.yaml file.

For example:

aliases:
  # Aliases for Atmos native commands
  tf: terraform
  tp: terraform plan
  up: terraform apply
  down: terraform destroy
  ds: describe stacks
  dc: describe component
  # Aliases for Atmos custom commands
  ls: list stacks
  lc: list components

Execute an alias as you would any Atmos native or custom command:

> atmos ls

plat-ue2-dev
plat-ue2-prod
plat-ue2-staging
plat-uw2-dev
plat-uw2-prod
plat-uw2-staging

The aliases configured in the aliases section automatically appear in Atmos help, and are shown as
alias for '<command>'.

For example:

An alias automatically supports all command line arguments and flags that the aliased command accepts.

For example:

• atmos up <component> -s <stack> supports all the parameters from the aliased command atmos terraform apply <component> -s <stack>
• atmos dc <component> -s <stack> supports all the parameters from the aliased command atmos describe component <component> -s <stack>

references

• closes #506

Bump the website group in /website with 1 update @dependabot (#545)

Bumps the website group in /website with 1 update: @mdx-js/react.

Updates @mdx-js/react from 3.0.0 to 3.0.1

Release notes

Sourced from @​mdx-js/react's releases.

3.0.1

Fix

• 49fd094a Fix generated JSX pragmas for new babel by @​remcohaszing in mdx-js/mdx#2438
• d1fface1 Refactor to handle uncaught webpack errors by @​remcohaszing in mdx-js/mdx#2398

Types

• c03e16c6 Add declaration maps
• 85c5dd05 Fix webpack loader types by @​remcohaszing in mdx-js/mdx#2386

Site

• 38f7a5c9 Fix reset of playground render errors by @​ManasMakde in mdx-js/mdx#2392
• 680445df Add note on broken react runtime types by @​ky1ejs in mdx-js/mdx#2383

Full Changelog: mdx-js/mdx@3.0.0...3.0.1

Commits

• 78aee48 3.0.1
• c03e16c Add declaration maps
• 0e6dd7a Update dev-dependencies
• 038bb68 Refactor some version numbers in docs
• See full diff in compare view

Dependabot will resolve any conflicts with this PR as long as you don't alter it yourself. You can also trigger a rebase manually by commenting @dependabot rebase.

---

Dependabot commands and options

You can trigger Dependabot actions by commenting on this PR:

• @dependabot rebase will rebase this PR
• @dependabot recreate will recreate this PR, overwriting any edits that have been made to it
• @dependabot merge will merge this PR after your CI passes on it
• @dependabot squash and merge will squash and merge this PR after your CI passes on it
• @dependabot cancel merge will cancel a previously requested merge and block automerging
• @dependabot reopen will reopen this PR if it is closed
• @dependabot close will close this PR and stop Dependabot recreating it. You can achieve the same result by closing it manually
• @dependabot show <dependency name> ignore conditions will show all of the ignore conditions of the specified dependency
• @dependabot ignore <dependency name> major version will close this group update PR and stop Dependabot creating any more for the specific dependency's major version (unless you unignore this specific dependency's major version or upgrade to it yourself)
• @dependabot ignore <dependency name> minor version will close this group update PR and stop Dependabot creating any more for the specific dependency's minor version (unless you unignore this specific dependency's minor version or upgrade to it yourself)
• @dependabot ignore <dependency name> will close this group update PR and stop Dependabot creating any more for the specific dependency (unless you unignore this specific dependency or upgrade to it yourself)
• @dependabot unignore <dependency name> will remove all of the ignore conditions of the specified dependency
• @dependabot unignore <dependency name> <ignore condition> will remove the ignore condition of the specified dependency and ignore conditions

🚀 Enhancements

Simplify install page @osterman (#544)

what

• Use tabs for each installation method
• Add new "installer" script installation method

why

• Make it easier to get started

v1.64.1

🚀 Enhancements

Fix responsiveness of css @osterman (#543)

what

• Use % instead of vw, since the outter container is capped at a certain px size.
• Set a minimum height of the header in px, otherwise if based on vh it can be impossibly small and gets eaten by the nav bar
• Move the footer outside of main, so it's consistent with the header.

why

• New landing page introduced in #540 wasn't tested on all screensizes

v1.64.0

Create Landing page @osterman (#540)

what

• Create a custom landing page
• Update other docs

why

• Explain what Atmos does in a few easy steps

v1.63.0

Add `integrations.github` to `atmos.yaml` @aknysh (#538)

what

• Add integrations.github to atmos.yaml
• Don't search and process stacks when executing atmos describe config command

why

• integrations.github is a free-form map section that can be used to define any configuration for GitHub (e.g. GitHub Actions). It's returned by the command atmos describe config (https://atmos.tools/cli/commands/describe/config)

v1.62.0

Add `atmos docs` CLI command @aknysh (#537)

what

• Add atmos docs CLI command

why

• Use this command to open the Atmos docs

v1.61.0

what

• Update readme to be more consistent with atmos.tools
• Fix links
• Add features/benefits
• Add use-cases
• Add glossary

why

• Better explain what atmos does and why