GitLab BDA

Welcome to the GitLab BDA (Blue Dynamics Alliance) deployment documentation. This documentation follows the Diátaxis framework to provide clear, purposeful documentation for different needs.

Quick Links

• Getting Started: See the GitLab BDA README in /dp-infra/gitlabbda/README.md for setup and deployment

• Main Cluster Documentation: KUP6S Cluster Docs

• Migration Guide: See MIGRATION.md in /dp-infra/gitlabbda/MIGRATION.md

About This Deployment

GitLab BDA (Blue Dynamics Alliance) is a production-ready GitLab CE deployment with:

• GitLab Community Edition v18.5.1 via official Helm chart

• CloudNativePG PostgreSQL with high availability

• Harbor Registry v2.14.0 with vulnerability scanning

• Hetzner S3 fsn1 object storage

• Redis for caching and job queuing

• ArgoCD GitOps deployment

• CDK8S infrastructure as code (TypeScript)

Target Workload: 2-5 concurrent users

---

Documentation Structure

Explanation (Understanding)

Conceptual guides that explain the “why” behind architectural decisions and design patterns.

• Architecture Overview - High-level system design

• ArgoCD GitOps Workflow - GitOps deployment pipeline

• CDK8S Approach - Infrastructure as Code with TypeScript

• Storage Architecture - Hetzner Volumes + Longhorn + S3 strategy

• GitLab Components - How GitLab pieces fit together

• Harbor Integration - Container registry architecture

• Security Model - Authentication, secrets, RBAC

• Monitoring & Observability - Metrics and logs

Reference (Lookup)

Technical specifications for quick lookup of configuration, APIs, and commands.

• Configuration Reference - Complete config.yaml documentation

• ArgoCD Configuration - Application manifest and sync policies

• Constructs API - CDK8S constructs reference

• Secrets Reference - All secrets and ESO configuration

• S3 Buckets - Object storage buckets

• Resource Requirements - CPU, memory, storage specs

• Environment Variables - All configurable variables

• Version Compatibility - Component version matrix

• Endpoints & Ports - Service endpoints and ports

• Troubleshooting - Common issues and solutions

• kubectl Commands - Common operations

How-To Guides (Tasks)

Step-by-step guides for accomplishing specific tasks.

• How-To Guides - Operational task guides (coming soon)

Tutorials (Learning)

Learning-oriented lessons that teach concepts through hands-on examples.

• Tutorials - Learning-oriented guides (coming soon)

---

Documentation Philosophy

This documentation follows Diátaxis principles:

Explanation answers “Why?” - Helps you understand the system Reference answers “What?” - Helps you look up details How-To answers “How?” - Helps you accomplish tasks Tutorials answer “Can you show me?” - Helps you learn

Where to Start

• New to GitLab BDA? → Start with Architecture Overview

• Understanding GitOps? → Read ArgoCD GitOps Workflow

• Need configuration details? → Check Configuration Reference

• Troubleshooting issues? → See Troubleshooting

• Learning CDK8S? → Read CDK8S Approach

---

Related Documentation

Main Cluster Documentation

• Application Secrets Architecture - Generic ESO pattern (applies to all apps)

• Deploy Multi-Architecture Applications - ARM64/AMD64 deployment patterns

• Cluster Capabilities Reference - Cluster infrastructure overview

Deployment Files

Located in /dp-infra/gitlabbda/ repository directory:

• README.md - Quick start and setup guide

• MIGRATION.md - Migrating from existing GitLab

• CLAUDE.md - Development guidelines for this deployment

• config.yaml - Configuration file

• charts/ - CDK8S TypeScript source code

• manifests/ - Generated Kubernetes manifests (ArgoCD reads these)

---

Contributing

When updating this deployment:

1. Always fix the CDK8S charts first (charts/*.ts)

2. Rebuild manifests: bash -c 'source .env && npm run build'

3. Update documentation if architecture or configuration changes

4. Commit both code and docs together

5. ArgoCD automatically deploys changes from git

See /dp-infra/gitlabbda/CLAUDE.md for detailed development guidelines.

---

Table of Contents

Explanation

• Architecture Overview
• ArgoCD GitOps Workflow for GitLab BDA
• CDK8S Approach for GitLab BDA
• Storage Architecture for GitLab BDA
• GitLab Components Architecture
• Harbor Container Registry Integration
• Security Model
• Monitoring & Observability

Reference

• ArgoCD Configuration
• Configuration
• CDK8S Constructs API
• GitLab BDA Secrets Configuration
• S3 Buckets
• Resource Requirements
• Environment Variables
• Version Compatibility
• Endpoints & Ports
• Troubleshooting
• kubectl Commands

How-To

• How-To Guides

Tutorials

• Tutorials

---

Documentation last updated: 2025-10-29