# buildkite/agent architecture

> Architecture diagram of the GitHub repository buildkite/agent, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-01-16). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/buildkite/agent
- Repository: https://github.com/buildkite/agent

## Overview

##### Core Components (Main Layer)
- Agent Core (from /agent directory)
- Job Runner (from /agent/job_runner.go)
- API Client (from /api directory)
- CLI Command Interface (from /clicommand directory)

##### Integration Layer
- Buildkite.com API (primary connection)
- Cloud Provider Metadata Services (AWS EC2, GCP, ECS)
- Container Platforms (Kubernetes, Docker)
- Artifact Storage (S3, GCS, Azure Blob)

##### Job Execution Layer
- Components from /internal/job:
- Job Executor
- Git Checkout System
- Plugin System
- Hook System
- Docker Integration

##### Supporting Systems
- Logging System (/logger)
- Metrics Collection (/metrics)
- Process Management (/process)
- Lock Management (/lock)
- Status Monitoring (/status)

Use these visual elements:

##### Plugin Architecture
- How the agent supports extensibility through plugins
- Plugin interface from /agent/plugin

##### Job Pipeline
- Flow from job reception to execution
- Hook points in the pipeline

##### Multi-platform Support
- Platform-specific components
- Container integration points

##### Security Layer
- Authentication mechanisms
- OIDC integration points
- Credential management

Additional Considerations:

##### Integration points for
- CI/CD systems
- Source control systems
- Artifact storage systems

##### Observability components
- Logging
- Metrics
- Status reporting

## Diagram (Mermaid)

```mermaid
graph TB
    subgraph Legend
        A[Service]:::core --- B[External Service]:::external
        C[(Storage)]:::storage --- D([Supporting System]):::support
        E{Security Component}:::security
        style Legend fill:#f5f5f5,stroke:#333
    end

    subgraph Core["Core Components"]
        AgentCore[Agent Core]:::core
        JobRunner[Job Runner]:::core
        APIClient[API Client]:::core
        CLI[CLI Interface]:::core
    end

    subgraph External["Integration Layer"]
        BuildkiteAPI[Buildkite.com API]:::external
        AWS[AWS EC2 Metadata]:::external
        GCP[GCP Metadata]:::external
        K8s[Kubernetes]:::external
        Docker[Docker Platform]:::external
        S3[(S3 Storage)]:::storage
        GCS[(GCS Storage)]:::storage
        Azure[(Azure Blob)]:::storage
    end

    subgraph JobExec["Job Execution Layer"]
        Executor[Job Executor]:::exec
        GitSystem[Git Checkout]:::exec
        PluginSys[Plugin System]:::exec
        HookSystem[Hook System]:::exec
        DockerInt[Docker Integration]:::exec
        Pipeline[Pipeline Management]:::exec
    end

    subgraph Support["Supporting Systems"]
        Logger([Logging System]):::support
        Metrics([Metrics Collection]):::support
        Process([Process Management]):::support
        Lock([Lock Management]):::support
        Status([Status Monitoring]):::support
    end

    subgraph Security["Security Layer"]
        OIDC{OIDC Integration}:::security
        Artifacts{Artifact System}:::security
    end

    %% Core Connections
    AgentCore --> JobRunner
    AgentCore --> APIClient
    AgentCore --> CLI
    JobRunner --> Executor
    APIClient --> BuildkiteAPI
    
    %% Job Execution Connections
    Executor --> GitSystem
    Executor --> PluginSys
    Executor --> HookSystem
    Executor --> DockerInt
    Executor --> Pipeline
    
    %% External Service Connections
    APIClient -.-> AWS
    APIClient -.-> GCP
    DockerInt -.-> Docker
    DockerInt -.-> K8s
    
    %% Storage Connections
    Artifacts -.-> S3
    Artifacts -.-> GCS
    Artifacts -.-> Azure
    
    %% Security Connections
    APIClient --> OIDC
    Executor --> Artifacts
    
    %% Support System Connections
    AgentCore --> Logger
    AgentCore --> Metrics
    AgentCore --> Process
    AgentCore --> Lock
    AgentCore --> Status

    %% Styling
    classDef core fill:#b3d9ff,stroke:#333
    classDef external fill:#90EE90,stroke:#333
    classDef exec fill:#FFB366,stroke:#333
    classDef support fill:#E6E6E6,stroke:#333
    classDef security fill:#FF9999,stroke:#333
    classDef storage fill:#DEB887,stroke:#333

    %% Click Events
    click AgentCore "https://github.com/buildkite/agent/tree/main/agent"
    click JobRunner "https://github.com/buildkite/agent/blob/main/agent/job_runner.go"
    click APIClient "https://github.com/buildkite/agent/tree/main/api"
    click CLI "https://github.com/buildkite/agent/tree/main/clicommand"
    click Executor "https://github.com/buildkite/agent/blob/main/internal/job/executor.go"
    click GitSystem "https://github.com/buildkite/agent/blob/main/internal/job/git.go"
    click PluginSys "https://github.com/buildkite/agent/tree/main/agent/plugin"
    click HookSystem "https://github.com/buildkite/agent/tree/main/internal/job/hook"
    click DockerInt "https://github.com/buildkite/agent/blob/main/internal/job/docker.go"
    click Logger "https://github.com/buildkite/agent/tree/main/logger"
    click Metrics "https://github.com/buildkite/agent/tree/main/metrics"
    click Process "https://github.com/buildkite/agent/tree/main/process"
    click Lock "https://github.com/buildkite/agent/tree/main/lock"
    click Status "https://github.com/buildkite/agent/tree/main/status"
    click K8s "https://github.com/buildkite/agent/tree/main/kubernetes"
    click AWS "https://github.com/buildkite/agent/blob/main/agent/ec2_meta_data.go"
    click GCP "https://github.com/buildkite/agent/blob/main/agent/gcp_meta_data.go"
    click Artifacts "https://github.com/buildkite/agent/tree/main/internal/artifact"
    click OIDC "https://github.com/buildkite/agent/blob/main/api/oidc.go"
    click Pipeline "https://github.com/buildkite/agent/blob/main/agent/pipeline_uploader.go"
```
