From d7956123c1c0855cd1ce6c65cb9323041fd6e79b Mon Sep 17 00:00:00 2001 From: undefinedhuman Date: Sun, 27 Apr 2025 16:23:22 +0200 Subject: [PATCH 1/4] feat(cli): add docs for beta lint cli command Signed-off-by: undefinedhuman --- content/master/cli/command-reference.md | 161 ++++++++++++++++++++++++ 1 file changed, 161 insertions(+) diff --git a/content/master/cli/command-reference.md b/content/master/cli/command-reference.md index 7e442888d..4c146c80c 100644 --- a/content/master/cli/command-reference.md +++ b/content/master/cli/command-reference.md @@ -1093,4 +1093,165 @@ crossplane beta validate schema resources.yaml Total 5 resources: 0 missing schemas, 4 success cases, 1 failure cases ``` +### beta lint +The `crossplane beta lint` command checks [composite resource definitions]({{}}) +against a set of best practices. These rules help ensure that your XRDs are well-formed and follow Crossplane's API design guidelines. + +{{< hint "note" >}} +The `crossplane beta lint` command performs all checks offline. + +A Kubernetes cluster running Crossplane isn't required. +{{< /hint >}} + +### Flags + +{{< table "table table-sm table-striped" >}} +| Short flag | Long flag | Description | +| ------------ | ------------------ | ------------------------------------------------------------------------ | +| `-h` | `--help` | Show context sensitive help. | +| `-o` | `--output` | Output format. Valid values are stdout (default) or json. | +| | `--skip-reference` | Skip printing the reference docs to the rule that was violated. | +{{< /table >}} + +#### Rule XRD001 - No boolean fields + +Boolean fields are inflexible and cannot be extended. Replace them with enum-based strings so you can introduce additional states later. +See [Kubernetes API conventions](https://github.com/kubernetes/community/blob/master/contributors/devel/sig-architecture/api-conventions.md#primitive-types) + +```yaml {label="Incorrect:"} +# Removed for brevity +properties: + spec: + type: object + properties: + enabled: + type: boolean # flagged by XRD001 +``` + +```yaml {label="Best practice:"} +# Removed for brevity +properties: + enabled: + type: string + enum: + - Enabled + - Disabled +``` + +#### Rule XRD002 - Check for required fields + +Marking fields as required up front forces every user to provide them and makes future changes risky - this rule flags any `required:` +list in your XRD so you can decide if each field truly needs to be mandatory. + +```yaml +# Removed for brevity +properties: + spec: + type: object + properties: + version: + type: string + required: # flagged by XRD002 + - version +``` + +#### Rule XRD003 - Check for missing descriptions + +Every property in your schema should include a description: so that `kubectl explain` and documentation generators can produce helpful output. + +```yaml {label="Incorrect:"} +# Removed for brevity +versions: +- name: v1alpha1 + schema: + openAPIV3Schema: + type: object + properties: + spec: + type: object + properties: + version: # flagged by XRD003 + type: string + +``` + +```yaml {label="Best practice:"} +# Removed for brevity +properties: + spec: + type: object + properties: + version: + type: string + description: | + The version of the database engine to deploy. +``` + +#### Ignore rules + +If you need to opt out of a specific check for example, a field that you know is safe even though it violates a rule +you can append a `# nolint ` comment directly above the violating node or line: + +```yaml {label="Missing description"} +# Removed for brevity +properties: + spec: + type: object + properties: + # nolint XRD003 + version: + type: string +``` + +```yaml {label="Boolean field"} +# Removed for brevity +properties: + spec: + type: object + properties: + version: + # nolint XRD001 + type: boolean +``` + +#### Example usage + +Running the command on an XRD file: + +```shell +crossplane beta lint my-xrd.yaml +xdatabases.custom-api.example.org:20 [XRD001] Boolean field detected at path spec.versions[0].schema.openAPIV3Schema.properties.spec.properties.enabled — consider using an enum instead for extensibility. More information: (https://github.com/kubernetes/community/blob/master/contributors/devel/sig-architecture/api-conventions.md#primitive-types) +xdatabases.custom-api.example.org:25 [XRD002] Required field 'enabled' at path spec.versions[0].schema.openAPIV3Schema.properties.spec.required — consider making it optional with a default. +Found 2 issues: 0 errors, 2 warnings +exit status 2 +``` + +This outputs any violations of the best practices, along with references to the relevant guidelines for fixing them. + +To integrate in CI or tooling, output as JSON (--output=json): + +```shell +crossplane beta lint my-xrd.yaml --output=json +{ + "summary": { + "valid": false, + "total": 3, + "errors": 0, + "warnings": 3 + }, + "issues": [ + { + "id": "XRD001", + "name": "xdatabases.custom-api.example.org", + "line": 20, + "error": false, + "reference": "https://github.com/kubernetes/community/blob/master/contributors/devel/sig-archi +tecture/api-conventions.md#primitive-types", + "message": "Boolean field detected at path spec.versions[0].schema.openAPIV3Schema.properties. +spec.properties.enabled — consider using an enum instead for extensibility." + }, + ... + ] +} +``` From c850a8d90d5c50210006f8d004a7e32add646e72 Mon Sep 17 00:00:00 2001 From: undefinedhuman Date: Sun, 27 Apr 2025 16:33:46 +0200 Subject: [PATCH 2/4] chore: add missing new line Signed-off-by: undefinedhuman --- content/master/cli/command-reference.md | 1 + 1 file changed, 1 insertion(+) diff --git a/content/master/cli/command-reference.md b/content/master/cli/command-reference.md index 4c146c80c..0ce92c142 100644 --- a/content/master/cli/command-reference.md +++ b/content/master/cli/command-reference.md @@ -1093,6 +1093,7 @@ crossplane beta validate schema resources.yaml Total 5 resources: 0 missing schemas, 4 success cases, 1 failure cases ``` + ### beta lint The `crossplane beta lint` command checks [composite resource definitions]({{}}) From 27e60dcb08fd16e14b67c3d9bc5ed5ffe20f31cb Mon Sep 17 00:00:00 2001 From: undefinedhuman Date: Sun, 27 Apr 2025 16:39:21 +0200 Subject: [PATCH 3/4] fix(crank): headers Signed-off-by: undefinedhuman --- content/master/cli/command-reference.md | 11 ++++++----- 1 file changed, 6 insertions(+), 5 deletions(-) diff --git a/content/master/cli/command-reference.md b/content/master/cli/command-reference.md index 0ce92c142..e75ef676c 100644 --- a/content/master/cli/command-reference.md +++ b/content/master/cli/command-reference.md @@ -1093,7 +1093,6 @@ crossplane beta validate schema resources.yaml Total 5 resources: 0 missing schemas, 4 success cases, 1 failure cases ``` - ### beta lint The `crossplane beta lint` command checks [composite resource definitions]({{}}) @@ -1105,7 +1104,7 @@ The `crossplane beta lint` command performs all checks offline. A Kubernetes cluster running Crossplane isn't required. {{< /hint >}} -### Flags +#### Flags {{< table "table table-sm table-striped" >}} | Short flag | Long flag | Description | @@ -1115,7 +1114,9 @@ A Kubernetes cluster running Crossplane isn't required. | | `--skip-reference` | Skip printing the reference docs to the rule that was violated. | {{< /table >}} -#### Rule XRD001 - No boolean fields +#### Rules + +##### Rule XRD001 - No boolean fields Boolean fields are inflexible and cannot be extended. Replace them with enum-based strings so you can introduce additional states later. See [Kubernetes API conventions](https://github.com/kubernetes/community/blob/master/contributors/devel/sig-architecture/api-conventions.md#primitive-types) @@ -1140,7 +1141,7 @@ properties: - Disabled ``` -#### Rule XRD002 - Check for required fields +##### Rule XRD002 - Check for required fields Marking fields as required up front forces every user to provide them and makes future changes risky - this rule flags any `required:` list in your XRD so you can decide if each field truly needs to be mandatory. @@ -1157,7 +1158,7 @@ properties: - version ``` -#### Rule XRD003 - Check for missing descriptions +##### Rule XRD003 - Check for missing descriptions Every property in your schema should include a description: so that `kubectl explain` and documentation generators can produce helpful output. From 001a0c46aef7b501f7472a5d6cdda9fc97dce3cf Mon Sep 17 00:00:00 2001 From: undefinedhuman Date: Sun, 27 Apr 2025 16:44:40 +0200 Subject: [PATCH 4/4] fix(crank): remove rule keyword Signed-off-by: undefinedhuman --- content/master/cli/command-reference.md | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/content/master/cli/command-reference.md b/content/master/cli/command-reference.md index e75ef676c..036065b4f 100644 --- a/content/master/cli/command-reference.md +++ b/content/master/cli/command-reference.md @@ -1116,7 +1116,7 @@ A Kubernetes cluster running Crossplane isn't required. #### Rules -##### Rule XRD001 - No boolean fields +##### XRD001 - No boolean fields Boolean fields are inflexible and cannot be extended. Replace them with enum-based strings so you can introduce additional states later. See [Kubernetes API conventions](https://github.com/kubernetes/community/blob/master/contributors/devel/sig-architecture/api-conventions.md#primitive-types) @@ -1141,7 +1141,7 @@ properties: - Disabled ``` -##### Rule XRD002 - Check for required fields +##### XRD002 - Check for required fields Marking fields as required up front forces every user to provide them and makes future changes risky - this rule flags any `required:` list in your XRD so you can decide if each field truly needs to be mandatory. @@ -1158,7 +1158,7 @@ properties: - version ``` -##### Rule XRD003 - Check for missing descriptions +##### XRD003 - Check for missing descriptions Every property in your schema should include a description: so that `kubectl explain` and documentation generators can produce helpful output.