drunk.charts

Development Guide

This guide provides everything you need to know to contribute to and extend the Drunk Charts project. Whether you’re fixing bugs, adding features, or creating new charts, this guide will help you get started.

Getting Started
Development Environment
Project Structure
Development Workflow
Testing
Contributing Guidelines
Release Process
Best Practices

Getting Started

Prerequisites

Git: Version control
Helm: 3.0+ for chart development and testing
Kubernetes: Local cluster (minikube, kind, Docker Desktop) for testing
Docker: For building and testing container images
Text Editor: VS Code with Helm/YAML extensions recommended

Clone the Repository

git clone https://github.com/baoduy/drunk.charts.git
cd drunk.charts

Repository Structure

drunk.charts/
├── README.md                    # Main project documentation
├── docs/                        # Comprehensive documentation
│   ├── README.md               # Documentation index
│   ├── quick-start.md          # Quick start guide
│   ├── drunk-app.md            # drunk-app chart documentation
│   ├── drunk-lib.md            # drunk-lib library documentation
│   ├── architecture.md         # Architecture overview
│   ├── development.md          # This file
│   └── examples/               # Configuration examples
├── drunk-app/                   # Application chart
│   ├── Chart.yaml              # Chart metadata
│   ├── values.yaml             # Default values
│   ├── templates/              # Chart templates
│   ├── tests/                  # Chart tests
│   └── README.md               # Chart-specific docs
├── drunk-lib/                   # Library chart  
│   ├── Chart.yaml              # Chart metadata (type: library)
│   ├── values.yaml             # Default template values
│   └── templates/              # Reusable template library
└── .github/                     # GitHub workflows and templates
    └── workflows/              # CI/CD automation

Development Environment

Local Setup

Install Dependencies

# Install Helm
curl https://get.helm.sh/helm-v3.12.0-linux-amd64.tar.gz | tar xz
sudo mv linux-amd64/helm /usr/local/bin/

# Install helm-unittest plugin for testing
helm plugin install https://github.com/helm-unittest/helm-unittest
   
# Install Kubernetes cluster (choose one)
# Docker Desktop, minikube, or kind

Verify Setup

helm version
kubectl cluster-info
helm unittest --help

IDE Configuration

VS Code Extensions

{
  "recommendations": [
    "ms-kubernetes-tools.vscode-kubernetes-tools",
    "redhat.vscode-yaml",
    "tim-koike.helm-intellisense"
  ]
}

VS Code Settings

{
  "yaml.schemas": {
    "https://json.schemastore.org/chart.json": "Chart.yaml",
    "https://json.schemastore.org/helmfile.json": "helmfile.yaml"
  },
  "files.associations": {
    "*.tpl": "yaml"
  }
}

Project Structure

Chart Organization

drunk-lib (Library Chart)

drunk-lib/
├── Chart.yaml                 # type: library, version, dependencies
├── values.yaml               # Default configuration for templates
└── templates/
    ├── _helpers.tpl          # Common helper functions
    ├── _deployment.tpl       # Deployment template
    ├── _service.tpl          # Service template
    ├── _configmap.tpl        # ConfigMap template
    ├── _secrets.tpl          # Secret template
    ├── _ingress.tpl          # Ingress template
    ├── _volumes.tpl          # PVC template
    ├── _cronjob.tpl          # CronJob template
    ├── _job.tpl              # Job template
    ├── _hpa.tpl              # HPA template
    ├── _serviceaccount.tpl   # ServiceAccount template
    ├── _secretprovider.tpl   # SecretProviderClass template
    └── _tls-secrets.tpl      # TLS Secret template

drunk-app (Application Chart)

drunk-app/
├── Chart.yaml                # Depends on drunk-lib
├── values.yaml              # User-facing configuration
├── templates/               # Thin wrappers around drunk-lib
│   ├── deployment.yaml      # 
│   ├── service.yaml         # 
│   └── ...                  # One file per resource type
├── tests/                   # Unit tests
│   └── deployment_test.yaml
└── values.example.yaml         # Test configuration

