Atlantis

Español

English

Español

English

Apariencia

Config de atlantis.yaml a nivel de repo ​

Un archivo atlantis.yaml especificado en la raíz de un repo de Terraform te permite indicar a Atlantis la estructura de tu repo y establecer workflows personalizados.

¿Necesito un archivo atlantis.yaml? ​

Los archivos atlantis.yaml solo se requieren si deseas personalizar algún aspecto de Atlantis. La config predeterminada de Atlantis funciona para muchos usuarios sin cambios.

Lee los casos de uso para determinar si lo necesitas.

Habilitar atlantis.yaml ​

De forma predeterminada, todos los repos pueden tener un archivo atlantis.yaml, pero algunas de las keys están restringidas de forma predeterminada.

Las keys restringidas se pueden establecer en el archivo de config del repo repos.yaml del lado del servidor. Puedes habilitar atlantis.yaml para sobrescribir keys restringidas estableciendo allí la key allowed_overrides. Consulta Server Side Repo Config para más detalles.

Notas:

  • De forma predeterminada, se usa el archivo atlantis.yaml en la raíz del repo.
  • Puedes cambiar este comportamiento configurando Server Side Repo Config

DANGER

Atlantis usa la versión atlantis.yaml del pull request, similar a otros sistemas CI/CD. Si estás permitiendo a los usuarios crear workflows personalizados entonces esto significa que cualquiera que pueda crear un pull request a tu repo puede ejecutar código arbitrario en el servidor de Atlantis.

De forma predeterminada, esto no está permitido.

WARNING

Una vez que existe un archivo atlantis.yaml en un repo y uno o más projects están configurados, Atlantis no intentará determinar automáticamente dónde ejecutar plan. En su lugar, solo seguirá la configuración del proyecto. Esto significa que necesitarás definir cada proyecto en tu repo.

Si tienes muchos directorios con configuración de Terraform, cada directorio tendrá que ser definido.

Este comportamiento puede sobrescribirse estableciendo autodiscover.mode en enabled, en cuyo caso Atlantis seguirá intentando descubrir proyectos que no fueron configurados explícitamente. Si el directorio de cualquier proyecto descubierto entra en conflicto con un proyecto configurado manualmente, el proyecto configurado manualmente tendrá prioridad.

Ejemplo usando todas las keys ​

yaml
version: 3 # Available since v0.1.0
automerge: true # Available since v0.15.0
autodiscover: # Available since v0.18.0
  mode: auto
  ignore_paths:
  - some/path
delete_source_branch_on_merge: true # Available since v0.15.0
parallel_plan: true # Available since v0.17.0
parallel_apply: true # Available since v0.17.0
abort_on_execution_order_fail: true # Available since v0.17.0
projects:
- name: my-project-name # Available since v0.1.0
  branch: /main/ # Available since v0.21.0
  dir: . # Available since v0.1.0
  workspace: default # Available since v0.1.0
  terraform_distribution: terraform # Available since v0.33.0
  terraform_version: v0.11.0 # Available since v0.1.0
  delete_source_branch_on_merge: true # Available since v0.17.0
  repo_locking: true # deprecated: use repo_locks instead, Available since v0.17.0
  repo_locks: # Available since v0.17.0
    mode: on_plan
  custom_policy_check: false # Available since v0.17.0
  autoplan: # Available since v0.1.0
    when_modified: ["*.tf", "../modules/**/*.tf", ".terraform.lock.hcl"]
    enabled: true
  plan_requirements: [mergeable, approved, undiverged] # Available since v0.17.0
  apply_requirements: [mergeable, approved, undiverged] # Available since v0.17.0
  import_requirements: [mergeable, approved, undiverged] # Available since v0.17.0
  silence_pr_comments: ["apply"] # Available since v0.17.0
  execution_order_group: 1 # Available since v0.17.0
  depends_on: # Available since v0.20.0
    - project-1
  workflow: myworkflow # Available since v0.17.0
workflows: # Available since v0.1.0
  myworkflow:
    plan:
      steps:
      - run: my-custom-command arg1 arg2
      - run:
          command: my-custom-command arg1 arg2
          output: hide
      - init
      - plan:
          extra_args: ["-lock", "false"]
      - run: my-custom-command arg1 arg2
    apply:
      steps:
      - run: echo hi
      - apply
