Component Relationships and Dependencies
Visual guide to understanding how all homelab components interact and depend on each other.
Table of Contents
- Overview
- Dependency Hierarchy
- Service Communication Patterns
- Data Flow Diagrams
- Integration Points
- Troubleshooting Dependencies
Overview
The homelab infrastructure follows a layered architecture where each layer depends on the services below it. Understanding these relationships is crucial for troubleshooting, scaling, and maintaining the environment.
Dependency Hierarchy
Layer-by-Layer Dependencies
┌─────────────────────────────────────────────────────────────┐
│ Application Layer │
│ ┌─────────────┐ ┌─────────────┐ ┌─────────────────────┐ │
│ │ Web Apps │ │ APIs │ │ Microservices │ │
│ │ (React) │ │ (REST/gRPC) │ │ (Spring/Go) │ │
│ └─────────────┘ └─────────────┘ └─────────────────────┘ │
└─────────────────────────────────────────────────────────────┘
│ depends on
▼
┌─────────────────────────────────────────────────────────────┐
│ Platform Services Layer │
│ ┌─────────────┐ ┌─────────────┐ ┌─────────────────────┐ │
│ │ Knative │ │ Harbor │ │ Contour │ │
│ │(Serverless) │ │ (Registry) │ │ (Ingress) │ │
│ └─────────────┘ └─────────────┘ └─────────────────────┘ │
│ ┌─────────────┐ ┌─────────────┐ ┌─────────────────────┐ │
│ │cert-manager │ │ TBS │ │ Tekton │ │
│ │ (TLS) │ │(Buildpacks) │ │ (Pipelines) │ │
│ └─────────────┘ └─────────────┘ └─────────────────────┘ │
└─────────────────────────────────────────────────────────────┘
│ depends on
▼
┌─────────────────────────────────────────────────────────────┐
│ Kubernetes Platform Layer │
│ ┌─────────────┐ ┌─────────────┐ ┌─────────────────────┐ │
│ │ Management │ │ Development │ │ Production │ │
│ │ Cluster │ │ Cluster │ │ Cluster │ │
│ └─────────────┘ └─────────────┘ └─────────────────────┘ │
└─────────────────────────────────────────────────────────────┘
│ depends on
▼
┌─────────────────────────────────────────────────────────────┐
│ BOSH Control Plane │
│ ┌─────────────┐ ┌─────────────┐ ┌─────────────────────┐ │
│ │ BOSH │ │ Concourse │ │ Jumpbox │ │
│ │ Director │ │ CI/CD │ │ (Bastion) │ │
│ └─────────────┘ └─────────────┘ └─────────────────────┘ │
└─────────────────────────────────────────────────────────────┘
│ depends on
▼
┌─────────────────────────────────────────────────────────────┐
│ Infrastructure Virtualization │
│ ┌─────────────┐ ┌─────────────┐ ┌─────────────────────┐ │
│ │ vCenter │ │ NSX-T │ │ ESXi │ │
│ │ Management │ │ Network │ │ Hosts │ │
│ └─────────────┘ └─────────────┘ └─────────────────────┘ │
└─────────────────────────────────────────────────────────────┘
│ depends on
▼
┌─────────────────────────────────────────────────────────────┐
│ Physical Infrastructure │
│ ┌─────────────┐ ┌─────────────┐ ┌─────────────────────┐ │
│ │ Intel NUCs │ │ Network │ │ Storage │ │
│ │ (Compute) │ │ Equipment │ │ (NAS) │ │
│ └─────────────┘ └─────────────┘ └─────────────────────┘ │
└─────────────────────────────────────────────────────────────┘
Critical Path Dependencies
Bootstrap Sequence (Must be done in order):
- Physical infrastructure (power, network, storage)
- ESXi hosts and vCenter
- NSX-T networking
- BOSH Director and Jumpbox
- TKG Management Cluster
- Platform services (cert-manager, Contour, Harbor)
- Workload clusters and applications
Service Communication Patterns
Control Plane Communications
┌─────────────────────────────────────────────────────────────┐
│ Control Plane Traffic │
└─────────────────────────────────────────────────────────────┘
BOSH Director ◄──────────────────────────► vCenter Server
│ │
│ VM Lifecycle │ vSphere API
│ Health Monitoring │ Resource Management
▼ ▼
ESXi Host 1 ◄──────► ESXi Host 2 ◄──────► ESXi Host 3
│ │ │
│ vMotion │ vMotion │ vMotion
│ Storage │ Storage │ Storage
▼ ▼ ▼
┌─────────────┐ ┌─────────────┐ ┌─────────────┐
│TKG Mgmt VMs │ │TKG Mgmt VMs │ │TKG Mgmt VMs │
└─────────────┘ └─────────────┘ └─────────────┘
Data Plane Communications
┌─────────────────────────────────────────────────────────────┐
│ Application Traffic Flow │
└─────────────────────────────────────────────────────────────┘
Internet User
│ HTTPS Request
▼
UXG Gateway (Firewall)
│ Port Forward 443
▼
NSX-T T1 Load Balancer
│ Distribute Traffic
▼
┌─────────────┐ ┌─────────────┐ ┌─────────────┐
│ Contour │ │ Contour │ │ Contour │
│Instance 1 │ │Instance 2 │ │Instance 3 │
└─────────────┘ └─────────────┘ └─────────────┘
│ Route │ Route │ Route
▼ ▼ ▼
┌─────────────┐ ┌─────────────┐ ┌─────────────┐
│Application │ │Application │ │Application │
│ Pod A │ │ Pod B │ │ Pod C │
└─────────────┘ └─────────────┘ └─────────────┘
Build and Deploy Pipeline
┌─────────────────────────────────────────────────────────────┐
│ CI/CD Pipeline Dependencies │
└─────────────────────────────────────────────────────────────┘
Developer
│ git push
▼
┌─────────────┐ webhook ┌─────────────┐
│ Git Repo │─────────────→ │ Concourse │
│(Source Code)│ │ Pipeline │
└─────────────┘ └─────────────┘
│ trigger build
▼
┌─────────────┐ ┌─────────────┐
│ Harbor │◄──────────────│ TBS │
│ Registry │ push image │ (Cloud │
│(Store+Scan) │ │Buildpacks) │
└─────────────┘ └─────────────┘
│ deploy ▲
▼ │ base images
┌─────────────┐ pull ┌─────────────┐
│ Kubernetes │◄──────────────│ Kubernetes │
│ Cluster │ │ Image Pull │
│(Runtime) │ │ Secret │
└─────────────┘ └─────────────┘
Data Flow Diagrams
Certificate Management Flow
┌─────────────────────────────────────────────────────────────┐
│ Automated Certificate Lifecycle │
└─────────────────────────────────────────────────────────────┘
cert-manager Controller
│ 1. Request Certificate
▼
┌─────────────┐ 2. ACME ┌─────────────┐
│Let's Encrypt│◄─── Challenge──│ Route53 │
│ CA │ │DNS Provider │
└─────────────┘ └─────────────┘
│ 3. Issue Certificate ▲
▼ │ 2a. Create
┌─────────────┐ │ TXT Record
│ TLS Secret │ │
│(cert + key) │ ┌──────────────┐
└─────────────┘ │cert-manager │
│ 4. Mount Certificate │Route53 Solver│
▼ └──────────────┘
┌─────────────┐ 5. Auto-reload
│ Contour │◄─────────────────────┐
│ Ingress │ │
│ Controller │ │
└─────────────┘ │
│ 6. Serve HTTPS │
▼ │
┌─────────────┐ ┌─────────────┐
│Application │ │ Certificate │
│ Services │ │Update Watch │
└─────────────┘ └─────────────┘
Image Build and Deploy Flow
┌─────────────────────────────────────────────────────────────┐
│ Container Image Lifecycle │
└─────────────────────────────────────────────────────────────┘
┌─────────────┐ 1. Source ┌─────────────┐
│ Git Repo │──── Change ──→│ Concourse │
│ │ │ Pipeline │
└─────────────┘ └─────────────┘
│ 2. Trigger Build
▼
┌─────────────┐
│ TBS │
│(Buildpacks) │
└─────────────┘
│ 3. Create Image
▼
┌─────────────┐ 4. Push ┌─────────────┐
│ Harbor │◄──── Image ───│ Container │
│ Registry │ │ Image │
└─────────────┘ └─────────────┘
│ 5. Vulnerability ▲
│ Scan Results │ 3a. Build Process
▼ │
┌─────────────┐ ┌─────────────┐
│ Security │ │ Stack │
│ Report │ │ (Base OS) │
└─────────────┘ └─────────────┘
│ 6. Deploy if Secure │
▼ │ 3b. OS Updates
┌─────────────┐ 7. Pull ┌─────────────┐
│ Kubernetes │◄───Image──────│ Automated │
│ Cluster │ │ Rebase │
└─────────────┘ └─────────────┘
Integration Points
Key Service Integrations
| Service A | Service B | Integration Type | Purpose |
|---|---|---|---|
| cert-manager | Route53 | DNS-01 Challenge | Certificate validation |
| Contour | cert-manager | TLS Certificate | HTTPS termination |
| Harbor | TBS | Image Registry | Store built images |
| TKG | Harbor | Image Pull | Container runtime |
| Concourse | TBS | Build Trigger | Automated builds |
| NSX-T | TKG | Network Policy | Micro-segmentation |
| BOSH | vCenter | VM Lifecycle | Infrastructure management |
| Knative | TKG | Serverless Runtime | Auto-scaling applications |
Authentication and Authorization Flow
┌─────────────────────────────────────────────────────────────┐
│ Authentication Chain │
└─────────────────────────────────────────────────────────────┘
User/Service Account
│ 1. Authenticate
▼
┌─────────────┐ 2. Validate ┌─────────────┐
│ vCenter SSO │◄─── Tokens ────│ TKG Cluster │
│ Identity │ │ API │
└─────────────┘ └─────────────┘
│ 3. Authorize │ 4. RBAC Check
▼ ▼
┌─────────────┐ ┌─────────────┐
│ vSphere │ │ Kubernetes │
│ Permissions │ │ RBAC │
└─────────────┘ └─────────────┘
│ 5. Allow/Deny
▼
┌─────────────┐
│ Application │
│ Access │
└─────────────┘
Troubleshooting Dependencies
Common Dependency Issues
Issue: Harbor Images Not Pulling
Check Dependency Chain:
- TKG cluster → Harbor registry connectivity
- Harbor → Certificate validity (cert-manager)
- cert-manager → DNS resolution (Route53)
- Route53 → Internet connectivity
Debug Commands:
# Test connectivity
kubectl run test --image=harbor.tkg.markalston.net/library/nginx --rm -it
# Check certificate
kubectl get certificates -n cert-manager
# Verify DNS resolution
nslookup harbor.tkg.markalston.net
Issue: Applications Not Accessible Externally
Check Dependency Chain:
- Application → Service → Ingress (Contour)
- Contour → NSX-T Load Balancer
- NSX-T LB → UXG Gateway port forwarding
- UXG Gateway → Internet routing
Debug Commands:
# Check ingress status
kubectl get httpproxy -A
# Verify load balancer
kubectl get svc -n projectcontour envoy
# Test internal connectivity
kubectl run test --image=curlimages/curl --rm -it -- curl -v http://app.internal
Health Check Matrix
| Component | Health Check Command | Expected Result |
|---|---|---|
| ESXi Hosts | ssh root@esxi-host "esxcli system version get" | Version information |
| vCenter | curl -k https://vcenter/ui/ | HTTP 200 response |
| NSX-T | curl -k https://nsxt-manager/api/v1/cluster/status | Cluster status |
| BOSH | bosh -e homelab vms | VM list |
| TKG | kubectl get nodes | All nodes Ready |
| Harbor | curl -k https://harbor/api/v2.0/health | Healthy status |
| Contour | kubectl get pods -n projectcontour | All pods Running |
This dependency understanding enables effective troubleshooting and system maintenance across the entire homelab infrastructure.
Reference this guide when diagnosing issues or planning infrastructure changes