# gruntwork-io/cloud-nuke architecture

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

- Interactive diagram: https://gitdiagram.com/gruntwork-io/cloud-nuke
- Repository: https://github.com/gruntwork-io/cloud-nuke

## Overview

##### Project Type & Purpose
- cloud-nuke is an open-source CLI utility designed to help users clean up AWS resources. Its primary functions are to safely inspect and delete (nuke) various AWS resource types based on user configuration or command-line options.
- It provides both a destructive “nuke” mode for cleaning up test or unused accounts and a non-destructive “inspect” mode, with additional filtering (e.g., by resource age, region, or tags).

##### Key Components
a. CLI Interface
- A command-line interface that parses user input/flags (located in the “commands” directory) and dispatches execution.
- This component handles arguments like resource types, region filtering, exclude options, dry-run mode, and logging level.

b. Configuration Management
- The “config” package (with sample configurations in “config/examples”) is responsible for reading YAML configuration files that specify which resources to include or exclude.
- This module should be drawn as a configuration parser that feeds rules to the resource processing logic.

c. AWS Resource Interaction Layer
- The “aws” package is the core of cloud-nuke. It encapsulates:
- AWS API interactions (query.go, resource.go, region.go).
- Individual resource modules (found in “aws/resources/”) for each supported AWS resource.
- Testing packages for each module, ensuring robust handling of AWS responses.
- This component should be depicted as a modular library that abstracts AWS API calls. Consider showing submodules for:
▸ Common resource management
▸ Resource-specific logic (e.g., EC2, S3, IAM, etc.)
▸ “IsNukable” checks with DryRun capabilities, validating permissions.

d. Telemetry & Logging
- The “telemetry” package collects non-sensitive usage metrics.
- The “logging” package (with the logger.go file) manages logging details based on the chosen log level.
- As cross-cutting utilities influencing core operation, capturing run details and errors.

e. Utility & Helper Modules
- The “util” package supports context management, error handling, string and time utilities.
- Additionally, components like “externalcreds” manage AWS credential configuration.

f. Report Generation & UI
- The “report” package generates summaries for operations (listing what resources were found, deleted, or would be deleted).
- The “ui” package provides additional formatting or terminal output styling.
- These are consumer-facing outputs that culminate the processing cycle.

##### Relationships & Interactions
1. User issues command (e.g., “cloud-nuke aws …”).
2. CLI parses options and invokes the commands module.
3. The commands module calls the configuration parser to load any provided YAML config.
4. With configuration in hand, the AWS layer (via packages in “aws” and “aws/resources”) is invoked to perform:
- Authentication (leveraging “externalcreds” and AWS SDK configuration).
- API queries that scan (inspect) AWS resources across regions.
- Execution of deletion based on filtering rules.
5. Throughout the process, logging and telemetry capture the operation’s details.
6. Finally, the report and UI packages format and display the results for confirmation and auditing.

- From the CLI → Configuration Manager.
- From the CLI → AWS Resource Manager.
- AWS Resource Manager communicates back to Report Generation.
- Logging and Telemetry should be shown as a “side channel” that collects events from each module.

##### Architectural Patterns & Design Principles
- Modularity: The project is structured with clear separation between AWS-specific logic, config parsing, CLI command handling, and utility functions.
- Layered Design: The user interface (CLI & UI), business logic (AWS resources scanning and deletion), and supportive layers (logging, telemetry, utility) form distinct layers.
- Dependency Injection: AWS credentials and configuration are injected (e.g., via the “externalcreds” package) to allow flexibility and testing.
- Testability: Multiple test directories (e.g., aws_test.go, various resource tests) indicate the design supports unit testing.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% User Interaction
    subgraph "User Input"
        CLI["CLI Handler"]:::cli
    end

    %% Configuration Layer
    subgraph "Configuration Layer"
        CONFIG["Config Parser"]:::config
    end

    %% AWS Operations Layer
    subgraph "AWS Operations"
        AWS["AWS Resource Manager"]:::aws
    end

    %% Output Layer
    subgraph "Output Layer"
        REPORT["Report Generator"]:::report
        UI["UI Formatter"]:::report
    end

    %% Support Services
    subgraph "Support Services"
        TELEMETRY["Telemetry"]:::telemetry
        LOGGING["Logging"]:::logging
        UTIL["Utilities & Helpers"]:::util
        CREDS["External Credentials"]:::util
    end

    %% CI/CD Pipeline
    subgraph "CI/CD Pipeline"
        CICD1["CircleCI"]:::cicd
        CICD2["GitHub Actions"]:::cicd
    end

    %% Main Flow Connections
    CLI -->|"parses"| CONFIG
    CLI -->|"invokes"| AWS
    CONFIG -->|"config_data"| AWS
    AWS -->|"result_output"| REPORT
    AWS -->|"result_output"| UI

    %% Support Logging and Telemetry (dotted connections)
    CLI ---|"logs"| LOGGING
    CONFIG ---|"logs"| LOGGING
    AWS ---|"logs"| LOGGING
    REPORT ---|"logs"| LOGGING
    UI ---|"logs"| LOGGING

    CLI ---|"metrics"| TELEMETRY
    AWS ---|"metrics"| TELEMETRY
    REPORT ---|"metrics"| TELEMETRY
    UI ---|"metrics"| TELEMETRY

    %% Utility and Credential Usage
    CLI ---|"uses"| UTIL
    CONFIG ---|"uses"| UTIL
    AWS ---|"uses"| UTIL
    AWS ---|"uses"| CREDS

    %% CI/CD Integration (side channels)
    CICD1 ---|"automates"| CLI
    CICD2 ---|"automates"| CLI

    %% Click Events for mapped components
    click CLI "https://github.com/gruntwork-io/cloud-nuke/blob/master/commands/cli.go"
    click CONFIG "https://github.com/gruntwork-io/cloud-nuke/blob/master/config/config.go"
    click AWS "https://github.com/gruntwork-io/cloud-nuke/blob/master/aws/aws.go"
    click TELEMETRY "https://github.com/gruntwork-io/cloud-nuke/blob/master/telemetry/telemetry.go"
    click LOGGING "https://github.com/gruntwork-io/cloud-nuke/blob/master/logging/logger.go"
    click UTIL "https://github.com/gruntwork-io/cloud-nuke/tree/master/util"
    click CREDS "https://github.com/gruntwork-io/cloud-nuke/blob/master/externalcreds/creds.go"
    click REPORT "https://github.com/gruntwork-io/cloud-nuke/blob/master/report/report.go"
    click UI "https://github.com/gruntwork-io/cloud-nuke/blob/master/ui/ui.go"

    %% Styles
    classDef cli fill:#ffcc00,stroke:#333,stroke-width:2px;
    classDef config fill:#ccffcc,stroke:#333,stroke-width:2px;
    classDef aws fill:#add8e6,stroke:#333,stroke-width:2px;
    classDef telemetry fill:#ffb6c1,stroke:#333,stroke-width:2px;
    classDef logging fill:#ffe4b5,stroke:#333,stroke-width:2px;
    classDef util fill:#d3d3d3,stroke:#333,stroke-width:2px;
    classDef report fill:#90ee90,stroke:#333,stroke-width:2px;
    classDef cicd fill:#dda0dd,stroke:#333,stroke-width:2px;
```