allowed_regexp_prefixes: # Available since v0.19.0
- dev/
- staging/

Ejemplo de hacer DRY de proyectos usando YAML anchors ​

yaml
projects:
   - &template
     name: template
     dir: template
     workflow: custom
     autoplan:
        enabled: true
        when_modified:
           - "./terraform/modules/**/*.tf"
           - "**/*.tf"
           - ".terraform.lock.hcl"

   - <<: *template
     name: ue1-prod-titan
     dir: ./terraform/titan
     workspace: ue1-prod

   - <<: *template
     name: ue1-stage-titan
     dir: ./terraform/titan
     workspace: ue1-stage

   - <<: *template
     name: ue1-dev-titan
     dir: ./terraform/titan
     workspace: ue1-dev

Generar proyectos automáticamente ​

Esto es útil si tienes muchos proyectos en un repositorio. Esto asume el workspace default (o ningún workspace).

Ejecuta esto en la raíz de tu repositorio. Esto usará gnu grep para buscar archivos terraform por un backend S3 (directorio terraform), recuperar la ruta del directorio, recuperar las entradas únicas, y luego usar yq para devolver el YAML de una configuración simple de directorio de proyecto que luego puede modificarse según tus preferencias.

sh
grep -P 'backend[\s]+"s3"' **/*.tf |
  rev | cut -d'/' -f2- | rev |
  sort |
  uniq |
  while read d; do \
    echo '[ {"name": "'"$d"'","dir": "'"$d"'", "autoplan": {"when_modified": ["**/*.tf.*"] }} ]' | yq -PM; \
  done

Casos de uso ​

Deshabilitar autoplanning ​

yaml
version: 3
projects:
   - dir: project1
     autoplan:
        enabled: false

Esto hará que Atlantis deje de ejecutar automáticamente plan cuando project1/ se actualiza en un pull request.

Ejecutar plans y applies en paralelo ​

yaml
version: 3
parallel_plan: true
parallel_apply: true

Esto ejecutará plans y applies para todos tus proyectos en paralelo.

Habilitar estas opciones puede reducir significativamente la duración de los plans y applies, especialmente para repositorios con muchos proyectos.

Usa --parallel-pool-size para configurar el número máximo de plans y applies que pueden ejecutarse en paralelo. El valor predeterminado es 15.

Los plans y applies en paralelo funcionan tanto entre múltiples directorios como entre múltiples workspaces.

Configurar Planning ​

Dada la estructura de directorios:

plain
.
├── modules
│   └── module1
│       ├── main.tf
│       ├── outputs.tf
│       └── submodule
│           ├── main.tf
│           └── outputs.tf
└── project1
    └── main.tf

Si quieres que Atlantis haga plan de project1/ cada vez que cualquier archivo .tf bajo module1/ cambie o cualquier archivo .tf o .tfvars bajo project1/ cambie, podrías usar la siguiente configuración:

yaml
version: 3
projects:
   - dir: project1
     autoplan:
        when_modified: ["../modules/**/*.tf", "*.tf*", ".terraform.lock.hcl"]

Nota:

  • when_modified usa la sintaxis de .dockerignore
  • Las rutas son relativas al directorio del proyecto.
  • when_modified será usado tanto por los plans automáticos como por los ejecutados manualmente.
  • when_modified seguirá funcionando para plans ejecutados manualmente incluso cuando autoplan esté deshabilitado.
  • El valor predeterminado de when_modified incluye **/*.tf*, **/*.tofu, **/*.tofu.json, **/terragrunt.hcl y **/.terraform.lock.hcl. Los valores personalizados de when_modified sobrescriben completamente estos valores predeterminados.

Soporte para Terraform Workspaces ​

yaml
version: 3
projects:
   - dir: project1
     workspace: staging
   - dir: project1
     workspace: production

Con la config anterior, cuando Atlantis determine que la configuración del directorio project1 ha cambiado, ejecutará plan para ambos workspaces staging e production.

