Upgrading to v0.14

Crossplane made a small handful of breaking changes in v0.14. The most broadly impactful change was updating the CompositeResourceDefinition (XRD) schema to support defining multiple versions of a composite resource (XR) at once. This guide covers how to upgrade from v0.13 of Crossplane to v0.14.

• Updating CompositeResourceDefinitions
• Updating Packages

Updating CompositeResourceDefinitions

In v0.14 the schema of XRD was updated to support defining multiple versions of an XR. This update requires manual update steps. To upgrade from v0.13 to v0.14 you must:

1. Ensure you have up-to-date YAML representations of all of your XRDs.
2. helm upgrade your Crossplane release.
3. Update and apply all of your XRDs.

Note that Crossplane will not actively reconcile your XRs between steps 2 and 3, and you will see some errors in the events and logs, but your managed resources (and thus infrastructure) will continue to run. Follow the below steps in order to update your XRDs for v0.14:

1. Rename spec.crdSpecTemplate to spec.versions.
2. Move spec.versions.group to spec.group.
3. Move spec.versions.names to spec.names.
4. Rename spec.versions.version to spec.versions.name
5. Rename spec.versions.validation (if set) to spec.versions.schema.
6. Rename spec.versions.additionalPrinterColumns[].JSONPath (if set) to spec.versions.additionalPrinterColumns[].jsonPath.
7. Set spec.versions.served to true.
8. Set spec.versions.referenceable to true.
9. Make spec.versions a single element array.

For example, the below XRD:

 1apiVersion: apiextensions.crossplane.io/v1alpha1
 2kind: CompositeResourceDefinition
 3metadata:
 4  name: xpostgresqlinstances.database.example.org
 5spec:
 6  claimNames:
 7    kind: PostgreSQLInstance
 8    plural: postgresqlinstances
 9  connectionSecretKeys:
10    - username
11    - password
12    - endpoint
13    - port
14  crdSpecTemplate:
15    group: database.example.org
16    version: v1alpha1
17    names:
18      kind: XPostgreSQLInstance
19      plural: xpostgresqlinstances
20    validation:
21      openAPIV3Schema:
22        type: object
23        properties:
24          spec:
25            type: object
26            properties:
27              parameters:
28                type: object
29                properties:
30                  storageGB:
31                    type: integer
32                required:
33                  - storageGB
34            required:
35              - parameters

Would become:

 1apiVersion: apiextensions.crossplane.io/v1alpha1
 2kind: CompositeResourceDefinition
 3metadata:
 4  name: xpostgresqlinstances.database.example.org
 5spec:
 6  group: database.example.org
 7  names:
 8    kind: XPostgreSQLInstance
 9    plural: xpostgresqlinstances
10  claimNames:
11    kind: PostgreSQLInstance
12    plural: postgresqlinstances
13  connectionSecretKeys:
14    - username
15    - password
16    - endpoint
17    - port
18  versions:
19  - name: v1alpha1
20    served: true
21    referenceable: true
22    schema:
23      openAPIV3Schema:
24        type: object
25        properties:
26          spec:
27            type: object
28            properties:
29              parameters:
30                type: object
31                properties:
32                  storageGB:
33                    type: integer
34                required:
35                  - storageGB
36            required:
37              - parameters

Updating Packages

A minor breaking change was made to on-disk package types (meta.pkg.crossplane.io). In v0.13, the spec.crossplane field was present to specify a compatible Crossplane version range, but it was not honored by the package manager when packages were installed. The field was refactored to spec.crossplane.version meaning that packages that previously specified spec.crossplane will fail to parse when building with the Crossplane CLI or installing into a Crossplane Kubernetes cluster. If spec.crossplane was not specified, packages compatible with Crossplane v0.13 will continue to be compatible in v0.14. This is true for both Provider and Configuration packages.

The following example shows how a Configuration package that specified spec.crossplane can be updated to specify Crossplane version constraints that will be honored by the package manager in v0.14:

1apiVersion: meta.pkg.crossplane.io/v1alpha1
2kind: Configuration
3metadata:
4  name: my-configuration
5spec:
6  crossplane: ">=v0.13.0"

Would become:

1apiVersion: meta.pkg.crossplane.io/v1alpha1
2kind: Configuration
3metadata:
4  name: my-configuration
5spec:
6  crossplane:
7    version: ">=v0.13.0"

Please note that while spec.dependsOn is also a valid field in on-disk package types, it is not yet honored by the package manager and will be ignored at installation time.