ADR-003: Environment Manager Web UI

Status

Accepted

Context

The existing feature branch environment workflow relies on shell scripts (create-feature-env.sh, destroy-feature-env.sh). While functional, this approach has several limitations:

  1. Requires CLI access - Developers need kubectl and git configured locally

  2. No visibility - Cannot easily view all environments or their status

  3. Manual image selection - No interface to browse available Harbor tags

  4. No build integration - Branch-based images require separate workflow triggers

  5. Limited validation - Script-based creation prone to naming conflicts

  6. No ArgoCD visibility - Must use separate ArgoCD UI to check sync status

Decision

Implement a web-based Environment Manager with the following components:

Backend (Flask API)

  • RESTful API for environment CRUD operations

  • Integration with ArgoCD API for status and sync

  • Integration with Harbor API for image tag discovery

  • Integration with GitHub Actions for build triggers

  • Git operations for committing values and application files

  • Modular architecture with blueprints and services

Frontend (SPA)

  • HTML5/CSS3/JavaScript web interface

  • Tab-based navigation (List, Create, Services Manager)

  • Service card selection UI

  • Real-time form validation

  • Environment name duplicate detection

Deployment

  • Docker Compose for local development

  • Nginx for static file serving and API proxy

  • Environment variable configuration

Architecture

Environment Manager Components
Figure 1. Environment Manager Components

Consequences

Positive

  • Self-service - Developers can create environments without DevOps assistance

  • Visibility - Single dashboard for all environments

  • Discoverability - Browse available image tags and branches

  • Validation - Real-time duplicate detection and input validation

  • Automation - Integrated build triggers for branch-based images

  • Speed - ArgoCD sync optimization reduces deployment time from 3-5 min to 10-15 sec

  • Flexibility - Partial or full environment selection

  • Auditability - All changes go through Git commits

Negative

  • Additional infrastructure - Docker containers for frontend and backend

  • Maintenance - Web application code to maintain

  • Security surface - Web interface requires authentication considerations

  • Dependencies - Multiple external API integrations to maintain

Mitigations

  • Containerized deployment simplifies infrastructure

  • Modular codebase architecture for maintainability

  • Environment variables for sensitive configuration

  • Graceful degradation when external services unavailable

Implementation Details

API Endpoints

Endpoint Purpose

GET /api/environments

List all environments with status

POST /api/environments

Create new environment

DELETE /api/environments/{name}

Delete environment

GET /api/services

Get service configuration

GET /api/tags/{service}

Get Harbor tags

POST /api/builds/{service}

Trigger build

Environment Types

  • Partial - Selected services, uses parent database

  • Full - All services, dedicated database

Key Features

  1. Duplicate Name Protection - Three-layer validation (frontend cache, submit check, backend check)

  2. ArgoCD Sync Optimization - Immediate sync trigger after git commit

  3. Harbor Image Verification - Wait for images before creating environment

  4. ArgoCD Image Updater Integration - Manage automatic image updates

File Structure

backend/
├── app.py              # Flask entry point
├── config.py           # Configuration constants
├── utils/helpers.py    # Utility functions
├── services/           # External service integrations
└── routes/             # API endpoint blueprints

frontend/
├── index.html          # Main page
├── css/styles.css      # Styles
└── js/                 # JavaScript modules

Alternatives Considered

  1. ArgoCD ApplicationSet - Rejected: Less flexibility for partial environments

  2. Backstage plugin - Rejected: Too heavyweight, requires Backstage adoption

  3. Jenkins pipeline - Rejected: Less interactive, no real-time validation

  4. GitOps UI (Weaveworks) - Rejected: Limited Harbor/GitHub integration

  5. Enhanced shell scripts - Rejected: Cannot provide web-based visibility

Security Considerations

  • Harbor and GitHub tokens stored as environment variables

  • ArgoCD API accessed with service account token

  • Git commits attributed to service account

  • No direct kubectl access needed by users

  • Rate limiting on API endpoints

References

Decision date: 2025-12