Skip to content

Commit 9b9df1e

Browse files
grokspawngrokspawn
authored
add general agents info (#457)
Signed-off-by: grokspawn <[email protected]>
1 parent d6a5128 commit 9b9df1e

File tree

1 file changed

+301
-0
lines changed

1 file changed

+301
-0
lines changed

‎AGENTS.md‎

Lines changed: 301 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,301 @@
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 operator-verify CLI
107+
```bash
108+
make install # Build and install operator-verify CLI
109+
```
110+
111+
### Testing
112+
```bash
113+
make test-unit # Run unit tests
114+
make test # Run all tests
115+
make TEST=<name> test-unit # Run specific test
116+
```
117+
118+
### Code Generation
119+
```bash
120+
make generate # Generate deep-copy methods
121+
make manifests # Generate CRD manifests
122+
make verify # Verify generated code is up-to-date
123+
```
124+
125+
### Code Quality
126+
```bash
127+
make format # Format source code
128+
make tidy # Update and verify dependencies
129+
```
130+
131+
## Validation Usage
132+
133+
### Using Default Validators
134+
135+
```go
136+
import (
137+
apimanifests "github.com/operator-framework/api/pkg/manifests"
138+
apivalidation "github.com/operator-framework/api/pkg/validation"
139+
)
140+
141+
// Load bundle
142+
bundle, err := apimanifests.GetBundleFromDir(path)
143+
if err != nil {
144+
return err
145+
}
146+
147+
// Run default validators
148+
validators := apivalidation.DefaultBundleValidators
149+
results := validators.Validate(bundle.ObjectsToValidate()...)
150+
151+
// Check results
152+
for _, result := range results {
153+
if result.HasError() {
154+
fmt.Printf("Error: %v\n", result)
155+
}
156+
}
157+
```
158+
159+
### Using Optional Validators
160+
161+
```go
162+
// Add optional validators
163+
validators := apivalidation.DefaultBundleValidators
164+
validators = validators.WithValidators(apivalidation.OperatorHubValidator)
165+
validators = validators.WithValidators(apivalidation.GoodPracticesValidator)
166+
167+
// Pass optional key/values
168+
optionalValues := map[string]string{
169+
"k8s-version": "1.28",
170+
}
171+
objs := append(bundle.ObjectsToValidate(), optionalValues)
172+
173+
results := validators.Validate(objs...)
174+
```
175+
176+
### CLI Usage
177+
178+
```bash
179+
# Install operator-verify
180+
make install
181+
182+
# Verify manifests
183+
operator-verify manifests /path/to/manifest.yaml
184+
```
185+
186+
## Code Generation
187+
188+
This repository uses controller-gen for code generation:
189+
190+
### Generated Code
191+
- **Deep-copy methods**: Auto-generated for all API types (`zz_generated.deepcopy.go`)
192+
- **CRD manifests**: Generated from Go type definitions in `crds/`
193+
- **Embedded CRDs**: Go code embedding CRD YAML in `crds/zz_defs.go`
194+
195+
### Regenerating Code
196+
```bash
197+
make generate manifests # Regenerate everything
198+
make verify # Verify nothing changed
199+
```
200+
201+
**Important**: Never edit generated files directly - modify the source types and regenerate.
202+
203+
## Common Tasks for AI Agents
204+
205+
### Understanding Validation Flow
206+
1. Bundle loaded via `pkg/manifests`
207+
2. Validators instantiated from `pkg/validation`
208+
3. Each validator checks specific aspects (CSV format, CRD structure, etc.)
209+
4. Results aggregated with errors/warnings
210+
5. Results returned to caller
211+
212+
### Adding a New Validator
213+
1. Create new validator in `pkg/validation/internal/`
214+
2. Implement `interfaces.Validator` interface
215+
3. Add validator to appropriate suite in `pkg/validation/validation.go`
216+
4. Write unit tests in `*_test.go`
217+
5. Document validator behavior
218+
219+
### Modifying API Types
220+
1. Edit type definition in `pkg/operators/v*/`
221+
2. Update CRD markers (kubebuilder comments) if needed
222+
3. Run `make generate manifests` to regenerate code
223+
4. Run `make verify` to ensure clean state
224+
5. Update tests if behavior changed
225+
226+
### Understanding CRD Structure
227+
- All CRDs defined in `pkg/operators/v*/`
228+
- Generated to `crds/*.yaml` via controller-gen
229+
- Embedded in Go code at `crds/zz_defs.go`
230+
- Used by OLM and other operator-framework components
231+
232+
## Important Dependencies
233+
234+
| Dependency | Purpose |
235+
|------------|---------|
236+
| k8s.io/api | Kubernetes core types |
237+
| k8s.io/apimachinery | Kubernetes meta types |
238+
| sigs.k8s.io/controller-tools | Code generation (controller-gen) |
239+
| github.com/blang/semver/v4 | Semantic versioning |
240+
| github.com/operator-framework/operator-registry | Registry integration |
241+
242+
## Navigation Tips
243+
244+
### Finding API Definitions
245+
- Core OLM types: `pkg/operators/v1alpha1/`
246+
- OperatorGroup: `pkg/operators/v1/operatorgroup_types.go`
247+
- OperatorCondition: `pkg/operators/v2/operatorcondition_types.go`
248+
249+
### Finding Validators
250+
- Validator implementations: `pkg/validation/internal/`
251+
- Validator interfaces: `pkg/validation/interfaces/`
252+
- Main orchestration: `pkg/validation/validation.go`
253+
254+
### Finding Utilities
255+
- Bundle loading: `pkg/manifests/bundle.go`
256+
- Image references: `pkg/operators/reference/`
257+
- Version utilities: `pkg/lib/version/`
258+
259+
## Anti-Patterns to Avoid
260+
261+
1. **Don't modify generated code** - Edit source types and regenerate
262+
2. **Don't skip `make verify`** - Always verify generated code is current
263+
3. **Don't add breaking API changes** - This is a library used by multiple projects
264+
4. **Don't add validators without tests** - All validators must be thoroughly tested
265+
5. **Don't bypass validation interfaces** - Use the provided validator framework
266+
267+
## Resources and Links
268+
269+
- [OLM Documentation](https://olm.operatorframework.io/)
270+
- [Operator SDK Bundle Validation](https://sdk.operatorframework.io/docs/cli/operator-sdk_bundle_validate/)
271+
- [Operator Framework Community](https://github.com/operator-framework/community)
272+
- [Validation Package Docs](https://pkg.go.dev/github.com/operator-framework/api@master/pkg/validation)
273+
274+
## Quick Reference
275+
276+
### Common Build Targets
277+
```bash
278+
make install # Install operator-verify CLI
279+
make test-unit # Run unit tests
280+
make generate manifests # Generate code and CRDs
281+
make verify # Verify no uncommitted changes
282+
make format tidy # Format and tidy code
283+
```
284+
285+
### Tool Management
286+
Tools are managed via Makefile and installed to `./bin/`:
287+
- `controller-gen` - Kubernetes code generator
288+
- `yq` - YAML processor for CRD patching
289+
- `kind` - Local Kubernetes clusters
290+
291+
## Contributing
292+
293+
See [DCO](DCO) for Developer Certificate of Origin requirements.
294+
295+
When contributing:
296+
1. Run `make verify` before submitting PRs
297+
2. Add tests for new validators or API changes
298+
3. Update CRD generation if modifying types
299+
4. Follow existing patterns for consistency
300+
301+
[olm]: https://github.com/operator-framework/operator-lifecycle-manager

0 commit comments

Comments
 (0)