Add README files and diagrams across repository

2026-05-06 06:36:53 +00:00
parent c88428d092
commit 1e2db3e125
31 changed files with 616 additions and 0 deletions
@@ -0,0 +1,27 @@
+# infra-run
+
+`infra-run` is the operational core of this repository. It groups automation, scripts, runbooks, and supporting documentation for Linux infrastructure work, incident response, and controlled change execution.
+
+## Diagram
+
+```mermaid
+flowchart TD
+  A["infra-run"] --> B["ansible"]
+  A --> C["docs"]
+  A --> D["runbooks"]
+  A --> E["scripts"]
+  E --> E1["bash"]
+  E --> E2["python"]
+```
+
+## Scope
+
+- `ansible` - placeholder structure for infrastructure automation and testing.
+- `docs` - supporting technical notes and written documentation.
+- `runbooks` - procedural operational guides.
+- `scripts` - executable tooling for operations and diagnostics.
+
+## Notes
+
+- This folder reflects the structure of a production-oriented operations repository.
+- Current implementation is strongest in the Bash tooling under `scripts/bash`.
@@ -0,0 +1,29 @@
+# infra-run/ansible
+
+This directory reserves the Ansible automation area for future infrastructure-as-code content. It is organized around the standard separation of inventory, roles, playbooks, collections, and tests.
+
+## Diagram
+
+```mermaid
+flowchart TD
+  A["ansible"] --> B["collections"]
+  A --> C["inventory"]
+  A --> D["playbooks"]
+  A --> E["roles"]
+  A --> F["tests"]
+  C --> C1["group_vars"]
+  C --> C2["host_vars"]
+```
+
+## Scope
+
+- `collections` - vendored or custom Ansible collections.
+- `inventory` - environment inventory definitions and variables.
+- `playbooks` - executable playbooks for repeatable operations.
+- `roles` - reusable automation roles.
+- `tests` - validation and test harnesses for Ansible content.
+
+## Notes
+
+- The directory layout is already prepared for growth even where content is still placeholder-only.
+- This keeps the repository ready for automation expansion alongside the existing script toolkits.
@@ -0,0 +1,23 @@
+# infra-run/ansible/collections
+
+This folder is reserved for Ansible collections used by the `infra-run` automation area. It is intended for dependencies or custom collections that support playbooks and roles.
+
+## Diagram
+
+```mermaid
+flowchart TD
+  A["collections"] --> B["External or custom collections"]
+  B --> C["Modules"]
+  B --> D["Plugins"]
+  B --> E["Roles integration"]
+```
+
+## Scope
+
+- Store collection dependencies close to the operational automation they support.
+- Keep collection usage explicit for repeatable execution in controlled environments.
+
+## Notes
+
+- The directory currently contains only a placeholder file.
+- A local README helps preserve intent before real collection content is added.
@@ -0,0 +1,23 @@
+# infra-run/ansible/inventory
+
+This directory is intended for Ansible inventory definitions. It separates shared variables from host-specific values to support clean environment modeling and safer automation.
+
+## Diagram
+
+```mermaid
+flowchart TD
+  A["inventory"] --> B["group_vars"]
+  A --> C["host_vars"]
+  B --> D["Shared environment variables"]
+  C --> E["Per-host overrides"]
+```
+
+## Scope
+
+- `group_vars` - variables applied at group or environment level.
+- `host_vars` - variables tailored to individual nodes.
+
+## Notes
+
+- The structure is present even though the repository currently keeps this area sanitized and mostly empty.
+- This is the natural companion to future playbooks and roles under `infra-run/ansible`.
@@ -0,0 +1,17 @@
+# infra-run/ansible/inventory/group_vars
+
+This folder is reserved for shared Ansible variables applied to inventory groups. It is the right place for environment defaults, role inputs, and group-level operational settings.
+
+## Diagram
+
+```mermaid
+flowchart LR
+  A["group_vars"] --> B["Environment defaults"]
+  A --> C["Role parameters"]
+  A --> D["Shared operational values"]
+```
+
+## Notes
+
+- Use this layer when multiple hosts should inherit the same configuration.
+- The directory is currently a placeholder and does not expose environment-specific data.
@@ -0,0 +1,17 @@
+# infra-run/ansible/inventory/host_vars
+
+This folder is intended for host-specific Ansible variables. It complements `group_vars` by capturing node-level differences that should not be shared across an entire inventory group.
+
+## Diagram
+
+```mermaid
+flowchart LR
+  A["host_vars"] --> B["Host A overrides"]
+  A --> C["Host B overrides"]
+  A --> D["Per-node secrets or tuning"]
+```
+
+## Notes
+
+- Use this area when operational differences are specific to one server.
+- The directory is intentionally empty in the sanitized portfolio state.
@@ -0,0 +1,18 @@
+# infra-run/ansible/playbooks
+
+This directory is intended for executable Ansible playbooks that coordinate roles, inventories, and operational tasks. In the current portfolio state it acts as a prepared entry point for future automation runs.
+
+## Diagram
+
+```mermaid
+flowchart TD
+  A["playbooks"] --> B["Provisioning flows"]
+  A --> C["Hardening flows"]
+  A --> D["Patch workflows"]
+  A --> E["Decommission workflows"]
+```
+
+## Notes
+
+- Playbooks belong here when the repository expands beyond script-first operations.
+- The directory currently contains only placeholder content.
@@ -0,0 +1,18 @@
+# infra-run/ansible/roles
+
+This folder is reserved for reusable Ansible roles. Roles make it possible to organize configuration logic into predictable, testable units that can be shared across playbooks.
+
+## Diagram
+
+```mermaid
+flowchart TD
+  A["roles"] --> B["common"]
+  A --> C["monitoring"]
+  A --> D["storage"]
+  A --> E["security"]
+```
+
+## Notes
+
+- The role layout is not yet populated, but the structure is in place for future automation modules.
+- Keeping a README here documents intent even before role code exists.
@@ -0,0 +1,17 @@
+# infra-run/ansible/tests
+
+This directory is reserved for validation of Ansible content. It represents the testing layer that would support inventories, roles, and playbooks as the automation footprint grows.
+
+## Diagram
+
+```mermaid
+flowchart LR
+  A["tests"] --> B["Syntax checks"]
+  A --> C["Molecule or scenario tests"]
+  A --> D["Post-run validation"]
+```
+
+## Notes
+
+- The folder is currently a placeholder.
+- Its presence reflects a design goal of keeping automation testable, not just executable.
@@ -0,0 +1,17 @@
+# infra-run/docs
+
+This directory is intended for supporting technical documentation tied to the operational tooling in `infra-run`. It is the natural home for implementation notes, architecture writeups, and operational reference material.
+
+## Diagram
+
+```mermaid
+flowchart TD
+  A["docs"] --> B["Architecture notes"]
+  A --> C["Operational references"]
+  A --> D["Change preparation notes"]
+```
+
+## Notes
+
+- The folder currently contains only a placeholder file.
+- It complements `runbooks` by focusing on reference material rather than step-by-step execution flows.
@@ -0,0 +1,18 @@
+# infra-run/runbooks
+
+This directory is reserved for runbook-style procedures that describe how to perform controlled operational work. It sits alongside the executable scripts and captures the human workflow around them.
+
+## Diagram
+
+```mermaid
+flowchart TD
+  A["runbooks"] --> B["Pre-check"]
+  A --> C["Change execution"]
+  A --> D["Post-check"]
+  A --> E["Rollback or escalation"]
+```
+
+## Notes
+
+- The directory is currently a placeholder.
+- It is intended to hold narrative procedures that complement the script-based toolkits.
@@ -0,0 +1,23 @@
+# infra-run/scripts
+
+This directory groups executable tooling used across the `infra-run` project. It separates shell-first operational scripts from future Python-based utilities while keeping both under one automation entry point.
+
+## Diagram
+
+```mermaid
+flowchart TD
+  A["scripts"] --> B["bash"]
+  A --> C["python"]
+  B --> D["Operational toolkits"]
+  C --> E["Future helper utilities"]
+```
+
+## Scope
+
+- `bash` - current implementation area with production-style operations toolkits.
+- `python` - reserved space for future supporting utilities.
+
+## Notes
+
+- The repository currently emphasizes Bash because it maps directly to day-to-day Linux operations.
+- The structure leaves room for higher-level helpers without mixing concerns.
@@ -2,6 +2,20 @@

 Small, practical Bash scripts for Linux operations checks and incident triage. The scripts are sanitized examples inspired by production Linux operations work and avoid destructive actions or root-only assumptions.

