DOCSEARCHbyAlgolia
Submit Docs

burrito

repository·main·Indexed 20 days ago

https://github.com/padok-team/burrito

A Kubernetes Operator acting as Terraform Automation Collaboration Software (TACoS). Burrito automates Terraform workflows, including continuous planning, apply execution, and PR/MR integration, while providing a Web UI to visualize state changes and address state drift.

Tokens
40.3K
Snippets
123
Records
171
Agent score
72%

What's inside burrito

  1. Overview of Burrito (TACoS)

    main

    Burrito is a TACoS (Terraform Automation Collaboration Software) Kubernetes Operator. It is designed to manage Terraform infrastructure-as-code (IaC) by addressing state drift, simplifying CI/CD pipeline configuration, and providing visibility into state modifications through a Web UI.

    Key capabilities include:

    • Continuous Planning: Automatically plans Terraform code and executes applies when necessary.
    • PR/MR Integration: Provides out-of-the-box integration for Pull Requests and Merge Requests, eliminating the need for custom Terraform CI/CD pipelines.
    • State Visualization: A Web UI that allows users to navigate and understand the modifications made during terraform apply operations.

  2. What is Burrito?

    main
    Burrito is a TACoS (Terraform Automation Collaboration Software) Kubernetes Operator. It is designed to manage and automate Infrastructure as Code (IaC) in a Kubernetes-native way, functioning similarly to how ArgoCD manages applications. It provides a centralized way to handle Terraform-based workflows within a Kubernetes cluster.

  3. Overview of Burrito UI Homepage features

    main

    The Burrito UI homepage provides a high-level overview of all registered Terraform layers. Each layer is represented as a card containing:

    • Namespace: The Kubernetes namespace.
    • Repository: The source code repository.
    • Branch: The git branch being used.
    • Code path: The directory path within the repository.
    • Last plan result: The outcome of the most recent plan.
    • State: The current synchronization status, which can be Error, Out-of-sync, or OK.

  4. What are Sync Windows and how do they work?

    main

    Sync windows allow you to control when Burrito can execute plan, apply, or both actions on specific Terraform layers. They are used to restrict operations during certain timeframes, such as business hours or maintenance windows.

    Core Logic

    • No window defined: The layer is always allowed to be applied.
    • deny window: The layer is blocked from the specified actions during the window.
    • allow window: The layer is only permitted to perform the specified actions during the window.
    • Conflict Resolution: If multiple windows overlap for the same layer, a deny window always takes precedence over an allow window.
    • Action Scoping: A window only affects the actions explicitly listed in its actions field. If actions is omitted, the window applies to nothing.
    # Example of the logic applied to a layer
syncWindows:
  - kind: allow
    schedule: "0 9 * * *"
    duration: "8h"
    layers: ["prod*"]
    actions: ["apply"]
  - kind: deny
    schedule: "0 12 * * *"
    duration: "1h"
    layers: ["prod*"]
    actions: ["apply"]
