# newrelic/open-install-library architecture

> Architecture diagram of the GitHub repository newrelic/open-install-library, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-05-26). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/newrelic/open-install-library
- Repository: https://github.com/newrelic/open-install-library

## Overview

##### Project type and purpose
- This is an open-source “install library” tool (not a typical web app). It provides:
- A command-line interface (newrelic-cli)
- A collection of YAML “recipes” for automated installation of New Relic products
- A validator component to enforce recipe schemas
- An automated test framework that provisions cloud or local environments, runs recipes, validates data ingestion, and tears down resources
- CI/CD pipelines via GitHub Actions

##### File structure
- Top-level:
- Dockerfile.validator, validator/ → Node.js validator for recipe schema
- recipes/ → YAML definitions of install recipes per product, platform, language
- test/ → test definitions (test/definitions) + ansible/Terraform-based test deploy scripts (test/deploy)
- .github/workflows/ → CI workflows (cleanup, non-regression, smoke, release)
- README.md, docs/ → user and developer documentation
- Patterns:
- Plugin-style architecture: recipes are “plugins” loaded by the CLI
- Validator enforces recipe structure against schema (validator/schema-v1.json)
- Test framework uses Deployer + Terraform + Ansible roles to verify each recipe
- Key config/build:
- validator/package.json → Node.js module
- GitHub Actions YAML → CI orchestration

##### README for additional insights
- Describes mission, usage, testing approach
- Explains test framework relies on Deployer and definitions under test/definitions

##### Main components
a. newrelic-cli
- Downloads via install.sh / install.ps1
- Loads recipes (recipes/)
- Invokes validator module
- Executes selected recipe (Ansible playbooks under recipes/)
- Calls New Relic REST API to register instrumentation
b. Validator service
- Node.js process
- Validates recipe YAML against JSON schema
c. Recipes
- YAML files per product/platform
- Mapped to Ansible roles, templates, handlers
d. Test Framework
- Definitions (test/definitions): JSON describing cloud infra needs
- Deployer (external GitHub project): provisions AWS/Azure/GCP or local resources
- Terraform & Ansible roles (test/deploy): executes recipe, runs assertions
- Validates that telemetry arrives in New Relic
e. CI/CD (GitHub Actions)
- Workflows: cleanup, validation, non-regression, smoke tests, release
- Steps: run validator → run test framework → report → publish
f. External services
- Cloud providers (AWS, Azure, GCP)
- New Relic APIs
- DNS, artifact hosting (GitHub Releases, npm for validator)

##### Relationships and interactions
- User invokes newrelic-cli → reads recipes → passes recipe to validator → if valid, CLI triggers
recipe execution
→ Ansible roles configure components on target host or provisioned infra
→ Agents forward data to New Relic APIs
- Test framework triggered by CI: definitions → Deployer → provision infra → run recipe → assertions → teardown
- CI orchestrates validator, test framework, release publication

##### Architectural patterns and design principles
- Modular/Plugin: recipes are independent modules
- Separation of concerns: CLI, validator, recipes, and tests are decoupled
- Infrastructure-as-Code: long-lived test definitions drive Terraform/Ansible provisioning
- Schema-driven validation: recipes must conform to a JSON schema
- GitOps/CI: automated pipeline ensures quality gates

##### Technologies, frameworks, libraries
- Node.js for validator
- Bash/PowerShell for CLI install script
- Ansible roles embedded in recipes and test/deploy
- Terraform (test/deploy/terraform)
- GitHub Actions for CI
- Deployer (external) for provisioning
- Docker for validator container
- YAML/JSON for recipes and definitions

##### Detail
- Data-flow directions
- Break out test framework subcomponents (definitions, deployer, Terraform, assertions)
- Validator schema file as supporting artifact

## Diagram (Mermaid)

