feat(transpiler): add schema validation for CRD attributes (#1165)

Author: kimpenhaus

docs/docs/operator/building-blocks/entities.mdx

@@ -137,7 +137,7 @@ public class EntitySpec
 - `[RangeMinimum]` and `[RangeMaximum]`: Defines numeric value ranges
 - `[MultipleOf]`: Specifies that a number must be a multiple of a given value
 - `[Items]`: Defines minimum and maximum items for arrays
-- `[UniqueItems]`: Marks an array property as requiring unique items (`uniqueItems: true`)
+- `[UniqueItems]`: **Rejected by the transpiler.** Kubernetes CRD schemas do not allow `uniqueItems: true`, so applying this attribute now fails transpilation. Use `[XListType(XListType.Set)]` for Kubernetes set semantics instead
 - `[PropertyLimits]`: Specifies minimum and maximum number of properties for an object
 - `[ValidationRule]`: Defines custom validation rules using CEL expressions. Can be applied to properties and to class types — in both cases it emits `x-kubernetes-validations` on the corresponding schema node. When applied to both a class and a property of that type, the rules are merged (class rules first, then property rules). Class-level rules are also collected across the **class inheritance chain**: a rule placed on a base class is inherited by every derived entity or nested type, and all rules found along the chain are merged onto the schema node
 

src/KubeOps.Transpiler/CrdSchemaAttributeValidator.cs

@@ -102,6 +102,9 @@ public static V1CustomResourceDefinition Transpile(
                 };
             }
 
+            var validationRules = type.GetInheritedCustomAttributesData<ValidationRuleAttribute>().ToList();
+            CrdSchemaAttributeValidator.ValidateValidationRuleAttributes(type, validationRules, context);
+
             version.Schema = new()
             {
                 OpenAPIV3Schema = new()
@@ -127,8 +130,7 @@ public static V1CustomResourceDefinition Transpile(
                         { Count: > 0 } list => list,
                         _ => null,
                     },
-                    XKubernetesValidations = context.MapValidationRules(
-                        type.GetInheritedCustomAttributesData<ValidationRuleAttribute>()),
+                    XKubernetesValidations = context.MapValidationRules(validationRules),
                 },
             };
 
@@ -240,7 +242,7 @@ private static IEnumerable<V1CustomResourceColumnDefinition> MapPrinterColumns(
             }
 
             var mapped = context.Map(prop, EmptyAncestors);
-            yield return new()
+            var column = new V1CustomResourceColumnDefinition
             {
                 Name = attr.GetCustomAttributeCtorArg<string>(context, 1) ?? prop.GetPropertyName(context),
                 JsonPath = $"{path}.{prop.GetPropertyName(context)}",
@@ -253,6 +255,11 @@ private static IEnumerable<V1CustomResourceColumnDefinition> MapPrinterColumns(
                     _ => 1,
                 },
             };
+            CrdSchemaAttributeValidator.ValidatePrinterColumn(
+                prop,
+                column,
+                nameof(AdditionalPrinterColumnAttribute));
+            yield return column;
         }
 
         foreach (var attr in type.GetInheritedCustomAttributesData<GenericAdditionalPrinterColumnAttribute>())
@@ -288,7 +295,7 @@ private static IEnumerable<V1CustomResourceColumnDefinition> MapPrinterColumns(
                 continue;
             }
 
-            yield return new()
+            var column = new V1CustomResourceColumnDefinition
             {
                 Name = colName,
                 JsonPath = jsonPath,
@@ -301,6 +308,11 @@ private static IEnumerable<V1CustomResourceColumnDefinition> MapPrinterColumns(
                     _ => 1,
                 },
             };
+            CrdSchemaAttributeValidator.ValidatePrinterColumn(
+                type,
+                column,
+                nameof(GenericAdditionalPrinterColumnAttribute));
+            yield return column;
         }
     }
 
@@ -452,6 +464,8 @@ private static V1JSONSchemaProps Map(
                 : propValidations;
         }
 
+        CrdSchemaAttributeValidator.Validate(prop, props, context);
+
         return props;
     }
 
