Contributing to Aotanami¶

Thank you for your interest in contributing to Aotanami! This document provides guidelines and instructions for contributing.

Code of Conduct¶

By participating in this project, you agree to abide by our Code of Conduct.

How to Contribute¶

Reporting Issues¶

• Use GitHub Issues for bug reports and feature requests
• Security vulnerabilities: Please see our Security Policy — do not use public issues
• Include reproduction steps, expected behavior, and actual behavior
• Include your Kubernetes version, Aotanami version, and cloud provider

Pull Requests¶

1. Fork the repository and create a feature branch from main
2. Follow the commit conventions below
3. Write tests for new functionality
4. Ensure all CI checks pass (make lint test)
5. Update documentation if your change affects user-facing behavior
6. Submit a PR against main

Commit Conventions¶

We follow Conventional Commits:

<type>(<scope>): <description>

[optional body]

[optional footer(s)]

Types: feat, fix, docs, style, refactor, perf, test, build, ci, chore

Scopes: scanner, monitor, llm, remediation, dashboard, notifier, helm, api, crd, ci

Examples:

feat(scanner): add RBAC over-permission detection
fix(llm): respect hourly token budget limits
docs(api): add OpenAPI spec for incidents endpoint

Development Setup¶

Prerequisites¶

• Go 1.25+
• Docker
• kubectl
• kind or minikube
• Kubebuilder 4.x
• Helm 3.x

Getting Started¶

# Clone your fork
git clone https://github.com/<your-username>/aotanami.git
cd aotanami

# Add upstream remote
git remote add upstream https://github.com/aotanami/aotanami.git

# Install dependencies
make install

# Generate manifests and code
make manifests generate

# Run tests
make test

# Run locally against a kind cluster
kind create cluster --name aotanami-dev
make install  # Install CRDs
make run      # Run the operator

Project Structure¶

├── api/v1alpha1/          # CRD type definitions
├── cmd/                   # Entrypoint
├── config/                # Kubebuilder kustomize configs
├── deploy/helm/           # Helm chart
├── docs/                  # Documentation
├── internal/
│   ├── controller/        # Kubebuilder controllers
│   ├── webhook/           # Admission webhooks
│   ├── llm/               # LLM client (BYO keys)
│   ├── scanner/           # Security scanner
│   ├── monitor/           # Real-time monitoring
│   ├── anomaly/           # Anomaly detection
│   ├── compliance/        # Compliance frameworks
│   ├── costoptimizer/     # Cost optimization
│   ├── drift/             # Config drift detection
│   ├── remediation/       # GitOps fix generator
│   ├── notifier/          # Alert routing
│   ├── dashboard/         # Embedded web UI
│   ├── api/               # REST API
│   └── ...
└── hack/                  # Development scripts

Useful Make Targets¶

Testing¶

• Unit tests: Place in the same package as the code being tested
• Integration tests: Use envtest (Kubebuilder's test framework)
• Coverage: Aim for >80% coverage on new code

# Run all tests with coverage
make test

# Run specific package tests
go test ./internal/scanner/... -v

Questions?¶

Open a Discussion for questions about the project.

Thank you for contributing to Aotanami! 🎉