Skip to content

Commit aac9cda

Browse files
negznegz
committed
Add "What's new in v2.0?" page
This page is targeted at folks who're already familiar with v1.x and just want to know what's new. Signed-off-by: Nic Cope <[email protected]>
1 parent 7a596b4 commit aac9cda

File tree

4 files changed

+249
-1
lines changed

4 files changed

+249
-1
lines changed

‎content/v2.0-preview/_index.md

Lines changed: 3 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -15,6 +15,9 @@ Crossplane organizes its documentation into the following sections:
1515
* [What's Crossplane?]({{<ref "whats-crossplane">}}) introduces Crossplane
1616
and explains why you should use it.
1717

18+
* [What's New in v2?]({{<ref "whats-new">}}) highlights what's changed in
19+
Crossplane v2.
20+
1821
* [Get Started]({{<ref "get-started">}}) explains how to install Crossplane and
1922
create a control plane.
2023

‎content/v2.0-preview/get-started/_index.md

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1,6 +1,6 @@
11
---
22
title: Get Started
3-
weight: 4
3+
weight: 40
44
description: Get started with Crossplane.
55
---
66

‎content/v2.0-preview/get-started/get-started-with-managed-resources.md

Lines changed: 9 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -36,6 +36,15 @@ This guide requires:
3636
* An AWS account with permissions to create an S3 storage bucket
3737
* AWS [access keys](https://docs.aws.amazon.com/cli/latest/userguide/cli-configure-quickstart.html#cli-configure-quickstart-creds)
3838
39+
{{<hint "note">}}
40+
Only AWS managed resources support the Crossplane v2 preview.
41+
42+
<!-- vale gitlab.FutureTense = NO -->
43+
Maintainers will update the managed resources for other systems including Azure,
44+
GCP, Terraform, Helm, GitHub, etc to support Crossplane v2 soon.
45+
<!-- vale gitlab.FutureTense = YES -->
46+
{{</hint>}}
47+
3948
## Install support for the managed resource
4049
4150
Follow these steps to install support for the `Bucket` managed resource:

‎content/v2.0-preview/whats-new/_index.md

Lines changed: 236 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,236 @@
1+
---
2+
title: What's New in v2?
3+
weight: 4
4+
description: Learn what's new in the Crossplane v2 preview
5+
---
6+
**Crossplane v2 makes Crossplane more useful, more intuitive, and less
7+
opinionated.**
8+
9+
Crossplane v2 makes three major changes:
10+
11+
* **Composite resources are now namespaced**
12+
* **Managed resources are now namespaced**
13+
* **Composition supports any Kubernetes resource**
14+
15+
Despite these major changes, Crossplane v2 is backward compatible with
16+
Crossplane v1.
17+
18+
```mermaid
19+
flowchart LR
20+
user(User)
21+
22+
subgraph ns [my-namespace]
23+
direction LR
24+
xr("App (XR)")
25+
dply("Deployment")
26+
svc("Service")
27+
rds("RDSInstance (MR)")
28+
end
29+
30+
user --create-->xr
31+
xr compose-dply@--compose--> dply
32+
xr compose-svc@--compose--> svc
33+
xr compose-rds@--compose--> rds
34+
compose-dply@{animate: true}
35+
36+
compose-dply@{animate: true}
37+
compose-svc@{animate: true}
38+
compose-rds@{animate: true}
39+
```
40+
41+
**Crossplane v2 is better suited to building control planes for applications,
42+
not just infrastructure.** It removes the need for awkward abstractions like
43+
claims and provider-kubernetes Objects.
44+
45+
{{<hint "tip">}}
46+
Most users can upgrade to Crossplane v2 without breaking changes.
47+
{{</hint>}}
48+
49+
{{<hint "note">}}
50+
This page assumes you're familiar with Crossplane. New to Crossplane? Read
51+
[What's Crossplane]({{<ref "whats-crossplane">}}) instead.
52+
{{</hint>}}
53+
54+
55+
## Namespaced composite resources
56+
57+
Crossplane v2 makes composite resources (XRs) namespaced by default.
58+
59+
A namespaced XR can any resource ([not just Crossplane resources](#compose-any-resource))
60+
in its namespace.
61+
62+
A namespaced XR looks like this:
63+
64+
```yaml
65+
apiVersion: example.crossplane.io/v1
66+
kind: App
67+
metadata:
68+
namespace: default
69+
name: my-app
70+
spec:
71+
image: nginx
72+
crossplane:
73+
compositionRef:
74+
name: app-kcl
75+
compositionRevisionRef:
76+
name: app-kcl-41b6efe
77+
resourceRefs:
78+
- apiVersion: apps/v1
79+
kind: Deployment
80+
name: my-app-9bj8j
81+
- apiVersion: v1
82+
kind: Service
83+
name: my-app-bflc4
84+
```
85+
86+
{{<hint "note">}}
87+
Crossplane v2 moves all an XR's "Crossplane machinery" under `spec.crossplane`.
88+
This makes it easier for users to tell which fields are important to them, and
89+
which are just "Crossplane stuff" they can ignore.
90+
{{</hint>}}
91+
92+
Composite resource definitions (XRDs) now have a `scope` field. The `scope`
93+
field defaults to `Namespaced` in the new v2alpha1 version of the XRD API.
94+
95+
```yaml
96+
apiVersion: apiextensions.crossplane.io/v2alpha1
97+
kind: CompositeResourceDefinition
98+
metadata:
99+
name: apps.example.crossplane.io
100+
spec:
101+
scope: Namespaced
102+
group: example.crossplane.io
103+
names:
104+
kind: App
105+
plural: apps
106+
versions:
107+
- name: v1
108+
# Removed for brevity
109+
```
110+
111+
You can also set the `scope` field to `Cluster` to create a cluster scoped XR. A
112+
cluster scoped XR can compose any cluster scoped resource. A cluster scoped XR
113+
can also compose any namespaced resource in any namespace.
114+
115+
With namespaced XRs there's no longer a need for claims. **The new namespaced
116+
and cluster scoped XRs in Crossplane v2 don't support claims.**
117+
118+
{{<hint "tip">}}
119+
Crossplane v2 is backward compatible with v1-style XRs.
120+
121+
When you use v1 of the XRD API `scope` defaults to a special `LegacyCluster`
122+
mode. `LegacyCluster` XRs support claims and don't use `spec.crossplane`.
123+
{{</hint>}}
124+
125+
## Namespaced managed resources
126+
127+
Crossplane v2 makes all managed resources (MRs) namespaced.
128+
129+
This enables a namespaced XR to compose entirely of namespaced resources -
130+
whether they're a Crossplane MR like an `RDSInstance`, a Kubernetes resource
131+
like a `Deployment`, or a third party custom resource like a
132+
[Cluster API](https://cluster-api.sigs.k8s.io) `Cluster`.
133+
134+
A namespaced MR looks like this:
135+
136+
```yaml
137+
apiVersion: s3.aws.m.upbound.io/v1beta1
138+
kind: Bucket
139+
metadata:
140+
namespace: default
141+
generateName: my-bucket
142+
spec:
143+
forProvider:
144+
region: us-east-2
145+
```
146+
147+
Namespaced MRs work great with or without composition. Crossplane v2 isn't
148+
opinionated about using composition and MRs together. Namespaces enable fine
149+
grained access control over who can create what MRs.
150+
151+
{{<hint "note">}}
152+
During the Crossplane v2 preview only namespaced AWS managed resources are
153+
available.
154+
155+
<!-- vale gitlab.FutureTense = NO -->
156+
Maintainers will update the managed resources for other systems including Azure,
157+
GCP, Terraform, Helm, GitHub, etc to support namespaced MRs soon.
158+
<!-- vale gitlab.FutureTense = YES -->
159+
{{</hint>}}
160+
161+
{{<hint "tip">}}
162+
Crossplane v2 is backward compatible with v1-style cluster scoped MRs.
163+
164+
<!-- vale gitlab.FutureTense = NO -->
165+
New provider releases will support both namespaced and cluster scoped MRs.
166+
Crossplane v2 considers cluster scoped MRs a legacy feature. Crossplane will
167+
deprecate and remove cluster scoped MRs at a future date.
168+
<!-- vale gitlab.FutureTense = YES -->
169+
{{</hint>}}
170+
171+
## Compose any resource
172+
173+
Crossplane v2 isn't opinionated about using composition together with managed
174+
resources.
175+
176+
You can create a composite resource (XR) that composes any resource, whether
177+
it's a Crossplane MR like an `RDSInstance`, a Kubernetes resource like a
178+
`Deployment`, or a third party custom resource like a
179+
[CloudNativePG](https://cloudnative-pg.io) PostgreSQL `Cluster`.
180+
181+
```mermaid
182+
flowchart LR
183+
user(User)
184+
185+
subgraph ns [my-namespace]
186+
direction LR
187+
xr("App (XR)")
188+
dply("Deployment")
189+
svc("Service")
190+
pg("CloudNativePG Cluster")
191+
end
192+
193+
user --create-->xr
194+
xr compose-dply@--compose--> dply
195+
xr compose-svc@--compose--> svc
196+
xr compose-pg@--compose--> pg
197+
compose-dply@{animate: true}
198+
199+
compose-dply@{animate: true}
200+
compose-svc@{animate: true}
201+
compose-pg@{animate: true}
202+
```
203+
204+
This opens composition to exciting new use cases - for example building custom
205+
app models with Crossplane.
206+
207+
## Backward compatibility
208+
209+
Crossplane v2 makes the following breaking changes:
210+
211+
* It removes native patch and transform composition.
212+
* It removes the `ControllerConfig` type.
213+
* It removes support for external secret stores.
214+
215+
Crossplane deprecated native patch and transform composition in Crossplane
216+
v1.17. It's replaced by composition functions.
217+
218+
Crossplane deprecated the `ControllerConfig` type in v1.11. It's replaced by the
219+
`DeploymentRuntimeConfig` type.
220+
221+
Crossplane added external secret stores in v1.7. External secret stores have
222+
remained in alpha for over two years and are now unmaintained.
223+
224+
{{<hint "important">}}
225+
As long as you're not using these deprecated or alpha features, Crossplane v2 is
226+
backward compatible with Crossplane v1.x.
227+
{{</hint>}}
228+
229+
<!-- vale gitlab.FutureTense = NO -->
230+
Crossplane v2 supports legacy v1-style XRs and MRs. Most users will be able to
231+
upgrade from v1.x to Crossplane v2 without breaking changes.
232+
233+
Existing Compositions will require minor updates to work with Crossplane v2
234+
style XRs. A migration guide will be available closer to the final release of
235+
Crossplane v2.
236+
<!-- vale gitlab.FutureTense = YES -->

0 commit comments

Comments
 (0)