Template Usage Guide

Creating a New Project from This Template

This repository is designed as a GitHub template to bootstrap new Kubernetes-based projects quickly.

Why Use This Template?

• ✅ Production-ready infrastructure from day one
• ✅ Best practices baked in
• ✅ Fully documented and tested
• ✅ Customizable for your needs
• ✅ AI-assisted configuration with GitHub Copilot

Creating from Template

Option 1: GitHub Web UI

1. Navigate to github.com/ianlintner/green_field_cluster
2. Click the "Use this template" button (green button at top right)
3. Select "Create a new repository"
4. Enter your project details:
5. Repository name (e.g., my-awesome-project)
6. Description
7. Public or Private
8. Click "Create repository from template"

Option 2: GitHub CLI

gh repo create my-awesome-project \
  --template ianlintner/green_field_cluster \
  --private \
  --clone

Option 3: Using git directly

# Clone the template
git clone https://github.com/ianlintner/green_field_cluster.git my-project
cd my-project

# Remove the original remote
git remote remove origin

# Add your new repository as remote
git remote add origin https://github.com/yourusername/my-project.git

# Push to your new repository
git push -u origin main

Customization Workflow

1. Initial Setup

After creating your repository from the template:

cd my-project

# Update project information
# Edit these files:
# - README.md (update project name and description)
# - mkdocs.yml (update site_name, repo_url)
# - helm/greenfield-cluster/Chart.yaml (update name, description)

2. Configure with Copilot

Open your project in an IDE with GitHub Copilot enabled and describe your requirements:

3. Deployment Workflow

Common Customizations

Remove Unused Components

If you don't need certain databases:

resources:
  - namespace
  - redis
  - postgres
  # - mysql        # Commented out - not needed
  # - mongodb      # Commented out - not needed
  - kafka
  - otel-collector
  - jaeger
  - prometheus
  - grafana
  - fastapi-app

mysql:
  enabled: false    # Disable MySQL

mongodb:
  enabled: false    # Disable MongoDB

Add Your Application

Create manifests for your application:

# Create your app directory
mkdir -p kustomize/base/my-app

# Add manifests
cat > kustomize/base/my-app/deployment.yaml << 'EOF'
apiVersion: apps/v1
kind: Deployment
metadata:
  name: my-app
  namespace: greenfield
spec:
  replicas: 2
  selector:
    matchLabels:
      app: my-app
  template:
    metadata:
      labels:
        app: my-app
    spec:
      containers:
        - name: my-app
          image: my-registry/my-app:latest
          ports:
            - containerPort: 8080
          env:
            - name: OTEL_EXPORTER_OTLP_ENDPOINT
              value: "http://otel-collector:4317"
            - name: DATABASE_URL
              valueFrom:
                secretKeyRef:
                  name: my-app-secret
                  key: database-url
EOF

Adjust Resource Sizes

For different environments, modify the overlays:

# kustomize/overlays/prod/kustomization.yaml
resources:
  - ../../base

replicas:
  - name: my-app
    count: 10  # Scale up for production

patches:
  - target:
      kind: Deployment
      name: my-app
    patch: |-
      - op: replace
        path: /spec/template/spec/containers/0/resources/limits/memory
        value: 2Gi

Working with Copilot in Template Repos

Best Practices for Copilot Instructions

When working with this template, use these patterns:

1. Provide Context: Always mention you're working with a template

   "This is a template repository for Kubernetes clusters. I need to..."
   

2. Be Specific: Describe exactly what you need

   "Add a new microservice called 'user-service' that connects to PostgreSQL"
   

3. Reference Existing Patterns: Point to similar components

   "Create a deployment similar to fastapi-app but for my Node.js API"
   

4. Ask for Best Practices: Leverage Copilot's knowledge

   "What's the best way to configure resource limits for a production database?"
   

Example: Adding a New Service

Deployment After Customization

Once you've customized your cluster:

# Validate your changes
make validate

# Deploy to development
kubectl apply -k kustomize/overlays/dev/

# Or deploy with Helm
helm install my-project helm/greenfield-cluster \
  --namespace my-project \
  --create-namespace

Continuous Customization

As your project evolves:

1. Add new components as needed
2. Scale resources based on load
3. Update configurations for optimization
4. Leverage Copilot for ongoing development

Getting Help

• Use @copilot in your IDE for suggestions
• Check the Examples for common patterns
• Review Architecture for understanding component interactions
• See Best Practices for production guidelines

Template Maintenance

To keep your project updated with template improvements:

# Add the template as a remote
git remote add template https://github.com/ianlintner/green_field_cluster.git

# Fetch template updates
git fetch template

# Cherry-pick or merge specific improvements
git cherry-pick <commit-hash>