badblocks/docker-easy-haproxy
1
0
Fork 0
Code Activity
docker-easy-haproxy/RELEASE.md
Joao Gilberto Magalhaes d3149637b4 Add detailed release guide and update Makefile test command 
- Introduced `RELEASE.md` with comprehensive steps for creating, automating, and troubleshooting EasyHAProxy releases.
- Enhanced the Makefile `test` command to include verbosity in the pytest execution.
2025-12-02 11:54:47 -05:00

9.1 KiB
Raw Blame History

EasyHAProxy Release Guide

This guide explains how to create a new release of EasyHAProxy, including Docker images, Helm charts, and documentation updates.

Table of Contents

Overview

The EasyHAProxy release process uses GitHub Actions to automatically:

  • Run tests
  • Build multi-architecture Docker images (amd64, arm64)
  • Publish Docker images to Docker Hub
  • Update Helm chart versions
  • Publish Helm charts
  • Update documentation

Prerequisites

Before creating a release, ensure you have:

  1. Permissions:

    • Write access to the GitHub repository
    • Docker Hub credentials (for maintainers)
    • Access to GitHub secrets (for CI/CD)

  2. Local Setup:

    • Git configured with your credentials
    • Docker installed (for local testing)
    • Python 3.x with pytest (for running tests)

  3. Repository Secrets (for maintainers):

    • DOCKER_REGISTRY: Docker Hub registry URL
    • DOCKER_REGISTRY_USER: Docker Hub username
    • DOCKER_REGISTRY_TOKEN: Docker Hub access token
    • DOC_TOKEN: GitHub token for documentation updates

Release Process

Version Numbering

EasyHAProxy follows Semantic Versioning:

  • MAJOR.MINOR.PATCH (e.g., 4.6.0)
    • MAJOR: Breaking changes or major architectural updates
    • MINOR: New features, plugin additions, backward-compatible changes
    • PATCH: Bug fixes, documentation updates, minor improvements

Current Version: 4.6.0 (as of Chart.yaml)

Automated Release (Recommended)

The automated release process is triggered by pushing a semantic version tag.

Step 1: Prepare the Release

  1. Ensure all changes are committed and pushed:

    git status
git add .
git commit -m "Prepare release X.Y.Z"
git push origin master

  2. Run tests locally:

    cd src/
pytest tests/ -vv

  3. Build and test Docker image locally:

    make build
# Or manually:
docker build -t byjg/easy-haproxy:local -f build/Dockerfile .

Step 2: Create and Push a Release Tag

  1. Create a new semantic version tag:

    # For a new minor version (new features)
git tag 4.7.0

# For a patch version (bug fixes)
git tag 4.6.1

# For a major version (breaking changes)
git tag 5.0.0

  2. Push the tag to GitHub:

    git push origin 4.7.0

  3. Monitor the GitHub Actions workflow:

Step 3: What Happens Automatically

