The core functionality of Atlantis enables developers and operators to run terraform plan and apply directly from Terraform pull requests. Atlantis then comments back on the pull request with the output of the commands:
In simple terms:
- When developers make changes to their Terraform code and open a pull request (PR) in GitHub, GitLab, or another version control system, Atlantis automatically runs
terraform planand shows the result in the PR. - After review and approval, developers can run
terraform applyright from the PR by commenting on it. This eliminates the need for developers to manually run Terraform commands locally, making collaboration easier and more secure.
Here’s a comparison of Terraform workflows with Atlantis versus without Atlantis:
Summary:
- With Atlantis, Terraform operations are automated, more controlled, and integrated into a GitOps workflow, improving collaboration, security, and consistency across teams.
- Without Atlantis, while Terraform still works effectively, it requires more manual handling, which increases the risk of errors, inconsistencies, and slower collaboration.
| Feature/Aspect | With Atlantis | Without Atlantis |
|---|---|---|
| Collaboration | Collaborates via pull requests. Automatically comments on PRs with plan and apply results. | Manual collaboration, typically requires team members to run Terraform commands individually. |
| Automation | Automatically runs terraform plan and terraform apply on PR events. | Requires users to manually run Terraform commands on their local machines or a shared environment. |
| Approval Workflow | Changes reviewed and approved via GitOps workflow (PR reviews). Terraform applies are run only after approval. | No standardized approval workflow. Approvals and code reviews are manual and not integrated with the Terraform process. |
| CI/CD Integration | Fully integrated into CI/CD pipeline. Automatic plan on each PR and apply on approval. | CI/CD requires manual integration (scripts/automation) to trigger plan and apply. |
| Locking Mechanism | Atlantis automatically locks workspaces and PRs to prevent race conditions. | Locking has to be managed manually, often leading to potential race conditions or state file conflicts. |
| Infrastructure as Code (IaC) Visibility | PR-based workflow provides clear visibility of infrastructure changes before they are applied. | Changes are often made directly via CLI, and visibility is limited to the person making the changes unless using a separate tool. |
| Security | Enforces policies and governance on infrastructure changes. All actions are logged in the PR history. | Security depends on manual enforcement. It’s easier for users to bypass processes without a central audit log. |
| Reproducibility | Commands are run in a controlled environment (e.g., in Docker containers), ensuring consistency. | Results may vary depending on the user’s local environment, making reproducibility harder to guarantee. |
| Error Reporting | Automatically reports errors as comments in the PR, simplifying troubleshooting. | Errors must be manually communicated by the person running Terraform, making debugging slower and less transparent. |
| Complexity of Setup | Requires setting up the Atlantis server, webhooks, and permissions (initial setup can be complex). | No additional setup required beyond Terraform and your version control system, but workflows are more manual. |
| Handling Multiple Projects | Atlantis supports multiple projects with separate configurations in the same repository. | Managing multiple projects manually, requiring more complex handling of state files and environments. |
| Cost Optimization | Automates and schedules Terraform operations, reducing manual intervention and potentially avoiding unnecessary cloud resource usage. | Requires manual effort to optimize cost by running Terraform commands or adjusting schedules. |
| Auditability | Provides a full audit trail of all Terraform commands via PR history and logs. | Limited auditability. Logs are scattered and depend on manual documentation. |
| User Control | Users interact with Terraform by commenting on pull requests (e.g., atlantis plan, atlantis apply). | Users run Terraform commands manually, either locally or in a shared environment. |
| State Management | State is locked and handled centrally via Atlantis. Prevents concurrent modifications to the same resources. | Users must manually manage state file locking, leading to potential risks of conflicts and corruption. |
Use cases of Atlantis
Here are some key use cases of Atlantis for developers and software projects:
1. Collaborative Infrastructure Management (GitOps Approach)
Atlantis allows multiple developers to collaborate on infrastructure changes using pull requests (PRs). Developers can propose changes in Terraform code, and Atlantis automatically runs terraform plan and comments on the results in the PR. Once the changes are approved, terraform apply can be triggered directly from the PR, making the entire process seamless and automated.
Use Case:
A team of developers is managing cloud infrastructure. When one developer proposes a new resource or change, other team members can review the plan, suggest modifications, and approve or reject the changes directly through GitHub or GitLab.
2. Automated Terraform Plan & Apply on PR
Atlantis automates the execution of terraform plan and terraform apply when developers submit pull requests or comments. This removes the need for manual runs on developer machines, ensuring consistent infrastructure provisioning.
Use Case:
In a project, a developer adds new infrastructure in a feature branch. Upon submitting the pull request, Atlantis automatically runs terraform plan, showing potential changes in the infrastructure. The team can then review the plan and approve the changes, triggering terraform apply to provision the infrastructure.
3. State Management and Locking
Atlantis manages Terraform state files and ensures that no two developers are applying conflicting infrastructure changes at the same time. It locks the Terraform state to prevent race conditions and ensures changes are applied safely.
Use Case:
Two developers want to update different parts of the infrastructure. Without Atlantis, their simultaneous Terraform actions could corrupt the state file. With Atlantis, when one developer runs terraform apply, Atlantis locks the state file to prevent the other developer from making changes until the operation is complete.
4. Infrastructure as Code (IaC) Governance
By requiring all Terraform changes to go through pull requests, Atlantis enforces governance over the infrastructure. Every change is reviewed and approved by team members, ensuring that only validated changes are applied to the infrastructure.
Use Case:
A project has strict compliance and security requirements. All Terraform changes must be reviewed by a senior engineer. Atlantis integrates with the version control system to enforce this policy—no changes are applied until they are reviewed, ensuring governance and compliance.
5. Multi-Project or Multi-Environment Support
Atlantis supports multiple Terraform projects and environments in the same repository. This is useful for teams managing complex infrastructures with different environments (e.g., dev, staging, production).
Use Case:
In a microservices project, each service may have its own Terraform project. Atlantis can manage plans and applies for each project separately, allowing the team to work on multiple infrastructure components at the same time without conflicts.
6. CI/CD Pipeline Integration
Atlantis integrates with existing CI/CD pipelines by automating infrastructure deployment via Terraform. This allows infrastructure to be provisioned or updated automatically as part of the pipeline, ensuring that changes are applied in a controlled and consistent manner.
Use Case:
A project’s CI/CD pipeline includes a step to provision cloud infrastructure before deploying the application. Atlantis automates Terraform operations, allowing the pipeline to run terraform plan and apply based on the code changes, ensuring that the environment is always up to date.
7. Audit Trail and Security
Atlantis provides an audit trail of all Terraform operations, including who proposed, reviewed, and applied changes. This is crucial for security and compliance, especially in organizations that need to track infrastructure modifications.
Use Case:
In a financial services project, compliance requires that all infrastructure changes are tracked and auditable. With Atlantis, the PR history shows who initiated, reviewed, and approved each Terraform plan and apply operation, providing a full audit trail.
8. Decentralized Terraform Operations
Developers don’t need direct access to the cloud provider’s account or credentials to make changes. Atlantis handles the Terraform commands and applies the changes on behalf of developers, reducing the risk of unauthorized or accidental changes.
Use Case:
A company managing sensitive infrastructure restricts direct access to its cloud accounts. Developers use Atlantis to propose infrastructure changes, which are applied by the system without the developers needing access to cloud credentials, improving security.
9. Testing and Staging Environments
Atlantis can be used to manage infrastructure for test or staging environments, allowing teams to automatically provision test environments when a new branch is pushed. This ensures that infrastructure changes can be tested in isolation before being applied to production.
Use Case:
In a project, a developer opens a PR for a new feature, and Atlantis automatically provisions a test environment to validate the changes. Once the feature is tested and approved, Atlantis applies the changes to production through the same PR.
10. Drift Detection and Infrastructure Consistency
Atlantis helps ensure infrastructure consistency by continuously running terraform plan for each PR and showing what will change in the infrastructure. This can help detect infrastructure drift (where the actual infrastructure differs from the code) early.
Use Case:
A team managing a large infrastructure wants to ensure that the code matches the actual resources in the cloud. Whenever a change is proposed, Atlantis shows exactly what will be modified, helping identify any unexpected differences and ensuring that the infrastructure stays consistent.
Atlantis Walkthrough
How Atlantis Works?
Terraform Workflow Without Atlantis
Terraform Workflow With Atlantis
How Atlantis works?
Summary of How Atlantis Works:
- Webhook Trigger: Atlantis listens for pull request events via a webhook.
- Plan Execution: On PR creation or updates, Atlantis automatically runs
terraform planand posts the output in the PR for review. - Review and Approval: Team members review the changes and approve the PR.
- Apply Execution: Once approved, Atlantis runs
terraform applywhen the command is added as a comment. - State Management: Atlantis handles Terraform state locking and ensures safe, conflict-free operations.
- Auditability: Every operation is recorded in the PR, creating a clear audit trail of all infrastructure changes.
Atlantis works by integrating with Git-based version control systems (like GitHub, GitLab, or Bitbucket) to automate the process of running Terraform commands (plan and apply) as part of the GitOps workflow. Here’s a step-by-step explanation of how Atlantis works:
1. Setup and Configuration
Atlantis is deployed as a server, typically running in a container (e.g., Docker). It listens for events from your version control system (VCS), such as pull requests (PRs), which signal that Terraform changes have been made. You configure Atlantis with environment variables and settings like VCS provider credentials, repository access rules, and webhooks.
- You set up a webhook in the VCS (e.g., GitHub) that sends events (like PR creation or updates) to Atlantis.
- A configuration file (
atlantis.yaml) in the root of your repository tells Atlantis how to handle Terraform operations for different directories and environments.
2. Pull Request Creation (Terraform Plan Execution)
When a developer opens a pull request to propose infrastructure changes, Atlantis is triggered via the webhook. It automatically runs terraform plan to show what changes will be made based on the proposed code. The result of the plan is posted back as a comment on the PR.
- Example Workflow:
- Developer makes Terraform changes in a feature branch.
- They create a pull request (PR) to merge those changes into the main branch.
- The webhook triggers Atlantis.
- Atlantis runs
terraform plan, and the plan output is added as a comment in the PR.
This helps developers and reviewers see the exact changes that will be made before applying them.
3. Pull Request Review and Approval
Once the terraform plan output is available in the PR, team members can review the proposed changes. This allows for code review and infrastructure review to happen simultaneously, providing full visibility into what resources will be modified, created, or destroyed.
- Review Process:
- Reviewers can suggest changes or approve the PR.
- If approved, the developer or reviewer can trigger the next step (
terraform apply) directly from the PR.
4. Terraform Apply
After the PR is approved, Atlantis waits for a specific command (e.g., atlantis apply) to be added as a comment in the PR. This command triggers Atlantis to run terraform apply, which applies the proposed changes to the infrastructure.
- Safe Apply: By requiring explicit approval and a separate apply step, Atlantis ensures that no changes are applied until the team has reviewed and approved them.
5. State Management and Locking
Atlantis handles Terraform state and locking automatically. When it runs terraform apply, it locks the state file to prevent other operations from making concurrent changes. Once the apply is complete, the lock is released.
- This prevents race conditions where multiple users might attempt to modify the same resources simultaneously.
6. Handling Multiple Projects and Environments
Atlantis can manage multiple Terraform projects and environments in the same repository using the atlantis.yaml configuration file. You can define different workflows for each project or environment, specifying how Atlantis should run plan and apply for each.
- For example, you can have separate configurations for
dev,staging, andproductionenvironments, each with its own Terraform directory and workflow.
7. Post-Apply Workflow
Once the terraform apply command is successfully executed, Atlantis updates the PR with the results of the apply. The PR is now ready to be merged into the main branch, and the infrastructure changes have been applied.
8. Audit Trail and Logging
Atlantis provides a complete audit trail of all Terraform commands run for each PR. Every plan and apply operation is recorded as comments in the PR, providing full transparency and traceability of all infrastructure changes.
9. Custom Workflows and Policies
Atlantis allows you to define custom workflows using the atlantis.yaml file. This flexibility lets you specify the steps to be followed during the plan and apply processes. You can also enforce policy checks to ensure that all changes meet security and compliance requirements before they are applied.
Key Atlantis terminologies and their equivalent or related concepts in Terraform:
Here’s a comparison of key Atlantis terminologies and their equivalent or related concepts in Terraform:
| Atlantis Terminology | Equivalent/Related Terraform Terminology | Explanation |
|---|---|---|
| Plan | terraform plan | In Atlantis, a Plan refers to running terraform plan automatically when a pull request (PR) is created or updated. This command previews the changes without applying them. |
| Apply | terraform apply | In Atlantis, Apply refers to running terraform apply, which applies the proposed infrastructure changes. This is usually triggered after reviewing and approving a PR. |
| Autoplan | N/A (Custom Automation Feature) | Autoplan in Atlantis automatically runs terraform plan when specific files (like .tf files) are modified in a pull request. Terraform alone does not have this feature. |
| Workspace | terraform workspace | A Workspace in Atlantis corresponds to Terraform’s workspaces. It allows you to manage multiple states (e.g., for different environments like dev, staging, prod). |
| Project | N/A (Group of Terraform Configurations) | A Project in Atlantis refers to a specific directory containing Terraform code, which Atlantis will manage. Terraform doesn’t explicitly group files as projects. |
| Locking | terraform state lock (with manual actions) | Atlantis automatically handles locking the Terraform state to prevent concurrent operations. In Terraform, state locking needs to be managed manually when running commands. |
| Unlock | N/A (Manual with Terraform) | Unlock in Atlantis releases the lock on a workspace or PR if the command was not completed successfully. Terraform doesn’t have an automatic unlock system like Atlantis. |
| Webhook | N/A (VCS Integration) | Webhook in Atlantis is used to trigger actions when events (like pull request creation) happen in a VCS (GitHub, GitLab). Terraform does not have native webhook support. |
| Atlantis.yaml | N/A (Terraform doesn’t use .yaml) | The atlantis.yaml file configures how Atlantis runs Terraform commands for specific projects, directories, and workflows. Terraform uses .tf files for configurations. |
| Policy Check | Sentinel (in Terraform Enterprise), Custom Policy Integration | Atlantis can be configured to enforce policy checks before applying changes. Terraform has a similar concept using Sentinel in the enterprise version. |
| Command | Terraform CLI Commands (e.g., plan, apply, destroy) | An Atlantis Command is similar to running a Terraform command like plan, apply, or destroy from the CLI, but triggered through a PR comment. |
| Comment Command | N/A (Terraform does not use comments) | Atlantis allows users to comment on PRs with commands like atlantis plan or atlantis apply to trigger Terraform actions. Terraform CLI lacks this feature. |
| Atlantis Server | N/A (Terraform doesn’t require a server) | Atlantis Server is the backend that runs and manages Terraform commands. In Terraform, commands are typically run locally or in a CI/CD pipeline without a central server. |
| PR (Pull Request) | N/A (Separate to Terraform) | Pull Requests are how infrastructure changes are proposed and reviewed in Atlantis. Terraform does not have a native GitOps pull request workflow. |
| Run Plan in PR | terraform plan locally or in CI/CD | Atlantis runs the plan in the pull request and posts the result as a comment. In Terraform, this would be done manually or via a CI pipeline outside of Git. |
| Apply via Comment | terraform apply after review (manual or automated) | Atlantis allows apply to be triggered by commenting atlantis apply in the PR. In Terraform, you need to manually run terraform apply after the plan is reviewed. |
| VCS Integration | N/A (Handled via CI/CD) | Atlantis integrates directly with VCS providers (GitHub, GitLab, Bitbucket). In Terraform, integration with version control is typically done through CI/CD automation. |
Summary:
- Atlantis enhances Terraform workflows by automating
planandapplycommands directly in pull requests, using comments and webhooks. - While Terraform is typically run from the CLI or CI/CD pipelines, Atlantis adds a GitOps workflow layer, handling state locking, automating plans on PR changes, and offering governance features.
- Atlantis.yaml file and workflows bring more automation and project-specific controls, whereas Terraform focuses primarily on infrastructure management without direct GitOps integration.
List of All Atlantis Commands
Here’s a list of Atlantis commands with their explanation in a tabular format:
Key Notes:
- Plan commands (
atlantis plan) are used to preview infrastructure changes based on code in a pull request. - Apply commands (
atlantis apply) are used to apply changes after review and approval. - Unlock commands (
atlantis unlock) release locks on workspaces or projects if operations fail or stall. - The commands can be targeted to specific projects or workspaces, making them flexible for multi-environment or multi-project setups.
| Command | Explanation | Usage Example |
|---|---|---|
| atlantis plan | Runs terraform plan on the pull request. This command checks the Terraform code and shows what changes will be made to the infrastructure. | atlantis plan in a PR comment triggers the plan. |
| atlantis apply | Runs terraform apply on the changes proposed by terraform plan after it has been approved by reviewers. This command applies the changes to the infrastructure. | atlantis apply in a PR comment applies the approved changes. |
| atlantis unlock | Unlocks the pull request or workspace if it is stuck in a locked state due to a failed or canceled operation. | atlantis unlock frees up locked resources. |
| atlantis help | Displays help information about Atlantis and its commands. This command provides a brief description of the available commands and options. | atlantis help shows the list of commands and options. |
| atlantis version | Shows the current version of the Atlantis server that is running. This is useful for verifying the version during troubleshooting or setup. | atlantis version prints the current version. |
| atlantis apply -d <directory> | Applies changes to the specific Terraform directory specified in the command. This is useful when working with multiple Terraform directories in a repository. | atlantis apply -d /my-terraform-dir applies the changes only to that directory. |
| atlantis plan -d <directory> | Runs terraform plan for a specific directory in the repository. This command allows users to run plans only for the directory where the code has changed. | atlantis plan -d /my-terraform-dir plans changes for that directory. |
| atlantis plan -p <project> | Runs terraform plan for a specific project defined in atlantis.yaml. This is useful in repositories with multiple projects. | atlantis plan -p my-project runs a plan for a specific project. |
| atlantis apply -p <project> | Runs terraform apply for a specific project defined in atlantis.yaml. This is useful when different projects exist in the same repository. | atlantis apply -p my-project applies changes to a specific project. |
| atlantis plan -w <workspace> | Runs terraform plan for a specific workspace. Workspaces allow users to maintain different states (e.g., dev, staging, prod). | atlantis plan -w staging runs a plan for the staging workspace. |
| atlantis apply -w <workspace> | Runs terraform apply for a specific workspace. This command allows users to apply changes to a specific environment. | atlantis apply -w production applies changes to the production workspace. |
| atlantis unlock -p <project> | Unlocks a specific project in case a plan or apply operation was stuck and didn’t release the lock. | atlantis unlock -p my-project unlocks a specific project. |
| atlantis unlock -w <workspace> | Unlocks a specific workspace in case a plan or apply operation was stuck and didn’t release the lock. | atlantis unlock -w dev unlocks a specific workspace. |
| atlantis approve_policies | Approves the policy check results, if Atlantis is configured with policy checks. This command is used to bypass or accept policy results before applying the changes. | atlantis approve_policies approves the policy check results. |
- DevOps Certified Professionals (DCP)
- Site Reliability Engineering Certified Professionals (SRECP)
- Master in DevOps Engineering (MDE)
- DevSecOps Certified Professionals (DSOCP)
URL - https://www.devopsschool.com/certification/
My Linkedin - https://www.linkedin.com/in/rajeshkumarin
- Installing Jupyter: Get up and running on your computer - November 2, 2024
- An Introduction of SymOps by SymOps.com - October 30, 2024
- Introduction to System Operations (SymOps) - October 30, 2024