# Result: 'prod*' layers can only apply during 09:00-12:00 and 13:00-17:00. 
# The 12:00-13:00 window is blocked by the 'deny' rule.

  5. Understand the Burrito architectural components

    main

    Burrito is composed of several specialized Kubernetes Controllers and a Datastore to manage Terraform lifecycles:

    • The Server: A REST server that exposes the API for the Web UI and listens for Git webhook events.
    • The Repository Controller: A Kubernetes Controller managing TerraformRepository resources. It handles Git authentication, fetches branch metadata/commits, creates Git bundles for code distribution, and tracks synchronization state.
    • The Layer Controller: A Kubernetes Controller monitoring TerraformLayer resources. It detects drift by running terraform plan and can trigger terraform apply when necessary or when new commits are detected.
    • The Run Controller: A Kubernetes Controller monitoring TerraformRun resources. It manages the execution of plan and apply commands by creating runner pods, handling retries, and managing Kubernetes Leases to prevent concurrent Terraform commands on the same layer.
    • The Datastore: An HTTP proxy used by runners to upload/download Terraform plan files, runner logs, and Git bundles.

  6. Configure Datastore authentication and authorization

    main

    Authentication

    Cloud provider implementations (S3, GCS, Azure) use the default credentials chain of the respective SDKs. You can specify credentials by updating the datastore.serviceAccount.metadata field with appropriate annotations (e.g., iam.amazonaws.com/role for AWS).

    Authorization

    Authorization is handled via TokenReview and mounted volumes. Burrito uses a custom audience for TokenReview to ensure tokens are scoped specifically to the Datastore.

  7. Summary of scheduling knobs by optimization goal

    main

    Choose your scheduling configuration based on your primary objective:

    GoalStrategy
    Cost controlLower maxConcurrentRunnerPods; use cheaper or autoscaled nodes for runners.
    Lower latencySpread datastore and hermitcrab close to runner zones; set trafficDistribution: PreferSameZone on their Services.
    IsolationSeparate runners from controllers, server, and datastore using dedicated node pools.
    ResilienceUse topologySpreadConstraints and anti-affinity for shared multi-replica components.

  8. How TerraformLayer states and conditions work

    main

    The TerraformLayer controller uses Kubernetes conditions to determine the state of a layer.

    Conditions

    • IsPlanArtifactUpToDate: Used for drift detection by comparing the last terraform plan timestamp (stored in an annotation) with the current date.
    • IsApplyUpToDate: Checks if an apply is needed by comparing the checksum of the last planned binary against the last applied binary (stored in annotations).
    • IsLastRelevantCommitPlanned: Checks if a new commit requires a plan by comparing the last planned commit, the last commit introducing changes, and the last commit on the branch (stored in annotations).

    States

    • Idle: No runner is currently needed.
    • PlanNeeded: Burrito needs to start a plan runner.
    • ApplyNeeded: Burrito needs to start an apply runner.

    Note: If using the dry remediation strategy, a layer will remain in ApplyNeeded until it no longer needs to enter PlanNeeded.

  9. How Git Bundles work in Burrito

    main

    Instead of runners performing a full git clone of a repository, Burrito uses Git Bundles. A bundle is a single file containing all necessary Git objects (commits, trees, blobs) for a specific branch or revision.

    Benefits of using Bundles:

    • Efficiency: Only necessary objects are transferred.
    • Security: Runners do not need direct network access to the Git provider; they only need access to the Burrito datastore.
    • Performance: Unpacking a bundle is faster than a standard clone.
    • Portability: Bundles act as single-file snapshots of a specific state.

    Lifecycle: The controller creates the bundle and stores it in the datastore with metadata (namespace, name, branch, and revision). When a runner starts, it requests the specific bundle for the required branch and revision, then unpacks it locally.

  11. How the Repository Controller manages TerraformRepository resources

    main

    The Repository Controller is a component in Burrito that manages the lifecycle of TerraformRepository resources. It automates the process of connecting to Git providers, tracking branch changes, and preparing code for runners.

    Core Workflow:

    1. Authentication: Connects to the Git provider using provided credentials.
    2. Revision Detection: Monitors branches to identify the latest commit SHA (revision).
    3. Bundle Creation: Generates Git bundles for specific branches to optimize data transfer.
    4. Distribution: Stores these bundles in a datastore so runners can access code without direct Git access.
    5. Status Updates: Updates the TerraformRepository resource status with the latest branch and revision information.

  12. Use overrideRunnerSpec to customize the runner pod

    main

    The overrideRunnerSpec field in the TerraformLayer specification allows you to modify the default runner pod specification. This is primarily used to inject custom configurations required for private resources, such as:

    • Volumes: Adding secret or configMap volumes containing credentials or configuration files.
    • VolumeMounts: Mounting those volumes into specific paths (e.g., /home/burrito/.ssh/ or /home/burrito/.terraform.d/).
    • Environment Variables: Setting variables like GIT_SSH_COMMAND or TF_CLI_CONFIG_FILE to instruct tools how to use the mounted files.