# Adding a New Component to the Diff Workflow

This guide explains how to add a new component to the CI diff workflow. The workflow automatically detects changes to production environment files and shows what would change upon deployment.

## Quick Start

Adding a new component requires only **2 steps**:

1. **Create a `diff.sh` script** for your component
2. **Register the component** in `diff-components.json`

No workflow modifications needed!

## Step 1: Create the diff.sh Script

Create `deployments/<your-component>/diff.sh`:

```bash
#!/bin/bash

set -euo pipefail

WORKSPACE=$(unset CDPATH && cd $(dirname "${BASH_SOURCE[0]}") && pwd)
LIB_DIR="$WORKSPACE/../lib"

# Source the shared diff library
source "$LIB_DIR/diff-lib.sh"

# Parse arguments (sets VENDOR, ENV, REGION, LOGICAL_REGION, OUTPUT_FILE)
parse_diff_args "$@"

# Ensure kubeconfig permissions
ensure_kubeconfig_permissions

# =============================================================================
# Define your component-specific diffs below
# =============================================================================

# Example: kubectl diff for raw manifests
kubectl_diff "$WORKSPACE/manifests/envs/${ENV}-${VENDOR}-${LOGICAL_REGION}/" "My Component"

# Example: helm diff for Helm releases
# helm_diff "release-name" "path/to/chart" \
#     "$WORKSPACE/values/${ENV}-${VENDOR}-${LOGICAL_REGION}/values.yaml" \
#     "namespace" \
#     "My Helm Release" \
#     "1.0.0"  # Optional: chart version

# Write summary (required at the end)
write_diff_summary
```

Make it executable:
```bash
chmod +x deployments/<your-component>/diff.sh
```

## Step 2: Register the Component

Add your component to `deployments/diff-components.json`:

```json
{
  "components": [
    {
      "name": "dataplane",
      "path": "deployments/dataplane",
      "description": "Dataplane components (VMCluster, Loki, Alertmanager)",
      "chart_paths": ["deployments/charts/alertmanager"]
    },
    {
      "name": "regional-server",
      "path": "deployments/regional-server",
      "description": "Regional server and data server components",
      "chart_paths": []
    },
    {
      "name": "your-component",
      "path": "deployments/your-component",
      "description": "Description of your component",
      "chart_paths": []
    }
  ],
  "vendors": ["aws", "gcp", "azure", "alicloud"]
}
```

### Component Configuration Fields

| Field | Required | Description |
|-------|----------|-------------|
| `name` | Yes | Unique identifier for the component |
| `path` | Yes | Path to the component directory (relative to repo root) |
| `description` | No | Human-readable description |
| `chart_paths` | Yes | Array of Helm chart paths that belong to this component. When these charts change, the workflow will diff all prod environments. Use `[]` for kubectl-only components. |

## Directory Structure Requirements

Your component must follow this structure:

```
deployments/<your-component>/
├── diff.sh                           # Diff script (required)
└── <subdir>/
    └── envs/
        ├── prod-aws-<region>/        # AWS production environments
        ├── prod-gcp-<region>/        # GCP production environments
        ├── prod-azure-<region>/      # Azure production environments
        └── prod-alicloud-<region>/   # Alicloud production environments
```

The workflow detects changes by matching the pattern: `<path>/**/envs/prod-*/**`

## Available Library Functions

The shared library (`deployments/lib/diff-lib.sh`) provides:

| Function | Description |
|----------|-------------|
| `parse_diff_args "$@"` | Parses arguments: vendor, env, region, logical_region, output_file |
| `kubectl_diff "$path" "$name"` | Run kubectl diff on a file/directory |
| `helm_diff "$release" "$chart" "$values" "$ns" "$name" "$version"` | Run helm diff |
| `write_output "$text"` | Write to output file or stdout |
| `write_diff_summary` | Write final summary (required at end of script) |
| `ensure_kubeconfig_permissions` | Set proper kubeconfig file permissions |

### Function Details

#### `kubectl_diff`
```bash
kubectl_diff "/path/to/manifests/" "Component Name"
```
- Runs `kubectl diff --show-managed-fields=false -f <path>`
- Outputs formatted markdown with collapsible diff details

#### `helm_diff`
```bash
helm_diff "release-name" "chart-path-or-repo" "/path/to/values.yaml" "namespace" "Display Name" "1.0.0"
```
- Runs `helm diff upgrade` with dyff output
- Handles new installations gracefully
- Version parameter is optional

## How the Workflow Works

```
┌─────────────────────────────────────────────────────────────────┐
│                    detect-and-build-matrix                       │
│  1. Reads diff-components.json                                   │
│  2. Detects which components have prod changes                   │
│  3. Builds dynamic matrix of (component, vendor) pairs          │
└─────────────────────────────────────────────────────────────────┘
                              │
                              ▼
┌─────────────────────────────────────────────────────────────────┐
│                    diff (matrix job)                             │
│  Runs in parallel for each (component, vendor) combination:     │
│  • Sets up cloud credentials (AWS/GCP/Azure/Alicloud)           │
│  • Installs kubectl (and helm if requires_helm=true)            │
│  • Runs component's diff.sh for each affected region            │
│  • Uploads results as artifacts                                  │
└─────────────────────────────────────────────────────────────────┘
                              │
                              ▼
┌─────────────────────────────────────────────────────────────────┐
│                       comment-pr                                 │
│  • Downloads all diff artifacts                                  │
│  • Combines results into single markdown                         │
│  • Posts/updates PR comment                                      │
└─────────────────────────────────────────────────────────────────┘
```

## Testing Locally

```bash
# Set up kubeconfig for target cluster
aws eks update-kubeconfig --region us-east-1 --name o11y-prod-regional-us-east-1

# Run diff script
cd deployments/<your-component>
bash diff.sh aws prod us-east-1 us-east-1

# Or output to file
bash diff.sh aws prod us-east-1 us-east-1 /tmp/diff-output.md
```

## Manual Trigger

You can manually trigger the workflow via GitHub Actions UI:

- **git-ref**: Branch or commit to diff
- **components**: Comma-separated list (e.g., `dataplane,regional-server`) or `all`

## Notes

- Environment naming: `prod-<vendor>-<logical_region>` (e.g., `prod-aws-us-east-1`)
- Only production (`prod-*`) environments are diffed
- BYOC clusters are automatically skipped
- All component/vendor combinations run in parallel
- Results are combined into a single PR comment