gh-openshift-eng-ai-helpers-plugins-openshift/commands/crd-review.md

description, argument-hint

description	argument-hint
Review Kubernetes CRDs against Kubernetes and OpenShift API conventions	repository-path

Name

openshift:crd-review

Synopsis

/openshift:crd-review [repository-path]

Description

The openshift:crd-review command analyzes Go Kubernetes Custom Resource Definitions (CRDs) in a repository against both:

• Kubernetes API Conventions as defined in the Kubernetes community guidelines
• OpenShift API Conventions as defined in the OpenShift development guide

This command helps ensure CRDs follow best practices for:

• API naming conventions and patterns
• Resource structure and field organization
• Status field design and patterns
• Field types and validation
• Documentation standards
• OpenShift-specific requirements

The review covers Go API type definitions, providing actionable feedback to improve API design.

Key Convention Checks

Kubernetes API Conventions

Naming Conventions

• Resource Names: Must follow DNS label format (lowercase, alphanumeric, hyphens)
• Field Names: PascalCase for Go, camelCase for JSON
• Avoid: Abbreviations, underscores, ambiguous names
• Include: Units/types in field names when needed (e.g., timeoutSeconds)

API Structure

• Required Fields: Every API object must embed a k8s.io/apimachinery/pkg/apis/meta/v1 TypeMeta struct
• Metadata: Every API object must include a k8s.io/apimachinery/pkg/apis/meta/v1 ObjectMeta struct called metadata
• Spec/Status Separation: Clear separation between desired state (spec) and observed state (status)

Status Field Design

• Conditions: Must include conditions array with:
  • type: Clear, human-readable condition type
  • status: True, False, or Unknown
  • reason: Machine-readable reason code
  • message: Human-readable message
  • lastTransitionTime: RFC 3339 timestamp

Field Types

• Integers: Prefer int32 over int64
• Avoid: Unsigned integers, floating-point values
• Enums: Use string constants, not numeric values
• Optional Fields: Use pointers in Go

Versioning

• Group Names: Use domain format (e.g., myapp.example.com)
• Version Strings: Must match DNS label format (e.g., v1, v1beta1)
• Migration: Provide clear paths between versions

OpenShift API Conventions

Configuration vs Workload APIs

• Configuration APIs: Typically cluster-scoped, manage cluster behavior
• Workload APIs: Usually namespaced, user-facing resources

Field Design

• Avoid Boolean Fields: Use enumerations that describe end-user behavior instead of binary true/false
  • ❌ Bad: paused: true
  • ✅ Good: lifecycle: "Paused" with enum values ["Paused", "Active"]
• Object References: Use specific types, omit "Ref" suffix
• Clear Semantics: Each field should have one clear purpose

Documentation Requirements

• Godoc Comments: Comprehensive documentation for all exported types and fields
• JSON Field Names: Use JSON names in documentation (not Go names)
• User-Facing: Write for users, not just developers
• Explain Interactions: Document how fields interact with each other

Validation

• Kubebuilder Tags: Use validation markers (+kubebuilder:validation:*)
• Enum Values: Explicitly define allowed values
• Field Constraints: Define minimums, maximums, patterns
• Meaningful Errors: Validation messages should guide users

Union Types

• Discriminated Unions: Use a discriminator field to select variant
• Optional Pointers: All union members should be optional pointers
• Validation: Ensure exactly one union member is set

Implementation

The command performs the following analysis workflow:

1. Repository Discovery

   • Find Go API types (typically in api/, pkg/apis/ directories)
   • Identify CRD generation markers (+kubebuilder comments)

2. Kubernetes Convention Validation

   • Naming validation: Check resource names, field names, condition types
   • Structure validation: Verify required fields, metadata, spec/status separation
   • Status validation: Ensure conditions array, proper condition structure
   • Field type validation: Check integer types, avoid floats, validate enums
   • Versioning validation: Verify group names and version strings

3. OpenShift Convention Validation

   • API classification: Identify configuration vs workload APIs
   • Field design: Flag boolean fields, check enumerations
   • Documentation: Verify Godoc comments, user-facing descriptions
   • Validation markers: Check kubebuilder validation tags
   • Union types: Validate discriminated union patterns

