Skip to content

Commit 029548b

Browse files
negznegz
committed
Move all introductory info to a "What is Crossplane?" page
I found myself unsure where to introduce Crossplane and its components on the landing page and getting started pages. A dedicated page seemed like a better idea. Signed-off-by: Nic Cope <[email protected]>
1 parent 549c338 commit 029548b

File tree

3 files changed

+234
-108
lines changed

3 files changed

+234
-108
lines changed

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

Lines changed: 3 additions & 26 deletions
Original file line numberDiff line numberDiff line change
@@ -8,36 +8,13 @@ cascade:
88
Welcome to the Crossplane documentation. Crossplane is a control plane framework
99
for platform engineering.
1010

11-
Crossplane lets you build control planes to manage your cloud native software.
12-
It lets you design the APIs and abstractions that your users use to interact
13-
with your control planes.
14-
15-
Crossplane has a rich ecosystem of extensions that make building a control plane
16-
faster and easier. It's built on Kubernetes, so it works with all the Kubernetes
17-
tools you already use.
18-
19-
{{< hint "tip" >}}
20-
**A control plane is software that controls other software.**
21-
22-
Control planes are a core cloud native pattern. The major cloud providers are
23-
all built using control planes.
24-
25-
Control planes expose an API. You use the API to tell the control plane what
26-
software it should configure and how - this is your _desired state_.
27-
28-
A control plane can configure any cloud native software. It could deploy an app,
29-
create a load balancer, or create a GitHub repository.
30-
31-
The control plane configures your software, then monitors it throughout its
32-
lifecycle. If your software ever _drifts_ from your desired state, the control
33-
plane automatically corrects the drift.
34-
{{< /hint >}}
35-
36-
3711
# Using the documentation
3812

3913
Crossplane organizes its documentation into the following sections:
4014

15+
* [What is Crossplane?]({{<ref "what-is-crossplane">}}) introduces Crossplane
16+
and explains why you should use it.
17+
4118
* [Get Started]({{<ref "get-started">}}) explains how to install Crossplane and
4219
create a control plane.
4320

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

Lines changed: 0 additions & 82 deletions
Original file line numberDiff line numberDiff line change
@@ -4,85 +4,3 @@ weight: 4
44
description: Get started with Crossplane.
55
---
66