Template Naming Conventions

Library templates: _templatename.tpl (underscore prefix)
Named templates: drunk-lib.resourceType (e.g., drunk-lib.deployment)
Application templates: resourcetype.yaml (e.g., deployment.yaml)

Development Workflow

1. Setting Up a Feature Branch

# Create feature branch
git checkout -b feature/my-new-feature

# Or for bug fixes
git checkout -b fix/issue-description

2. Making Changes

Adding New Template to drunk-lib

Create template file:

touch drunk-lib/templates/_newresource.tpl

Implement template:

---
apiVersion: v1
kind: NewResource
metadata:
  name: 
  labels: 
spec:
  # Resource specification

Add to drunk-app:

# drunk-app/templates/newresource.yaml

Update default values:

# drunk-lib/values.yaml
newResource:
  enabled: false
  # ... configuration options

Modifying Existing Templates

Identify the template in drunk-lib
Make changes while maintaining backward compatibility
Update tests
Update documentation

3. Testing Changes

# Test template rendering
helm template test-release drunk-app/ --debug

# Test with custom values
helm template test-release drunk-app/ -f test-values.yaml

# Run unit tests
helm unittest drunk-app/

# Test specific templates
helm template test-release drunk-app/ --show-only templates/deployment.yaml

4. Updating Documentation

Update relevant .md files in docs/
Update chart README files if needed
Add examples for new features
Update configuration reference tables

Testing

Unit Testing with helm-unittest

Tests are located in tests/ directories and use the helm-unittest plugin.

Example Test Structure

# drunk-app/tests/deployment_test.yaml
suite: test deployment
templates:
  - deployment.yaml
tests:
  - it: should create deployment with default values
    asserts:
      - isKind:
          of: Deployment
      - equal:
          path: metadata.name
          value: RELEASE-NAME-drunk-app
      - equal:
          path: spec.replicas
          value: 1

  - it: should set custom replica count
    set:
      deployment.replicaCount: 3
    asserts:
      - equal:
          path: spec.replicas
          value: 3

Running Tests

# Run all tests
helm unittest drunk-app/

# Run specific test
helm unittest drunk-app/tests/deployment_test.yaml

# Run tests with verbose output
helm unittest drunk-app/ -v

Integration Testing

Local Kubernetes Testing

# Install chart in local cluster
helm install test-release drunk-app/ -f test-values.yaml

# Verify deployment
kubectl get all -l app.kubernetes.io/name=drunk-app

# Test application functionality
kubectl port-forward svc/test-release-drunk-app 8080:80

# Cleanup
helm uninstall test-release

Test Values

Create comprehensive test values in values.example.yaml:

global:
  image: "nginx"
  tag: "1.21"

deployment:
  enabled: true
  replicaCount: 2
  ports:
    http: 80

service:
  type: ClusterIP

ingress:
  enabled: true
  hosts:
    - host: test.example.com
      paths:
        - path: /
          pathType: Prefix

resources:
  requests:
    cpu: 100m
    memory: 128Mi
  limits:
    cpu: 500m
    memory: 512Mi

Automated Testing

The project uses GitHub Actions for CI/CD:

# .github/workflows/test.yml
name: Test Charts
on: [push, pull_request]

jobs:
  test:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v3
      - name: Set up Helm
        uses: azure/setup-helm@v3
      - name: Run chart tests
        run: |
          helm unittest drunk-app/
          helm unittest drunk-lib/

Contributing Guidelines

Code Style

YAML Formatting

Use 2 spaces for indentation
Keep lines under 120 characters
Use meaningful variable names
Add comments for complex logic

Template Best Practices

# Good: Clear conditionals
# Template content

# Good: Proper indentation
labels:

# Good: Safe value access
resources:

