Skip to content

CONTRIBUTING.md

Latest commit

 

History

History
294 lines (221 loc) · 8.09 KB

CONTRIBUTING.md

File metadata and controls

294 lines (221 loc) · 8.09 KB

Contributing to Workload-Variant-Autoscaler

Welcome! We're excited that you're interested in contributing to the Workload-Variant-Autoscaler (WVA) project.

General Contributing Guidelines

For general contribution guidelines including code of conduct, commit message format, PR process, and community standards, please see the llm-d Contributing Guide.

This document covers WVA-specific development setup and workflows.

WVA-Specific Development

Prerequisites

  • Go 1.25.0+
  • Docker 17.03+
  • kubectl 1.31.0+ (or oc for OpenShift)
  • Kind (for local development)
  • Basic understanding of Kubernetes controllers and operators

Setting Up Your Development Environment

  1. Fork and clone the repository:

    git clone https://github.com/<your-username>/workload-variant-autoscaler.git
cd workload-variant-autoscaler

  2. Add upstream remote:

    git remote add upstream https://github.com/llm-d/llm-d-workload-variant-autoscaler.git

  3. Install dependencies:

    go mod download

  4. Set up a local Kind cluster with emulated GPUs:

    make deploy-llm-d-wva-emulated-on-kind

  5. Run tests to verify setup:

    make test

See Developer Guide for detailed setup instructions.

GitHub Agentic Workflows

The repository uses AI-powered workflows to automate repetitive tasks:

  • Documentation Updates: Automatically syncs docs with code changes
  • Workflow Creation: Interactive designer for new workflows
  • Workflow Debugging: Assists with troubleshooting

Learn more in the Agentic Workflows Guide.

WVA Project Structure

workload-variant-autoscaler/
├── api/v1alpha1/         # CRD definitions and types
├── cmd/                  # Main application entry point
├── config/               # Kubernetes manifests
│   ├── crd/             # CRD base manifests
│   ├── rbac/            # RBAC configurations
│   ├── manager/         # Controller deployment configs
│   └── samples/         # Example VariantAutoscaling CRs
├── deploy/               # Deployment scripts
│   ├── kubernetes/      # Standard K8s deployment
│   ├── openshift/       # OpenShift-specific deployment
│   └── kind-emulator/   # Local development with Kind
├── docs/                 # Documentation
│   ├── user-guide/      # User-facing documentation
│   ├── developer-guide/ # Development and testing guides
│   ├── integrations/    # Integration guides (HPA, KEDA, Prometheus)
│   ├── tutorials/       # Step-by-step tutorials
│   └── design/          # Architecture and design docs
├── internal/             # Private application code
│   ├── controller/      # Main reconciliation logic
│   ├── collector/       # Metrics collection
│   ├── optimizer/       # Optimization engine
│   ├── actuator/        # Metric emission & actuation
│   ├── modelanalyzer/   # Model performance analysis
│   ├── metrics/         # Metrics definitions
│   └── utils/           # Utility functions
├── pkg/                  # Public libraries (inferno optimizer)
│   ├── analyzer/        # Queue theory models
│   ├── solver/          # Optimization algorithms
│   ├── core/            # Core domain models
│   ├── config/          # Configuration structures
│   └── manager/         # Optimization manager
├── test/                 # Tests
│   ├── e2e/             # End-to-end tests
│   └── utils/           # Test utilities
├── hack/                 # Dev scripts (e.g. hack/burst_load_generator.sh for manual load)
└── charts/               # Helm charts
    └── workload-variant-autoscaler/

WVA-Specific Development Tasks

Testing Your Changes

Run unit tests:

make test

Run E2E tests (Kind or OpenShift):

# Smoke tests (Kind)
make test-e2e-smoke

# Full suite (Kind)
make test-e2e-full

# OpenShift: set KUBECONFIG and ENVIRONMENT, then run
export ENVIRONMENT=openshift
make test-e2e-smoke
# or make test-e2e-full

# Run specific tests
FOCUS="Basic VA lifecycle" make test-e2e-smoke

Run linter:

make lint

# Auto-fix linting issues
make lint-fix

Modifying CRDs

If you modify the VariantAutoscaling CRD in api/v1alpha1/:

  1. Generate updated manifests and code:

    make manifests generate

  2. Update CRD documentation:

    make crd-docs

  3. Verify CRD changes:

    kubectl explain variantautoscaling.spec

Building and Deploying

Build the controller binary:

make build

Run controller locally (connects to configured cluster):

make run

Build Docker image:

make docker-build IMG=<your-registry>/wva-controller:tag

Deploy to cluster:

make deploy IMG=<your-registry>/wva-controller:tag

Deploy with llm-d for testing:

make deploy-llm-d-wva-emulated-on-kind IMG=<your-registry>/wva-controller:tag

Documentation

Updating Documentation

When making code changes, update relevant documentation in:

  • docs/user-guide/ - User-facing changes (CRD changes, new features)
  • docs/developer-guide/ - Development workflow changes
  • docs/integrations/ - Integration guide updates
  • docs/design/ - Architecture or design changes
  • README.md - High-level feature changes

Testing Documentation

Verify all commands and examples work:

# Test installation steps from docs
# Test configuration examples
# Verify all code snippets are correct

WVA-Specific Code Guidelines

Controller Development

  • Use the logger package from internal/logger
  • Always use backoff retries for Kubernetes API calls (see internal/utils)
  • Update Kubernetes conditions for status visibility
  • Emit metrics for observability

Performance Modeling

When modifying queue models in pkg/analyzer/:

  • Ensure mathematical correctness
  • Add comprehensive unit tests
  • Validate against real workload data when possible
  • Document assumptions and limitations

Optimization Algorithms

When modifying solvers in pkg/solver/:

  • Consider computational complexity
  • Test edge cases (zero load, overload, etc.)
  • Ensure feasibility checking
  • Document algorithm choices

Getting Help

Common Development Tasks

Running the Controller Locally

# Option 1: Run outside cluster (connects to KUBECONFIG cluster)
make run

# Option 2: Deploy to Kind cluster
make deploy-llm-d-wva-emulated-on-kind

Debugging

# View controller logs
kubectl logs -n workload-variant-autoscaler-system \
  -l control-plane=controller-manager --tail=100 -f

# Check VariantAutoscaling status
kubectl describe variantautoscaling <name> -n <namespace>

# Check emitted metrics
kubectl get --raw "/apis/external.metrics.k8s.io/v1beta1/namespaces/<namespace>/wva_desired_replicas" | jq

Cleaning Up

# Destroy Kind cluster
make destroy-kind-cluster

# Undeploy from cluster
make undeploy

# Uninstall CRDs
make uninstall

Pre-Submission Checklist

Before submitting your PR, ensure:

  • make test passes
  • make lint passes (fix issues with make lint-fix)
  • make test-e2e-smoke passes (if controller logic changed; use make test-e2e-full for full suite)
  • Documentation updated (if user-facing changes)
  • CRD docs regenerated (if CRD changed): make crd-docs
  • Commit messages follow conventional commits
  • PR description clearly explains the change

License

By contributing, you agree that your contributions will be licensed under the Apache License 2.0.

Thank you for contributing to Workload-Variant-Autoscaler!