Skip to content

Commit 89f1d47

Browse files
negznegz
authored
Merge pull request #905 from negz/so-fresh
Add "What's new in v2.0?" page
2 parents 045bd0b + ffe6d2c commit 89f1d47

File tree

8 files changed

+258
-3
lines changed

8 files changed

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

‎utils/vale/styles/Crossplane/Spelling.yml

Lines changed: 4 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -17,5 +17,8 @@ ignore:
1717
- Crossplane/provider-words.txt
1818
- Crossplane/allowed-jargon.txt
1919
filters:
20-
- v\d\.\d\d
20+
- v\d # e.g. v1, v2
21+
- v\d\.[x\d]\d? # e.g. v1.1, v2.10, v1.x
22+
- v\dalpha\d # e.g. v1alpha1, v2alpha1
23+
- v\dbeta\d # e.g. v1beta1, v2beta2
2124
- \/.*

‎utils/vale/styles/Crossplane/allowed-jargon.txt

Lines changed: 0 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -99,6 +99,5 @@ TLS
9999
tolerations
100100
UI
101101
VM
102-
v2
103102
webhooks.enabled
104103
YAML

‎utils/vale/styles/Crossplane/brands.txt

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -2,6 +2,7 @@ Algolia
22
ArgoCD
33
Bootstrap
44
CC-BY
5+
CloudNativePG
56
CloudSQL
67
CNCF
78
Commonmark

‎utils/vale/styles/Crossplane/provider-words.txt

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -16,6 +16,7 @@ provider-aws-iam
1616
provider-aws-s3
1717
provider-gcp
1818
provider-helm
19+
provider-kubernetes
1920
Pub/Sub
2021
PubSub
2122
S3

0 commit comments

Comments
 (0)