Skip to content

Commit ba2e768

Browse files
Copilottheunrepentantgeek
Copilot
and
theunrepentantgeek
authored
Create GitHub Copilot instructions for Azure Service Operator development (#4866)
* Initial plan * Create comprehensive GitHub Copilot instructions for Azure Service Operator Co-authored-by: theunrepentantgeek <1272094+theunrepentantgeek@users.noreply.github.com> --------- Co-authored-by: copilot-swe-agent[bot] <198982749+Copilot@users.noreply.github.com> Co-authored-by: theunrepentantgeek <1272094+theunrepentantgeek@users.noreply.github.com>
1 parent 5dd58da commit ba2e768

File tree

1 file changed

+142
-0
lines changed

1 file changed

+142
-0
lines changed

‎.github/copilot-instructions.md

Lines changed: 142 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,142 @@
1+
# Azure Service Operator v2
2+
3+
**ALWAYS follow these instructions first and fallback to search or bash commands only when you encounter unexpected information that does not match the info here.**
4+
5+
Azure Service Operator (ASO) v2 is a Kubernetes operator written in Go that manages Azure resources through Kubernetes Custom Resource Definitions (CRDs). The operator uses code generation from Azure OpenAPI specifications to create CRDs for Azure services.
6+
7+
## Working Effectively
8+
9+
### CRITICAL Dependencies and Setup
10+
- **NEVER CANCEL builds or tests** - Build processes can take 15+ minutes, tests can take 30+ minutes. Set timeout to 90+ minutes for full builds.
11+
- **ALWAYS run `git fetch --unshallow`** first if working with a shallow clone - the build system requires full git history.
12+
- **Go 1.24+** required - Check with `go version`
13+
- **Task** (taskfile) is the primary build tool - Use `./hack/tools/task --list` to see available commands
14+
- **Kustomize v4.5.7** required - v5+ is incompatible with current configuration format
15+
16+
### Bootstrap and Build Process
17+
```bash
18+
# CRITICAL: Fix shallow clone issue first
19+
git fetch --unshallow
20+
21+
# Install dependencies (if needed)
22+
.devcontainer/install-dependencies.sh --skip-installed
23+
24+
# CRITICAL: Fix kustomize compatibility if encountering format errors
25+
cd v2/config/crd/generated && ../../../../hack/tools/kustomize edit fix
26+
27+
# Quick validation and code generation (2-4 minutes)
28+
./hack/tools/task quick-checks
29+
30+
# Full CI validation (15-20 minutes) - NEVER CANCEL - Set timeout to 90+ minutes
31+
./hack/tools/task ci
32+
33+
# Individual component builds
34+
./hack/tools/task generator:build # Code generator (~1 minute)
35+
./hack/tools/task controller:build # Controller binary (~5 minutes)
36+
./hack/tools/task asoctl:build # CLI tool (~2 minutes)
37+
```
38+
39+
### Testing Commands
40+
```bash
41+
# Unit tests (NEVER CANCEL - Set timeout to 60+ minutes)
42+
./hack/tools/task generator:unit-tests # Generator tests (~1 minute)
43+
./hack/tools/task asoctl:unit-tests # CLI tests (~5 minutes)
44+
./hack/tools/task controller:test # Controller tests (~30 minutes)
45+
46+
# Integration tests (NEVER CANCEL - Set timeout to 90+ minutes)
47+
./hack/tools/task controller:test-integration-envtest # Record/replay tests (~20 minutes)
48+
49+
# Lint and format
50+
./hack/tools/task format-code # Format all code
51+
./hack/tools/task controller:lint # Lint controller (~5 minutes)
52+
./hack/tools/task generator:lint # Lint generator
53+
```
54+
55+
### Build Timing Expectations
56+
- **Generator unit tests**: < 1 minute
57+
- **ASO CLI unit tests**: ~5 minutes
58+
- **Controller build**: ~5 minutes
59+
- **Controller unit tests**: ~30 minutes - NEVER CANCEL
60+
- **Integration tests**: ~20 minutes - NEVER CANCEL
61+
- **Full CI pipeline**: ~45-60 minutes - NEVER CANCEL
62+
- **Code generation**: ~2-3 minutes
63+
64+
## Validation and Manual Testing
65+
66+
### ALWAYS validate changes by:
67+
1. **Run format and basic checks**: `./hack/tools/task quick-checks`
68+
2. **Build components**: `./hack/tools/task controller:build asoctl:build generator:build`
69+
3. **Run unit tests**: `./hack/tools/task controller:test generator:unit-tests asoctl:unit-tests`
70+
4. **Run linting**: `./hack/tools/task controller:lint generator:lint`
71+
72+
### Manual Functionality Testing
73+
```bash
74+
# Build and package controller
75+
./hack/tools/task controller:docker-build
76+
77+
# Generate CRDs and configuration
78+
./hack/tools/task controller:run-kustomize
79+
80+
# Test CLI tool
81+
cd v2/cmd/asoctl && go run . --help
82+
```
83+
84+
## Common Workarounds and Known Issues
85+
86+
### Kustomize Version Compatibility
87+
If you encounter `invalid Kustomization: json: cannot unmarshal string` errors:
88+
```bash
89+
cd v2/config/crd/generated
90+
../../../../hack/tools/kustomize edit fix
91+
```
92+
93+
### Shallow Clone Issues
94+
If build fails with git describe errors:
95+
```bash
96+
git fetch --unshallow
97+
```
98+
99+
### Python Script Warnings
100+
Python regex syntax warnings in header check script are non-blocking and can be ignored.
101+
102+
## Repository Structure and Navigation
103+
104+
### Key Directories
105+
- **`v2/`** - Main ASO v2 codebase (ASO v1 is deprecated)
106+
- **`v2/api/`** - Generated Kubernetes API types for Azure resources
107+
- **`v2/cmd/controller/`** - Main controller implementation
108+
- **`v2/cmd/asoctl/`** - CLI tool for ASO management
109+
- **`v2/tools/generator/`** - Code generator from Azure OpenAPI specs
110+
- **`v2/config/`** - Kubernetes manifests and configuration
111+
- **`v2/samples/`** - Example resource definitions
112+
- **`hack/tools/`** - Build tools and dependencies
113+
- **`.devcontainer/`** - Development container configuration
114+
115+
### Generated vs Source Files
116+
- Files ending in `*_gen.go` are code-generated - DO NOT edit manually
117+
- Customizations go in `customizations` subdirectories
118+
- Run code generation after modifying generator or config: `./hack/tools/task controller:generate-types`
119+
120+
## Language and Technology Stack
121+
- **Go 1.24+** - Primary language
122+
- **Kubernetes 1.16+** - Target platform
123+
- **Controller Runtime** - Kubernetes controller framework
124+
- **Azure ARM APIs** - Source of truth for resource definitions
125+
- **Docker** - Container builds
126+
- **Helm 3** - Package management
127+
- **Task** - Build automation
128+
- **Kustomize v4.5.7** - Kubernetes configuration management
129+
130+
## Key Development Patterns
131+
- Code generation drives API definitions from Azure OpenAPI specs
132+
- Controller follows standard Kubernetes controller pattern with reconciliation loops
133+
- Heavy use of conversion functions between API versions
134+
- ARM resource definitions map to Kubernetes CRDs
135+
- Record/replay testing for Azure integration without live resources
136+
137+
## Debugging and Troubleshooting
138+
- Use `./hack/tools/task --list` to see all available commands
139+
- Check `Taskfile.yml` for command definitions and dependencies
140+
- Build artifacts go in `v2/bin/` and `v2/out/`
141+
- Test outputs go in `reports/` directory
142+
- Generated code lives in `v2/api/` and is regenerated on each build

0 commit comments

Comments
 (0)