Helper Function Guidelines

# Good: Reusable helper

# Usage
name: 

Pull Request Process

Create Feature Branch
```
git checkout -b feature/description
```
Make Changes
- Follow coding standards
- Add/update tests
- Update documentation

Test Locally

helm unittest drunk-app/
helm template test drunk-app/ --debug

Submit PR
- Write clear commit messages
- Reference related issues
- Include testing instructions
Review Process
- Automated tests must pass
- Code review by maintainers
- Documentation review

Commit Message Format

type(scope): short description

Detailed description if needed

Fixes #123

Types: feat, fix, docs, test, refactor, style, chore

Examples:

feat(drunk-lib): add StatefulSet template support

Add comprehensive StatefulSet template with volume claim templates
and proper pod management policies.

Fixes #45

Release Process

Version Management

Both charts follow semantic versioning:

Major: Breaking changes (e.g., 1.0.0 → 2.0.0)
Minor: New features, backward compatible (e.g., 1.0.0 → 1.1.0)
Patch: Bug fixes (e.g., 1.0.0 → 1.0.1)

Release Steps

Update Chart Versions

# drunk-lib/Chart.yaml
version: 1.0.8  # Increment version
   
# drunk-app/Chart.yaml  
version: 1.2.7  # Increment version
dependencies:
  - name: drunk-lib
    version: 1.0.8  # Update dependency

Update Dependency
```
cd drunk-app/
helm dependency update
```

Test Release

helm package drunk-lib/
helm package drunk-app/

Create Release
- Create Git tag: git tag v1.2.7
- Push tag: git push origin v1.2.7
- GitHub Actions will automatically build and publish

Automated Release

The project uses GitHub Actions for automated releases:

# .github/workflows/release.yml
name: Release Charts
on:
  push:
    tags:
      - 'v*'

jobs:
  release:
    runs-on: ubuntu-latest
    steps:
      - name: Checkout
        uses: actions/checkout@v3
      - name: Package and Release
        run: |
          helm package drunk-lib/
          helm package drunk-app/
          # Upload to GitHub Releases

Best Practices

Template Development

Defensive Programming

# Check for required values
   
# Safe value access
setting: 

Resource Naming

# Use consistent naming helpers
name: 
labels: 

Configuration Validation
```
# Validate mutually exclusive options
```

Documentation Standards

Template Documentation
- Document all configuration options
- Provide examples for complex features
- Explain default behaviors
Code Comments
Change Documentation
- Update relevant docs with changes
- Add migration notes for breaking changes
- Include examples for new features

Security Considerations

Default Security

# Always include security contexts
securityContext:
  allowPrivilegeEscalation: false
  readOnlyRootFilesystem: true
  runAsNonRoot: true

Secret Handling

# Never expose secrets in logs
# Create secret without logging values

Resource Limits

# Always set resource limits
resources:
  limits:
    cpu: 
    memory: 

Performance Optimization

Conditional Rendering

# Only render when needed
# Resource definition

Template Caching
- Use helm template --debug to check rendering performance
- Minimize complex loops in templates
- Cache repeated calculations in variables

Troubleshooting Development Issues

Common Problems

Template Syntax Errors

# Debug template rendering
helm template test drunk-app/ --debug

Value Access Issues

# Check available values
helm template test drunk-app/ --debug | grep -A 10 "VALUES:"

Dependency Issues

# Update dependencies
helm dependency update drunk-app/
   
# Check dependency status
helm dependency list drunk-app/

Test Failures

# Run tests with verbose output
helm unittest drunk-app/ -v
   
# Test specific template
helm unittest drunk-app/tests/deployment_test.yaml -v

Getting Help

Documentation: Start with the main docs
Issues: GitHub Issues
Discussions: GitHub Discussions
Author: Steven Hoang

Happy coding! 🍻 Your contributions help make Kubernetes deployments easier for everyone.