Custom Resource Definition (CRD)

These are the mandatory, top-level fields that identify the resource type in the Kubernetes API.

• apiVersion: Specifies the API group and version for the CRD (e.g., inferensys.com/v1alpha1).
• kind: The singular, CamelCase name of the Custom Resource (e.g., ParallelSimulation). Together, they allow the Kubernetes API server to route and process requests for your custom objects.

This section contains identifying information about the specific instance of the Custom Resource, following the same pattern as native Kubernetes objects.

• name: The unique identifier for this resource instance within its namespace.
• namespace: The Kubernetes namespace where the resource is deployed (if namespaced).
• labels and annotations: Key-value pairs for organizing, selecting, and attaching arbitrary metadata to the object.

The spec is the required, user-defined configuration for the desired state of the Custom Resource. It is the most critical component, defined by the schema in the CRD.

• Example: For a ParallelSimulation CR, the spec might define fields like replicaCount: 1000, physicsEngine: "NVIDIA Isaac Sim", and trainingAlgorithm. The controller watches this section to reconcile the actual system state with this declared intent.

The status is an optional, read-only section populated by the custom controller to report the actual observed state of the system.

• It contains information like phase: "Running", completedReplicas: 850, and lastError: "".
• Users and other controllers query the status to understand the current condition of the resource without inspecting the underlying pods or services directly. It should never be modified by the user.

The CRD contains a formal OpenAPI v3 schema that defines the structure, data types, validation rules, and defaults for the spec and status fields.

• Validation: Enforces that user-provided spec values are correct (e.g., replicaCount must be an integer > 0).
• Documentation: Serves as inline API documentation for the Custom Resource.
• Tooling Compatibility: Enables IDE autocompletion and kubectl explain functionality (kubectl explain parallelsimulation.spec.replicaCount).

A fundamental property defined in the CRD that determines the resource's visibility and isolation.

• Namespaced: The Custom Resource exists within a specific namespace (e.g., training-sim-west). This is typical for workload-like resources.
• Cluster-Scoped: The Custom Resource is visible across the entire cluster (e.g., a ClusterSimulationPolicy). This is used for cluster-wide configuration. The scope cannot be changed after the CRD is created.

CRDs allow teams to model their own domain concepts as first-class Kubernetes resources. This is the core use case for encapsulating complex application configurations.

• Examples: Defining a Database resource with fields for engine, version, storage size, and backup schedules, or a ModelDeployment resource specifying framework, GPU requirements, and scaling policies.
• Benefit: This creates a declarative API that integrates seamlessly with Kubernetes tooling (kubectl, GitOps, RBAC). Operators and controllers can then watch these custom objects and execute the necessary logic to reconcile the actual state with the declared state.

CRDs are the declarative component of the Operator Pattern, which packages human operational knowledge into software. A custom controller watches the CRD instances and takes action.

• How it works: A user creates a YAML for a custom resource (e.g., etcdCluster). The custom controller detects this new object and automatically provisions pods, configures networking, and handles backups or failover.
• Real-world use: The Prometheus Operator defines a ServiceMonitor CRD to declaratively manage how Prometheus discovers targets. The Cert-Manager uses Certificate and Issuer CRDs to automate TLS certificate lifecycle management.

CRDs provide a structured way to define and manage multi-step processes, such as CI/CD pipelines, data processing jobs, or ML training runs, as Kubernetes-native objects.

• Key Example: The Argo Workflows project defines a Workflow CRD. Each step in a pipeline becomes a Kubernetes Pod, and the workflow engine manages dependencies and execution order.
• Advantage: This leverages Kubernetes' scheduling, resilience, and observability for workflow steps. Users can kubectl get workflows to see status, and logs are aggregated through standard Kubernetes mechanisms.

CRDs enable the Kubernetes-native management of external infrastructure through controllers that act as a bridge to cloud provider APIs (AWS, GCP, Azure).

• Mechanism: A controller watches for CRDs like S3Bucket or PostgreSQLInstance. When one is created, the controller calls the respective cloud API to provision the resource and updates the CRD's status field.
• Crossplane: This project is built entirely on this concept, using Composite Resource Definitions (XRDs)—an advanced form of CRD—to define and compose cloud infrastructure. It allows declaring a full application stack (cluster, database, cache) using Kubernetes YAML.

Platform engineering teams use CRDs to create self-service abstractions for developers, hiding the complexity of underlying infrastructure.

• Internal Platform as a Product: Teams can define CRDs for FeatureFlag, CanaryRelease, or Quota that enforce organizational policies and best practices.
• Governance: Platform controllers can validate these resources, ensure compliance, and automatically generate the necessary underlying Kubernetes primitives (Deployments, ConfigMaps, NetworkPolicies). This provides a consistent, auditable interface for application teams.

Service meshes like Istio and Linkerd heavily utilize CRDs to allow users to declaratively manage traffic routing, security policies, and observability settings.

• Istio's API: It defines CRDs such as VirtualService (for routing rules), DestinationRule (for load balancing policies), and AuthorizationPolicy (for access control).
• Impact: Network operators can apply these resources using kubectl apply, and the Istio control plane dynamically reconfigures the data plane (Envoy proxies) without requiring manual intervention or application redeployment. This decouples traffic management from application code.