7-
Crossplane has three major components:
8-
9-
* [Composition](#composition)
10-
* [Managed resources](#managed-resources)
11-
* [Package manager](#package-manager)
12-
13-
You can use all the components to build your control plane, or pick only the
14-
ones you need.
15-
16-
# Composition
17-
18-
Composition lets you build custom APIs to control your cloud-native software.
19-
20-
Crossplane extends Kubernetes. You build your custom APIs by using Crossplane to
21-
extend Kubernetes with new custom resources.
22-
23-
To extend Kubernetes without using Crossplane you have to write a Kubernetes
24-
controller. The controller is the software that reacts when a user calls the
25-
custom resource API.
26-
27-
With Crossplane you don't have to write a controller. Instead you configure a
28-
pipeline of functions. The functions tell Crossplane what to do when a user
29-
calls the custom resource API. You can configure the functions using common
30-
languages, including YAML, [KCL](https://www.kcl-lang.io), and
31-
[Python](https://python.org).
32-
33-
You can use composition together with [managed resources](#managed-resources) to
34-
build new custom resource APIs powered by managed resources.
35-
36-
Follow [Get Started with Composition]({{<ref "./get-started-with-composition">}})
37-
to see how composition works.
38-
39-
{{<hint "tip">}}
40-
Not familiar with Kubernetes custom resources and controllers?
41-
42-
Read the Kubernetes documentation on
43-
[custom resources](https://kubernetes.io/docs/concepts/extend-kubernetes/api-extension/custom-resources/)
44-
and [controllers](https://kubernetes.io/docs/concepts/architecture/controller/).
45-
46-
Kubebuilder is a popular project for building Kubernetes controllers. Read the
47-
[Kubebuilder documentation](https://book.kubebuilder.io) to see what's
48-
involved in writing a controller.
49-
{{</hint>}}
50-
51-
# Managed resources
52-
53-
Managed resources (MRs) are ready-made Kubernetes custom resources.
54-
55-
Each MR extends Kubernetes with the ability to manage a new kind of resource.
56-
For example there's an RDS instance MR that extends Kubernetes with the ability
57-
to manage [AWS RDS](https://aws.amazon.com/rds/) instances.
58-
59-
Crossplane has an extensive library of managed resources you can use to manage
60-
almost any cloud provider, or cloud-native software.
61-
62-
You can use managed resources together with [composition](#composition) to build
63-
new custom resource APIs powered by MRs.
64-
65-
Follow [Get Started with Managed Resources]({{<ref "./get-started-with-managed-resources">}})
66-
to see how managed resources work.
67-
68-
{{<hint "note">}}
69-
Only AWS managed resources support the Crossplane v2 preview.
70-
71-
<!-- vale gitlab.FutureTense = NO -->
72-
Maintainers will update the managed resources for other systems including Azure,
73-
GCP, Terraform, Helm, GitHub, etc to support Crossplane v2 soon.
74-
<!-- vale gitlab.FutureTense = YES -->
75-
{{</hint>}}
76-
77-
# Package manager
78-
79-
The Crossplane package manager lets you install new managed resources and
80-
composition functions.
81-
82-
You can also package any part of a control plane's configuration and install it
83-
using the package manager. This allows you to deploy several control planes with
84-
identical capabilities - for example one control planes per region or per
85-
service.
86-
87-
Read about Crossplane packages in [Concepts]({{<ref "../concepts/packages">}})
88-
to learn about the package manager.

‎content/v2.0-preview/what-is-crossplane/_index.md

Lines changed: 231 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,231 @@
1+
---
2+
title: What is Crossplane?
3+
weight: 3
4+
description: Learn what Crossplane is and why you'd use it.
5+
---
6+
7+
Crossplane is a control plane framework for platform engineering.
8+
9+
**Crossplane lets you build control planes to manage your cloud native software.**
10+
It lets you design the APIs and abstractions that your users use to interact
11+
with your control planes.
12+
13+
{{< hint "tip" >}}
14+
**A control plane is software that controls other software.**
15+
16+
Control planes are a core cloud native pattern. The major cloud providers are
17+
all built using control planes.
18+
19+
Control planes expose an API. You use the API to tell the control plane what
20+
software it should configure and how - this is your _desired state_.
21+
22+
A control plane can configure any cloud native software. It could deploy an app,
23+
create a load balancer, or create a GitHub repository.
24+
25+
The control plane configures your software, then monitors it throughout its
26+
lifecycle. If your software ever _drifts_ from your desired state, the control
27+
plane automatically corrects the drift.
28+
{{< /hint >}}
29+
30+
Crossplane has a rich ecosystem of extensions that make building a control plane
31+
faster and easier. It's built on Kubernetes, so it works with all the Kubernetes
32+
tools you already use.
33+
34+
**Crossplane's key value is that it unlocks the benefits of building your own
35+
Kubernetes custom resources without having to write controllers for them.**
36+
37+
{{<hint "note">}}
38+
Not familiar with Kubernetes custom resources and controllers?
39+
40+
Read the Kubernetes documentation on
41+
[custom resources](https://kubernetes.io/docs/concepts/extend-kubernetes/api-extension/custom-resources/)
42+
and [controllers](https://kubernetes.io/docs/concepts/architecture/controller/).
43+
44+
Kubebuilder is a popular project for building Kubernetes controllers. Look at
45+
the [Kubebuilder documentation](https://book.kubebuilder.io) to see what's
46+
involved in writing a controller. {{</hint>}}
47+
48+
# Crossplane components
49+
50+
Crossplane has three major components:
51+
52+
* [Composition](#composition)
53+
* [Managed resources](#managed-resources)
54+
* [Package manager](#package-manager)
55+
56+
You can use all three components to build your control plane, or pick only the
57+
ones you need.
58+
59+
## Composition
60+
61+
Composition lets you build custom APIs to control your cloud native software.
62+
63+
Crossplane extends Kubernetes. You build your custom APIs by using Crossplane to
64+
extend Kubernetes with new custom resources.
65+
66+
**To extend Kubernetes without using Crossplane you need a Kubernetes
67+
controller.** The controller is the software that reacts when a user calls the
68+
custom resource API.
69+
70+
Say you want your control plane to serve an `Application` custom resource API.
71+
When someone creates an `Application`, the control plane should create a
72+
Kubernetes `Deployment` and a `Service`.
73+
74+
**If there's not already a controller that does what you want - and exposes the
75+
API you want - you have to write the controller yourself.**
76+
77+
```mermaid
78+
flowchart TD
79+
user(User)
80+
81+
subgraph control [Control Plane]
82+
api(Application API)
83+
controller(Your Application Controller)
84+
deployment(Deployment API)
85+
service(Service API)
86+
end
87+
88+
user -- create --> api
89+
controller watch@<-- watch --> api
90+
controller -- create --> deployment
91+
controller -- create --> service
92+
93+
watch@{animate: true}
94+
```
95+
96+
**With Crossplane you don't have to write a controller**. Instead you configure
97+
a pipeline of functions. The functions return declarative configuration that
98+
Crossplane should apply.
99+
100+
```mermaid
101+
flowchart TD
102+
user(User)
103+
104+
subgraph control [Control Plane]
105+
api(Application API)
106+
107+
subgraph crossplane [Crossplane Composition]
108+
fn(Python Function)
109+
end
110+
111+
deployment(Deployment API)
112+
service(Service API)
113+
end
114+
115+
user -- create --> api
116+
crossplane watch@<-- watch --> api
117+
crossplane -- create --> deployment
118+
crossplane -- create --> service
119+
120+
watch@{animate: true}
121+
```
122+
123+
{{<hint "important">}}
124+
Composition functions allow you to express declarative configuration in various
125+
languages including YAML, [KCL](https://www.kcl-lang.io), and
126+
[Python](https://python.org).
127+
{{</hint>}}
128+
129+
You can use composition together with [managed resources](#managed-resources) to
130+
build new custom resource APIs powered by managed resources.
131+
132+
Follow [Get Started with Composition]({{<ref "../get-started/get-started-with-composition">}})
133+
to see how composition works.
134+
135+
## Managed resources
136+
137+
Managed resources (MRs) are ready-made Kubernetes custom resources.
138+
139+
Each MR extends Kubernetes with the ability to manage a new system. For example
140+
there's an RDS instance MR that extends Kubernetes with the ability to manage
141+
[AWS RDS](https://aws.amazon.com/rds/) instances.
142+
143+
Crossplane has an extensive library of managed resources you can use to manage
144+
almost any cloud provider, or cloud native software.
145+
146+
**With Crossplane you don't have to write a controller if you want to manage
147+
something outside of your Kubernetes cluster using a custom resource.** There's
148+
already a Crossplane managed resource for that.
149+
150+
```mermaid
151+
flowchart TD
152+
user(User)
153+
154+
subgraph control [Control Plane]
155+
instance(RDS Instance API)
156+
controller(Crossplane MR Controller)
157+
end
158+
159+
subgraph aws [Amazon Web Services]
160+
rds(RDS Instance)
161+
end
162+
163+
user -- create --> instance
164+
controller watch-rds@<-- watch --> instance
165+
controller -- create --> rds
166+
167+
watch-rds@{animate: true}
168+
```
169+
170+
You can use managed resources together with [composition](#composition) to build
171+
new custom resource APIs powered by MRs.
172+
173+
```mermaid
174+
flowchart TD
175+
user(User)
176+
177+
subgraph control [Control Plane]
178+
api(Application API)
179+
180+
subgraph crossplane [Crossplane Composition]
181+
fn(Python Function)
182+
end
183+
184+
deployment(Deployment API)
185+
service(Service API)
186+
instance(RDS Instance API)
187+
188+
controller(Crossplane MR Controller)
189+
end
190+
191+
subgraph aws [Amazon Web Services]
192+
rds(RDS Instance)
193+
end
194+
195+
user -- create --> api
196+
crossplane watch-apps@<-- watch --> api
197+
crossplane -- create --> deployment
198+
crossplane -- create --> service
199+
crossplane -- create --> instance
200+
201+
controller watch-rds@<-- watch --> instance
202+
controller -- create --> rds
203+
204+
watch-apps@{animate: true}
205+
watch-rds@{animate: true}
206+
```
207+
208+
Follow [Get Started with Managed Resources]({{<ref "../get-started/get-started-with-managed-resources">}})
209+
to see how managed resources work.
210+
211+
{{<hint "note">}}
212+
Only AWS managed resources support the Crossplane v2 preview.
213+
214+
<!-- vale gitlab.FutureTense = NO -->
215+
Maintainers will update the managed resources for other systems including Azure,
216+
GCP, Terraform, Helm, GitHub, etc to support Crossplane v2 soon.
217+
<!-- vale gitlab.FutureTense = YES -->
218+
{{</hint>}}
219+
220+
## Package manager
221+
222+
The Crossplane package manager lets you install new managed resources and
223+
composition functions.
224+
225+
You can also package any part of a control plane's configuration and install it
226+
using the package manager. This allows you to deploy several control planes with
227+
identical capabilities - for example one control planes per region or per
228+
service.
229+
230+
Read about Crossplane packages in [Concepts]({{<ref "../concepts/packages">}})
231+
to learn about the package manager.

0 commit comments

Comments
 (0)