# dourado/packer-ansible-terrafrom-gitlab architecture

> Architecture diagram of the GitHub repository dourado/packer-ansible-terrafrom-gitlab, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-05-12). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/dourado/packer-ansible-terrafrom-gitlab
- Repository: https://github.com/dourado/packer-ansible-terrafrom-gitlab

## Overview

##### Project type and purpose
- This is an Infrastructure-as-Code (IaC) orchestration project whose goal is to fully automate the build and deployment of a private GitLab Runner on AWS.
- Key tools:
- Packer: to bake an AMI
- Ansible: to provision that AMI (install Docker, Docker Machine and GitLab-Runner)
- Terraform: to deploy the AWS resources (VPC/networking/instance) using the AMI

##### File structure
- Top-level directories:
- packer/          ← Packer template + variables + gitlab PAT
- roles/           ← Ansible roles for provisioning
– docker/        ← installs Docker & Docker Machine
– gitlab-runner/ ← installs & configures GitLab Runner
- terraform/       ← Terraform root + modules
– modules/iam    ← IAM roles & policies
– modules/key    ← Key pair setup
- Root files:
- Makefile        ← orchestrates Packer & Terraform
- README.md       ← project overview & usage
- gitlab.yaml     ← CI/CD pipeline (optional)

##### Extract additional insights from README
- Workflow:
1. Run `make`
2. Packer calls Ansible playbooks (roles/docker + roles/gitlab-runner) → produces new AMI
3. Terraform uses the new AMI to spin up an EC2 instance in the specified VPC/Subnet/Security Group
4. Manual step: register the runner with GitLab using the provided `arquivo_exemplo.toml`

a. Main components
- Developer/CI host (where you run Make, Packer, Terraform)
- Packer service
- Ansible provisioners (Docker role, GitLab-Runner role)
- AWS account:
- VPC, Subnet, Security Group
- IAM roles & key pair
- AMI (output of Packer)
- EC2 instance (GitLab Runner)
- External GitLab service

b. Relationships & interactions
1. Developer Machine → invokes Packer → AWS API (create and configure AMI)
2. Packer → calls Ansible roles (via local or remote provisioner) to install Docker & Runner into the AMI
3. Developer Machine → invokes Terraform → AWS API (use AMI to launch EC2, attach IAM, key pair, network settings)
4. New EC2 instance boots → loads GitLab Runner → registers with GitLab service (manual token step)

c. Architectural patterns & design principles
- Separation of concerns:
- Image baking (Packer) vs. provisioning software (Ansible) vs. resource orchestration (Terraform)
- Modularity:
- Ansible roles for distinct tasks
- Terraform modules for IAM and key management
- Idempotence & reproducibility:
- Every run produces the same AMI and infrastructure state

d. Key technologies & frameworks
- Packer (AMI builder)
- Ansible (roles, playbooks)
- Terraform (IaC, modules)
- AWS (EC2, IAM, VPC, Subnets, SGs)
- Docker & Docker Machine
- GitLab Runner

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Control Plane
    subgraph "Control Plane"
        Developer["Developer Machine"]:::external
        Makefile["Makefile"]:::tool
        PackerCLI["Packer CLI"]:::tool
        TerraformCLI["Terraform CLI"]:::tool
    end

    Developer --> Makefile
    Makefile --> PackerCLI
    Makefile --> TerraformCLI

    %% Build Plane
    subgraph "Build Plane"
        Packer["Packer Configuration"]:::tool
        DockerRole["Ansible Docker Role"]:::provisioner
        subgraph "GitLab-Runner Role Components"
            GLTasks["tasks/main.yml"]:::provisioner
            GLHandlers["handlers/main.yml"]:::provisioner
            GLFiles["files/gitlab_runner.sh"]:::provisioner
            GLTemplates["templates/arquivo_exemplo.toml"]:::provisioner
        end
    end

    PackerCLI --> Packer
    Packer --> DockerRole
    Packer --> GLTasks
    Packer --> GLHandlers
    Packer --> GLFiles
    Packer --> GLTemplates

    %% Runtime Plane (AWS)
    subgraph "Runtime Plane (AWS)"
        VPC["VPC/Subnet/Security Group"]:::aws
        IAM["IAM Module"]:::aws
        KeyPair["Key-Pair Module"]:::aws
        AMI["AMI (Packer Output)"]:::aws
        EC2["EC2 Instance (GitLab Runner)"]:::aws
    end

    TerraformCLI --> IAM
    TerraformCLI --> KeyPair
    TerraformCLI --> AMI
    TerraformCLI --> EC2

    AMI --> EC2
    VPC --> EC2
    IAM --> EC2
    KeyPair --> EC2

    %% External Service
    subgraph "External Service"
        GitLab["GitLab Service"]:::external
    end

    EC2 -->|"register runner (manual)"| GitLab

    %% Click Events
    click Packer "https://github.com/dourado/packer-ansible-terrafrom-gitlab/tree/main/packer/"
    click DockerRole "https://github.com/dourado/packer-ansible-terrafrom-gitlab/blob/main/roles/docker/tasks/main.yml"
    click GLTasks "https://github.com/dourado/packer-ansible-terrafrom-gitlab/blob/main/roles/gitlab-runner/tasks/main.yml"
    click GLHandlers "https://github.com/dourado/packer-ansible-terrafrom-gitlab/blob/main/roles/gitlab-runner/handlers/main.yml"
    click GLFiles "https://github.com/dourado/packer-ansible-terrafrom-gitlab/blob/main/roles/gitlab-runner/files/gitlab_runner.sh"
    click GLTemplates "https://github.com/dourado/packer-ansible-terrafrom-gitlab/blob/main/roles/gitlab-runner/templates/arquivo_exemplo.toml"
    click TerraformCLI "https://github.com/dourado/packer-ansible-terrafrom-gitlab/blob/main/terraform/main.tf"
    click IAM "https://github.com/dourado/packer-ansible-terrafrom-gitlab/blob/main/terraform/modules/iam/main.tf"
    click KeyPair "https://github.com/dourado/packer-ansible-terrafrom-gitlab/blob/main/terraform/modules/key/main.tf"
    click Makefile "https://github.com/dourado/packer-ansible-terrafrom-gitlab/tree/main/Makefile"
    click README "https://github.com/dourado/packer-ansible-terrafrom-gitlab/blob/main/README.md"
    click GitLabCI "https://github.com/dourado/packer-ansible-terrafrom-gitlab/blob/main/gitlab.yaml"

    %% Styles
    classDef tool fill:#CCE5FF,stroke:#000,stroke-width:1px
    classDef provisioner fill:#E2FFE2,stroke:#000,stroke-width:1px
    classDef aws fill:#FFD2A6,stroke:#000,stroke-width:1px
    classDef external fill:#D3D3D3,stroke:#000,stroke-width:1px
```