Si quieres plan o apply para un workspace específico puedes usar

shell
atlantis plan -w staging -d project1

y

shell
atlantis apply -w staging -d project1

Usar archivos .tfvars ​

Consulta Casos de uso de Custom Workflow: Usar archivos .tfvars

Agregar argumentos extra a comandos de Terraform ​

Consulta Casos de uso de Custom Workflow: Agregar argumentos extra a comandos de Terraform

Comandos personalizados de init/plan/apply ​

Consulta Casos de uso de Custom Workflow: Comandos personalizados de init/plan/apply

Terragrunt ​

Consulta Casos de uso de Custom Workflow: Terragrunt

Ejecutar comandos personalizados ​

Consulta Casos de uso de Custom Workflow: Ejecutar comandos personalizados

Distribuciones de Terraform ​

Si deseas usar una distribución diferente de Terraform que la establecida por la flag --default-tf-version, entonces establece la key terraform_distribution:

yaml
version: 3
projects:
   - dir: project1
     terraform_distribution: opentofu

Atlantis descargará y usará automáticamente esta distribución. Los valores válidos son terraform e opentofu. Si se omite terraform_version y el proyecto usa una restricción required_version, Atlantis resuelve esa restricción contra la distribución seleccionada.

Versiones de Terraform ​

Si deseas usar una versión diferente de Terraform que la que está en PATH de Atlantis o está establecida por la flag --default-tf-version, entonces establece la key terraform_version:

yaml
version: 3
projects:
   - dir: project1
     terraform_version: 0.10.0

Atlantis descargará y usará automáticamente esta versión.

Requerir aprobaciones para producción ​

En este ejemplo, solo queremos requerir aprobaciones apply para el directorio production.

yaml
version: 3
projects:
   - dir: staging
   - dir: production
     plan_requirements: [approved]
     apply_requirements: [approved]
     import_requirements: [approved]

WARNING

plan_requirements, apply_requirements e import_requirements son keys restringidas, por lo que este repo necesitará estar configurado para que se le permita establecer esta key. Consulta Server-Side Repo Config Use Cases.

Orden de planning/applying ​

yaml
version: 3
abort_on_execution_order_fail: true
projects:
   - dir: project1
     execution_order_group: 2
   - dir: project2
     execution_order_group: 1

Con esta config anterior, Atlantis ejecuta planning/applying para project2 primero, luego para project1. Varios proyectos pueden tener el mismo execution_order_group. No se garantiza ningún orden dentro de un grupo. parallel_plan e parallel_apply respetan estos grupos de orden, por lo que el planning/applying en paralelo funciona en cada grupo uno por uno.

Si cualquier plan/apply falla y abort_on_execution_order_fail está establecido en true a nivel de repo, todos los grupos siguientes serán abortados. Para este ejemplo, si project2 falla entonces project1 no se ejecutará.

Los grupos de orden de ejecución son útiles cuando tienes dependencias entre proyectos. Sin embargo, solo son aplicables en el caso en que inicies un apply global para todos tus proyectos, es decir atlantis apply. Si inicias un apply en un solo proyecto, entonces los grupos de orden de ejecución se ignoran. Por lo tanto, la key depends_on es más útil en este caso. y puede usarse junto con grupos de orden de ejecución.

La siguiente configuración es un ejemplo de cómo usar juntos grupos de orden de ejecución y depends_on para imponer dependencias entre proyectos.

yaml
version: 3
projects:
   - name: development
     dir: .
     autoplan:
        when_modified: ["*.tf", "vars/development.tfvars"]
     execution_order_group: 1
     workspace: development
     workflow: infra
   - name: staging
     dir: .
     autoplan:
        when_modified: ["*.tf", "vars/staging.tfvars"]
     depends_on: ["development"]
     execution_order_group: 2
     workspace: staging
     workflow: infra
   - name: production
     dir: .
     autoplan:
        when_modified: ["*.tf", "vars/production.tfvars"]
     depends_on: ["staging"]
     execution_order_group: 3
     workspace: production
     workflow: infra

la funcionalidad depends_on se asegurará de que production no se aplique antes que staging, por ejemplo.

TIP

