diff --git a/content/v2.0-preview/_index.md b/content/v2.0-preview/_index.md index 3c8f0c85..181460a0 100644 --- a/content/v2.0-preview/_index.md +++ b/content/v2.0-preview/_index.md @@ -1,51 +1,30 @@ --- -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. -
+# Using the documentation -Crossplane is an open source Kubernetes extension that transforms your Kubernetes -cluster into a **universal control plane**. +Crossplane organizes its documentation into the following sections: -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. +* [What's Crossplane?]({{}}) introduces Crossplane + and explains why you should use 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. +* [Get Started]({{}}) explains how to install Crossplane and + create a control plane. -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. +* [Concepts]({{}}) introduces Crossplane's key concepts. -{{< 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. +* [Guides]({{}}) guide you through common use cases, like + monitoring Crossplane or extending it by writing a composition function. -Crossplane extends the Kubernetes control plane to be a **universal control -plane** to check, report and act on any resource, anywhere. - -{{< /hint >}} +* [CLI Reference]({{}}) documents the `crossplane` command-line + interface that you can use to configure a Crossplane control plane. - -# 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. - - -Crossplane is a [Cloud Native Compute Foundation](https://www.cncf.io/) project. +* [API Reference]({{}}) documents the APIs that you can use to + configure a Crossplane control plane. diff --git a/content/v2.0-preview/get-started/_index.md b/content/v2.0-preview/get-started/_index.md index 500c561b..241e3017 100644 --- a/content/v2.0-preview/get-started/_index.md +++ b/content/v2.0-preview/get-started/_index.md @@ -4,332 +4,3 @@ 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 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. - - -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. - -{{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. - -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]({{}}) | | 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 >}} - -## 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. - - - -## 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. - -{{< 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_. -{{}} -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. diff --git a/content/v2.0-preview/whats-crossplane/_index.md b/content/v2.0-preview/whats-crossplane/_index.md new file mode 100644 index 00000000..c0802615 --- /dev/null +++ b/content/v2.0-preview/whats-crossplane/_index.md @@ -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. + +{{}} +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 [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. + + +{{}} +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 +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(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]({{}}) +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 plane 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/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; + } + } +} diff --git a/utils/vale/styles/Crossplane/allowed-jargon.txt b/utils/vale/styles/Crossplane/allowed-jargon.txt index fe830288..5bbe6b27 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 @@ -25,6 +26,7 @@ CSS CUE CVEs DatabaseInstance +DevOps DNS docs-specific emptyDir @@ -95,5 +97,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 db4c4ae6..6a9fc46b 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