When you push a semantic version tag, GitHub Actions will:

  1. Run Tests (Test job):

    • Install Python dependencies
    • Run pytest on all tests

  2. Build Multi-Arch Docker Images (Build job):

    • Build for linux/amd64 and linux/arm64
    • Tag image with version number (e.g., byjg/easy-haproxy:4.7.0)
    • Push to Docker Hub

  3. Update Versions (Helm job):

    • Update helm/easyhaproxy/Chart.yaml:
      • appVersion: Set to new version (e.g., 4.7.0)
      • version: Auto-increment patch version (e.g., 0.1.9 → 0.1.10)
    • Update all version references in:
      • deploy/docker/docker-compose.yml
      • deploy/kubernetes/easyhaproxy-*.yml
      • docs/kubernetes.md
      • examples/*/*.yml
    • Commit and push changes with message: [skip ci] Update from X.Y.Z to A.B.C

  4. Publish Helm Chart (HelmDeploy job):

  5. Update Documentation (Documentation job):

    • Publish documentation updates

Step 4: Verify the Release

  1. Check Docker Hub:

    docker pull byjg/easy-haproxy:4.7.0
docker images | grep easy-haproxy

  2. Verify Helm chart:

    helm repo add byjg https://opensource.byjg.com/helm
helm repo update
helm search repo easyhaproxy

  3. Create GitHub Release:

Manual Release

For emergency releases or when CI/CD is unavailable.

Manual Docker Build (Multi-Arch)

  1. Set up environment:

    export DOCKER_USERNAME=your-username
export DOCKER_PASSWORD=your-token
export DOCKER_REGISTRY=docker.io
export VERSIONS="4.7.0"

  2. Run multi-arch build:

    ./build-multiarch.sh

    This script uses buildah and podman to create multi-architecture images.

Manual Helm Chart Update

  1. Update Chart.yaml:

    cd helm/easyhaproxy/

# Update appVersion
sed -i 's/appVersion: ".*"/appVersion: "4.7.0"/' Chart.yaml

# Increment chart version
# From: version: 0.1.9
# To:   version: 0.1.10
nano Chart.yaml

  2. Package and publish Helm chart:

    helm package helm/easyhaproxy/
# Follow your Helm repository's publishing process

Helm Chart Release

The Helm chart version is automatically managed by CI/CD, but you can manually control it:

Helm Chart Version Strategy

  • Chart version (version in Chart.yaml):

    • Auto-incremented by CI/CD (patch version)
    • Format: 0.1.X where X increments with each Docker release
    • Manual override: Edit Chart.yaml before tagging

  • App version (appVersion in Chart.yaml):

    • Set to Docker image version (e.g., 4.7.0)
    • Automatically updated by CI/CD

Current Helm Chart

Post-Release Checklist

After a successful release:

  • Verify Docker image on Docker Hub
  • Test Docker image: docker run byjg/easy-haproxy:X.Y.Z --version
  • Verify Helm chart availability
  • Test Helm installation
  • Create GitHub Release with changelog
  • Update project README if needed
  • Announce release (if major/minor)
  • Update dependent projects (if applicable)

Troubleshooting

Build Fails

Problem: GitHub Actions build job fails

Solutions:

  1. Check test output in GitHub Actions logs
  2. Run tests locally: cd src/ && pytest tests/ -vv
  3. Fix failing tests and push changes
  4. Delete and recreate tag: 
    git tag -d 4.7.0
git push origin :refs/tags/4.7.0
git tag 4.7.0
git push origin 4.7.0

Docker Push Fails

Problem: Cannot push to Docker Hub

Solutions:

  1. Verify Docker Hub credentials in GitHub secrets
  2. Check Docker Hub token permissions
  3. Ensure image name matches: byjg/easy-haproxy

Helm Chart Not Published

Problem: Helm chart doesn't appear in repository

Solutions:

  1. Check HelmDeploy job logs in GitHub Actions
  2. Verify DOC_TOKEN secret is valid
  3. Wait a few minutes for chart to propagate
  4. Clear Helm cache: helm repo update

Version Not Updated

Problem: Version references not updated in docs/examples

Solutions:

  1. Check Helm job logs for sed command errors
  2. Verify commit was pushed with [skip ci] message
  3. Manually update version references if needed: 
    find examples -type f -name '*.yml' -exec sed -i "s/\(byjg\/easy-haproxy:\)[0-9\.]*/\1X.Y.Z/g" {} \;

Multi-Arch Build Issues

Problem: ARM64 build fails

Solutions:

  1. Verify QEMU is set up in GitHub Actions
  2. Check build logs for architecture-specific errors
  3. Test locally with Docker Buildx: 
    docker buildx create --use
docker buildx build --platform linux/amd64,linux/arm64 -t test .

Quick Reference

Commands

# Local build
make build

# Run tests
cd src/ && pytest tests/ -vv

# Create release tag
git tag 4.7.0 && git push origin 4.7.0

# Pull specific version
docker pull byjg/easy-haproxy:4.7.0

# Install Helm chart
helm install easyhaproxy byjg/easyhaproxy --version 0.1.10

# Check Helm chart info
helm show chart byjg/easyhaproxy

Important URLs

Version History

Version Release Date Type Highlights
4.6.0 2024-11-27 Minor FastCGI plugin, JWT enhancements
4.5.0 2024-XX-XX Minor Previous release
... ... ... ...

Need Help?