¿Qué sucede si una o más dependencias de un proyecto no están aplicadas?

Si hay uno o más proyectos en la lista de dependencias que no están en estado aplicado, los usuarios verán un mensaje de error como este: Can't apply your project unless you apply its dependencies

Config de autodiscovery ​

yaml
autodiscover:
   mode: "auto"

Lo anterior es la configuración predeterminada para autodiscover.mode. Cuando autodiscover.mode es auto, los proyectos se descubrirán solo si el repo no tiene ningún projects configurado.

yaml
autodiscover:
   mode: "disabled"

Con la config anterior, Atlantis nunca intentará descubrir proyectos, incluso cuando no haya ningún projects configurado. Esto es útil si generas dinámicamente config de Atlantis en hooks pre_workflow. Consulta Dynamic Repo Config Generation.

yaml
autodiscover:
   mode: "enabled"

Con la config anterior, Atlantis intentará incondicionalmente descubrir proyectos basándose en modified_files, incluso cuando el directorio del proyecto falte en los projects configurados en la configuración del repo. Si un proyecto descubierto tiene el mismo directorio que un proyecto que fue configurado manualmente en projects, la configuración manual tendrá prioridad.

Usa esta funcionalidad cuando algunos proyectos requieren una configuración específica en un repo con muchos proyectos, pero sigue siendo deseable que Atlantis haga plan/apply para proyectos no enumerados en la config.

Esta configuración se ignora si está configurada en el servidor, consulta Server Side Repo Config