+## Diagram
+
+```mermaid
+flowchart TD
+  A["bash"] --> B["os-healthcheck"]
+  A --> C["disk-full"]
+  A --> D["veritas"]
+  A --> E["gpfs"]
+  B --> B1["Host diagnostics"]
+  C --> C1["Incident workflow"]
+  D --> D1["VxVM and VCS change flow"]
+  E --> E1["Spectrum Scale expansion flow"]
+```
+
 ## Scripts

 - `os-healthcheck/healthcheck.sh` - general host health overview.
@@ -2,6 +2,20 @@

 Production-style Bash toolkit for diagnosing and handling a disk full incident on Linux systems. It is intentionally conservative: default mode is safe, cleanup actions require `--execute` and an operator confirmation prompt, and the scripts do not assume root access.

+## Diagram
+
+```mermaid
+flowchart TD
+  A["disk-full"] --> B["01_disk_overview.sh"]
+  A --> C["02_find_big_files.sh"]
+  A --> D["03_deleted_open_files.sh"]
+  A --> E["04_top_dirs.sh"]
+  A --> F["05_log_cleanup.sh"]
+  A --> G["06_quick_fix.sh"]
+  A --> H["07_postcheck.sh"]
+  A --> I["disk_full_runbook.sh"]
+```
+
 ## Why Disk Full Incidents Happen

 - **Logs** - application, audit, system, or middleware logs can grow faster than rotation policy expects.
