Skip to content

Commit 85c6313

Browse files
negznegz
committed
Merge "introduction" into the get started landing page
Signed-off-by: Nic Cope <[email protected]>
1 parent 6590826 commit 85c6313

File tree

3 files changed

+331
-335
lines changed

3 files changed

+331
-335
lines changed

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

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -43,7 +43,7 @@ plane** to check, report and act on any resource, anywhere.
4343
# Get started
4444
* [Install Crossplane]({{<ref "get-started/install">}}) in your Kubernetes cluster
4545
* Learn more about how Crossplane works in the
46-
[Crossplane introduction]({{<ref "get-started/introduction" >}})
46+
[Crossplane introduction]({{<ref "get-started" >}})
4747
* Join the [Crossplane Slack](https://slack.crossplane.io/) and start a
4848
conversation with a community of over 7,000 operators.
4949

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

Lines changed: 330 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -3,3 +3,333 @@ title: Get Started
33
weight: 4
44
description: Get started with Crossplane.
55
---
6+
7+
Crossplane connects your Kubernetes cluster to external,
8+
non-Kubernetes resources, and allows platform teams to build custom Kubernetes
9+
APIs to consume those resources.
10+
11+
<!-- vale gitlab.SentenceLength = NO -->
12+
Crossplane creates Kubernetes
13+
[Custom Resource Definitions](https://kubernetes.io/docs/tasks/extend-kubernetes/custom-resources/custom-resource-definitions/)
14+
(`CRDs`) to represent the external resources as native
15+
[Kubernetes objects](https://kubernetes.io/docs/concepts/overview/working-with-objects/kubernetes-objects/).
16+
As native Kubernetes objects, you can use standard commands like `kubectl create`
17+
and `kubectl describe`. The full
18+
[Kubernetes API](https://kubernetes.io/docs/reference/using-api/) is available
19+
for every Crossplane resource.
20+
<!-- vale gitlab.SentenceLength = YES -->
21+
22+
Crossplane also acts as a
23+
[Kubernetes Controller](https://kubernetes.io/docs/concepts/architecture/controller/)
24+
to watch the state of the external resources and provide state enforcement. If
25+
something modifies or deletes a resource outside of Kubernetes, Crossplane reverses
26+
the change or recreates the deleted resource.
27+
28+
{{<img src="/media/crossplane-intro-diagram.png" alt="Diagram showing a user communicating to Kubernetes. Crossplane connected to Kubernetes and Crossplane communicating with AWS, Azure and GCP" align="center">}}
29+
With Crossplane installed in a Kubernetes cluster, users only communicate with
30+
Kubernetes. Crossplane manages the communication to external resources like AWS,
31+
Azure or Google Cloud.
32+
33+
Crossplane also allows the creation of custom Kubernetes APIs. Platform teams can
34+
combine external resources and simplify or customize the APIs presented to the
35+
platform consumers.
36+
37+
## Crossplane components overview
38+
This table provides a summary of Crossplane components and their roles.
39+
40+
{{< table "table table-hover table-sm">}}
41+
| Component | Abbreviation | Scope | Summary |
42+
| --- | --- | --- | ---- |
43+
| [Provider]({{<ref "#providers">}}) | | cluster | Creates new Kubernetes Custom Resource Definitions for an external service. |
44+
| [ProviderConfig]({{<ref "#provider-configurations">}}) | `PC` | cluster | Applies settings for a _Provider_. |
45+
| [Managed Resource]({{<ref "#managed-resources">}}) | `MR` | cluster | A Provider resource created and managed by Crossplane inside the Kubernetes cluster. |
46+
| [Composition]({{<ref "#compositions">}}) | | cluster | A template for creating multiple _managed resources_ at once. |
47+
| [Composite Resources]({{<ref "#composite-resources" >}}) | `XR` | cluster | Uses a _Composition_ template to create multiple _managed resources_ as a single Kubernetes object. |
48+
| [CompositeResourceDefinitions]({{<ref "#composite-resource-definitions" >}}) | `XRD` | cluster | Defines the API schema for _Composite Resources_ |
49+
{{< /table >}}
50+
51+
## The Crossplane Pod
52+
When installed in a Kubernetes cluster Crossplane creates an initial set of
53+
Custom Resource Definitions (`CRDs`) of the core Crossplane components.
54+
55+
{{< expand "View the initial Crossplane CRDs" >}}
56+
After installing Crossplane use `kubectl get crds` to view the Crossplane
57+
installed CRDs.
58+
59+
```shell
60+
❯ kubectl get crd
61+
NAME
62+
compositeresourcedefinitions.apiextensions.crossplane.io
63+
compositionrevisions.apiextensions.crossplane.io
64+
compositions.apiextensions.crossplane.io
65+
configurationrevisions.pkg.crossplane.io
66+
configurations.pkg.crossplane.io
67+
deploymentruntimeconfigs.pkg.crossplane.io
68+
environmentconfigs.apiextensions.crossplane.io
69+
functionrevisions.pkg.crossplane.io
70+
functions.pkg.crossplane.io
71+
locks.pkg.crossplane.io
72+
providerrevisions.pkg.crossplane.io
73+
providers.pkg.crossplane.io
74+
storeconfigs.secrets.crossplane.io
75+
usages.apiextensions.crossplane.io
76+
```
77+
{{< /expand >}}
78+
79+
The following sections describe the functions of some of these CRDs.
80+
81+
<!-- vale Google.Headings = NO -->
82+
<!-- allow "Providers" -->
83+
## Providers
84+
<!-- vale Google.Headings = YES -->
85+
A Crossplane _Provider_ creates a second set of CRDs that define how Crossplane
86+
connects to a non-Kubernetes service. Each external service relies on its own
87+
Provider. For example,
88+
[AWS](https://github.com/crossplane-contrib/provider-upjet-aws),
89+
[Azure](https://github.com/crossplane-contrib/provider-upjet-azure)
90+
and [GCP](https://github.com/crossplane-contrib/provider-upjet-gcp)
91+
are different providers for each cloud service.
92+
93+
{{< hint "tip" >}}
94+
Most Providers are for cloud services but Crossplane can use a Provider to
95+
connect to any service with an API.
96+
{{< /hint >}}
97+
98+
For example, an AWS Provider defines Kubernetes CRDs for AWS resources like EC2
99+
compute instances or S3 storage buckets.
100+
101+
The Provider defines the Kubernetes API definition for the external resource.
102+
For example,
103+
[provider-upjet-aws](https://github.com/crossplane-contrib/provider-upjet-aws)
104+
defines a
105+
[`bucket`](https://github.com/crossplane-contrib/provider-upjet-aws/blob/release-1.20/package/crds/s3.aws.upbound.io_buckets.yaml)
106+
resource for creating and managing AWS S3 storage buckets.
107+
108+
In the `bucket` CRD is a
109+
[`spec.forProvider.region`](https://github.com/crossplane-contrib/provider-upjet-aws/blob/release-1.20/package/crds/s3.aws.upbound.io_buckets.yaml#L91)
110+
value that defines which AWS region to deploy the bucket in.
111+
112+
Crossplane's [public package registries](https://www.crossplane.io/registries) contain a large
113+
collection of Crossplane Providers.
114+
115+
More providers are available in the [Crossplane Contrib repository](https://github.com/crossplane-contrib/).
116+
117+
Providers are cluster scoped and available to all cluster namespaces.
118+
119+
View all installed Providers with the command `kubectl get providers`.
120+
121+
## Provider configurations
122+
Providers have _ProviderConfigs_. _ProviderConfigs_ configure settings
123+
related to the Provider like authentication or global defaults for the
124+
Provider.
125+
126+
The API endpoints for ProviderConfigs are unique to each Provider.
127+
128+
_ProviderConfigs_ are cluster scoped and available to all cluster namespaces.
129+
130+
View all installed ProviderConfigs with the command `kubectl get providerconfig`.
131+
132+
## Managed resources
133+
A Provider's CRDs map to individual _resources_ inside the provider. When
134+
Crossplane creates and monitors a resource it's a _Managed Resource_.
135+
136+
Using a Provider's CRD creates a unique _Managed Resource_. For example,
137+
using the Provider AWS's `bucket` CRD, Crossplane creates a `bucket` _Managed Resource_
138+
inside the Kubernetes cluster that's connected to an AWS S3 storage bucket.
139+
140+
The Crossplane controller provides state enforcement for _Managed Resources_.
141+
Crossplane enforces the settings and existence of _Managed Resources_. This
142+
"Controller Pattern" is like how the Kubernetes
143+
[kube-controller-manager](https://kubernetes.io/docs/reference/command-line-tools-reference/kube-controller-manager/)
144+
enforces state for pods.
145+
146+
_Managed Resources_ are cluster scoped and available to all cluster namespaces.
147+
148+
Use `kubectl get managed` to view all _managed resources_.
149+
{{<hint "warning" >}}
150+
The `kubectl get managed` creates a lot of Kubernetes API queries.
151+
Both the `kubectl` client and kube-apiserver throttle the API queries.
152+
153+
Depending on the size of the API server and number of managed resources, this
154+
command may take minutes to return or may timeout.
155+
156+
For more information, read
157+
[Kubernetes issue #111880](https://github.com/kubernetes/kubernetes/issues/111880)
158+
and
159+
[Crossplane issue #3459](https://github.com/crossplane/crossplane/issues/3459).
160+
{{< /hint >}}
161+
162+
## Compositions
163+
164+
A _Composition_ is a template for a collection of _managed resource_. _Compositions_
165+
allow platform teams to define a set of _managed resources_ as a
166+
single object.
167+
168+
For example, a compute _managed resource_ may require the creation of a storage
169+
resource and a virtual network as well. A single _Composition_ can define all three
170+
resources in a single _Composition_ object.
171+
172+
Using _Compositions_ simplifies the deployment of infrastructure made up of
173+
multiple _managed resources_. _Compositions_ also enforce standards and settings
174+
across deployments.
175+
176+
Platform teams can define fixed or default settings for each _managed resource_ inside a
177+
_Composition_ or define fields and settings that users may change.
178+
179+
Using the previous example, the platform team may set a compute resource size
180+
and virtual network settings. But the platform team allows users to define the
181+
storage resource size.
182+
183+
Creating a _Composition_ Crossplane doesn't create any managed
184+
resources. The _Composition_ is only a template for a collection of _managed
185+
resources_ and their settings. A _Composite Resource_ creates the specific resources.
186+
187+
{{< hint "note" >}}
188+
The [_Composite Resources_]({{<ref "#composite-resources">}}) section discusses
189+
_Composite Resources_.
190+
{{< /hint >}}
191+
192+
_Compositions_ are cluster scoped and available to all cluster namespaces.
193+
194+
Use `kubectl get compositions` to view all _compositions_.
195+
196+
197+
## Composite Resources
198+
199+
A _Composite Resource_ (`XR`) is a set of provisioned _managed resources_. A
200+
_Composite Resource_ uses the template defined by a _Composition_ and applies
201+
any user defined settings.
202+
203+
Multiple unique _Composite Resource_ objects can use the same _Composition_. For
204+
example, a _Composition_ template can create a compute, storage and networking
205+
set of _managed resources_. Crossplane uses the same _Composition_ template
206+
every time a user requests this set of resources.
207+
208+
If a _Composition_ allows a user to define resource settings, users apply them
209+
in a _Composite Resource_.
210+
211+
{{< hint "tip" >}}
212+
_Compositions_ are templates for a set of _managed resources_.
213+
_Composite Resources_ fill out the template and create _managed resources_.
214+
215+
Deleting a _Composite Resource_ deletes all the _managed resources_ it created.
216+
{{< /hint >}}
217+
218+
_Composite Resources_ are cluster scoped and available to all cluster namespaces.
219+
220+
Use `kubectl get composite` to view all _Composite Resources_.
221+
222+
## Composite Resource Definitions
223+
_Composite Resource Definitions_ (`XRDs`) create custom Kubernetes APIs used by
224+
_Composite Resources_.
225+
226+
Platform teams define the custom APIs.
227+
These APIs can define specific values
228+
like storage space in gigabytes, generic settings like `small` or `large`,
229+
deployment options like `cloud` or `onprem`. Crossplane doesn't limit the API definitions.
230+
231+
The _Composite Resource Definition's_ `kind` is from Crossplane.
232+
```yaml
233+
apiVersion: apiextensions.crossplane.io/v1
234+
kind: CompositeResourceDefinition
235+
```
236+
237+
The `spec` of a _Composite Resource Definition_ creates the `apiVersion`,
238+
`kind` and `spec` of a _Composite Resource_.
239+
240+
{{< hint "tip" >}}
241+
The _Composite Resource Definition_ defines the parameters for a _Composite
242+
Resource_.
243+
{{< /hint >}}
244+
245+
A _Composite Resource Definition_ has four main `spec` parameters:
246+
* A {{<hover label="specGroup" line="3" >}}group{{< /hover >}}
247+
to define the
248+
{{< hover label="xr2" line="2" >}}apiVersion{{</hover >}}
249+
in a _Composite Resource_ .
250+
* The {{< hover label="specGroup" line="7" >}}versions.name{{</hover >}}
251+
that defines the version used in a _Composite Resource_.
252+
* A {{< hover label="specGroup" line="5" >}}names.kind{{</hover >}}
253+
to define the _Composite Resource_
254+
{{< hover label="xr2" line="3" >}}kind{{</hover>}}.
255+
* A {{< hover label="specGroup" line="8" >}}versions.schema{{</hover>}} section
256+
to define the _Composite Resource_ {{<hover label="xr2" line="6" >}}spec{{</hover >}}.
257+
258+
```yaml {label="specGroup"}
259+
# Composite Resource Definition (XRD)
260+
spec:
261+
group: test.example.org
262+
names:
263+
kind: MyComputeResource
264+
versions:
265+
- name: v1alpha1
266+
schema:
267+
# Removed for brevity
268+
```
269+
270+
A _Composite Resource_ based on this _Composite Resource Definition_ looks like this:
271+
272+
```yaml {label="xr2"}
273+
# Composite Resource (XR)
274+
apiVersion: test.example.org/v1alpha1
275+
kind: MyComputeResource
276+
metadata:
277+
name: my-resource
278+
spec:
279+
storage: "large"
280+
```
281+
282+
A _Composite Resource Definition_ {{< hover label="specGroup" line="8" >}}schema{{</hover >}} defines the _Composite Resource_
283+
{{<hover label="xr2" line="6" >}}spec{{</hover >}} parameters.
284+
285+
These parameters are the new, custom APIs, that developers can use.
286+
287+
For example, creating a compute _managed resource_ requires knowledge of a
288+
cloud provider's compute class names like AWS's `m6in.large` or GCP's
289+
`e2-standard-2`.
290+
291+
A _Composite Resource Definition_ can limit the choices to `small` or `large`.
292+
A _Composite Resource_ uses those options and the _Composition_ maps them
293+
to specific cloud provider settings.
294+
295+
The following _Composite Resource Definition_ defines a {{<hover label="specVersions" line="17" >}}storage{{< /hover >}}
296+
parameter. The storage is a
297+
{{<hover label="specVersions" line="18">}}string{{< /hover >}}
298+
and the OpenAPI
299+
{{<hover label="specVersions" line="19" >}}oneOf{{< /hover >}} requires the
300+
options to be either {{<hover label="specVersions" line="20" >}}small{{< /hover >}}
301+
or {{<hover label="specVersions" line="21" >}}large{{< /hover >}}.
302+
303+
```yaml {label="specVersions"}
304+
# Composite Resource Definition (XRD)
305+
spec:
306+
group: test.example.org
307+
names:
308+
kind: MyComputeResource
309+
versions:
310+
- name: v1alpha1
311+
served: true
312+
referenceable: true
313+
schema:
314+
openAPIV3Schema:
315+
type: object
316+
properties:
317+
spec:
318+
type: object
319+
properties:
320+
storage:
321+
type: string
322+
oneOf:
323+
- pattern: '^small$'
324+
- pattern: '^large$'
325+
required:
326+
- storage
327+
```
328+
329+
A _Composite Resource Definition_ can define a wide variety of settings and options.
330+
331+
Creating a _Composite Resource Definition_ enables the creation of _Composite
332+
Resources_.
333+
334+
## Next steps
335+
Build your own Crossplane platform using one of the quickstart guides.

0 commit comments

Comments
 (0)