4. Report Generation

   • List all findings with severity levels (Critical, Warning, Info)
   • Provide specific file and line references
   • Include remediation suggestions
   • Highlight whether a suggested change might lead to breaking API changes
   • Link to relevant convention documentation

Output Format

The command generates a structured report with:

• Summary: Overview of findings by severity
• Kubernetes Findings: Issues related to upstream conventions
• OpenShift Findings: Issues related to OpenShift-specific patterns
• Recommendations: Actionable steps to improve API design
• openshift/api crd-command reference: Add a prominent note notifying the user of the existence of the openshift/api repository's api-review command (https://github.com/openshift/api/blob/master/.claude/commands/api-review.md) for PR reviews against that repository.

Each finding includes:

• Severity level (❌ Critical, ⚠️ Warning, 💡 Info)
• File location and line number
• Description of the issue
• Remediation suggestion
• Link to relevant documentation

Examples

Example 1: Review current repository

/crd-review

Analyzes CRDs in the current working directory.

Example 2: Review specific repository

/crd-review /path/to/operator-project

Analyzes CRDs in the specified directory.

Example 3: Review with detailed output

The command automatically provides detailed output including:

• All CRD files found
• Go API type definitions
• Compliance summary
• Specific violations with file references

Common Findings

Kubernetes Convention Issues

Boolean vs Enum Fields

Issue: Using boolean where enum is better

// ❌ Bad
type MySpec struct {
    Enabled bool `json:"enabled"`
}

// ✅ Good
type MySpec struct {
    // State defines the operational state
    // Valid values are: "Enabled", "Disabled", "Auto"
    // +kubebuilder:validation:Enum=Enabled;Disabled;Auto
    State string `json:"state"`
}

Missing Status Conditions

Issue: Status without conditions array

// ❌ Bad
type MyStatus struct {
    Ready bool `json:"ready"`
}

// ✅ Good
type MyStatus struct {
    // Conditions represent the latest available observations
    // +listType=map
    // +listMapKey=type
    Conditions []metav1.Condition `json:"conditions,omitempty"`
}

Improper Field Naming

Issue: Ambiguous or abbreviated names

// ❌ Bad
type MySpec struct {
    Timeout int `json:"timeout"` // Ambiguous unit
    Cnt     int `json:"cnt"`     // Abbreviation
}

// ✅ Good
type MySpec struct {
    // TimeoutSeconds is the timeout in seconds
    // +kubebuilder:validation:Minimum=1
    TimeoutSeconds int32 `json:"timeoutSeconds"`

    // Count is the number of replicas
    // +kubebuilder:validation:Minimum=0
    Count int32 `json:"count"`
}

OpenShift Convention Issues

Missing Documentation

Issue: Exported fields without Godoc

// ❌ Bad
type MySpec struct {
    Field string `json:"field"`
}

// ✅ Good
type MySpec struct {
    // field specifies the configuration field for...
    // This value determines how the operator will...
    // Valid values include...
    Field string `json:"field"`
}

Missing Validation

Issue: Fields without kubebuilder validation

// ❌ Bad
type MySpec struct {
    Mode string `json:"mode"`
}

// ✅ Good
type MySpec struct {
    // mode defines the operational mode
    // +kubebuilder:validation:Enum=Standard;Advanced;Debug
    // +kubebuilder:validation:Required
    Mode string `json:"mode"`
}

Best Practices

1. Start with Conventions: Review conventions before writing APIs
2. Use Code Generation: Leverage controller-gen and kubebuilder markers
3. Document Early: Write Godoc comments as you define types
4. Validate Everything: Add validation markers for all fields
5. Review Regularly: Run this command during development and before PRs
6. Follow Examples: Study well-designed APIs in OpenShift core

Arguments

• repository-path (optional): Path to repository containing CRDs. Defaults to current working directory.

Exit Codes

• 0: Analysis completed successfully
• 1: Error during analysis (e.g., invalid path, no CRDs found)

See Also

• Kubernetes API Conventions
• OpenShift API Conventions
• Kubebuilder Documentation
• Controller Runtime API