mirror of https://github.com/crossplane/docs.git
Merge pull request #897 from negz/intro
[v2] Add a "What's Crossplane?" page
This commit is contained in:
Nic Cope
GitHub
commit
9adb066cf2
|
|
@ -1,51 +1,30 @@
|
||||||
---
|
---
|
||||||
title: "Overview"
|
title: "Welcome"
|
||||||
weight: -1
|
weight: -1
|
||||||
cascade:
|
cascade:
|
||||||
version: "2.0-preview"
|
version: "2.0-preview"
|
||||||
---
|
---
|
||||||
|
|
||||||
{{< img src="/media/banner.png" alt="Crossplane Popsicle Truck" size="large" >}}
|
Welcome to the Crossplane documentation. Crossplane is a control plane framework
|
||||||
|
for platform engineering.
|
||||||
|
|
||||||
<br />
|
# Using the documentation
|
||||||
|
|
||||||
Crossplane is an open source Kubernetes extension that transforms your Kubernetes
|
Crossplane organizes its documentation into the following sections:
|
||||||
cluster into a **universal control plane**.
|
|
||||||
|
|
||||||
Crossplane lets you manage anything, anywhere, all through standard Kubernetes
|
* [What's Crossplane?]({{<ref "whats-crossplane">}}) introduces Crossplane
|
||||||
APIs. Crossplane can even let you
|
and explains why you should use it.
|
||||||
[order a pizza](https://blog.crossplane.io/providers-101-ordering-pizza-with-kubernetes-and-crossplane/)
|
|
||||||
directly from Kubernetes. If it has an API, Crossplane can connect to it.
|
|
||||||
|
|
||||||
With Crossplane, platform teams can create new abstractions and custom
|
* [Get Started]({{<ref "get-started">}}) explains how to install Crossplane and
|
||||||
APIs with the full power of Kubernetes policies, namespaces, role based access
|
create a control plane.
|
||||||
controls and more. Crossplane brings all your non-Kubernetes resources under
|
|
||||||
one roof.
|
|
||||||
|
|
||||||
Custom APIs, created by platform teams, allow security and compliance
|
* [Concepts]({{<ref "concepts">}}) introduces Crossplane's key concepts.
|
||||||
enforcement across resources or clouds, without exposing any complexity to the
|
|
||||||
developers. A single API call can create multiple resources, in multiple clouds
|
|
||||||
and use Kubernetes as the control plane for everything.
|
|
||||||
|
|
||||||
{{< hint "tip" >}}
|
* [Guides]({{<ref "guides">}}) guide you through common use cases, like
|
||||||
**What's a control plane?**
|
monitoring Crossplane or extending it by writing a composition function.
|
||||||
<!-- vale Google.WordList = NO -->
|
|
||||||
Control planes create and manage the lifecycle of resources. Control planes
|
|
||||||
constantly _check_ that the intended resources exist, _report_ when the intended
|
|
||||||
state doesn't match reality and _act_ to make things right.
|
|
||||||
|
|
||||||
Crossplane extends the Kubernetes control plane to be a **universal control
|
* [CLI Reference]({{<ref "cli">}}) documents the `crossplane` command-line
|
||||||
plane** to check, report and act on any resource, anywhere.
|
interface that you can use to configure a Crossplane control plane.
|
||||||
<!-- vale Google.WordList = YES -->
|
|
||||||
{{< /hint >}}
|
|
||||||
|
|
||||||
|
* [API Reference]({{<ref "api">}}) documents the APIs that you can use to
|
||||||
# Get started
|
configure a Crossplane control plane.
|
||||||
* [Install Crossplane]({{<ref "get-started/install">}}) in your Kubernetes cluster
|
|
||||||
* Learn more about how Crossplane works in the
|
|
||||||
[Crossplane introduction]({{<ref "get-started" >}})
|
|
||||||
* Join the [Crossplane Slack](https://slack.crossplane.io/) and start a
|
|
||||||
conversation with a community of over 7,000 operators.
|
|
||||||
|
|
||||||
|
|
||||||
Crossplane is a [Cloud Native Compute Foundation](https://www.cncf.io/) project.
|
|
||||||
|
|
|
||||||
|
|
@ -4,332 +4,3 @@ weight: 4
|
||||||
description: Get started with Crossplane.
|
description: Get started with Crossplane.
|
||||||
---
|
---
|
||||||
|
|
||||||
Crossplane connects your Kubernetes cluster to external,
|
|
||||||
non-Kubernetes resources, and allows platform teams to build custom Kubernetes
|
|
||||||
APIs to consume those resources.
|
|
||||||
|
|
||||||
<!-- vale gitlab.SentenceLength = NO -->
|
|
||||||
Crossplane creates Kubernetes
|
|
||||||
[Custom Resource Definitions](https://kubernetes.io/docs/tasks/extend-kubernetes/custom-resources/custom-resource-definitions/)
|
|
||||||
(`CRDs`) to represent the external resources as native
|
|
||||||
[Kubernetes objects](https://kubernetes.io/docs/concepts/overview/working-with-objects/kubernetes-objects/).
|
|
||||||
As native Kubernetes objects, you can use standard commands like `kubectl create`
|
|
||||||
and `kubectl describe`. The full
|
|
||||||
[Kubernetes API](https://kubernetes.io/docs/reference/using-api/) is available
|
|
||||||
for every Crossplane resource.
|
|
||||||
<!-- vale gitlab.SentenceLength = YES -->
|
|
||||||
|
|
||||||
Crossplane also acts as a
|
|
||||||
[Kubernetes Controller](https://kubernetes.io/docs/concepts/architecture/controller/)
|
|
||||||
to watch the state of the external resources and provide state enforcement. If
|
|
||||||
something modifies or deletes a resource outside of Kubernetes, Crossplane reverses
|
|
||||||
the change or recreates the deleted resource.
|
|
||||||
|
|
||||||
{{<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">}}
|
|
||||||
With Crossplane installed in a Kubernetes cluster, users only communicate with
|
|
||||||
Kubernetes. Crossplane manages the communication to external resources like AWS,
|
|
||||||
Azure or Google Cloud.
|
|
||||||
|
|
||||||
Crossplane also allows the creation of custom Kubernetes APIs. Platform teams can
|
|
||||||
combine external resources and simplify or customize the APIs presented to the
|
|
||||||
platform consumers.
|
|
||||||
|
|
||||||
## Crossplane components overview
|
|
||||||
This table provides a summary of Crossplane components and their roles.
|
|
||||||
|
|
||||||
{{< table "table table-hover table-sm">}}
|
|
||||||
| Component | Abbreviation | Scope | Summary |
|
|
||||||
| --- | --- | --- | ---- |
|
|
||||||
| [Provider]({{<ref "#providers">}}) | | cluster | Creates new Kubernetes Custom Resource Definitions for an external service. |
|
|
||||||
| [ProviderConfig]({{<ref "#provider-configurations">}}) | `PC` | cluster | Applies settings for a _Provider_. |
|
|
||||||
| [Managed Resource]({{<ref "#managed-resources">}}) | `MR` | cluster | A Provider resource created and managed by Crossplane inside the Kubernetes cluster. |
|
|
||||||
| [Composition]({{<ref "#compositions">}}) | | cluster | A template for creating multiple _managed resources_ at once. |
|
|
||||||
| [Composite Resources]({{<ref "#composite-resources" >}}) | `XR` | cluster | Uses a _Composition_ template to create multiple _managed resources_ as a single Kubernetes object. |
|
|
||||||
| [CompositeResourceDefinitions]({{<ref "#composite-resource-definitions" >}}) | `XRD` | cluster | Defines the API schema for _Composite Resources_ |
|
|
||||||
{{< /table >}}
|
|
||||||
|
|
||||||
## The Crossplane Pod
|
|
||||||
When installed in a Kubernetes cluster Crossplane creates an initial set of
|
|
||||||
Custom Resource Definitions (`CRDs`) of the core Crossplane components.
|
|
||||||
|
|
||||||
{{< expand "View the initial Crossplane CRDs" >}}
|
|
||||||
After installing Crossplane use `kubectl get crds` to view the Crossplane
|
|
||||||
installed CRDs.
|
|
||||||
|
|
||||||
```shell
|
|
||||||
❯ kubectl get crd
|
|
||||||
NAME
|
|
||||||
compositeresourcedefinitions.apiextensions.crossplane.io
|
|
||||||
compositionrevisions.apiextensions.crossplane.io
|
|
||||||
compositions.apiextensions.crossplane.io
|
|
||||||
configurationrevisions.pkg.crossplane.io
|
|
||||||
configurations.pkg.crossplane.io
|
|
||||||
deploymentruntimeconfigs.pkg.crossplane.io
|
|
||||||
environmentconfigs.apiextensions.crossplane.io
|
|
||||||
functionrevisions.pkg.crossplane.io
|
|
||||||
functions.pkg.crossplane.io
|
|
||||||
locks.pkg.crossplane.io
|
|
||||||
providerrevisions.pkg.crossplane.io
|
|
||||||
providers.pkg.crossplane.io
|
|
||||||
storeconfigs.secrets.crossplane.io
|
|
||||||
usages.apiextensions.crossplane.io
|
|
||||||
```
|
|
||||||
{{< /expand >}}
|
|
||||||
|
|
||||||
The following sections describe the functions of some of these CRDs.
|
|
||||||
|
|
||||||
<!-- vale Google.Headings = NO -->
|
|
||||||
<!-- allow "Providers" -->
|
|
||||||
## Providers
|
|
||||||
<!-- vale Google.Headings = YES -->
|
|
||||||
A Crossplane _Provider_ creates a second set of CRDs that define how Crossplane
|
|
||||||
connects to a non-Kubernetes service. Each external service relies on its own
|
|
||||||
Provider. For example,
|
|
||||||
[AWS](https://github.com/crossplane-contrib/provider-upjet-aws),
|
|
||||||
[Azure](https://github.com/crossplane-contrib/provider-upjet-azure)
|
|
||||||
and [GCP](https://github.com/crossplane-contrib/provider-upjet-gcp)
|
|
||||||
are different providers for each cloud service.
|
|
||||||
|
|
||||||
{{< hint "tip" >}}
|
|
||||||
Most Providers are for cloud services but Crossplane can use a Provider to
|
|
||||||
connect to any service with an API.
|
|
||||||
{{< /hint >}}
|
|
||||||
|
|
||||||
For example, an AWS Provider defines Kubernetes CRDs for AWS resources like EC2
|
|
||||||
compute instances or S3 storage buckets.
|
|
||||||
|
|
||||||
The Provider defines the Kubernetes API definition for the external resource.
|
|
||||||
For example,
|
|
||||||
[provider-upjet-aws](https://github.com/crossplane-contrib/provider-upjet-aws)
|
|
||||||
defines a
|
|
||||||
[`bucket`](https://github.com/crossplane-contrib/provider-upjet-aws/blob/release-1.20/package/crds/s3.aws.upbound.io_buckets.yaml)
|
|
||||||
resource for creating and managing AWS S3 storage buckets.
|
|
||||||
|
|
||||||
In the `bucket` CRD is a
|
|
||||||
[`spec.forProvider.region`](https://github.com/crossplane-contrib/provider-upjet-aws/blob/release-1.20/package/crds/s3.aws.upbound.io_buckets.yaml#L91)
|
|
||||||
value that defines which AWS region to deploy the bucket in.
|
|
||||||
|
|
||||||
Crossplane's [public package registries](https://www.crossplane.io/registries) contain a large
|
|
||||||
collection of Crossplane Providers.
|
|
||||||
|
|
||||||
More providers are available in the [Crossplane Contrib repository](https://github.com/crossplane-contrib/).
|
|
||||||
|
|
||||||
Providers are cluster scoped and available to all cluster namespaces.
|
|
||||||
|
|
||||||
View all installed Providers with the command `kubectl get providers`.
|
|
||||||
|
|
||||||
## Provider configurations
|
|
||||||
Providers have _ProviderConfigs_. _ProviderConfigs_ configure settings
|
|
||||||
related to the Provider like authentication or global defaults for the
|
|
||||||
Provider.
|
|
||||||
|
|
||||||
The API endpoints for ProviderConfigs are unique to each Provider.
|
|
||||||
|
|
||||||
_ProviderConfigs_ are cluster scoped and available to all cluster namespaces.
|
|
||||||
|
|
||||||
View all installed ProviderConfigs with the command `kubectl get providerconfig`.
|
|
||||||
|
|
||||||
## Managed resources
|
|
||||||
A Provider's CRDs map to individual _resources_ inside the provider. When
|
|
||||||
Crossplane creates and monitors a resource it's a _Managed Resource_.
|
|
||||||
|
|
||||||
Using a Provider's CRD creates a unique _Managed Resource_. For example,
|
|
||||||
using the Provider AWS's `bucket` CRD, Crossplane creates a `bucket` _Managed Resource_
|
|
||||||
inside the Kubernetes cluster that's connected to an AWS S3 storage bucket.
|
|
||||||
|
|
||||||
The Crossplane controller provides state enforcement for _Managed Resources_.
|
|
||||||
Crossplane enforces the settings and existence of _Managed Resources_. This
|
|
||||||
"Controller Pattern" is like how the Kubernetes
|
|
||||||
[kube-controller-manager](https://kubernetes.io/docs/reference/command-line-tools-reference/kube-controller-manager/)
|
|
||||||
enforces state for pods.
|
|
||||||
|
|
||||||
_Managed Resources_ are cluster scoped and available to all cluster namespaces.
|
|
||||||
|
|
||||||
Use `kubectl get managed` to view all _managed resources_.
|
|
||||||
{{<hint "warning" >}}
|
|
||||||
The `kubectl get managed` creates a lot of Kubernetes API queries.
|
|
||||||
Both the `kubectl` client and kube-apiserver throttle the API queries.
|
|
||||||
|
|
||||||
Depending on the size of the API server and number of managed resources, this
|
|
||||||
command may take minutes to return or may timeout.
|
|
||||||
|
|
||||||
For more information, read
|
|
||||||
[Kubernetes issue #111880](https://github.com/kubernetes/kubernetes/issues/111880)
|
|
||||||
and
|
|
||||||
[Crossplane issue #3459](https://github.com/crossplane/crossplane/issues/3459).
|
|
||||||
{{< /hint >}}
|
|
||||||
|
|
||||||
## Compositions
|
|
||||||
|
|
||||||
A _Composition_ is a template for a collection of _managed resource_. _Compositions_
|
|
||||||
allow platform teams to define a set of _managed resources_ as a
|
|
||||||
single object.
|
|
||||||
|
|
||||||
For example, a compute _managed resource_ may require the creation of a storage
|
|
||||||
resource and a virtual network as well. A single _Composition_ can define all three
|
|
||||||
resources in a single _Composition_ object.
|
|
||||||
|
|
||||||
Using _Compositions_ simplifies the deployment of infrastructure made up of
|
|
||||||
multiple _managed resources_. _Compositions_ also enforce standards and settings
|
|
||||||
across deployments.
|
|
||||||
|
|
||||||
Platform teams can define fixed or default settings for each _managed resource_ inside a
|
|
||||||
_Composition_ or define fields and settings that users may change.
|
|
||||||
|
|
||||||
Using the previous example, the platform team may set a compute resource size
|
|
||||||
and virtual network settings. But the platform team allows users to define the
|
|
||||||
storage resource size.
|
|
||||||
|
|
||||||
Creating a _Composition_ Crossplane doesn't create any managed
|
|
||||||
resources. The _Composition_ is only a template for a collection of _managed
|
|
||||||
resources_ and their settings. A _Composite Resource_ creates the specific resources.
|
|
||||||
|
|
||||||
{{< hint "note" >}}
|
|
||||||
The [_Composite Resources_]({{<ref "#composite-resources">}}) section discusses
|
|
||||||
_Composite Resources_.
|
|
||||||
{{< /hint >}}
|
|
||||||
|
|
||||||
_Compositions_ are cluster scoped and available to all cluster namespaces.
|
|
||||||
|
|
||||||
Use `kubectl get compositions` to view all _compositions_.
|
|
||||||
|
|
||||||
|
|
||||||
## Composite Resources
|
|
||||||
|
|
||||||
A _Composite Resource_ (`XR`) is a set of provisioned _managed resources_. A
|
|
||||||
_Composite Resource_ uses the template defined by a _Composition_ and applies
|
|
||||||
any user defined settings.
|
|
||||||
|
|
||||||
Multiple unique _Composite Resource_ objects can use the same _Composition_. For
|
|
||||||
example, a _Composition_ template can create a compute, storage and networking
|
|
||||||
set of _managed resources_. Crossplane uses the same _Composition_ template
|
|
||||||
every time a user requests this set of resources.
|
|
||||||
|
|
||||||
If a _Composition_ allows a user to define resource settings, users apply them
|
|
||||||
in a _Composite Resource_.
|
|
||||||
|
|
||||||
{{< hint "tip" >}}
|
|
||||||
_Compositions_ are templates for a set of _managed resources_.
|
|
||||||
_Composite Resources_ fill out the template and create _managed resources_.
|
|
||||||
|
|
||||||
Deleting a _Composite Resource_ deletes all the _managed resources_ it created.
|
|
||||||
{{< /hint >}}
|
|
||||||
|
|
||||||
_Composite Resources_ are cluster scoped and available to all cluster namespaces.
|
|
||||||
|
|
||||||
Use `kubectl get composite` to view all _Composite Resources_.
|
|
||||||
|
|
||||||
## Composite Resource Definitions
|
|
||||||
_Composite Resource Definitions_ (`XRDs`) create custom Kubernetes APIs used by
|
|
||||||
_Composite Resources_.
|
|
||||||
|
|
||||||
Platform teams define the custom APIs.
|
|
||||||
These APIs can define specific values
|
|
||||||
like storage space in gigabytes, generic settings like `small` or `large`,
|
|
||||||
deployment options like `cloud` or `onprem`. Crossplane doesn't limit the API definitions.
|
|
||||||
|
|
||||||
The _Composite Resource Definition's_ `kind` is from Crossplane.
|
|
||||||
```yaml
|
|
||||||
apiVersion: apiextensions.crossplane.io/v1
|
|
||||||
kind: CompositeResourceDefinition
|
|
||||||
```
|
|
||||||
|
|
||||||
The `spec` of a _Composite Resource Definition_ creates the `apiVersion`,
|
|
||||||
`kind` and `spec` of a _Composite Resource_.
|
|
||||||
|
|
||||||
{{< hint "tip" >}}
|
|
||||||
The _Composite Resource Definition_ defines the parameters for a _Composite
|
|
||||||
Resource_.
|
|
||||||
{{< /hint >}}
|
|
||||||
|
|
||||||
A _Composite Resource Definition_ has four main `spec` parameters:
|
|
||||||
* A {{<hover label="specGroup" line="3" >}}group{{< /hover >}}
|
|
||||||
to define the
|
|
||||||
{{< hover label="xr2" line="2" >}}apiVersion{{</hover >}}
|
|
||||||
in a _Composite Resource_ .
|
|
||||||
* The {{< hover label="specGroup" line="7" >}}versions.name{{</hover >}}
|
|
||||||
that defines the version used in a _Composite Resource_.
|
|
||||||
* A {{< hover label="specGroup" line="5" >}}names.kind{{</hover >}}
|
|
||||||
to define the _Composite Resource_
|
|
||||||
{{< hover label="xr2" line="3" >}}kind{{</hover>}}.
|
|
||||||
* A {{< hover label="specGroup" line="8" >}}versions.schema{{</hover>}} section
|
|
||||||
to define the _Composite Resource_ {{<hover label="xr2" line="6" >}}spec{{</hover >}}.
|
|
||||||
|
|
||||||
```yaml {label="specGroup"}
|
|
||||||
# Composite Resource Definition (XRD)
|
|
||||||
spec:
|
|
||||||
group: test.example.org
|
|
||||||
names:
|
|
||||||
kind: MyComputeResource
|
|
||||||
versions:
|
|
||||||
- name: v1alpha1
|
|
||||||
schema:
|
|
||||||
# Removed for brevity
|
|
||||||
```
|
|
||||||
|
|
||||||
A _Composite Resource_ based on this _Composite Resource Definition_ looks like this:
|
|
||||||
|
|
||||||
```yaml {label="xr2"}
|
|
||||||
# Composite Resource (XR)
|
|
||||||
apiVersion: test.example.org/v1alpha1
|
|
||||||
kind: MyComputeResource
|
|
||||||
metadata:
|
|
||||||
name: my-resource
|
|
||||||
spec:
|
|
||||||
storage: "large"
|
|
||||||
```
|
|
||||||
|
|
||||||
A _Composite Resource Definition_ {{< hover label="specGroup" line="8" >}}schema{{</hover >}} defines the _Composite Resource_
|
|
||||||
{{<hover label="xr2" line="6" >}}spec{{</hover >}} parameters.
|
|
||||||
|
|
||||||
These parameters are the new, custom APIs, that developers can use.
|
|
||||||
|
|
||||||
For example, creating a compute _managed resource_ requires knowledge of a
|
|
||||||
cloud provider's compute class names like AWS's `m6in.large` or GCP's
|
|
||||||
`e2-standard-2`.
|
|
||||||
|
|
||||||
A _Composite Resource Definition_ can limit the choices to `small` or `large`.
|
|
||||||
A _Composite Resource_ uses those options and the _Composition_ maps them
|
|
||||||
to specific cloud provider settings.
|
|
||||||
|
|
||||||
The following _Composite Resource Definition_ defines a {{<hover label="specVersions" line="17" >}}storage{{< /hover >}}
|
|
||||||
parameter. The storage is a
|
|
||||||
{{<hover label="specVersions" line="18">}}string{{< /hover >}}
|
|
||||||
and the OpenAPI
|
|
||||||
{{<hover label="specVersions" line="19" >}}oneOf{{< /hover >}} requires the
|
|
||||||
options to be either {{<hover label="specVersions" line="20" >}}small{{< /hover >}}
|
|
||||||
or {{<hover label="specVersions" line="21" >}}large{{< /hover >}}.
|
|
||||||
|
|
||||||
```yaml {label="specVersions"}
|
|
||||||
# Composite Resource Definition (XRD)
|
|
||||||
spec:
|
|
||||||
group: test.example.org
|
|
||||||
names:
|
|
||||||
kind: MyComputeResource
|
|
||||||
versions:
|
|
||||||
- name: v1alpha1
|
|
||||||
served: true
|
|
||||||
referenceable: true
|
|
||||||
schema:
|
|
||||||
openAPIV3Schema:
|
|
||||||
type: object
|
|
||||||
properties:
|
|
||||||
spec:
|
|
||||||
type: object
|
|
||||||
properties:
|
|
||||||
storage:
|
|
||||||
type: string
|
|
||||||
oneOf:
|
|
||||||
- pattern: '^small$'
|
|
||||||
- pattern: '^large$'
|
|
||||||
required:
|
|
||||||
- storage
|
|
||||||
```
|
|
||||||
|
|
||||||
A _Composite Resource Definition_ can define a wide variety of settings and options.
|
|
||||||
|
|
||||||
Creating a _Composite Resource Definition_ enables the creation of _Composite
|
|
||||||
Resources_.
|
|
||||||
|
|
||||||
## Next steps
|
|
||||||
Build your own Crossplane platform using one of the quickstart guides.
|
|
||||||
|
|
|
||||||
|
|
@ -0,0 +1,237 @@
|
||||||
|
---
|
||||||
|
title: What's Crossplane?
|
||||||
|
weight: 3
|
||||||
|
description: Learn what Crossplane is and why you'd use it.
|
||||||
|
---
|
||||||
|
|
||||||
|
Crossplane is a control plane framework for platform engineering.
|
||||||
|
|
||||||
|
**Crossplane lets you build control planes to manage your cloud native software.**
|
||||||
|
It lets you design the APIs and abstractions that your users use to interact
|
||||||
|
with your control planes.
|
||||||
|
|
||||||
|
{{< hint "tip" >}}
|
||||||
|
**A control plane is software that controls other software.**
|
||||||
|
|
||||||
|
Control planes are a core cloud native pattern. The major cloud providers are
|
||||||
|
all built using control planes.
|
||||||
|
|
||||||
|
Control planes expose an API. You use the API to tell the control plane what
|
||||||
|
software it should configure and how - this is your _desired state_.
|
||||||
|
|
||||||
|
A control plane can configure any cloud native software. It could deploy an app,
|
||||||
|
create a load balancer, or create a GitHub repository.
|
||||||
|
|
||||||
|
The control plane configures your software, then monitors it throughout its
|
||||||
|
lifecycle. If your software ever _drifts_ from your desired state, the control
|
||||||
|
plane automatically corrects the drift.
|
||||||
|
{{< /hint >}}
|
||||||
|
|
||||||
|
Crossplane has a rich ecosystem of extensions that make building a control plane
|
||||||
|
faster and easier. It's built on Kubernetes, so it works with all the Kubernetes
|
||||||
|
tools you already use.
|
||||||
|
|
||||||
|
**Crossplane's key value is that it unlocks the benefits of building your own
|
||||||
|
Kubernetes custom resources without having to write controllers for them.**
|
||||||
|
|
||||||
|
Not familiar with Kubernetes custom resources and controllers?
|
||||||
|
[This DevOps Toolkit video](https://www.youtube.com/watch?v=aM2Y9m2Kazk) has a
|
||||||
|
great explanation.
|
||||||
|
|
||||||
|
{{<hint "note">}}
|
||||||
|
Kubebuilder is a popular project for building Kubernetes controllers. Look at
|
||||||
|
the [Kubebuilder documentation](https://book.kubebuilder.io) to see what's
|
||||||
|
involved in writing a controller.
|
||||||
|
{{</hint>}}
|
||||||
|
|
||||||
|
# Crossplane components
|
||||||
|
|
||||||
|
Crossplane has three major components:
|
||||||
|
|
||||||
|
* [Composition](#composition)
|
||||||
|
* [Managed resources](#managed-resources)
|
||||||
|
* [Package manager](#package-manager)
|
||||||
|
|
||||||
|
You can use all three components to build your control plane, or pick only the
|
||||||
|
ones you need.
|
||||||
|
|
||||||
|
## Composition
|
||||||
|
|
||||||
|
Composition lets you build custom APIs to control your cloud native software.
|
||||||
|
|
||||||
|
Crossplane extends Kubernetes. You build your custom APIs by using Crossplane to
|
||||||
|
extend Kubernetes with new custom resources.
|
||||||
|
|
||||||
|
**To extend Kubernetes without using Crossplane you need a Kubernetes
|
||||||
|
controller.** The controller is the software that reacts when a user calls the
|
||||||
|
custom resource API.
|
||||||
|
|
||||||
|
Say you want your control plane to serve an `Application` custom resource API.
|
||||||
|
When someone creates an `Application`, the control plane should create a
|
||||||
|
Kubernetes `Deployment` and a `Service`.
|
||||||
|
|
||||||
|
**If there's not already a controller that does what you want - and exposes the
|
||||||
|
API you want - you have to write the controller yourself.**
|
||||||
|
|
||||||
|
```mermaid
|
||||||
|
flowchart TD
|
||||||
|
user(User)
|
||||||
|
|
||||||
|
subgraph control [Control Plane]
|
||||||
|
api(Application API)
|
||||||
|
controller[Your Application Controller]
|
||||||
|
deployment(Deployment API)
|
||||||
|
service(Service API)
|
||||||
|
end
|
||||||
|
|
||||||
|
user -- create --> api
|
||||||
|
controller watch@<-- watch --> api
|
||||||
|
controller -- create --> deployment
|
||||||
|
controller -- create --> service
|
||||||
|
|
||||||
|
watch@{animate: true}
|
||||||
|
```
|
||||||
|
|
||||||
|
**With Crossplane you don't have to write a controller**. Instead you configure
|
||||||
|
a pipeline of functions. The functions return declarative configuration that
|
||||||
|
Crossplane should apply.
|
||||||
|
|
||||||
|
```mermaid
|
||||||
|
flowchart TD
|
||||||
|
user(User)
|
||||||
|
|
||||||
|
subgraph control [Control Plane]
|
||||||
|
api(Application API)
|
||||||
|
|
||||||
|
subgraph crossplane [Composition Engine]
|
||||||
|
fn(Python Function)
|
||||||
|
end
|
||||||
|
|
||||||
|
deployment(Deployment API)
|
||||||
|
service(Service API)
|
||||||
|
end
|
||||||
|
|
||||||
|
user -- create --> api
|
||||||
|
crossplane watch@<-- watch --> api
|
||||||
|
crossplane -- create --> deployment
|
||||||
|
crossplane -- create --> service
|
||||||
|
|
||||||
|
watch@{animate: true}
|
||||||
|
```
|
||||||
|
|
||||||
|
With Composition you avoid writing and maintaining complex controller code
|
||||||
|
that's hard to get right. Instead you focus on expressing your business
|
||||||
|
logic, and work in your preferred language.
|
||||||
|
|
||||||
|
|
||||||
|
{{<hint "important">}}
|
||||||
|
Composition functions are like configuration language plugins.
|
||||||
|
|
||||||
|
Functions allow you to write your configuration in several languages, including
|
||||||
|
[YAML](https://yaml.org), [KCL](https://www.kcl-lang.io),
|
||||||
|
[Python](https://python.org), and [Go](https://go.dev).
|
||||||
|
{{</hint>}}
|
||||||
|
|
||||||
|
You can use composition together with [managed resources](#managed-resources) to
|
||||||
|
build new custom resource APIs powered by managed resources.
|
||||||
|
|
||||||
|
Follow [Get Started with Composition]({{<ref "../get-started/get-started-with-composition">}})
|
||||||
|
to see how composition works.
|
||||||
|
|
||||||
|
## Managed resources
|
||||||
|
|
||||||
|
Managed resources (MRs) are ready-made Kubernetes custom resources.
|
||||||
|
|
||||||
|
Each MR extends Kubernetes with the ability to manage a new system. For example
|
||||||
|
there's an RDS instance MR that extends Kubernetes with the ability to manage
|
||||||
|
[AWS RDS](https://aws.amazon.com/rds/) instances.
|
||||||
|
|
||||||
|
Crossplane has an extensive library of managed resources you can use to manage
|
||||||
|
almost any cloud provider, or cloud native software.
|
||||||
|
|
||||||
|
**With Crossplane you don't have to write a controller if you want to manage
|
||||||
|
something outside of your Kubernetes cluster using a custom resource.** There's
|
||||||
|
already a Crossplane managed resource for that.
|
||||||
|
|
||||||
|
```mermaid
|
||||||
|
flowchart TD
|
||||||
|
user(User)
|
||||||
|
|
||||||
|
subgraph control [Control Plane]
|
||||||
|
instance(RDS Instance API)
|
||||||
|
controller(Managed Resource Controller)
|
||||||
|
end
|
||||||
|
|
||||||
|
subgraph aws [Amazon Web Services]
|
||||||
|
rds(RDS Instance)
|
||||||
|
end
|
||||||
|
|
||||||
|
user -- create --> instance
|
||||||
|
controller watch-rds@<-- watch --> instance
|
||||||
|
controller -- create --> rds
|
||||||
|
|
||||||
|
watch-rds@{animate: true}
|
||||||
|
```
|
||||||
|
|
||||||
|
You can use managed resources together with [composition](#composition) to build
|
||||||
|
new custom resource APIs powered by MRs.
|
||||||
|
|
||||||
|
```mermaid
|
||||||
|
flowchart TD
|
||||||
|
user(User)
|
||||||
|
|
||||||
|
subgraph control [Control Plane]
|
||||||
|
api(Application API)
|
||||||
|
|
||||||
|
subgraph crossplane [Composition Engine]
|
||||||
|
fn(Python Function)
|
||||||
|
end
|
||||||
|
|
||||||
|
deployment(Deployment API)
|
||||||
|
service(Service API)
|
||||||
|
instance(RDS Instance API)
|
||||||
|
|
||||||
|
controller(Managed Resource Controller)
|
||||||
|
end
|
||||||
|
|
||||||
|
subgraph aws [Amazon Web Services]
|
||||||
|
rds(RDS Instance)
|
||||||
|
end
|
||||||
|
|
||||||
|
user -- create --> api
|
||||||
|
crossplane watch-apps@<-- watch --> api
|
||||||
|
crossplane -- create --> deployment
|
||||||
|
crossplane -- create --> service
|
||||||
|
crossplane -- create --> instance
|
||||||
|
|
||||||
|
controller watch-rds@<-- watch --> instance
|
||||||
|
controller -- create --> rds
|
||||||
|
|
||||||
|
watch-apps@{animate: true}
|
||||||
|
watch-rds@{animate: true}
|
||||||
|
```
|
||||||
|
|
||||||
|
Follow [Get Started with Managed Resources]({{<ref "../get-started/get-started-with-managed-resources">}})
|
||||||
|
to see how managed resources work.
|
||||||
|
|
||||||
|
{{<hint "note">}}
|
||||||
|
Only AWS managed resources support the Crossplane v2 preview.
|
||||||
|
|
||||||
|
<!-- vale gitlab.FutureTense = NO -->
|
||||||
|
Maintainers will update the managed resources for other systems including Azure,
|
||||||
|
GCP, Terraform, Helm, GitHub, etc to support Crossplane v2 soon.
|
||||||
|
<!-- vale gitlab.FutureTense = YES -->
|
||||||
|
{{</hint>}}
|
||||||
|
|
||||||
|
## Package manager
|
||||||
|
|
||||||
|
The Crossplane package manager lets you install new managed resources and
|
||||||
|
composition functions.
|
||||||
|
|
||||||
|
You can also package any part of a control plane's configuration and install it
|
||||||
|
using the package manager. This allows you to deploy several control planes with
|
||||||
|
identical capabilities - for example one control plane per region or per
|
||||||
|
service.
|
||||||
|
|
||||||
|
Read about Crossplane packages in [Concepts]({{<ref "../concepts/packages">}})
|
||||||
|
to learn about the package manager.
|
||||||
|
|
@ -10,5 +10,14 @@
|
||||||
stroke: var(--body-font-color) !important;
|
stroke: var(--body-font-color) !important;
|
||||||
}
|
}
|
||||||
|
|
||||||
|
.cluster {
|
||||||
|
&>rect {
|
||||||
|
fill: color-mix(in srgb,
|
||||||
|
color-mix(in srgb, var(--hint-note-background) 50%, #ffffff 50%) 80%,
|
||||||
|
transparent 100%) !important;
|
||||||
|
}
|
||||||
|
span {
|
||||||
|
color: var(--body-font-color) !important;
|
||||||
|
}
|
||||||
|
}
|
||||||
}
|
}
|
||||||
|
|
@ -13,6 +13,7 @@ Buf
|
||||||
CEL
|
CEL
|
||||||
CI
|
CI
|
||||||
CLI
|
CLI
|
||||||
|
cloud-native
|
||||||
cluster-scoped
|
cluster-scoped
|
||||||
cluster-wide
|
cluster-wide
|
||||||
ClusterRole
|
ClusterRole
|
||||||
|
|
@ -25,6 +26,7 @@ CSS
|
||||||
CUE
|
CUE
|
||||||
CVEs
|
CVEs
|
||||||
DatabaseInstance
|
DatabaseInstance
|
||||||
|
DevOps
|
||||||
DNS
|
DNS
|
||||||
docs-specific
|
docs-specific
|
||||||
emptyDir
|
emptyDir
|
||||||
|
|
@ -95,5 +97,6 @@ TLS
|
||||||
tolerations
|
tolerations
|
||||||
UI
|
UI
|
||||||
VM
|
VM
|
||||||
|
v2
|
||||||
webhooks.enabled
|
webhooks.enabled
|
||||||
YAML
|
YAML
|
||||||
|
|
@ -14,6 +14,7 @@ Grammarly
|
||||||
Graphviz
|
Graphviz
|
||||||
HashiCorp
|
HashiCorp
|
||||||
instant.page
|
instant.page
|
||||||
|
Kubebuilder
|
||||||
Kustomize
|
Kustomize
|
||||||
Netlify
|
Netlify
|
||||||
NodeJS
|
NodeJS
|
||||||
|
|
|
||||||
|
|
@ -35,6 +35,7 @@ pre-provisioned
|
||||||
pre-release
|
pre-release
|
||||||
race-conditions
|
race-conditions
|
||||||
read-only
|
read-only
|
||||||
|
ready-made
|
||||||
resource-specific
|
resource-specific
|
||||||
right-hand
|
right-hand
|
||||||
run-time
|
run-time
|
||||||
|
|
|
||||||
Loading…
Reference in New Issue