From 9188eb598af9bb8a74fef0b1971a15419278d217 Mon Sep 17 00:00:00 2001 From: Nic Cope Date: Wed, 26 Mar 2025 15:30:50 -0700 Subject: [PATCH 01/11] Rework the landing page This tries to: * Modernize how we frame Crossplane * Briefly introduce folks to the docs sections Signed-off-by: Nic Cope --- content/v2.0-preview/_index.md | 70 +++++++++++++++++----------------- 1 file changed, 35 insertions(+), 35 deletions(-) diff --git a/content/v2.0-preview/_index.md b/content/v2.0-preview/_index.md index 3c8f0c85..1d72ae99 100644 --- a/content/v2.0-preview/_index.md +++ b/content/v2.0-preview/_index.md @@ -1,51 +1,51 @@ --- -title: "Overview" +title: "Welcome" weight: -1 cascade: 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. -
+Crossplane lets you build control planes to manage your apps, infrastructure, or +anything else. It lets you design the APIs and abstractions that your users use +to interact with your control planes. -Crossplane is an open source Kubernetes extension that transforms your Kubernetes -cluster into a **universal control plane**. - -Crossplane lets you manage anything, anywhere, all through standard Kubernetes -APIs. Crossplane can even let you -[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 -APIs with the full power of Kubernetes policies, namespaces, role based access -controls and more. Crossplane brings all your non-Kubernetes resources under -one roof. - -Custom APIs, created by platform teams, allow security and compliance -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. +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. {{< hint "tip" >}} -**What's a control plane?** - -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. +**A control plane is software that controls other software.** -Crossplane extends the Kubernetes control plane to be a **universal control -plane** to check, report and act on any resource, anywhere. - +Control planes expose an API. You use the API to tell the control plane what +software it should deploy and how - this is your _desired state_. It could be +any cloud native software, like an app, a load balancer, or a GitHub repository. + +The control plane deploys your software, then monitors it throughout its +lifecycle. If your software ever _drifts_ from your desired state, the control +plane automatically corrects the drift. + +Control planes are a core cloud native pattern. The major cloud providers are +all built using control planes. {{< /hint >}} -# Get started -* [Install Crossplane]({{}}) in your Kubernetes cluster -* Learn more about how Crossplane works in the -[Crossplane introduction]({{}}) -* Join the [Crossplane Slack](https://slack.crossplane.io/) and start a -conversation with a community of over 7,000 operators. +# Using the documentation +Crossplane organizes its documentation into the following sections: -Crossplane is a [Cloud Native Compute Foundation](https://www.cncf.io/) project. +* [Get Started]({{}}) explains how to install Crossplane and + create a control plane. + +* [Concepts]({{}}) introduces Crossplane's key concepts. + +* [Guides]({{}}) guide you through common use cases, like + monitoring Crossplane or extending it by writing a composition function. + +* [CLI Reference]({{}}) documents the `crossplane` command-line + interface that you can use to configure a Crossplane control plane. + +* [API Reference]({{}}) documents the APIs that you can use to + configure a Crossplane control plane. From b4a722aa4ecaf248c9a3669f6d45eac081c52d92 Mon Sep 17 00:00:00 2001 From: Nic Cope Date: Wed, 26 Mar 2025 16:24:05 -0700 Subject: [PATCH 02/11] Talk about configuring software - not deploying it Signed-off-by: Nic Cope --- content/v2.0-preview/_index.md | 14 ++++++++------ 1 file changed, 8 insertions(+), 6 deletions(-) diff --git a/content/v2.0-preview/_index.md b/content/v2.0-preview/_index.md index 1d72ae99..5887df4c 100644 --- a/content/v2.0-preview/_index.md +++ b/content/v2.0-preview/_index.md @@ -8,9 +8,9 @@ cascade: Welcome to the Crossplane documentation. Crossplane is a control plane framework for platform engineering. -Crossplane lets you build control planes to manage your apps, infrastructure, or -anything else. It lets you design the APIs and abstractions that your users use -to interact with your control planes. +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. 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 @@ -20,10 +20,12 @@ tools you already use. **A control plane is software that controls other software.** Control planes expose an API. You use the API to tell the control plane what -software it should deploy and how - this is your _desired state_. It could be -any cloud native software, like an app, a load balancer, or a GitHub repository. +software it should configure and how - this is your _desired state_. -The control plane deploys your software, then monitors it throughout its +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. From f4b648cd82d26ee65ad8062ff4f9fd583db236db Mon Sep 17 00:00:00 2001 From: Nic Cope Date: Wed, 26 Mar 2025 17:25:06 -0700 Subject: [PATCH 03/11] Mention that clouds are built with control planes earlier Signed-off-by: Nic Cope --- content/v2.0-preview/_index.md | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/content/v2.0-preview/_index.md b/content/v2.0-preview/_index.md index 5887df4c..e0abad44 100644 --- a/content/v2.0-preview/_index.md +++ b/content/v2.0-preview/_index.md @@ -19,6 +19,9 @@ tools you already use. {{< 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_. @@ -28,9 +31,6 @@ 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. - -Control planes are a core cloud native pattern. The major cloud providers are -all built using control planes. {{< /hint >}} From 549c338f48cb331bda75e0b0813e9302dfb87093 Mon Sep 17 00:00:00 2001 From: Nic Cope Date: Wed, 26 Mar 2025 20:58:39 -0700 Subject: [PATCH 04/11] Update the get started landing page This is now where we introduce the three components of Crossplane. In future we might benefit from a more detailed "what is Crossplane?" page. Signed-off-by: Nic Cope --- content/v2.0-preview/get-started/_index.md | 363 +++--------------- .../vale/styles/Crossplane/allowed-jargon.txt | 2 + utils/vale/styles/Crossplane/brands.txt | 1 + .../styles/Crossplane/spelling-exceptions.txt | 1 + 4 files changed, 62 insertions(+), 305 deletions(-) diff --git a/content/v2.0-preview/get-started/_index.md b/content/v2.0-preview/get-started/_index.md index 500c561b..40b50f72 100644 --- a/content/v2.0-preview/get-started/_index.md +++ b/content/v2.0-preview/get-started/_index.md @@ -4,332 +4,85 @@ weight: 4 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. +Crossplane has three major components: - -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. - +* [Composition](#composition) +* [Managed resources](#managed-resources) +* [Package manager](#package-manager) -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. +You can use all the components to build your control plane, or pick only the +ones you need. -{{Diagram showing a user communicating to Kubernetes. Crossplane connected to Kubernetes and Crossplane communicating with AWS, Azure and GCP}} -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. +# Composition -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. +Composition lets you build custom APIs to control your cloud-native software. -## Crossplane components overview -This table provides a summary of Crossplane components and their roles. +Crossplane extends Kubernetes. You build your custom APIs by using Crossplane to +extend Kubernetes with new custom resources. -{{< table "table table-hover table-sm">}} -| Component | Abbreviation | Scope | Summary | -| --- | --- | --- | ---- | -| [Provider]({{}}) | | cluster | Creates new Kubernetes Custom Resource Definitions for an external service. | -| [ProviderConfig]({{}}) | `PC` | cluster | Applies settings for a _Provider_. | -| [Managed Resource]({{}}) | `MR` | cluster | A Provider resource created and managed by Crossplane inside the Kubernetes cluster. | -| [Composition]({{}}) | | cluster | A template for creating multiple _managed resources_ at once. | -| [Composite Resources]({{}}) | `XR` | cluster | Uses a _Composition_ template to create multiple _managed resources_ as a single Kubernetes object. | -| [CompositeResourceDefinitions]({{}}) | `XRD` | cluster | Defines the API schema for _Composite Resources_ | -{{< /table >}} +To extend Kubernetes without using Crossplane you have to write a Kubernetes +controller. The controller is the software that reacts when a user calls the +custom resource API. -## The Crossplane Pod -When installed in a Kubernetes cluster Crossplane creates an initial set of -Custom Resource Definitions (`CRDs`) of the core Crossplane components. +With Crossplane you don't have to write a controller. Instead you configure a +pipeline of functions. The functions tell Crossplane what to do when a user +calls the custom resource API. You can configure the functions using common +languages, including YAML, [KCL](https://www.kcl-lang.io), and +[Python](https://python.org). -{{< expand "View the initial Crossplane CRDs" >}} -After installing Crossplane use `kubectl get crds` to view the Crossplane -installed CRDs. +You can use composition together with [managed resources](#managed-resources) to +build new custom resource APIs powered by managed resources. -```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 >}} +Follow [Get Started with Composition]({{}}) +to see how composition works. -The following sections describe the functions of some of these CRDs. +{{}} +Not familiar with Kubernetes custom resources and controllers? - - -## Providers - -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. +Read the Kubernetes documentation on +[custom resources](https://kubernetes.io/docs/concepts/extend-kubernetes/api-extension/custom-resources/) +and [controllers](https://kubernetes.io/docs/concepts/architecture/controller/). -{{< hint "tip" >}} -Most Providers are for cloud services but Crossplane can use a Provider to -connect to any service with an API. -{{< /hint >}} +Kubebuilder is a popular project for building Kubernetes controllers. Read the +[Kubebuilder documentation](https://book.kubebuilder.io) to see what's +involved in writing a controller. +{{}} -For example, an AWS Provider defines Kubernetes CRDs for AWS resources like EC2 -compute instances or S3 storage buckets. +# Managed resources -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. +Managed resources (MRs) are ready-made Kubernetes custom resources. -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. +Each MR extends Kubernetes with the ability to manage a new kind of resource. +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's [public package registries](https://www.crossplane.io/registries) contain a large -collection of Crossplane Providers. +Crossplane has an extensive library of managed resources you can use to manage +almost any cloud provider, or cloud-native software. -More providers are available in the [Crossplane Contrib repository](https://github.com/crossplane-contrib/). +You can use managed resources together with [composition](#composition) to build +new custom resource APIs powered by MRs. -Providers are cluster scoped and available to all cluster namespaces. +Follow [Get Started with Managed Resources]({{}}) +to see how managed resources work. -View all installed Providers with the command `kubectl get providers`. +{{}} +Only AWS managed resources support the Crossplane v2 preview. -## Provider configurations -Providers have _ProviderConfigs_. _ProviderConfigs_ configure settings -related to the Provider like authentication or global defaults for the -Provider. + +Maintainers will update the managed resources for other systems including Azure, +GCP, Terraform, Helm, GitHub, etc to support Crossplane v2 soon. + +{{}} -The API endpoints for ProviderConfigs are unique to each Provider. +# Package manager -_ProviderConfigs_ are cluster scoped and available to all cluster namespaces. +The Crossplane package manager lets you install new managed resources and +composition functions. -View all installed ProviderConfigs with the command `kubectl get providerconfig`. +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 planes per region or per +service. -## 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_. -{{}} -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_]({{}}) 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 {{}}group{{< /hover >}} -to define the -{{< hover label="xr2" line="2" >}}apiVersion{{}} -in a _Composite Resource_ . -* The {{< hover label="specGroup" line="7" >}}versions.name{{}} -that defines the version used in a _Composite Resource_. -* A {{< hover label="specGroup" line="5" >}}names.kind{{}} -to define the _Composite Resource_ -{{< hover label="xr2" line="3" >}}kind{{}}. -* A {{< hover label="specGroup" line="8" >}}versions.schema{{}} section -to define the _Composite Resource_ {{}}spec{{}}. - -```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{{}} defines the _Composite Resource_ -{{}}spec{{}} 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 {{}}storage{{< /hover >}} -parameter. The storage is a -{{}}string{{< /hover >}} -and the OpenAPI -{{}}oneOf{{< /hover >}} requires the -options to be either {{}}small{{< /hover >}} -or {{}}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. +Read about Crossplane packages in [Concepts]({{}}) +to learn about the package manager. \ No newline at end of file diff --git a/utils/vale/styles/Crossplane/allowed-jargon.txt b/utils/vale/styles/Crossplane/allowed-jargon.txt index fe830288..9be8954b 100644 --- a/utils/vale/styles/Crossplane/allowed-jargon.txt +++ b/utils/vale/styles/Crossplane/allowed-jargon.txt @@ -13,6 +13,7 @@ Buf CEL CI CLI +cloud-native cluster-scoped cluster-wide ClusterRole @@ -95,5 +96,6 @@ TLS tolerations UI VM +v2 webhooks.enabled YAML \ No newline at end of file diff --git a/utils/vale/styles/Crossplane/brands.txt b/utils/vale/styles/Crossplane/brands.txt index 313f5e4c..040bc387 100644 --- a/utils/vale/styles/Crossplane/brands.txt +++ b/utils/vale/styles/Crossplane/brands.txt @@ -14,6 +14,7 @@ Grammarly Graphviz HashiCorp instant.page +Kubebuilder Kustomize Netlify NodeJS diff --git a/utils/vale/styles/Crossplane/spelling-exceptions.txt b/utils/vale/styles/Crossplane/spelling-exceptions.txt index 417b2521..00449038 100644 --- a/utils/vale/styles/Crossplane/spelling-exceptions.txt +++ b/utils/vale/styles/Crossplane/spelling-exceptions.txt @@ -35,6 +35,7 @@ pre-provisioned pre-release race-conditions read-only +ready-made resource-specific right-hand run-time From 029548b3104db7751c2b1f434ea2d6377b2f9f85 Mon Sep 17 00:00:00 2001 From: Nic Cope Date: Wed, 26 Mar 2025 21:17:20 -0700 Subject: [PATCH 05/11] 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 --- content/v2.0-preview/_index.md | 29 +-- content/v2.0-preview/get-started/_index.md | 82 ------- .../v2.0-preview/what-is-crossplane/_index.md | 231 ++++++++++++++++++ 3 files changed, 234 insertions(+), 108 deletions(-) create mode 100644 content/v2.0-preview/what-is-crossplane/_index.md diff --git a/content/v2.0-preview/_index.md b/content/v2.0-preview/_index.md index e0abad44..e168cf62 100644 --- a/content/v2.0-preview/_index.md +++ b/content/v2.0-preview/_index.md @@ -8,36 +8,13 @@ cascade: Welcome to the Crossplane documentation. 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. - -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. - -{{< 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 >}} - - # Using the documentation Crossplane organizes its documentation into the following sections: +* [What is Crossplane?]({{}}) introduces Crossplane + and explains why you should use it. + * [Get Started]({{}}) explains how to install Crossplane and create a control plane. diff --git a/content/v2.0-preview/get-started/_index.md b/content/v2.0-preview/get-started/_index.md index 40b50f72..241e3017 100644 --- a/content/v2.0-preview/get-started/_index.md +++ b/content/v2.0-preview/get-started/_index.md @@ -4,85 +4,3 @@ weight: 4 description: Get started with Crossplane. --- -Crossplane has three major components: - -* [Composition](#composition) -* [Managed resources](#managed-resources) -* [Package manager](#package-manager) - -You can use all the 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 have to write a Kubernetes -controller. The controller is the software that reacts when a user calls the -custom resource API. - -With Crossplane you don't have to write a controller. Instead you configure a -pipeline of functions. The functions tell Crossplane what to do when a user -calls the custom resource API. You can configure the functions using common -languages, including YAML, [KCL](https://www.kcl-lang.io), and -[Python](https://python.org). - -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]({{}}) -to see how composition works. - -{{}} -Not familiar with Kubernetes custom resources and controllers? - -Read the Kubernetes documentation on -[custom resources](https://kubernetes.io/docs/concepts/extend-kubernetes/api-extension/custom-resources/) -and [controllers](https://kubernetes.io/docs/concepts/architecture/controller/). - -Kubebuilder is a popular project for building Kubernetes controllers. Read the -[Kubebuilder documentation](https://book.kubebuilder.io) to see what's -involved in writing a controller. -{{}} - -# Managed resources - -Managed resources (MRs) are ready-made Kubernetes custom resources. - -Each MR extends Kubernetes with the ability to manage a new kind of resource. -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. - -You can use managed resources together with [composition](#composition) to build -new custom resource APIs powered by MRs. - -Follow [Get Started with Managed Resources]({{}}) -to see how managed resources work. - -{{}} -Only AWS managed resources support the Crossplane v2 preview. - - -Maintainers will update the managed resources for other systems including Azure, -GCP, Terraform, Helm, GitHub, etc to support Crossplane v2 soon. - -{{}} - -# 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 planes per region or per -service. - -Read about Crossplane packages in [Concepts]({{}}) -to learn about the package manager. \ No newline at end of file diff --git a/content/v2.0-preview/what-is-crossplane/_index.md b/content/v2.0-preview/what-is-crossplane/_index.md new file mode 100644 index 00000000..9233721d --- /dev/null +++ b/content/v2.0-preview/what-is-crossplane/_index.md @@ -0,0 +1,231 @@ +--- +title: What is 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? + +Read the Kubernetes documentation on +[custom resources](https://kubernetes.io/docs/concepts/extend-kubernetes/api-extension/custom-resources/) +and [controllers](https://kubernetes.io/docs/concepts/architecture/controller/). + +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. {{}} + +# 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 [Crossplane Composition] + 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} +``` + +{{}} +Composition functions allow you to express declarative configuration in various +languages including YAML, [KCL](https://www.kcl-lang.io), and +[Python](https://python.org). +{{}} + +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]({{}}) +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(Crossplane MR 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 [Crossplane Composition] + fn(Python Function) + end + + deployment(Deployment API) + service(Service API) + instance(RDS Instance API) + + controller(Crossplane MR 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]({{}}) +to see how managed resources work. + +{{}} +Only AWS managed resources support the Crossplane v2 preview. + + +Maintainers will update the managed resources for other systems including Azure, +GCP, Terraform, Helm, GitHub, etc to support Crossplane v2 soon. + +{{}} + +## 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 planes per region or per +service. + +Read about Crossplane packages in [Concepts]({{}}) +to learn about the package manager. \ No newline at end of file From 19507da13469d98d8009f2ef0316c1356db3e892 Mon Sep 17 00:00:00 2001 From: Nic Cope Date: Wed, 26 Mar 2025 23:03:10 -0700 Subject: [PATCH 06/11] Use Viktor's video that explains CRs and controllers I promise I'm not biased, I just happened to search for resources and found it a lot better than the Kubernetes docs. Signed-off-by: Nic Cope --- content/v2.0-preview/what-is-crossplane/_index.md | 11 +++++------ utils/vale/styles/Crossplane/allowed-jargon.txt | 1 + 2 files changed, 6 insertions(+), 6 deletions(-) diff --git a/content/v2.0-preview/what-is-crossplane/_index.md b/content/v2.0-preview/what-is-crossplane/_index.md index 9233721d..625e928a 100644 --- a/content/v2.0-preview/what-is-crossplane/_index.md +++ b/content/v2.0-preview/what-is-crossplane/_index.md @@ -34,16 +34,15 @@ 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. -Read the Kubernetes documentation on -[custom resources](https://kubernetes.io/docs/concepts/extend-kubernetes/api-extension/custom-resources/) -and [controllers](https://kubernetes.io/docs/concepts/architecture/controller/). - +{{}} 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. {{}} +involved in writing a controller. +{{}} # Crossplane components diff --git a/utils/vale/styles/Crossplane/allowed-jargon.txt b/utils/vale/styles/Crossplane/allowed-jargon.txt index 9be8954b..5bbe6b27 100644 --- a/utils/vale/styles/Crossplane/allowed-jargon.txt +++ b/utils/vale/styles/Crossplane/allowed-jargon.txt @@ -26,6 +26,7 @@ CSS CUE CVEs DatabaseInstance +DevOps DNS docs-specific emptyDir From edc20038520d4877b05b4c0b3ec6ca1a9038a207 Mon Sep 17 00:00:00 2001 From: Nic Cope Date: Thu, 27 Mar 2025 12:14:21 -0700 Subject: [PATCH 07/11] Fix typo - control plane singular Signed-off-by: Nic Cope --- content/v2.0-preview/what-is-crossplane/_index.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/content/v2.0-preview/what-is-crossplane/_index.md b/content/v2.0-preview/what-is-crossplane/_index.md index 625e928a..1dfc13f7 100644 --- a/content/v2.0-preview/what-is-crossplane/_index.md +++ b/content/v2.0-preview/what-is-crossplane/_index.md @@ -223,7 +223,7 @@ 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 planes per region or per +identical capabilities - for example one control plane per region or per service. Read about Crossplane packages in [Concepts]({{}}) From db98c82333f611b6a8de3a6006f00089c137bca5 Mon Sep 17 00:00:00 2001 From: Nic Cope Date: Thu, 27 Mar 2025 13:45:47 -0700 Subject: [PATCH 08/11] Briefly clarify why a function pipeline is better than a controller Signed-off-by: Nic Cope --- content/v2.0-preview/what-is-crossplane/_index.md | 13 ++++++++++--- 1 file changed, 10 insertions(+), 3 deletions(-) diff --git a/content/v2.0-preview/what-is-crossplane/_index.md b/content/v2.0-preview/what-is-crossplane/_index.md index 1dfc13f7..d9f6138b 100644 --- a/content/v2.0-preview/what-is-crossplane/_index.md +++ b/content/v2.0-preview/what-is-crossplane/_index.md @@ -119,10 +119,17 @@ 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. + + {{}} -Composition functions allow you to express declarative configuration in various -languages including YAML, [KCL](https://www.kcl-lang.io), and -[Python](https://python.org). +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). {{}} You can use composition together with [managed resources](#managed-resources) to From 45f61d1c593d1d87df5defc29bba1dbe4ac1d1d9 Mon Sep 17 00:00:00 2001 From: Nicholas Thomson Date: Thu, 27 Mar 2025 12:25:33 -0700 Subject: [PATCH 09/11] Fix box and edge colours of mermaid diagrams Signed-off-by: Nic Cope --- themes/geekboot/assets/scss/_mermaid.scss | 13 +++++++++++-- 1 file changed, 11 insertions(+), 2 deletions(-) diff --git a/themes/geekboot/assets/scss/_mermaid.scss b/themes/geekboot/assets/scss/_mermaid.scss index f19143a8..01a0ba74 100644 --- a/themes/geekboot/assets/scss/_mermaid.scss +++ b/themes/geekboot/assets/scss/_mermaid.scss @@ -10,5 +10,14 @@ stroke: var(--body-font-color) !important; } - -} \ No newline at end of file + .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; + } + } +} From f7b7f3ef467ba02402f32b344bc480bcc5cbc704 Mon Sep 17 00:00:00 2001 From: Nic Cope Date: Thu, 27 Mar 2025 13:55:15 -0700 Subject: [PATCH 10/11] Minor diagram tweaks Mostly say 'Composition Engine' rather than 'Crossplane Composition' to distinguish from the Composition API type. 'Crossplane Composition Engine' won't fit. Signed-off-by: Nic Cope --- content/v2.0-preview/what-is-crossplane/_index.md | 10 +++++----- 1 file changed, 5 insertions(+), 5 deletions(-) diff --git a/content/v2.0-preview/what-is-crossplane/_index.md b/content/v2.0-preview/what-is-crossplane/_index.md index d9f6138b..5384f93b 100644 --- a/content/v2.0-preview/what-is-crossplane/_index.md +++ b/content/v2.0-preview/what-is-crossplane/_index.md @@ -79,7 +79,7 @@ user(User) subgraph control [Control Plane] api(Application API) - controller(Your Application Controller) + controller[Your Application Controller] deployment(Deployment API) service(Service API) end @@ -103,7 +103,7 @@ user(User) subgraph control [Control Plane] api(Application API) - subgraph crossplane [Crossplane Composition] + subgraph crossplane [Composition Engine] fn(Python Function) end @@ -159,7 +159,7 @@ user(User) subgraph control [Control Plane] instance(RDS Instance API) - controller(Crossplane MR Controller) + controller(Managed Resource Controller) end subgraph aws [Amazon Web Services] @@ -183,7 +183,7 @@ user(User) subgraph control [Control Plane] api(Application API) - subgraph crossplane [Crossplane Composition] + subgraph crossplane [Composition Engine] fn(Python Function) end @@ -191,7 +191,7 @@ subgraph control [Control Plane] service(Service API) instance(RDS Instance API) - controller(Crossplane MR Controller) + controller(Managed Resource Controller) end subgraph aws [Amazon Web Services] From 1d4a2be614db6a9014dfa198710b34b2bb43440b Mon Sep 17 00:00:00 2001 From: Nic Cope Date: Thu, 27 Mar 2025 13:57:52 -0700 Subject: [PATCH 11/11] Rename to "What's Crossplane" Vale says it's better. Signed-off-by: Nic Cope --- content/v2.0-preview/_index.md | 2 +- .../{what-is-crossplane => whats-crossplane}/_index.md | 2 +- 2 files changed, 2 insertions(+), 2 deletions(-) rename content/v2.0-preview/{what-is-crossplane => whats-crossplane}/_index.md (99%) diff --git a/content/v2.0-preview/_index.md b/content/v2.0-preview/_index.md index e168cf62..181460a0 100644 --- a/content/v2.0-preview/_index.md +++ b/content/v2.0-preview/_index.md @@ -12,7 +12,7 @@ for platform engineering. Crossplane organizes its documentation into the following sections: -* [What is Crossplane?]({{}}) introduces Crossplane +* [What's Crossplane?]({{}}) introduces Crossplane and explains why you should use it. * [Get Started]({{}}) explains how to install Crossplane and diff --git a/content/v2.0-preview/what-is-crossplane/_index.md b/content/v2.0-preview/whats-crossplane/_index.md similarity index 99% rename from content/v2.0-preview/what-is-crossplane/_index.md rename to content/v2.0-preview/whats-crossplane/_index.md index 5384f93b..c0802615 100644 --- a/content/v2.0-preview/what-is-crossplane/_index.md +++ b/content/v2.0-preview/whats-crossplane/_index.md @@ -1,5 +1,5 @@ --- -title: What is Crossplane? +title: What's Crossplane? weight: 3 description: Learn what Crossplane is and why you'd use it. ---