# qb411/fis-template-library architecture

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

- Interactive diagram: https://gitdiagram.com/qb411/fis-template-library
- Repository: https://github.com/qb411/fis-template-library

## Overview

##### Project type and purpose
- This is an open-source repository of AWS Fault Injection Service (FIS) experiments.
- Each subdirectory under the root (e.g., aurora-cluster-failover, ec2-instances-terminate, mysql-rds-loadtest-failover, etc.) represents a distinct FIS experiment: JSON/YAML definitions, IAM policies/trust relationships, and—in some cases—CloudFormation or SSM scripts.

##### File structure
- Top level:
- README.md, CONTRIBUTING, LICENSE – repo metadata.
- Directories for each experiment (aurora-cluster-failover, ec2-spot-interruption, etc.).
- templates/ – central AWSFIS.json template plus example IAM policy/trust files.
- Per-experiment directories contain:
- AWSFIS.json or FIS experiment templates (defines targets, actions, stop conditions).
- IAM policy files (.json) and trust-relationship definitions.
- In some cases CloudFormation (e.g., mysql- and postgres-rds-loadtest-failover) and SSM scripts.
- Architectural choice: modular “Infrastructure as Code” experiments that plug into AWS FIS; each module is self-contained.

##### README for additional insights
- Purpose: simulate failure scenarios for resilience testing.
- Usage flow: checkout repo → pick experiment → customize JSON/YAML → run via AWS CLI/SDK/Console → monitor → analyze.

