|
| 1 | +# AGENTS.md - Agent Guidelines for Cluster API Provider OpenStack |
| 2 | + |
| 3 | +This document provides guidelines and useful commands for AI agents contributing to the Cluster API Provider OpenStack (CAPO) repository. |
| 4 | + |
| 5 | +> **⚠️ IMPORTANT**: When making changes to Makefile targets, PR requirements, code generation workflows, verification steps, or any other information referenced in this document, **AGENTS.md must be updated accordingly** to keep it synchronized with the actual project state. |
| 6 | +
|
| 7 | +## Overview |
| 8 | + |
| 9 | +Cluster API Provider OpenStack (CAPO) is a Kubernetes-native declarative infrastructure provider for managing Kubernetes clusters on OpenStack. It implements the Cluster API (CAPI) specification for self-managed Kubernetes clusters on OpenStack infrastructure. |
| 10 | + |
| 11 | +**Key Concepts:** |
| 12 | +- **CAPI**: Cluster API - the upstream Kubernetes project defining cluster lifecycle APIs |
| 13 | +- **CAPO**: Cluster API Provider OpenStack - this repository |
| 14 | +- **Reconciler**: Controller-runtime pattern for managing Kubernetes custom resources |
| 15 | +- **Scope**: Context and configuration wrapper for controllers and services |
| 16 | + |
| 17 | +## Key Requirements for Contributors |
| 18 | + |
| 19 | +### Legal Requirements |
| 20 | + |
| 21 | +- **CLA Required**: All contributors MUST sign the Kubernetes Contributor License Agreement (CLA) |
| 22 | +- See: https://git.k8s.io/community/CLA.md |
| 23 | + |
| 24 | +### Pull Request Labels |
| 25 | + |
| 26 | +All code PRs MUST be labeled with one of: |
| 27 | +- ⚠️ `:warning:` - major or breaking changes |
| 28 | +- ✨ `:sparkles:` - feature additions |
| 29 | +- 🐛 `:bug:` - patch and bugfixes |
| 30 | +- 📖 `:book:` - documentation or proposals |
| 31 | +- 🌱 `:seedling:` - minor or other |
| 32 | + |
| 33 | +## Essential Make Targets |
| 34 | + |
| 35 | +### Code Quality & Verification |
| 36 | + |
| 37 | +```bash |
| 38 | +# Run all verification checks (should pass before submitting PR) |
| 39 | +make verify |
| 40 | + |
| 41 | +# Verify boilerplate headers |
| 42 | +make verify-boilerplate |
| 43 | + |
| 44 | +# Verify go modules are up to date |
| 45 | +make verify-modules |
| 46 | + |
| 47 | +# Verify generated code is up to date |
| 48 | +make verify-gen |
| 49 | + |
| 50 | +# Verify container images for vulnerabilities |
| 51 | +make verify-container-images |
| 52 | + |
| 53 | +# Check code for security vulnerabilities |
| 54 | +make verify-govulncheck |
| 55 | + |
| 56 | +# Run all security checks (images + code) |
| 57 | +make verify-security |
| 58 | +``` |
| 59 | + |
| 60 | +### Linting |
| 61 | + |
| 62 | +```bash |
| 63 | +# Lint codebase |
| 64 | +make lint |
| 65 | + |
| 66 | +# Lint and auto-fix issues |
| 67 | +make lint-update |
| 68 | + |
| 69 | +# Run faster linters only |
| 70 | +make lint-fast |
| 71 | +``` |
| 72 | + |
| 73 | +### Testing |
| 74 | + |
| 75 | +```bash |
| 76 | +# Run unit tests |
| 77 | +make test |
| 78 | + |
| 79 | +# Run unit tests for CAPO specifically |
| 80 | +make test-capo |
| 81 | + |
| 82 | +# Build e2e test binaries |
| 83 | +make build-e2e-tests |
| 84 | + |
| 85 | +# Run e2e tests (requires OpenStack environment) |
| 86 | +make test-e2e |
| 87 | + |
| 88 | +# Run conformance tests |
| 89 | +make test-conformance |
| 90 | + |
| 91 | +# Compile e2e tests (verify they build) |
| 92 | +make compile-e2e |
| 93 | +``` |
| 94 | + |
| 95 | +### Code Generation |
| 96 | + |
| 97 | +```bash |
| 98 | +# Generate ALL code (manifests, deepcopy, clients, mocks, docs) |
| 99 | +make generate |
| 100 | + |
| 101 | +# Generate Go code (mocks, etc.) |
| 102 | +make generate-go |
| 103 | + |
| 104 | +# Generate controller-gen code (deepcopy, etc.) |
| 105 | +make generate-controller-gen |
| 106 | + |
| 107 | +# Generate client code (clientsets, listers, informers) |
| 108 | +make generate-codegen |
| 109 | + |
| 110 | +# Generate CRD manifests |
| 111 | +make generate-manifests |
| 112 | + |
| 113 | +# Generate API documentation |
| 114 | +make generate-api-docs |
| 115 | + |
| 116 | +# Generate cluster templates |
| 117 | +make templates |
| 118 | +``` |
| 119 | + |
| 120 | +### Dependency Management |
| 121 | + |
| 122 | +```bash |
| 123 | +# Update go modules |
| 124 | +make modules |
| 125 | + |
| 126 | +# Check for API differences (useful before breaking changes) |
| 127 | +make apidiff |
| 128 | +``` |
| 129 | + |
| 130 | +### Building |
| 131 | + |
| 132 | +```bash |
| 133 | +# Build manager binaries |
| 134 | +make managers |
| 135 | + |
| 136 | +# Build all binaries |
| 137 | +make binaries |
| 138 | + |
| 139 | +# Build Docker image |
| 140 | +make docker-build |
| 141 | + |
| 142 | +# Build debug Docker image |
| 143 | +make docker-build-debug |
| 144 | + |
| 145 | +# Build for all architectures |
| 146 | +make docker-build-all |
| 147 | +``` |
| 148 | + |
| 149 | +### Cleanup |
| 150 | + |
| 151 | +```bash |
| 152 | +# Clean all build artifacts |
| 153 | +make clean |
| 154 | + |
| 155 | +# Clean binaries only |
| 156 | +make clean-bin |
| 157 | + |
| 158 | +# Clean temporary files |
| 159 | +make clean-temporary |
| 160 | + |
| 161 | +# Clean release artifacts |
| 162 | +make clean-release |
| 163 | +``` |
| 164 | + |
| 165 | +## Important Development Patterns |
| 166 | + |
| 167 | +### Adding New OpenStack Resources |
| 168 | + |
| 169 | +1. Define API types in `/api/v1beta1` (or `/api/v1alpha1` for experimental features) |
| 170 | +2. Run `make generate` to create deepcopy methods and update CRDs |
| 171 | +3. Create controller in `/controllers` |
| 172 | +4. Create service implementation in `/pkg/cloud/services/<category>` |
| 173 | +5. Update or create scope in `/pkg/scope` if needed |
| 174 | +6. Add webhooks in `/pkg/webhooks` for validation/defaulting |
| 175 | +7. Add unit tests for controller and services |
| 176 | +8. Update documentation |
| 177 | +9. Generate cluster templates if applicable with `make templates` |
| 178 | + |
| 179 | +### Testing Strategy |
| 180 | + |
| 181 | +1. **Unit Tests**: Test individual functions/methods with mocks |
| 182 | +2. **Integration Tests**: Test controller behavior with envtest |
| 183 | +3. **E2E Tests**: Deploy real clusters on OpenStack, verify functionality |
| 184 | +4. **Conformance Tests**: Run upstream Kubernetes conformance suite |
| 185 | + |
| 186 | +## Pre-Submit Checklist for Agents |
| 187 | + |
| 188 | +Before submitting a PR, ensure: |
| 189 | + |
| 190 | +1. **Code is generated and up to date**: |
| 191 | + ```bash |
| 192 | + make generate |
| 193 | + ``` |
| 194 | + |
| 195 | +2. **Modules are tidy**: |
| 196 | + ```bash |
| 197 | + make modules |
| 198 | + ``` |
| 199 | + |
| 200 | +3. **Code passes linting**: |
| 201 | + ```bash |
| 202 | + make lint |
| 203 | + ``` |
| 204 | + |
| 205 | +4. **Tests pass**: |
| 206 | + ```bash |
| 207 | + make test |
| 208 | + ``` |
| 209 | + |
| 210 | +5. **All verification checks pass**: |
| 211 | + ```bash |
| 212 | + make verify |
| 213 | + ``` |
| 214 | + |
| 215 | +## Common Workflows |
| 216 | + |
| 217 | +### Making Code Changes |
| 218 | + |
| 219 | +1. Make your code changes |
| 220 | +2. Run code generation: `make generate` |
| 221 | +3. Update modules if needed: `make modules` |
| 222 | +4. Run tests: `make test` |
| 223 | +5. Lint the code: `make lint` |
| 224 | +6. Verify everything: `make verify` |
| 225 | +7. Commit changes with descriptive message |
| 226 | + |
| 227 | +### Updating Dependencies |
| 228 | + |
| 229 | +1. Update `go.mod` or `hack/tools/go.mod` as needed |
| 230 | +2. Run: `make modules` |
| 231 | +3. Run: `make verify-modules` |
| 232 | +4. Test that everything still works: `make test` |
| 233 | + |
| 234 | +## Common Issues |
| 235 | + |
| 236 | +### Linting Errors |
| 237 | + |
| 238 | +The project uses golangci-lint. If you get lint errors: |
| 239 | +1. Run `make lint-update` first to auto-fix |
| 240 | +2. Check `.golangci.yml` for enabled linters |
| 241 | +3. Some issues require manual fixes (cognitive complexity, error handling, etc.) |
| 242 | +4. Don't disable linters without good reason - fix the underlying issue |
| 243 | + |
| 244 | +### Test Failures |
| 245 | + |
| 246 | +- **envtest issues**: Ensure KUBEBUILDER_ASSETS is set correctly |
| 247 | +- **Flaky E2E tests**: Transient infrastructure issues, failure to deploy devstack |
| 248 | + |
| 249 | +### Generated File Drift |
| 250 | + |
| 251 | +If `make verify` fails with generated file drift: |
| 252 | +1. Run `make generate` to regenerate all files |
| 253 | +2. Review the changes to ensure they're expected |
| 254 | +3. Commit the generated files |
| 255 | +4. Never manually edit generated files |
| 256 | + |
| 257 | +## Documentation |
| 258 | + |
| 259 | +Primary documentation is in `/docs/book/src/` (mdBook format): |
| 260 | +- Getting started guides |
| 261 | +- Developer documentation |
| 262 | +- Troubleshooting guides |
| 263 | +- API reference |
| 264 | +- Cluster template documentation |
| 265 | + |
| 266 | +Build and serve docs locally: |
| 267 | +```bash |
| 268 | +make -C docs/book serve |
| 269 | +``` |
| 270 | + |
| 271 | +## Quick Reference |
| 272 | + |
| 273 | +| Task | Command | |
| 274 | +|------|---------| |
| 275 | +| Full verification before PR | `make verify && make test` | |
| 276 | +| Generate all code | `make generate` | |
| 277 | +| Update dependencies | `make modules` | |
| 278 | +| Lint and fix | `make lint-update` | |
| 279 | +| Run tests | `make test` | |
| 280 | +| Build binary | `make managers` | |
| 281 | +| Build Docker image | `make docker-build` | |
| 282 | +| Clean everything | `make clean` | |
| 283 | +| Check API compatibility | `make apidiff` | |
| 284 | +| Generate templates | `make templates` | |
| 285 | +| Build and serve docs | `make -C docs/book serve` | |
![github-actions[bot]](https://avatars.githubusercontent.com/in/15368?v=4&size=40){kind=avatar}
0 commit comments