Status

Table of Contents

Component to Script Mapping

This document explains how the organized test scripts in scripts/by-auth/ map to different system components of the Blueberry IDP.

Overview

The test scripts are organized into six categories based on their authentication requirements rather than functionality. This organization helps developers and operators understand which credentials are needed for testing specific parts of the system.

Component-Script Relationship Diagram

graph TB subgraph "System Components" API[["Blueberry API
(FastAPI)"]] UI[["Frontend UI
(HTMX + Alpine.js)"]] AUTH[["Firebase Auth"]] DB[["Firestore
Database"]] CACHE[["Redis
Cache"]] SECRETS[["Google Secret
Manager"]] ARGO[["ArgoCD
GitOps"]] K8S[["Kubernetes
GKE Autopilot"]] GITLAB[["GitLab
CI/CD"]] GITHUB[["GitHub
Actions"]] WEBHOOKS[["Webhook
Endpoints"]] COST[["Cost Tracking
& Analytics"]] end subgraph "Script Categories" subgraph "scripts/by-auth/" API_TOKEN["api-token/
• cost-tracking-demo.py
• create_environment_simple.py
• create_environment_gitlab.py
• reconcile-terminated.sh
• force-check-environment.py"] FIREBASE["firebase-auth/
• test-firebase-auth.py
• test-secret-manager-firebase.py
• test-create-environment.py
• manage-test-users.py
• test-auth-flow.py"] DIRECT_ACCESS["direct-access/
• debug-argocd-resources.py
• check-argocd-app.py
• sync-argocd-app.sh
• test-argocd-env-creation.sh
• delete-stuck-argocd-app.sh
• check-gcp-quotas.sh"] WEBHOOK_SCRIPTS["webhooks/
• webhook-curl-examples.sh
• webhook-examples.py
• test-slack-webhook.py
• test-github-webhook.py
• test-argocd-webhook.py"] NO_AUTH["no-auth/
• setup-dev.sh
• deploy-blueberry.sh
• wait-for-image.sh
• generate-helm-docs.py
• setup-docker-compose.sh"] DEVELOPMENT["development/
• debug-environment-creation.py
• test-environment-deletion.py
• troubleshoot-rbac.sh
• test-proxy-fix-k8s.py
• cleanup-environments.sh"] end end %% API Token Scripts Connections API_TOKEN -.->|"Authenticated API calls"| API API_TOKEN -.->|"Environment lifecycle"| DB API_TOKEN -.->|"Status reconciliation"| CACHE API_TOKEN -.->|"Cost tracking"| COST %% Firebase Auth Scripts Connections FIREBASE -.->|"Authentication testing"| AUTH FIREBASE -.->|"Secret retrieval"| SECRETS FIREBASE -.->|"User management"| DB FIREBASE -.->|"Token validation"| API %% Direct Access Scripts Connections DIRECT_ACCESS -.->|"Direct kubectl access"| K8S DIRECT_ACCESS -.->|"ArgoCD management"| ARGO DIRECT_ACCESS -.->|"GCP resource access"| SECRETS DIRECT_ACCESS -.->|"Firestore operations"| DB %% Webhook Testing Scripts Connections WEBHOOK_SCRIPTS -.->|"Webhook payloads"| WEBHOOKS WEBHOOK_SCRIPTS -.->|"GitHub events"| GITHUB WEBHOOK_SCRIPTS -.->|"GitLab events"| GITLAB WEBHOOK_SCRIPTS -.->|"ArgoCD notifications"| ARGO %% No Auth Scripts Connections NO_AUTH -.->|"Development setup"| API NO_AUTH -.->|"Documentation generation"| UI NO_AUTH -.->|"Image building"| GITLAB %% Development Scripts Connections DEVELOPMENT -.->|"Mixed authentication"| API DEVELOPMENT -.->|"Direct debugging"| K8S DEVELOPMENT -.->|"Environment testing"| ARGO DEVELOPMENT -.->|"RBAC troubleshooting"| K8S %% Component Relationships API -.->|"Stores data"| DB API -.->|"Caches responses"| CACHE API -.->|"Validates tokens"| AUTH API -.->|"Retrieves secrets"| SECRETS API -.->|"Creates applications"| ARGO ARGO -.->|"Deploys to"| K8S WEBHOOKS -.->|"Processes events"| API %% Styling classDef componentBox fill:#e1f5fe,stroke:#01579b,stroke-width:2px,color:#000 classDef scriptBox fill:#fff3e0,stroke:#e65100,stroke-width:2px,color:#000 classDef connection stroke:#666,stroke-width:1px,stroke-dasharray: 5 5 class API,UI,AUTH,DB,CACHE,SECRETS,ARGO,K8S,GITLAB,GITHUB,WEBHOOKS,COST componentBox class API_TOKEN,FIREBASE,DIRECT_ACCESS,WEBHOOK_SCRIPTS,NO_AUTH,DEVELOPMENT scriptBox

Script Category Details

1. API Token Scripts (api-token/)

Purpose: Test API functionality with Blueberry API tokens (starting with blb_).

Components Tested:
- Blueberry API: Authenticated HTTP calls to API endpoints
- Firestore Database: Environment data storage and retrieval
- Redis Cache: Status caching and reconciliation
- Cost Tracking: Resource cost collection and analytics

Key Scripts:
- cost-tracking-demo.py - Comprehensive cost tracking demonstration
- create_environment_simple.py - Basic environment creation
- create_environment_gitlab.py - GitLab pipeline environment creation
- reconcile-terminated.sh - Environment status reconciliation
- force-check-environment.py - Force environment health checks

Setup Requirements: Only BLUEBERRY_API_TOKEN (starts with blb_)

2. Firebase Auth Scripts (firebase-auth/)

Purpose: Test Firebase authentication and user management integration.

Components Tested:
- Firebase Auth: User authentication and token validation
- Google Secret Manager: Secret retrieval and management
- Firestore Database: User data and session management
- Blueberry API: Authenticated API calls with Firebase tokens

Key Scripts:
- test-firebase-auth.py - Firebase authentication flows
- test-secret-manager-firebase.py - Secret Manager integration
- test-create-environment.py - Environment creation with Firebase auth
- manage-test-users.py - Test user management
- test-auth-flow.py - Authentication flow verification

Setup Requirements: FIREBASE_API_KEY, test user credentials

3. Direct Access Scripts (direct-access/)

Purpose: Test using direct Kubernetes and GCP access without API layer.

Components Tested:
- Kubernetes: Direct kubectl operations
- ArgoCD: Application management and GitOps
- Google Secret Manager: Direct secret access
- Firestore Database: Direct database operations
- GCP Services: Resource quotas and permissions

Key Scripts:
- debug-argocd-resources.py - ArgoCD resource debugging
- check-argocd-app.py - ArgoCD application status
- sync-argocd-app.sh - Manual ArgoCD synchronization
- test-argocd-env-creation.sh - Environment-ArgoCD integration
- delete-stuck-argocd-app.sh - Force delete stuck applications
- check-gcp-quotas.sh - GCP quota monitoring

Setup Requirements: kubectl access, GCP credentials, ArgoCD permissions

4. Webhook Testing Scripts (webhooks/)

Purpose: Test webhook endpoints and external integrations.

Components Tested:
- Webhook Endpoints: Event processing and handling
- GitHub Actions: GitHub webhook integration
- GitLab CI/CD: GitLab webhook events
- ArgoCD: Application sync notifications
- Slack: Notification integrations

Key Scripts:
- webhook-curl-examples.sh - Generic webhook testing with cURL
- webhook-examples.py - Python webhook clients
- test-slack-webhook.py - Slack notification testing
- test-github-webhook.py - GitHub webhook simulation
- test-argocd-webhook.py - ArgoCD event testing

Setup Requirements: Various tokens for webhook authentication

5. No Auth Scripts (no-auth/)

Purpose: Utility scripts that don't require authentication.

Components Tested:
- Development Setup: Local environment configuration
- Documentation: HTML generation and static assets
- CI/CD Pipeline: Image building and deployment orchestration
- Development Tools: Code formatting and dependency management

Key Scripts:
- setup-dev.sh - Development environment setup
- deploy-blueberry.sh - Complete deployment orchestration
- wait-for-image.sh - CI/CD image availability checking
- generate-helm-docs.py - Helm chart documentation
- setup-docker-compose.sh - Docker Compose environment setup

Setup Requirements: None (public utilities)

6. Development Scripts (development/)

Purpose: Development and testing scripts with mixed authentication methods.

Components Tested:
- Environment Lifecycle: Creation, monitoring, and cleanup
- Kubernetes Debugging: RBAC, networking, and resource issues
- ArgoCD Operations: Application debugging and management
- System Integration: End-to-end testing and validation

Key Scripts:
- debug-environment-creation.py - Environment creation debugging
- test-environment-deletion.py - Deletion process verification
- troubleshoot-rbac.sh - RBAC permission troubleshooting
- test-proxy-fix-k8s.py - Kubernetes proxy middleware testing
- cleanup-environments.sh - Bulk environment cleanup

Setup Requirements: Mixed - may use API tokens, kubectl, or Firebase auth

Usage Patterns

Authentication-Based Testing Strategy

When testing specific components, choose scripts based on available credentials:

Available Credentials Use Scripts From Best For
API Token (blb_*) api-token/ API functionality, cost tracking
Firebase Credentials firebase-auth/ User authentication, secret access
kubectl + GCP Access direct-access/ Infrastructure debugging, ArgoCD
Webhook Tokens webhooks/ Integration testing, notifications
No Credentials no-auth/ Setup, documentation, utilities
Mixed/Development development/ Complex debugging scenarios

Development Workflow

  1. Setup: Start with no-auth/setup-dev.sh
  2. API Testing: Use api-token/ scripts for core functionality
  3. Authentication: Test with firebase-auth/ scripts
  4. Infrastructure: Debug with direct-access/ scripts
  5. Integration: Validate with webhooks/ scripts
  6. Troubleshooting: Use development/ scripts for complex issues

Troubleshooting Guide

When components fail, use these scripts for diagnosis:

  • API Issues: api-token/force-check-environment.py
  • Auth Problems: firebase-auth/test-firebase-auth.py
  • Environment Creation: development/debug-environment-creation.py
  • ArgoCD Issues: direct-access/debug-argocd-resources.py
  • Webhook Failures: webhooks/webhook-curl-examples.sh
  • RBAC Problems: development/troubleshoot-rbac.sh

Makefile Integration

Each script category has corresponding Makefile targets:

# Test by authentication type
make test-api-token     # API token-based testing
make test-firebase      # Firebase authentication
make test-direct        # Direct access (kubectl/GCP)
make test-webhooks      # Webhook endpoints
make test-development   # Development scenarios

# Setup and utilities
make setup-dev         # Development environment
make deploy            # Full deployment pipeline

Last Updated: July
2025
Diagram Source: This document contains the source Mermaid diagram

Document ID: architecture/diagrams/component-script-mapping