a. Main components
- Developer workstation / CI pipeline (GitHub repo)
- AWS CLI/SDK/Console (invokes experiments)
- AWS FIS (central orchestrator)
- Shared Templates bucket or Code repository (templates/*.json)
- IAM Roles & Policies (experiment-specific)
- AWS Targets:
– EC2 Instances (terminate, spot interruption)
– RDS Instances (MySQL, PostgreSQL failover; Aurora clusters)
– SAP components (EBS volumes, ASCS, DATABASE EC2s)
– SSM agent on targets (for executing load-test scripts or custom actions)
- Optional deployment services: CloudFormation (for load-test stacks), Systems Manager (SSM)

b. Relationships & interactions
1. Developer/CI pushes or updates templates in GitHub.
2. Operator uses AWS CLI/Console to create a new FIS experiment referencing a local or S3-hosted JSON/YAML.
3. AWS FIS service assumes the experiment’s IAM role (trust relationship) and executes defined actions on target resources.
4. FIS actions call AWS APIs to pause volumes, stop instances, inject chaos events, or trigger SSM documents.
5. For load-test experiments, FIS triggers CloudFormation to deploy test harness and SSM to run scripts.
6. Metrics and logs flow into CloudWatch or SSM Session Manager for monitoring and analysis.

c. Architectural patterns & design principles
– Modular IaC: each experiment is self-contained to simplify reuse.
– Principle of least privilege: experiment-specific IAM policies limit FIS actions.
– Decoupling: templates directory provides base definitions; experiment folders override or extend.
– Infrastructure orchestration: FIS coordinates cross-service calls via IAM to minimize direct manual intervention.

d. Relevant technologies
– AWS FIS (service orchestrator)
– AWS IAM (policies & roles)
– AWS CloudFormation (deploy load-test stacks)
– AWS Systems Manager (execute scripts via SSM documents)
– AWS CLI/SDK/Console (trigger experiments)
– JSON/YAML templates (experiment definitions)

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% Repository and CI
    subgraph "Repository (GitHub)" 
        direction TB
        RepoMeta["Metadata & CI"]:::repo
        Templates["Shared Templates Module"]:::repo
        subgraph "Experiments Modules"
            direction TB
            Aurora["Aurora Cluster Failover"]:::module
            EC2Term["EC2 Instances Termination"]:::module
            EC2Spot["EC2 Spot Interruption"]:::module
            MySQLRT["MySQL RDS Load-Test & Failover"]:::module
            PostgresRT["PostgreSQL RDS Load-Test & Failover"]:::module
            SAP_EBS["SAP EBS Pause (DB Data)"]:::module
            SAP_ASCS["SAP EC2 Stop – ASCS"]:::module
            SAP_DB["SAP EC2 Stop – Database"]:::module
        end
    end

    Developer["Developer/CI Pipeline"]:::client
    Operator["Operator (AWS CLI/Console)"]:::client

    AWSFIS["AWS FIS Service"]:::aws
    IAM["AWS IAM (Roles & Policies)"]:::aws
    CFN["AWS CloudFormation"]:::aws
    SSM["AWS Systems Manager"]:::aws

    subgraph "Target Resources"
        direction TB
        EC2["EC2 Instances"]:::target
        RDS["RDS Instances (MySQL/Postgres/Aurora)"]:::target
        SAPComp["SAP Components (EBS, ASCS, DB EC2)"]:::target
    end

    Monitoring["CloudWatch Metrics & Logs / SSM Session Manager"]:::monitor

    %% Relationships
    Developer -->|push/update| RepoMeta
    Developer -->|push/update| Templates
    Developer -->|push/update| Aurora
    Developer -->|push/update| EC2Term
    Developer -->|push/update| EC2Spot
    Developer -->|push/update| MySQLRT
    Developer -->|push/update| PostgresRT
    Developer -->|push/update| SAP_EBS
    Developer -->|push/update| SAP_ASCS
    Developer -->|push/update| SAP_DB

    Operator -->|fis:StartExperiment| AWSFIS
    Templates -->|referenced by| AWSFIS
    Aurora -->|experiment template| AWSFIS
    EC2Term -->|experiment template| AWSFIS
    EC2Spot -->|experiment template| AWSFIS
    MySQLRT -->|experiment template| AWSFIS
    PostgresRT -->|experiment template| AWSFIS
    SAP_EBS -->|experiment template| AWSFIS
    SAP_ASCS -->|experiment template| AWSFIS
    SAP_DB -->|experiment template| AWSFIS

    AWSFIS -->|AssumeRole| IAM
    AWSFIS -->|API calls| EC2
    AWSFIS -->|API calls| RDS
    AWSFIS -->|API calls| SAPComp
    AWSFIS -->|Trigger Stack| CFN
    CFN -->|deploy test harness| SSM
    SSM -->|Run scripts| SAPComp
    AWSFIS -->|invoke SSM documents| SSM

    AWSFIS -->|log & metrics| Monitoring
    SSM -->|log & metrics| Monitoring

    %% Click Events - Repository Metadata
    click RepoMeta/README "https://github.com/qb411/fis-template-library/blob/main/README.md"
    click RepoMeta/CONTRIBUTING "https://github.com/qb411/fis-template-library/blob/main/CONTRIBUTING.md"
    click RepoMeta/LICENSE "https://github.com/qb411/fis-template-library/tree/main/LICENSE"

    %% Click Events - Templates
    click Templates/AWSFIS "https://github.com/qb411/fis-template-library/blob/main/templates/AWSFIS.json"
    click Templates/EX_POLICY "https://github.com/qb411/fis-template-library/blob/main/templates/example-iam-policy.json"
    click Templates/EX_TRUST "https://github.com/qb411/fis-template-library/blob/main/templates/example-iam-trust-relationship.json"
    click Templates/README "https://github.com/qb411/fis-template-library/blob/main/templates/README.md"

    %% Click Events - Aurora
    click Aurora/TEMPLATE "https://github.com/qb411/fis-template-library/blob/main/aurora-cluster-failover/aurora-cluster-failover-template.json"
    click Aurora/POLICY "https://github.com/qb411/fis-template-library/blob/main/aurora-cluster-failover/aurora-cluster-failover-iam-policy.json"
    click Aurora/README "https://github.com/qb411/fis-template-library/blob/main/aurora-cluster-failover/README.md"

    %% Click Events - EC2 Termination
    click EC2Term/AWSFIS "https://github.com/qb411/fis-template-library/blob/main/ec2-instances-terminate/AWSFIS.json"
    click EC2Term/TEMPLATE "https://github.com/qb411/fis-template-library/blob/main/ec2-instances-terminate/ec2-instances-terminate-template.json"
    click EC2Term/POLICY "https://github.com/qb411/fis-template-library/blob/main/ec2-instances-terminate/ec2-instances-terminate-iam-policy.json"
    click EC2Term/TRUST "https://github.com/qb411/fis-template-library/blob/main/ec2-instances-terminate/fis-iam-trust-relationship.json"
    click EC2Term/README "https://github.com/qb411/fis-template-library/blob/main/ec2-instances-terminate/README.md"

    %% Click Events - EC2 Spot
    click EC2Spot/AWSFIS "https://github.com/qb411/fis-template-library/blob/main/ec2-spot-interruption/AWSFIS.json"
    click EC2Spot/TEMPLATE "https://github.com/qb411/fis-template-library/blob/main/ec2-spot-interruption/ec2-spot-interruption-template.json"
    click EC2Spot/POLICY "https://github.com/qb411/fis-template-library/blob/main/ec2-spot-interruption/ec2-spot-interruption-iam-policy.json"
    click EC2Spot/TRUST "https://github.com/qb411/fis-template-library/blob/main/ec2-spot-interruption/fis-iam-trust-relationship.json"
    click EC2Spot/README "https://github.com/qb411/fis-template-library/blob/main/ec2-spot-interruption/README.md"

    %% Click Events - MySQL RDS
    click MySQLRT/TEMPLATE "https://github.com/qb411/fis-template-library/blob/main/mysql-rds-loadtest-failover/fis-experiment-template.json"
    click MySQLRT/CFN "https://github.com/qb411/fis-template-library/blob/main/mysql-rds-loadtest-failover/cloudformation.yaml"
    click MySQLRT/SSM "https://github.com/qb411/fis-template-library/blob/main/mysql-rds-loadtest-failover/ssm-loadtest-mysql-shell-script.yaml"
    click MySQLRT/README "https://github.com/qb411/fis-template-library/blob/main/mysql-rds-loadtest-failover/README.md"

    %% Click Events - PostgreSQL RDS
    click PostgresRT/TEMPLATE1 "https://github.com/qb411/fis-template-library/blob/main/postgres-rds-loadtest-failover/fis-experiment-template.json"
    click PostgresRT/TEMPLATE2 "https://github.com/qb411/fis-template-library/blob/main/postgres-rds-loadtest-failover/fis-experiment.json"
    click PostgresRT/CFN "https://github.com/qb411/fis-template-library/blob/main/postgres-rds-loadtest-failover/cloudformation.yaml"
    click PostgresRT/SSM "https://github.com/qb411/fis-template-library/blob/main/postgres-rds-loadtest-failover/ssm-loadtest-shell-script.yaml"
    click PostgresRT/SCRIPT "https://github.com/qb411/fis-template-library/blob/main/postgres-rds-loadtest-failover/rds-load-test.sh"
    click PostgresRT/README "https://github.com/qb411/fis-template-library/blob/main/postgres-rds-loadtest-failover/readme.md"

    %% Click Events - SAP EBS
    click SAP_EBS/AWSFIS "https://github.com/qb411/fis-template-library/blob/main/sap-ebs-pause-database-data/AWSFIS.json"
    click SAP_EBS/TEMPLATE "https://github.com/qb411/fis-template-library/blob/main/sap-ebs-pause-database-data/sap-ebs-pause-database-data-template.json"
    click SAP_EBS/POLICY "https://github.com/qb411/fis-template-library/blob/main/sap-ebs-pause-database-data/sap-ebs-pause-database-data-policy.json"
    click SAP_EBS/TRUST "https://github.com/qb411/fis-template-library/blob/main/sap-ebs-pause-database-data/fis-iam-trust-relationship.json"
    click SAP_EBS/README "https://github.com/qb411/fis-template-library/blob/main/sap-ebs-pause-database-data/README.md"

    %% Click Events - SAP ASCS
    click SAP_ASCS/AWSFIS "https://github.com/qb411/fis-template-library/blob/main/sap-ec2-instance-stop-ascs/AWSFIS.json"
    click SAP_ASCS/TEMPLATE "https://github.com/qb411/fis-template-library/blob/main/sap-ec2-instance-stop-ascs/sap-ec2-instance-stop-sap-ascs-template.json"
    click SAP_ASCS/POLICY "https://github.com/qb411/fis-template-library/blob/main/sap-ec2-instance-stop-ascs/sap-ec2-instance-stop-sap-policy.json"
    click SAP_ASCS/TRUST "https://github.com/qb411/fis-template-library/blob/main/sap-ec2-instance-stop-ascs/fis-iam-trust-relationship.json"
    click SAP_ASCS/README "https://github.com/qb411/fis-template-library/blob/main/sap-ec2-instance-stop-ascs/README.md"

    %% Click Events - SAP DB
    click SAP_DB/AWSFIS "https://github.com/qb411/fis-template-library/blob/main/sap-ec2-instance-stop-database/AWSFIS.json"
    click SAP_DB/TEMPLATE "https://github.com/qb411/fis-template-library/blob/main/sap-ec2-instance-stop-database/sap-ec2-instance-stop-sap-database-template.json"
    click SAP_DB/POLICY "https://github.com/qb411/fis-template-library/blob/main/sap-ec2-instance-stop-database/sap-ec2-instance-stop-sap-database-policy.json"
    click SAP_DB/TRUST "https://github.com/qb411/fis-template-library/blob/main/sap-ec2-instance-stop-database/fis-iam-trust-relationship.json"
    click SAP_DB/README "https://github.com/qb411/fis-template-library/blob/main/sap-ec2-instance-stop-database/README.md"

    %% Styles
    classDef aws fill:#cfe2ff,stroke:#0366d6,stroke-width:2px;
    classDef target fill:#d1e7dd,stroke:#1e7e34,stroke-width:2px;
    classDef repo fill:#e2e3e5,stroke:#6c757d,stroke-width:2px;
    classDef module fill:#f8d7da,stroke:#842029,stroke-width:2px;
    classDef client fill:#fff3cd,stroke:#856404,stroke-width:2px;
    classDef monitor fill:#f0f0f0,stroke:#444444,stroke-width:2px;
```