@@ -617,6 +631,8 @@ private static V1JSONSchemaProps MapObjectType(
 
                 var nextAncestors = new HashSet<Type>(ancestors) { type };
                 var preservesUnknownFields = type.GetCustomAttributeData<PreserveUnknownFieldsAttribute>() != null;
+                var validationRules = type.GetInheritedCustomAttributesData<ValidationRuleAttribute>().ToList();
+                CrdSchemaAttributeValidator.ValidateValidationRuleAttributes(type, validationRules, context);
 
                 try
                 {
@@ -646,8 +662,7 @@ private static V1JSONSchemaProps MapObjectType(
                             _ => null,
                         },
                         XKubernetesPreserveUnknownFields = preservesUnknownFields ? true : null,
-                        XKubernetesValidations = context.MapValidationRules(
-                            type.GetInheritedCustomAttributesData<ValidationRuleAttribute>()),
+                        XKubernetesValidations = context.MapValidationRules(validationRules),
                     };
                 }
                 catch (Exception ex) when (preservesUnknownFields

src/KubeOps.Transpiler/Crds.cs

@@ -97,6 +97,28 @@ foreach (var crd in crds)
 - **Custom Build Tasks:** Integrate CRD generation directly into your MSBuild process.
 - **Schema Validation Tools:** Use the generated CRD schema for validating custom resource YAML files.
 
+### CRD Schema Validation
+
+The transpiler performs a narrow validation pass for schema attributes that are
+known to produce CRDs rejected by the Kubernetes API server. This includes
+`uniqueItems: true`, invalid `x-kubernetes-list-*` topology combinations,
+invalid `x-kubernetes-map-type` placement, and malformed validation-rule
+metadata. Additional printer columns are also checked so their type is one of
+the Kubernetes-supported column types.
+
+The transpiler does not try to be a full OpenAPI linter. Some OpenAPI keywords
+are semantically useful only on specific schema types, but Kubernetes currently
+accepts those CRD schemas at admission time. Those combinations remain
+transpilable for compatibility.
+
+For a server-side check against a local cluster, generate manifests and use
+Kubernetes server dry-run for the generated CRD YAML files:
+
+```bash
+kubeops generate operator MyOperator ./MyOperator.csproj --out ./k8s --format yaml
+kubectl apply --dry-run=server -f ./k8s/<generated-crd-file>.yaml
+```
+
 The assembly inspection and attribute processing logic within this package is also leveraged by the KubeOps CLI (`kubeops generate operator`) command. The CLI uses this package's capabilities to find types decorated with `[EntityRbac]` attributes when generating the RBAC manifests (`Role`/`ClusterRole`) for your operator.
 
 For more details on defining the C# classes themselves, see the main KubeOps documentation.

src/KubeOps.Transpiler/README.md

@@ -22,12 +22,13 @@ public async Task HandleAsync_CreateRequestWithoutObjectMetadataUid_DoesNotFailM
     {
         using var host = await TestHost.Create();
         var client = host.GetTestClient();
+        var entityWithoutMetadataUid = CreateTestSpec("createvalue", "PT10M");
 
         var admissionRequest = CreateAdmissionReview(
-            uid: "issue-753-mutation-create-uid",
+            admissionRequestUid: "issue-753-mutation-create-uid",
             operation: "CREATE",
             dryRun: false,
-            @object: CreateTestSpec("createvalue", "PT10M"));
+            @object: entityWithoutMetadataUid);
 
         var response = await PostWebhookAsync(
             client,
@@ -67,7 +68,7 @@ public async Task HandleAsync_Request_BindsAndMutatesCorrectly(
 
         var spec = CreateTestSpec(value, timeout);
         var admissionRequest = CreateAdmissionReview(
-            uid: uid,
+            admissionRequestUid: uid,
             operation: operation,
             dryRun: dryRun,
             @object: operation == "DELETE" ? null : spec,

test/KubeOps.Operator.Web.Test/Webhooks/Admission/Mutation/MutationWebhook.ModelBinding.Test.cs

@@ -22,12 +22,13 @@ public async Task HandleAsync_CreateRequestWithoutObjectMetadataUid_DoesNotFailM
     {
         using var host = await TestHost.Create();
         var client = host.GetTestClient();
+        var entityWithoutMetadataUid = CreateTestSpec("createvalue", "PT10M");
 
         var admissionRequest = CreateAdmissionReview(
-            uid: "issue-753-validation-create-uid",
+            admissionRequestUid: "issue-753-validation-create-uid",
             operation: "CREATE",
             dryRun: false,
-            @object: CreateTestSpec("createvalue", "PT10M"));
+            @object: entityWithoutMetadataUid);
 
         var response = await PostWebhookAsync(
             client,
@@ -96,7 +97,7 @@ public async Task HandleAsync_Request_BindsAndValidatesCorrectly(
         var @object = CreateTestSpec(newValue, newTimeout);
         var oldObject = CreateTestSpec(oldValue, oldTimeout);
         var admissionRequest = CreateAdmissionReview(
-            uid: uid,
+            admissionRequestUid: uid,
             operation: operation,
             dryRun: dryRun,
             @object: operation == "DELETE" ? null : @object,

test/KubeOps.Operator.Web.Test/Webhooks/Admission/Validation/ValidationWebhook.ModelBinding.Test.cs

@@ -21,7 +21,7 @@ protected static object CreateTestSpec(string value, string timeout)
         };
 
     protected static object CreateAdmissionReview(
-        string uid,
+        string admissionRequestUid,
         string operation,
         bool dryRun,
         object? @object = null,
@@ -32,7 +32,7 @@ protected static object CreateAdmissionReview(
             kind = "AdmissionReview",
             request = new
             {
-                uid,
+                uid = admissionRequestUid,
                 operation,
                 dryRun,
                 @object,