Environment Setup and Security

This document explains how to securely configure environment variables for your homelab infrastructure.

Overview

The homelab repository uses environment variables to keep sensitive credentials out of version control. All credentials and configuration values are stored in a .envrc file that is excluded from git.

Quick Setup

Copy the example environment file:
```
cp .envrc.example .envrc
```

Edit .envrc with your actual values:

# Use your preferred editor
vim .envrc
# or
code .envrc

Load environment variables:

# Option 1: Using direnv (recommended)
direnv allow
   
# Option 2: Manual sourcing
source .envrc

Required Environment Variables

vCenter/vSphere Credentials

export VCENTER_SERVER="vcenter.yourdomain.com"
export VCENTER_USERNAME="administrator@vsphere.local"
export VCENTER_PASSWORD="your-secure-password"

Harbor Registry

export HARBOR_ADMIN_PASSWORD="your-harbor-password"

AWS/Route53 (for certificate management)

export AWS_ACCESS_KEY_ID="your-aws-access-key"
export AWS_SECRET_ACCESS_KEY="your-aws-secret-key"
export ROUTE53_SECRET_ACCESS_KEY="your-route53-secret"

Docker Hub (for image pulls)

export DOCKER_HUB_USERNAME="your-dockerhub-username"
export DOCKER_HUB_PASSWORD="your-dockerhub-password"
export DOCKER_HUB_EMAIL="your-email@example.com"

Security Best Practices

1. Credential Management

Never commit .envrc to version control
Use strong, unique passwords for each service
Consider using a password manager to generate and store credentials
Rotate credentials regularly

2. File Permissions

# Secure the .envrc file
chmod 600 .envrc

3. Environment Isolation

Use separate .envrc files for different environments (dev, staging, prod)
Consider using different credential sets for each environment

4. Base64 Encoded Values

Some systems require base64-encoded passwords. The example file includes helpers:

export VCENTER_SSO_PASSWORD_BASE64="$(echo 'your-password' | base64)"

Using direnv (Recommended)

direnv automatically loads and unloads environment variables based on the current directory.

Installation

# macOS
brew install direnv

# Ubuntu/Debian
sudo apt install direnv

# Add to your shell profile
echo 'eval "$(direnv hook bash)"' >> ~/.bashrc
# or for zsh
echo 'eval "$(direnv hook zsh)"' >> ~/.zshrc

Usage

# Allow direnv to load .envrc in the current directory
direnv allow

# Variables are automatically loaded when entering the directory
cd /path/to/homelab
# Environment variables are now available

Environment Variable Reference

Network Configuration

MANAGEMENT_NETWORK: Management network CIDR
VSPHERE_NETWORK_CIDR: vSphere network range
HOMELAB_DOMAIN: Your homelab domain name

Service Endpoints

VCENTER_SERVER: vCenter server hostname/IP
NSXT_MANAGER_HOST: NSX-T manager hostname/IP
TKG_SERVICE_DOMAIN: Tanzu service domain

Storage Classes

CONTROL_PLANE_STORAGE_CLASS: Storage class for control plane nodes
DEFAULT_STORAGE_CLASS: Default storage class for workloads

Certificate Management

LETSENCRYPT_EMAIL: Email for Let’s Encrypt certificates
CERT_MANAGER_NAMESPACE: Namespace for cert-manager

Troubleshooting

Variables Not Loading

# Check if direnv is working
direnv status

# Manually source the file
source .envrc

# Verify variables are set
env | grep VCENTER

Permission Denied

# Check file permissions
ls -la .envrc

# Fix permissions
chmod 600 .envrc

Base64 Encoding Issues

# Encode a password
echo 'your-password' | base64

# Decode to verify
echo 'eW91ci1wYXNzd29yZAo=' | base64 -d

Migrating from Hardcoded Values

If you’re migrating from the old system with hardcoded credentials:

Identify hardcoded values in your files
Replace with environment variables using the format ${VARIABLE_NAME}
Add the variables to your .envrc file
Test thoroughly to ensure all services still work

Example Migration

# Before (hardcoded)
kubectl create secret generic route53-secret --from-literal=secret-access-key="abc123..."

# After (environment variable)
kubectl create secret generic route53-secret --from-literal=secret-access-key="${ROUTE53_SECRET_ACCESS_KEY}"

Security Considerations

What NOT to do

❌ Commit .envrc to git
❌ Share credentials in Slack/email
❌ Use default/weak passwords
❌ Store credentials in scripts

What TO do

✅ Use .envrc.example for documentation
✅ Use strong, unique passwords
✅ Rotate credentials regularly
✅ Use least-privilege access
✅ Monitor access logs