Skip to content

Commit e53b402

Browse files
grokspawngrokspawn
committed
add general agents info
Signed-off-by: grokspawn <[email protected]>
1 parent d6a5128 commit e53b402

File tree

1 file changed

+302
-0
lines changed

1 file changed

+302
-0
lines changed

‎AGENTS.md‎

Lines changed: 302 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,302 @@
1+
# AGENTS.md
2+
3+
This file provides AI agents with comprehensive context about the operator-framework/api repository to enable effective navigation, understanding, and contribution.
4+
5+
## Project Overview
6+
7+
This repository contains the API definitions and validation libraries used by [Operator Lifecycle Manager][olm] (OLMv0). It's a foundational library in the [Operator Framework](https://github.com/operator-framework) ecosystem.
8+
9+
### Core Capabilities
10+
- **API Definitions**: Kubernetes Custom Resource Definitions (CRDs) for OLM resources
11+
- **Manifest Validation**: Static validators for operator bundles and package manifests
12+
- **CLI Tool**: `operator-verify` for manifest verification
13+
- **Common Libraries**: Shared utilities for bundle and manifest manipulation
14+
15+
## Custom Resource Definitions (CRDs)
16+
17+
| Resource | API Group | Description |
18+
|----------|-----------|-------------|
19+
| **ClusterServiceVersion (CSV)** | operators.coreos.com/v1alpha1 | Defines operator metadata, installation strategy, permissions, and owned/required CRDs |
20+
| **Subscription** | operators.coreos.com/v1alpha1 | Tracks operator updates from a catalog channel |
21+
| **InstallPlan** | operators.coreos.com/v1alpha1 | Calculated list of resources to install/upgrade |
22+
| **CatalogSource** | operators.coreos.com/v1alpha1 | Repository of operators and metadata |
23+
| **OperatorGroup** | operators.coreos.com/v1 | Groups namespaces for operator installation scope |
24+
| **OperatorCondition** | operators.coreos.com/v2 | Tracks operator health status and conditions |
25+
26+
## Directory Structure
27+
28+
```
29+
api/
30+
├── cmd/ # Entry point binaries
31+
│ └── operator-verify/ # CLI tool for manifest verification
32+
│
33+
├── pkg/ # Core implementation
34+
│ ├── operators/ # OLM API types
35+
│ │ ├── v1alpha1/ # Core OLM types (CSV, Subscription, etc.)
36+
│ │ ├── v1/ # OperatorGroup, OperatorCondition v1
37+
│ │ ├── v2/ # OperatorCondition v2
38+
│ │ └── reference/ # Image reference parsing
39+
│ │
40+
│ ├── validation/ # Operator manifest validators
41+
│ │ ├── errors/ # Validation error types
42+
│ │ ├── interfaces/ # Validator interfaces
43+
│ │ └── internal/ # Validator implementations
44+
│ │
45+
│ ├── manifests/ # Bundle and manifest loaders
46+
│ │
47+
│ ├── constraints/ # Constraint and CEL validation
48+
│ │
49+
│ ├── lib/version/ # Version utilities
50+
│ │
51+
│ └── apis/scorecard/ # Scorecard configuration types
52+
│
53+
├── crds/ # Generated CRD YAML files
54+
│
55+
└── hack/ # Build scripts and tools
56+
```
57+
58+
## Key Packages and Their Responsibilities
59+
60+
### API Types (`pkg/operators/`)
61+
62+
Defines all Kubernetes custom resources used by OLM:
63+
- `v1alpha1/`: Core types (CSV, Subscription, InstallPlan, CatalogSource)
64+
- `v1/`: OperatorGroup, Operator, OperatorCondition
65+
- `v2/`: OperatorCondition v2
66+
- `reference/`: Container image reference parsing utilities
67+
68+
**Key files**:
69+
- `v1alpha1/clusterserviceversion_types.go` - CSV API definition
70+
- `v1/operatorgroup_types.go` - OperatorGroup API definition
71+
72+
### Validation (`pkg/validation/`)
73+
74+
Static validators for operator bundles and manifests:
75+
- **Default Validators**: Required checks for all operators
76+
- **Optional Validators**: Community, OperatorHub, and best practice validators
77+
- **Custom Validators**: Extensible validator interface
78+
79+
**Key files**:
80+
- `validation.go` - Main validator orchestration
81+
- `internal/bundle.go` - Bundle structure validation
82+
- `internal/csv.go` - CSV validation rules
83+
- `internal/operatorhub.go` - OperatorHub requirements
84+
85+
**Validator Types**:
86+
- `BundleValidator` - Bundle format and structure
87+
- `CSVValidator` - ClusterServiceVersion validation
88+
- `CRDValidator` - CRD validation
89+
- `OperatorHubValidator` - OperatorHub.io requirements
90+
- `GoodPracticesValidator` - Best practices checks
91+
- `AlphaDeprecatedAPIsValidator` - Deprecated API detection
92+
93+
### Manifests (`pkg/manifests/`)
94+
95+
Bundle and package manifest loaders:
96+
- Bundle loading from directories
97+
- PackageManifest parsing
98+
- Metadata extraction
99+
100+
**Key files**:
101+
- `bundle.go` - Bundle representation and loading
102+
- `bundleloader.go` - Bundle loading logic
103+
104+
## Development Workflow
105+
106+
### Building
107+
```bash
108+
make install # Build and install operator-verify CLI
109+
go build ./... # Build all packages
110+
```
111+
112+
### Testing
113+
```bash
114+
make test-unit # Run unit tests
115+
make test # Run all tests
116+
make TEST=<name> test-unit # Run specific test
117+
```
118+
119+
### Code Generation
120+
```bash
121+
make generate # Generate deep-copy methods
122+
make manifests # Generate CRD manifests
123+
make verify # Verify generated code is up-to-date
124+
```
125+
126+
### Code Quality
127+
```bash
128+
make format # Format source code
129+
make tidy # Update and verify dependencies
130+
```
131+
132+
## Validation Usage
133+
134+
### Using Default Validators
135+
136+
```go
137+
import (
138+
apimanifests "github.com/operator-framework/api/pkg/manifests"
139+
apivalidation "github.com/operator-framework/api/pkg/validation"
140+
)
141+
142+
// Load bundle
143+
bundle, err := apimanifests.GetBundleFromDir(path)
144+
if err != nil {
145+
return err
146+
}
147+
148+
// Run default validators
149+
validators := apivalidation.DefaultBundleValidators
150+
results := validators.Validate(bundle.ObjectsToValidate()...)
151+
152+
// Check results
153+
for _, result := range results {
154+
if result.HasError() {
155+
fmt.Printf("Error: %v\n", result)
156+
}
157+
}
158+
```
159+
160+
### Using Optional Validators
161+
162+
```go
163+
// Add optional validators
164+
validators := apivalidation.DefaultBundleValidators
165+
validators = validators.WithValidators(apivalidation.OperatorHubValidator)
166+
validators = validators.WithValidators(apivalidation.GoodPracticesValidator)
167+
168+
// Pass optional key/values
169+
optionalValues := map[string]string{
170+
"k8s-version": "1.28",
171+
}
172+
objs := append(bundle.ObjectsToValidate(), optionalValues)
173+
174+
results := validators.Validate(objs...)
175+
```
176+
177+
### CLI Usage
178+
179+
```bash
180+
# Install operator-verify
181+
make install
182+
183+
# Verify manifests
184+
operator-verify manifests /path/to/manifest.yaml
185+
```
186+
187+
## Code Generation
188+
189+
This repository uses controller-gen for code generation:
190+
191+
### Generated Code
192+
- **Deep-copy methods**: Auto-generated for all API types (`zz_generated.deepcopy.go`)
193+
- **CRD manifests**: Generated from Go type definitions in `crds/`
194+
- **Embedded CRDs**: Go code embedding CRD YAML in `crds/zz_defs.go`
195+
196+
### Regenerating Code
197+
```bash
198+
make generate manifests # Regenerate everything
199+
make verify # Verify nothing changed
200+
```
201+
202+
**Important**: Never edit generated files directly - modify the source types and regenerate.
203+
204+
## Common Tasks for AI Agents
205+
206+
### Understanding Validation Flow
207+
1. Bundle loaded via `pkg/manifests`
208+
2. Validators instantiated from `pkg/validation`
209+
3. Each validator checks specific aspects (CSV format, CRD structure, etc.)
210+
4. Results aggregated with errors/warnings
211+
5. Results returned to caller
212+
213+
### Adding a New Validator
214+
1. Create new validator in `pkg/validation/internal/`
215+
2. Implement `interfaces.Validator` interface
216+
3. Add validator to appropriate suite in `pkg/validation/validation.go`
217+
4. Write unit tests in `*_test.go`
218+
5. Document validator behavior
219+
220+
### Modifying API Types
221+
1. Edit type definition in `pkg/operators/v*/`
222+
2. Update CRD markers (kubebuilder comments) if needed
223+
3. Run `make generate manifests` to regenerate code
224+
4. Run `make verify` to ensure clean state
225+
5. Update tests if behavior changed
226+
227+
### Understanding CRD Structure
228+
- All CRDs defined in `pkg/operators/v*/`
229+
- Generated to `crds/*.yaml` via controller-gen
230+
- Embedded in Go code at `crds/zz_defs.go`
231+
- Used by OLM and other operator-framework components
232+
233+
## Important Dependencies
234+
235+
| Dependency | Purpose |
236+
|------------|---------|
237+
| k8s.io/api | Kubernetes core types |
238+
| k8s.io/apimachinery | Kubernetes meta types |
239+
| sigs.k8s.io/controller-tools | Code generation (controller-gen) |
240+
| github.com/blang/semver/v4 | Semantic versioning |
241+
| github.com/operator-framework/operator-registry | Registry integration |
242+
243+
## Navigation Tips
244+
245+
### Finding API Definitions
246+
- Core OLM types: `pkg/operators/v1alpha1/`
247+
- OperatorGroup: `pkg/operators/v1/operatorgroup_types.go`
248+
- OperatorCondition: `pkg/operators/v2/operatorcondition_types.go`
249+
250+
### Finding Validators
251+
- Validator implementations: `pkg/validation/internal/`
252+
- Validator interfaces: `pkg/validation/interfaces/`
253+
- Main orchestration: `pkg/validation/validation.go`
254+
255+
### Finding Utilities
256+
- Bundle loading: `pkg/manifests/bundle.go`
257+
- Image references: `pkg/operators/reference/`
258+
- Version utilities: `pkg/lib/version/`
259+
260+
## Anti-Patterns to Avoid
261+
262+
1. **Don't modify generated code** - Edit source types and regenerate
263+
2. **Don't skip `make verify`** - Always verify generated code is current
264+
3. **Don't add breaking API changes** - This is a library used by multiple projects
265+
4. **Don't add validators without tests** - All validators must be thoroughly tested
266+
5. **Don't bypass validation interfaces** - Use the provided validator framework
267+
268+
## Resources and Links
269+
270+
- [OLM Documentation](https://olm.operatorframework.io/)
271+
- [Operator SDK Bundle Validation](https://sdk.operatorframework.io/docs/cli/operator-sdk_bundle_validate/)
272+
- [Operator Framework Community](https://github.com/operator-framework/community)
273+
- [Validation Package Docs](https://pkg.go.dev/github.com/operator-framework/api@master/pkg/validation)
274+
275+
## Quick Reference
276+
277+
### Common Build Targets
278+
```bash
279+
make install # Install operator-verify CLI
280+
make test-unit # Run unit tests
281+
make generate manifests # Generate code and CRDs
282+
make verify # Verify no uncommitted changes
283+
make format tidy # Format and tidy code
284+
```
285+
286+
### Tool Management
287+
Tools are managed via Makefile and installed to `./bin/`:
288+
- `controller-gen` - Kubernetes code generator
289+
- `yq` - YAML processor for CRD patching
290+
- `kind` - Local Kubernetes clusters
291+
292+
## Contributing
293+
294+
See [DCO](DCO) for Developer Certificate of Origin requirements.
295+
296+
When contributing:
297+
1. Run `make verify` before submitting PRs
298+
2. Add tests for new validators or API changes
299+
3. Update CRD generation if modifying types
300+
4. Follow existing patterns for consistency
301+
302+
[olm]: https://github.com/operator-framework/operator-lifecycle-manager

0 commit comments

Comments
 (0)