Skip to content

Commit 1264015

Browse files
plumbisplumbis
authored
Post-release cleanup and expanded examples for beta validate (#712)
* Post-release cleanup and expanded examples for beta validate Signed-off-by: Pete Lumbis <[email protected]> * +IAM and sort Signed-off-by: Pete Lumbis <[email protected]> * sync with 1.15 update Signed-off-by: Pete Lumbis <[email protected]> * add feedback from @Piotr1215 Signed-off-by: Pete Lumbis <[email protected]> --------- Signed-off-by: Pete Lumbis <[email protected]>
1 parent 15edc91 commit 1264015

File tree

3 files changed

+293
-238
lines changed

3 files changed

+293
-238
lines changed

‎content/master/cli/command-reference.md

Lines changed: 144 additions & 117 deletions
Original file line numberDiff line numberDiff line change
@@ -4,6 +4,7 @@ title: Command Reference
44
description: "Command reference for the Crossplane CLI"
55
---
66

7+
78
<!-- vale Google.Headings = NO -->
89
The `crossplane` CLI provides utilities to make using Crossplane easier.
910

@@ -481,7 +482,7 @@ Inside the YAML file include an
481482
{{<hover label="apiVersion" line="3">}}metadata{{</hover>}} and
482483
{{<hover label="apiVersion" line="7">}}spec{{</hover>}}.
483484

484-
```yaml {label="or"}
485+
```yaml {label="apiVersion"}
485486
apiVersion: example.org/v1alpha1
486487
kind: ComposedResource
487488
metadata:
@@ -817,25 +818,19 @@ Configuration/platform-ref-aws v0.9.0 True
817818

818819
The `crossplane beta validate` command validates
819820
[compositions]({{<ref "../concepts/compositions">}}) against provider or XRD
820-
schema using the Kubernetes API server's validation library.
821+
schemas using the Kubernetes API server's validation library.
821822

822823
The `crossplane beta validate` command supports validating the following
823824
scenarios:
824825

826+
- Validate a managed resource or composite resource
827+
[against a Provider or XRD schema](#validate-resources-against-a-schema).
828+
- Use the output of `crossplane beta render` as [validation input](#validate-render-command-output).
825829
- Validate an [XRD against Kubernetes Common Expression Language](#validate-common-expression-language-rules)
826830
(CEL) rules.
827-
- A Crossplane resource against a schema, for example a Provider or
828-
Composite Resource Definition (XRD).
829-
- Validate the output of the `crossplane beta render` command to validate
830-
function-based compositions.
831-
- Validate all Crossplane resources against a directory of schema files.
832-
833-
831+
- Validate resources against a [directory of schemas](#validate-against-a-directory-of-schemas).
834832

835833

836-
- When validating resources against provider schemas, the command downloads and
837-
caches the providers' CRDs to make future runs much faster.
838-
839834
{{< hint "note" >}}
840835
The `crossplane beta validate` command performs all validation offline.
841836

@@ -855,72 +850,87 @@ A Kubernetes cluster running Crossplane isn't required.
855850
| | `--verbose` | Print verbose logging statements. |
856851
{{< /table >}}
857852

858-
#### Validate Common Expression Language rules
853+
#### Validate resources against a schema
859854

860-
XRDs can define [validation rules](https://kubernetes.io/docs/tasks/extend-kubernetes/custom-resources/custom-resource-definitions/#validation-rules) expressed in the Common Expression Language, CEL for short.
855+
The `crossplane beta validate` command can validate an XR and one or more
856+
managed resources against a provider's schema.
861857

862-
{{< expand "An example validation rule" >}}
863-
```yaml
864-
x-kubernetes-validations:
865-
- rule: "self.minReplicas <= self.replicas && self.replicas <= self.maxReplicas"
866-
message: "replicas should be in between minReplicas and maxReplicas."
867-
```
868-
{{< /expand >}}
858+
{{<hint "important" >}}
859+
When validating against a provider the `crossplane beta validate` command
860+
downloads the provider package to the `--cache-dir` directory. By default
861+
Crossplane uses `.crossplane` as the `--cache-dir` location.
869862

870-
`crossplane beta validate xrd.yaml rong-xr.yaml`
871-
{{< expand "CEL rule violation" >}}
872-
```console
873-
[x] CEL validation error example.crossplane.io/v1beta1, Kind=XR, example : spec: Invalid value: "object": replicas should be in between minReplicas and maxReplicas.
874-
Total 1 resources: 0 missing schemas, 0 success cases, 1 failure cases
875-
```
876-
{{< /expand >}}
863+
Access to a Kubernetes cluster or Crossplane pod isn't required.
864+
Validation requires the ability to download the provider package.
865+
{{< /hint >}}
877866

878-
#### Validate resource against a schema
867+
The `crossplane beta validate` command downloads and caches the schema CRD files
868+
in the `--cache-dir` directory. By default the Crossplane CLI uses
869+
`.crossplane/cache` as the cache location.
879870

880-
Validate a provider CRD against an XRD.
871+
To clear the cache and download the CRD files again use the `--clean-cache` flag.
881872

882-
`crossplane beta validate schemas.yaml resources.yaml`
873+
To validate a managed resource against a provider,
874+
first, create a provider manifest file. For example, to validate an IAM role
875+
from Provider AWS, use the
876+
[Provider AWS IAM](https://marketplace.upbound.io/providers/upbound/provider-aws-iam/v1.0.0)
877+
manifest.
883878

884-
{{< expand "Sample validation output" >}}
885-
```console
886-
[✓] example.crossplane.io/v1beta1, Kind=XR, example validated successfully
887-
Total 1 resources: 0 missing schemas, 1 success cases, 0 failure cases
888-
controlplane $ crossplane beta validate schemas.yaml resources.yaml
889-
[✓] example.crossplane.io/v1beta1, Kind=XR, example validated successfully
890-
[✓] iam.aws.upbound.io/v1beta1, Kind=AccessKey, sample-access-key-0 validated successfully
891-
[✓] iam.aws.upbound.io/v1beta1, Kind=AccessKey, sample-access-key-1 validated successfully
892-
[✓] iam.aws.upbound.io/v1beta1, Kind=User, test-user-0 validated successfully
893-
[✓] iam.aws.upbound.io/v1beta1, Kind=User, test-user-1 validated successfully
894-
Total 5 resources: 0 missing schemas, 5 success cases, 0 failure cases
879+
{{<hint "tip" >}}
880+
To validate a
881+
"[family provider](https://blog.upbound.io/new-provider-families)" use the
882+
provider manifests of the resources to validate.
883+
{{< /hint >}}
884+
885+
```yaml
886+
apiVersion: pkg.crossplane.io/v1
887+
kind: Provider
888+
metadata:
889+
name: provider-aws-iam
890+
spec:
891+
package: xpkg.upbound.io/upbound/provider-aws-iam:v1.0.0
895892
```
896-
{{< /expand >}}
897893

898-
{{< hint "important" >}}
899-
The command has two categories of output; _errors_ and _warnings_.
900-
If there is a validation error or warning, the command indicates it accordingly.
901-
{{< /hint >}}
894+
Now include the XR or managed resource to validate.
902895

903-
`crossplane beta validate missing-schemas.yaml resources.yaml`
896+
For example, to validate an
897+
{{<hover label="iamAK" line="2">}}AccessKey{{</hover>}} managed resource,
898+
provide a managed resource YAML file.
904899

905-
{{< expand "Missing schema validation" >}}
906-
```console
907-
[✓] example.crossplane.io/v1beta1, Kind=XR, example validated successfully
908-
[!] could not find CRD/XRD for: iam.aws.upbound.io/v1beta1, Kind=AccessKey
909-
[!] could not find CRD/XRD for: iam.aws.upbound.io/v1beta1, Kind=AccessKey
910-
[✓] iam.aws.upbound.io/v1beta1, Kind=User, test-user-0 validated successfully
911-
[✓] iam.aws.upbound.io/v1beta1, Kind=User, test-user-1 validated successfully
912-
Total 5 resources: 2 missing schemas, 3 success cases, 0 failure cases
900+
```yaml {label="iamAK"}
901+
apiVersion: iam.aws.upbound.io/v1beta1
902+
kind: AccessKey
903+
metadata:
904+
name: sample-access-key-0
905+
spec:
906+
forProvider:
907+
userSelector:
908+
matchLabels:
909+
example-name: test-user-0
913910
```
914-
{{< /expand >}}
911+
912+
Run the `crossplane beta validate` command providing the provider and managed
913+
resource YAML files as input.
914+
915+
```shell
916+
crossplane beta validate provider.yaml managedResource.yaml
917+
[✓] iam.aws.upbound.io/v1beta1, Kind=AccessKey, sample-access-key-0 validated successfully
918+
Total 1 resources: 0 missing schemas, 1 success case, 0 failure cases
919+
```
920+
915921

916922
#### Validate render command output
917923

918-
Passing the output of the _render_ command to the _validate_ command.
924+
You can pipe the output of `crossplane beta render` into
925+
`crossplane beta validate` to validate complete Crossplane resource pipelines,
926+
including XRs, compositions and composition functions.
919927

920-
`crossplane beta render xr.yaml composition.yaml func.yaml | crossplane beta validate schemas.yaml -`
928+
Use the `--include-full-xr` command with `crossplane beta render` and the `-`
929+
option with `crossplane beta validate` to pipe the output from
930+
`crossplane beta render` to the input of `crossplane beta validate`.
921931

922-
{{< expand "Pipe render result to validate command" >}}
923-
```console
932+
```shell {copy-lines="1"}
933+
crossplane beta render xr.yaml composition.yaml function.yaml --include-full-xr | crossplane beta validate schemas.yaml -
924934
[x] schema validation error example.crossplane.io/v1beta1, Kind=XR, example : status.conditions[0].lastTransitionTime: Invalid value: "null": status.conditions[0].lastTransitionTime in body must be of type string: "null"
925935
[x] schema validation error example.crossplane.io/v1beta1, Kind=XR, example : spec: Required value
926936
[✓] iam.aws.upbound.io/v1beta1, Kind=AccessKey, sample-access-key-0 validated successfully
@@ -929,62 +939,97 @@ Passing the output of the _render_ command to the _validate_ command.
929939
[✓] iam.aws.upbound.io/v1beta1, Kind=User, test-user-1 validated successfully
930940
Total 5 resources: 0 missing schemas, 4 success cases, 1 failure cases
931941
```
932-
{{< /expand >}}
933942

934-
Make sure to include full XR in the render output to avoid the _missing resource_ warning.
935943

936-
`crossplane beta render xr.yaml composition.yaml func.yaml --include-full-xr | crossplane beta validate schemas.yaml -`
944+
#### Validate Common Expression Language rules
945+
XRDs can define [validation rules](https://kubernetes.io/docs/tasks/extend-kubernetes/custom-resources/custom-resource-definitions/#validation-rules) expressed in the Common Expression Language
946+
([CEL](https://kubernetes.io/docs/reference/using-api/cel/)).
937947

938-
{{< expand "Use --include-full-xr flag" >}}
939-
```console
940-
[x] schema validation error example.crossplane.io/v1beta1, Kind=XR, example : status.conditions[0].lastTransitionTime: Invalid value: "null": status.conditions[0].lastTransitionTime in body must be of type string: "null"
941-
[✓] iam.aws.upbound.io/v1beta1, Kind=AccessKey, sample-access-key-0 validated successfully
942-
[✓] iam.aws.upbound.io/v1beta1, Kind=AccessKey, sample-access-key-1 validated successfully
943-
[✓] iam.aws.upbound.io/v1beta1, Kind=User, test-user-0 validated successfully
944-
[✓] iam.aws.upbound.io/v1beta1, Kind=User, test-user-1 validated successfully
945-
Total 5 resources: 0 missing schemas, 4 success cases, 1 failure cases
948+
949+
Apply a CEL rule with the
950+
{{<hover label="celXRD" line="12" >}}x-kubernetes-validations{{</hover>}} key
951+
inside the schema {{<hover label="celXRD" line="10" >}}spec{{</hover>}} object of an XRD.
952+
953+
```yaml {label="celXRD"}
954+
apiVersion: apiextensions.crossplane.io/v1
955+
kind: CompositeResourceDefinition
956+
metadata:
957+
name: myXR.crossplane.io
958+
spec:
959+
# Removed for brevity
960+
openAPIV3Schema:
961+
type: object
962+
properties:
963+
spec:
964+
type: object
965+
x-kubernetes-validations:
966+
- rule: "self.minReplicas <= self.replicas && self.replicas <= self.maxReplicas"
967+
message: "replicas should be in between minReplicas and maxReplicas."
968+
properties:
969+
minReplicas:
970+
type: integer
971+
maxReplicas:
972+
type: integer
973+
replicas:
974+
type: integer
975+
# Removed for brevity
946976
```
947-
{{< /expand >}}
948977

949-
#### Validate by directory
978+
The rule in this example checks that the vale of the
979+
{{<hover label="celXR" line="6">}}replicas{{</hover>}} field of an XR is between
980+
the {{<hover label="celXR" line="7">}}minReplicas{{</hover>}} and
981+
{{<hover label="celXR" line="8">}}maxReplicas{{</hover>}} values.
982+
983+
```yaml {label="celXR"}
984+
apiVersion: example.crossplane.io/v1beta1
985+
kind: XR
986+
metadata:
987+
name: example
988+
spec:
989+
replicas: 49
990+
minReplicas: 1
991+
maxReplicas: 30
992+
```
950993

951-
Pass a directory containing YAML files as an argument to the validate command.
994+
Running `crossplane beta validate` with the example XRD and XR produces an
995+
error.
952996

953-
{{< hint "tip" >}}
954-
The command processes only the Crossplane YAML files while ignoring files with
955-
other extensions.
956-
{{< /hint >}}
997+
```shell
998+
`crossplane beta validate xrd.yaml xr.yaml
999+
[x] CEL validation error example.crossplane.io/v1beta1, Kind=XR, example : spec: Invalid value: "object": replicas should be in between minReplicas and maxReplicas.
1000+
Total 1 resources: 0 missing schemas, 0 success cases, 1 failure cases
1001+
```
1002+
1003+
1004+
#### Validate against a directory of schemas
9571005
958-
`crossplane beta render xr.yaml composition.yaml func.yaml --include-full-xr > rendered.yaml`
1006+
The `crossplane beta render` command can validate a directory of YAML files.
9591007

960-
The _Extensions_ directory contains packages (provider and configuration) to validate against `tree Extensions`
1008+
The command only processes `.yaml` and `.yml` files, while ignoring all other
1009+
file types.
9611010

962-
{{< expand "An example directory content" >}}
963-
```console
964-
Extensions
1011+
With a directory of files, provide the directory and resource to validate.
1012+
1013+
For example, using a directory named
1014+
{{<hover label="validateDir" line="2">}}schemas{{</hover>}} containing the XRD
1015+
and Provider schemas.
1016+
1017+
```shell {label="validateDir"}
1018+
tree
1019+
schemas
9651020
|-- platform-ref-aws.yaml
9661021
|-- providers
9671022
| |-- a.txt
9681023
| `-- provider-aws-iam.yaml
9691024
`-- xrds
9701025
`-- xrd.yaml
971-
972-
2 directories, 4 files
9731026
```
974-
{{< /expand >}}
9751027

976-
`crossplane beta validate Extensions rendered.yaml`
977-
978-
{{< expand "Downloading packages and validating directory content" >}}
979-
```console
980-
package schemas does not exist, downloading: xpkg.upbound.io/upbound/configuration-observability-oss:v0.2.0
981-
package schemas does not exist, downloading: xpkg.upbound.io/upbound/configuration-gitops-flux:v0.2.0
982-
package schemas does not exist, downloading: xpkg.upbound.io/upbound/provider-aws-iam:v0.45.0
983-
package schemas does not exist, downloading: xpkg.upbound.io/upbound/platform-ref-aws:v0.9.0
984-
package schemas does not exist, downloading: xpkg.upbound.io/upbound/configuration-aws-network:v0.7.0
985-
package schemas does not exist, downloading: xpkg.upbound.io/upbound/configuration-aws-database:v0.5.0
986-
package schemas does not exist, downloading: xpkg.upbound.io/upbound/configuration-aws-eks:v0.5.0
987-
package schemas does not exist, downloading: xpkg.upbound.io/upbound/configuration-app:v0.2.0
1028+
Provide the directory name and a resource YAML file to the
1029+
`crossplane beta validate` command.
1030+
1031+
```shell
1032+
crossplane beta validate schema resources.yaml
9881033
[x] schema validation error example.crossplane.io/v1beta1, Kind=XR, example : status.conditions[0].lastTransitionTime: Invalid value: "null": status.conditions[0].lastTransitionTime in body must be of type string: "null"
9891034
[x] CEL validation error example.crossplane.io/v1beta1, Kind=XR, example : spec: Invalid value: "object": no such key: minReplicas evaluating rule: replicas should be greater than or equal to minReplicas.
9901035
[✓] iam.aws.upbound.io/v1beta1, Kind=AccessKey, sample-access-key-0 validated successfully
@@ -993,24 +1038,6 @@ package schemas does not exist, downloading: xpkg.upbound.io/upbound/configurat
9931038
[✓] iam.aws.upbound.io/v1beta1, Kind=User, test-user-1 validated successfully
9941039
Total 5 resources: 0 missing schemas, 4 success cases, 1 failure cases
9951040
```
996-
{{< /expand >}}
997-
998-
#### Local schemas cache
999-
1000-
The validate command downloads missing CRDs into a _.crossplane_ directory.
1001-
1002-
{{< hint "tip" >}}
1003-
Running the same command again doesn't trigger the download because the command
1004-
cached all the schemas.
1005-
{{< /hint >}}
1006-
1007-
Use a custom directory as a cache for downloading the schemas.
1008-
1009-
`crossplane beta validate Extensions rendered.yaml --cache-dir mycache`
1010-
1011-
Clean the cache directory.
1012-
1013-
`crossplane beta validate Extensions rendered.yaml --cache-dir mycache --clean-cache`
10141041

10151042
### beta xpkg init
10161043

0 commit comments

Comments
 (0)