```mermaid
graph TB
    %% CLI Layer
    subgraph "CLI Layer"
        CLI["newrelic-cli"]:::internal
        InstallScript["install.sh / install.ps1"]:::internal
    end

    %% Validator Service
    subgraph "Validator Service"
        Validator["Validator Service"]:::internal
        Schema["recipe-schema.json"]:::internal
    end

    %% Recipe Repository
    subgraph "Recipe Repository"
        Recipes["Recipes (YAML)"]:::internal
    end

    %% Test Framework
    subgraph "Test Framework"
        subgraph "Definitions"
            Defs["Test Definitions"]:::internal
        end
        Deployer["Deployer (External)"]:::external
        subgraph "Deploy Scripts"
            TD["Terraform & Ansible Roles"]:::internal
            Assertions["Assertions"]:::internal
        end
    end

    %% CI/CD
    subgraph "CI/CD (GitHub Actions)"
        CI["GitHub Actions"]:::ci
        Cleanup["cleanup.yml"]:::ci
        ValidationWF["validation.yml"]:::ci
        NonReg["nonregression.yml"]:::ci
        Smoke["smoke-eu.yml"]:::ci
        ReleaseWF["release.yml"]:::ci
        subgraph "Helper Scripts"
            MainJS["main.js"]:::ci
            PkgJSON["package.json"]:::ci
        end
    end

    %% Documentation & Examples
    subgraph "Documentation & Examples"
        DocsTF1["docs/test-framework/README.md"]:::doc
        DocsTF2["docs/test-framework/terraform.md"]:::doc
        DocsTF3["docs/test-framework/deployer.md"]:::doc
        DocsSpec1["docs/recipe-spec/spec.json"]:::doc
        DocsSpec2["docs/recipe-spec/recipe-spec.md"]:::doc
        Examples["examples/sample-linux-infrastructure.yaml"]:::doc
    end

    %% External Services
    subgraph "External Services"
        AWS["AWS"]:::external
        Azure["Azure"]:::external
        GCP["GCP"]:::external
        NR["New Relic API"]:::external
    end

    %% Connections
    CLI -->|"validate recipe"| Validator
    CLI -->|"load & execute"| Recipes
    CLI -->|"invoke install script"| InstallScript
    Recipes -->|"run Ansible roles"| AWS
    Recipes -->|"run Ansible roles"| Azure
    Recipes -->|"run Ansible roles"| GCP
    Recipes -->|"send telemetry"| NR

    CI -->|"validate recipes"| ValidationWF
    CI -->|"run cleanup"| Cleanup
    CI -->|"run non-regression tests"| NonReg
    CI -->|"run smoke tests"| Smoke
    CI -->|"publish release"| ReleaseWF
    CI -->|"invoke helper scripts"| MainJS

    CI -->|"invoke tests"| Defs
    Defs -->|"provision infra"| Deployer
    Deployer -->|"apply IaC"| TD
    TD --> AWS
    TD --> Azure
    TD --> GCP
    TD -->|"execute recipe"| Recipes
    TD -->|"run assertions"| Assertions
    Assertions -->|"verify telemetry"| NR
    Deployer -->|"teardown infra"| Deployer

    %% Click Events
    click Validator "https://github.com/newrelic/open-install-library/tree/main/validator/"
    click Schema "https://github.com/newrelic/open-install-library/blob/main/validator/schema-v1.json"
    click Recipes "https://github.com/newrelic/open-install-library/tree/main/recipes/"
    click Defs "https://github.com/newrelic/open-install-library/tree/main/test/definitions/"
    click TD "https://github.com/newrelic/open-install-library/tree/main/test/deploy/"
    click Cleanup "https://github.com/newrelic/open-install-library/blob/main/.github/workflows/cleanup.yml"
    click ValidationWF "https://github.com/newrelic/open-install-library/blob/main/.github/workflows/validation.yml"
    click NonReg "https://github.com/newrelic/open-install-library/blob/main/.github/workflows/nonregression.yml"
    click Smoke "https://github.com/newrelic/open-install-library/blob/main/.github/workflows/smoke-eu.yml"
    click ReleaseWF "https://github.com/newrelic/open-install-library/blob/main/.github/workflows/release.yml"
    click MainJS "https://github.com/newrelic/open-install-library/blob/main/.github/workflows/scripts/deployer-platform/main.js"
    click PkgJSON "https://github.com/newrelic/open-install-library/blob/main/.github/workflows/scripts/deployer-platform/package.json"
    click DocsTF1 "https://github.com/newrelic/open-install-library/blob/main/docs/test-framework/README.md"
    click DocsTF2 "https://github.com/newrelic/open-install-library/blob/main/docs/test-framework/terraform.md"
    click DocsTF3 "https://github.com/newrelic/open-install-library/blob/main/docs/test-framework/deployer.md"
    click DocsSpec1 "https://github.com/newrelic/open-install-library/blob/main/docs/recipe-spec/spec.json"
    click DocsSpec2 "https://github.com/newrelic/open-install-library/blob/main/docs/recipe-spec/recipe-spec.md"
    click Examples "https://github.com/newrelic/open-install-library/blob/main/examples/sample-linux-infrastructure.yaml"

    %% Styles
    classDef internal fill:#AED6F1,stroke:#333,stroke-width:1px
    classDef external fill:#ABEBC6,stroke:#333,stroke-width:1px
    classDef ci fill:#F9E79F,stroke:#333,stroke-width:1px
    classDef doc fill:#E8DAEF,stroke:#333,stroke-width:1px
```