yaml
autodiscover:
   mode: "enabled"
   ignore_paths:
      - dir/*

Autodiscover también puede configurarse para omitir directorios que coincidan con un path glob (como define el paquete de coincidencia de rutas doublestar).

Cuando ignore_paths está establecido, se aplica a:

  • Descubrimiento automático de proyectos durante autoplan e atlantis plan (sin -d)
  • atlantis apply (sin -d) al filtrar plans pendientes
  • Todos los comandos -d dirigidos (plan, apply, import, state rm, etc.) cuando autodiscovery está habilitado, si la ruta no tiene configuración explícita de proyecto

Esto hace que ignore_paths sea útil para configuraciones de múltiples instancias donde cada instancia de Atlantis administra un subárbol de directorios diferente. Por ejemplo, una instancia puede ignorar environments/prod/** mientras otra ignora environments/nonprod/**, evitando la interferencia entre instancias en comandos dirigidos.

Config de backend personalizado ​

Consulta Casos de uso de Custom Workflow: Config de backend personalizado

Referencia ​

Keys de nivel superior ​

yaml
version: 3
automerge: false
delete_source_branch_on_merge: false
projects:
workflows:
allowed_regexp_prefixes:
KeyTypeDefaultRequiredDescription
versionintnoneyesEsta key es requerida y debe establecerse en 3.
automergeboolfalsenoFusiona automáticamente el pull request cuando todos los plans están aplicados.
delete_source_branch_on_mergeboolfalsenoElimina automáticamente la rama fuente al fusionar.
projectsarray[Project][]noLista los proyectos en este repo.
workflows
(restricted)		map[string: Workflow]{}noWorkflows personalizados.
allowed_regexp_prefixesarray[string][]noLista los prefijos regexp permitidos para usar cuando se usa la flag --enable-regexp-cmd.

Project ​

yaml
name: myname
branch: /mybranch/
dir: mydir
workspace: myworkspace
execution_order_group: 0
delete_source_branch_on_merge: false
repo_locking: true # deprecated: use repo_locks instead
repo_locks:
   mode: on_plan
custom_policy_check: false
autoplan:
terraform_version: 0.11.0
plan_requirements: ["approved"]
apply_requirements: ["approved"]
import_requirements: ["approved"]
silence_pr_comments: ["apply"]
workflow: myworkflow
KeyTypeDefaultRequiredDescription
namestringnonemaybeRequerida si hay más de un proyecto con el mismo dir e workspace. Este nombre de proyecto puede usarse con la flag -p.
branchstringnonenoRegex que hace match de proyectos por la rama base del pull request (la rama en la que se fusionará el pull request). Solo se considerarán los proyectos que hagan match con la rama del PR. De forma predeterminada, todas las ramas hacen match.
dirstringnoneyesEl directorio de este proyecto relativo a la raíz del repo. Por ejemplo, si el proyecto estaba bajo ./project1 entonces usa project1. Usa . para indicar la raíz del repo.
workspacestring"default"noEl Terraform workspace del proyecto. Atlantis cambia a él en plan/apply. No /, \\, .., $, espacios en blanco ni caracteres de control, ni comenzar con - o ~.
execution_order_groupint0noÍndice del grupo de orden de ejecución. Los proyectos se ordenarán por este campo antes de planning/applying.
delete_source_branch_on_mergeboolfalsenoElimina automáticamente la rama fuente al fusionar.
repo_lockingbooltrueno(deprecated) Obtiene un bloqueo de repositorio en este proyecto al hacer plan.
repo_locksRepoLocksmode: on_plannoObtiene un bloqueo de repositorio en este proyecto en plan o apply. Consulta RepoLocks para más detalles.
custom_policy_checkboolfalsenoHabilita el uso de herramientas de policy check distintas de Conftest
autoplanAutoplannonenoUna configuración personalizada de autoplan. Si no se especifica, usará la config de autoplan. Consulta Autoplanning.
terraform_versionstringnonenoUna versión específica de Terraform para usar al ejecutar comandos para este proyecto. Debe ser compatible con Semver, p. ej. v0.11.0, 0.12.0-beta1.
plan_requirements
(restricted)		array[string]nonenoRequisitos que deben cumplirse antes de que atlantis plan pueda ejecutarse. Actualmente, los únicos requisitos soportados son approved, mergeable y undiverged. Consulta Command Requirements para más detalles.
apply_requirements
(restricted)		array[string]nonenoRequisitos que deben cumplirse antes de que atlantis apply pueda ejecutarse. Actualmente, los únicos requisitos soportados son approved, mergeable y undiverged. Consulta Command Requirements para más detalles.
import_requirements
(restricted)		array[string]nonenoRequisitos que deben cumplirse antes de que atlantis import pueda ejecutarse. Actualmente, los únicos requisitos soportados son approved, mergeable y undiverged. Consulta Command Requirements para más detalles.
silence_pr_commentsarray[string]nonenoSilencia comentarios de PR de las etapas definidas mientras preserva las verificaciones de estado del PR. Los valores soportados son: plan, apply.
workflow
(restricted)		stringnonenoUn workflow personalizado. Si no se especifica, Atlantis usará su workflow predeterminado.

TIP

Un proyecto representa un estado de Terraform. Típicamente, hay un estado por directorio y workspace; sin embargo, es posible tener múltiples estados en el mismo directorio usando terraform init -backend-config=custom-config.tfvars. Atlantis soporta esto, pero requiere que se especifique la key name. Consulta Custom Backend Config para más detalles.

Autoplan ​

yaml
enabled: true
when_modified: ["*.tf", "terragrunt.hcl", ".terraform.lock.hcl"]
KeyTypeDefaultRequiredDescription
enabledbooleantruenoSi autoplanning está habilitado para este proyecto.
when_modifiedarray[string]see belownoUsa la sintaxis de .dockerignore. Si cualquier archivo modificado en el pull request hace match, se hará plan de este proyecto. Consulta Autoplanning. Las rutas son relativas al directorio del proyecto.

Patrones predeterminados de when_modified: ["**/*.tf*", "**/*.tofu", "**/*.tofu.json", "**/terragrunt.hcl", "**/.terraform.lock.hcl"]. Los valores personalizados de when_modified sobrescriben completamente estos valores predeterminados. El valor predeterminado es global (no depende de la distribución).

RepoLocks ​

yaml
mode: on_apply
KeyTypeDefaultRequiredDescription
modeModeon_plannoSi los bloqueos de repositorio están habilitados o no para este proyecto en plan o apply. Los valores válidos son disabled, on_plan e on_apply.

Copyright Atlantis a Series of LF Projects, LLC. Para los términos de uso del sitio web, la política de marcas y otras políticas del proyecto, consulta LF Projects, LLC Policies.