@@ -4,6 +4,21 @@ Safe, sanitized Bash examples for planning and executing a GPFS / IBM Spectrum S

 These scripts are examples. Exact GPFS commands, flags, quorum practices, failure-group design, and storage naming standards vary by Spectrum Scale version and site policy.

+## Diagram
+
+```mermaid
+flowchart TD
+  A["gpfs"] --> B["01_cluster_overview.sh"]
+  A --> C["02_precheck_gpfs.sh"]
+  A --> D["03_detect_new_disks.sh"]
+  A --> E["04_create_nsd_stanza.sh"]
+  A --> F["05_add_nsd_to_filesystem.sh"]
+  A --> G["06_rebalance_filesystem.sh"]
+  A --> H["07_postcheck_gpfs.sh"]
+  A --> I["08_generate_report.sh"]
+  A --> J["gpfs_extend_runbook.sh"]
+```
+
 ## Concepts

 - **Cluster** - the Spectrum Scale administrative domain containing the nodes, daemon configuration, quorum policy, filesystems, and NSDs.
@@ -0,0 +1,39 @@
+# Linux Operations Healthcheck Toolkit
+
+This directory contains first-pass Linux diagnostics for common host checks. The scripts focus on health visibility, disk usage, service status, network troubleshooting, and lightweight reporting without making system changes.
+
+## Diagram
+
+```mermaid
+flowchart TD
+  A["os-healthcheck"] --> B["healthcheck.sh"]
+  A --> C["disk_check.sh"]
+  A --> D["service_check.sh"]
+  A --> E["system_report.sh"]
+  A --> F["network_troubleshoot.sh"]
+```
+
+## Scripts
+
+- `healthcheck.sh` - consolidated host overview.
+- `disk_check.sh` - threshold-based filesystem usage check.
+- `service_check.sh` - service state validation for critical daemons.
+- `system_report.sh` - timestamped report generation for quick evidence capture.
+- `network_troubleshoot.sh` - local network, DNS, route, and connectivity checks.
+
+## Usage
+
+```bash
+cd infra-run/scripts/bash/os-healthcheck
+
+./healthcheck.sh
+./disk_check.sh 90
+./service_check.sh sshd nginx
+./system_report.sh
+./network_troubleshoot.sh 8.8.8.8
+```
+
+## Notes
+
+- The toolkit is read-only and suited to initial triage.
+- It aligns with the portfolio pattern of quick pre-check and evidence collection steps.
@@ -2,6 +2,21 @@

 Production-style Bash examples for expanding storage in a Veritas environment. These scripts are sanitized operational tooling for a Linux Infrastructure Engineer portfolio: they show the flow, guardrails, logging, and validation patterns used in enterprise change work.

+## Diagram
+
+```mermaid
+flowchart TD
+  A["veritas"] --> B["01_detect_new_luns.sh"]
+  A --> C["02_precheck_vcs_vxvm.sh"]
+  A --> D["03_freeze_vcs_group.sh"]
+  A --> E["04_init_vxvm_disks.sh"]
+  A --> F["05_extend_diskgroup.sh"]
+  A --> G["06_extend_volume_fs.sh"]
+  A --> H["07_postcheck_vcs_vxvm.sh"]
+  A --> I["08_unfreeze_vcs_group.sh"]
+  A --> J["veritas_extend_runbook.sh"]
+```
+
 ## VxVM vs VCS

 Veritas Volume Manager (VxVM) manages disks, disk groups, volumes, plexes, and subdisks. It is the storage virtualization layer used to initialize SAN LUNs, add capacity to disk groups, and grow volumes.
@@ -0,0 +1,17 @@
+# infra-run/scripts/python
+
+This directory is reserved for Python helpers that may later complement the Bash-first operations tooling. It provides a separate place for richer parsing, reporting, or integration logic without mixing languages in the same toolkit directory.
+
+## Diagram
+
+```mermaid
+flowchart LR
+  A["python"] --> B["Future reporting utilities"]
+  A --> C["Parsers"]
+  A --> D["Automation helpers"]
+```
+
+## Notes
+
+- The folder currently contains only a placeholder file.
+- Keeping it explicit now makes future multi-language tooling easier to organize.