Skip to content

AGENTS.md

Latest commit

 

History

History
154 lines (115 loc) · 6.03 KB

AGENTS.md

File metadata and controls

154 lines (115 loc) · 6.03 KB
Raw

AGENTS.md

This file provides guidance for AI agents working on the agents-api repository.

Project Overview

agents-api is the canonical, read-only location for Kruise Agents API definitions and Go client. It provides stable Go types for serializing/deserializing Kruise Agents resources, intended for direct use by consumers.

Governance: All changes must originate in openkruise/agents (source repo); this repo is synced read-only.

Versioning: Follows v0.x.z scheme — x matches Kruise Agents major/minor; z increments for bugfixes or cherry-picks.

Repository Structure

agents-api/
├── agents/v1alpha1/         # Core API type definitions (CRD specs)
├── client/                  # Auto-generated Go client (clientset, informers, listers)
├── clients/                 # Multi-language client SDKs (Java, Python)
├── sdk/                     # Go SDK for E2B API and runtime (proto, sandbox, runtime)
├── examples/                # Usage examples (e.g. SandboxClaim)
├── hack/                    # Build scripts and code generation tooling
├── bin/                     # Locally downloaded tool binaries (controller-gen, openapi-gen)
├── vendor/                  # Go dependencies (vendored)
└── .github/workflows/       # CI workflows

Key Directories

  • agents/v1alpha1/ — Hand-written API type definitions. Contains CRD types:

    • sandbox_types.go — Sandbox resource
    • sandboxset_types.go — SandboxSet resource
    • sandboxclaim_types.go — SandboxClaim resource
    • sandboxtemplate_types.go — SandboxTemplate resource
    • sandboxupdateops_types.go — SandboxUpdateOps resource
    • checkpoint_types.go — Checkpoint resource
    • mount_types.go — Mount types
    • annotations.go — Shared annotation constants
    • e2b_annotations.go — E2B-specific annotation constants
    • zz_generated.deepcopy.go — Auto-generated deep copy methods (do not edit)
    • groupversion_info.go — Group version registration (agents.kruise.io/v1alpha1)

  • client/ — Auto-generated Kubernetes client libraries. Do not edit manually. Regenerated via make generate.

    • clientset/ — Typed client for interacting with Agents API resources
    • informers/ — Watch/informer implementations
    • listers/ — Resource lister implementations

  • sdk/ — Go SDK for E2B API integration and runtime management

    • proto/api/ — Auto-generated E2B API client (OpenAPI-based, do not edit)
    • proto/envd/ — Protobuf-generated envd service clients (do not edit)
    • runtime/ — Runtime client and command handling
    • sandbox/ — Sandbox management SDK
    • example/ — SDK usage examples

  • clients/java/ — Java client library (CRD-generated models, published to Maven Central)

  • clients/python/ — Python client library

Tech Stack

  • Language: Go 1.25.0
  • Module: github.com/openkruise/agents-api
  • Core Dependencies:
    • k8s.io/api, k8s.io/apimachinery, k8s.io/client-go v0.35.0
    • k8s.io/code-generator v0.35.0
    • k8s.io/kube-openapi v0.0.0-20250910181357-589584f1c912
    • sigs.k8s.io/controller-runtime v0.21.0
    • connectrpc.com/connect v1.19.2
    • github.com/go-bindata/go-bindata v3.1.2
    • google.golang.org/protobuf v1.36.9
  • Code Generation Tools:
    • controller-gen v0.16.5 (downloaded to ./bin/)
    • openapi-gen (version derived from go.mod)

Build Commands

All commands should be run from the project root directory.

# Run go vet across all packages
make vet

# Regenerate client code (clientset, informers, listers, deep-copy)
make generate

# Generate OpenAPI schema
make openapi-gen

# Generate CRD schema only
make gen-schema-only

# Generate OpenAPI schema (full pipeline)
make gen-openapi-schema

Code Generation Details

  • make generate runs hack/generate_client.sh, which:

    1. Runs go mod vendor
    2. Uses kube::codegen::gen_helpers to generate deep-copy and helper methods
    3. Uses kube::codegen::gen_client to generate clientset/informers/listers
    4. Copies generated output back into ./client/

  • make openapi-gen downloads openapi-gen binary to ./bin/ if not present

Important Rules

Do Not Edit Auto-Generated Code

The following files/directories are auto-generated and must not be edited by hand:

  • agents/v1alpha1/zz_generated.deepcopy.go
  • client/ (entire directory — regenerated by make generate)
  • sdk/proto/api/ (generated from E2B OpenAPI spec)
  • sdk/proto/envd/ (generated from protobuf definitions)

Editing API Types

When modifying CRD types in agents/v1alpha1/*_types.go:

  1. Edit only the hand-written type files (not zz_generated.deepcopy.go)
  2. After changes, run make generate to regenerate deep-copy methods and client code
  3. Run make vet to verify no issues
  4. For OpenAPI schema changes, run make gen-openapi-schema

Kubernetes API Conventions

  • API group: agents.kruise.io
  • API version: v1alpha1
  • Types use standard Kubernetes metav1.TypeMeta and metav1.ObjectMeta embeddings
  • Use +kubebuilder: markers for CRD schema annotations
  • Use +k8s:deepcopy-gen markers for deep-copy generation
  • Follow Kubernetes API conventions

CI Workflows

  • schema-update.yaml — Automatically runs make gen-openapi-schema on push to master when agents/** files change
  • generate-crd.yml — Manual workflow to generate Java CRD models from CRD YAML sources
  • publish-maven-central.yml — Manual workflow to publish Java client to Maven Central

Linting and Validation

# Run go vet (the primary lint tool for this project)
make vet

# Alternatively:
go vet ./...

There is no golangci-lint or similar tool configured. Use go vet for validation.

Git and Branch Conventions

  • Default branch: master
  • This is a read-only synced repo — changes should originate in openkruise/agents
  • The .gitignore excludes: bin/, vendor/, *.test, *.out, .idea/