mirror of https://github.com/crossplane/docs.git
docs snapshot for crossplane version `v1.3`
This commit is contained in:
Crossplane
parent
ac66cc34bd
commit
5d5cf9863f
|
|
@ -0,0 +1,216 @@
|
||||||
|
---
|
||||||
|
title: Terminology
|
||||||
|
toc: true
|
||||||
|
weight: 51
|
||||||
|
indent: true
|
||||||
|
---
|
||||||
|
|
||||||
|
# Terminology
|
||||||
|
|
||||||
|
## A Note on Style
|
||||||
|
|
||||||
|
Each type of Kubernetes resource has a ‘Pascal case’ name - i.e. a title case
|
||||||
|
name with no spaces between each word. Examples include ‘DaemonSet’ and
|
||||||
|
‘PersistentVolumeClaim’. Often these names are written using fixed width fonts
|
||||||
|
to draw attention to the fact that they’re a concrete type of resource within
|
||||||
|
the API - e.g. `PersistentVolumeClaim`.
|
||||||
|
|
||||||
|
Crossplane follows this convention. We often use names like RDSInstance or
|
||||||
|
CompositeResourceDefinition when discussing Crossplane types. Crossplane also
|
||||||
|
has “classes of types” - i.e. concepts that aren’t a distinct type of API
|
||||||
|
resource, but rather describe a group of conceptually similar types. For example
|
||||||
|
there is no ManagedResource type in Crossplane - instead types like RDSInstance
|
||||||
|
and GKECluster are said to be “a managed resource”.
|
||||||
|
|
||||||
|
Use your discretion as to whether you use pascal case when writing about a
|
||||||
|
distinct type - e.g. “RDS Instance” and “RDSInstance” are both fine. The pascal
|
||||||
|
case form makes more sense in contexts like documentation where you’re referring
|
||||||
|
to Crossplane’s RDSInstance managed resource rather than the general concept of
|
||||||
|
“an RDS instance”. Avoid using Pascal case when talking about classes of types -
|
||||||
|
i.e. always write “managed resource”, not “ManagedResource”. Each of the below
|
||||||
|
terms clarify whether they correspond to a single type, or a class of types.
|
||||||
|
|
||||||
|
### Why 'X'?
|
||||||
|
|
||||||
|
You may notice that Crossplane uses “X” as shorthand for “Crossplane” and/or
|
||||||
|
“Composite”. This is because some of our concepts - specifically Composite
|
||||||
|
Resources (XRs) and Composite Resource Definitions (XRDs) are modelled on
|
||||||
|
similar Kubernetes concepts - Custom Resources (CRs) and Custom Resource
|
||||||
|
Definitions (CRDs). We chose to abbreviate to (e.g.) XRD instead of CRD to avoid
|
||||||
|
confusion.
|
||||||
|
|
||||||
|
## Crossplane Terms
|
||||||
|
|
||||||
|
The below terms are commonly used in the Crossplane ecosystem.
|
||||||
|
|
||||||
|
### Composition
|
||||||
|
|
||||||
|
The term Composition has two related but distinct meanings.
|
||||||
|
|
||||||
|
“Composition” refers broadly to the feature of Crossplane that allows teams to
|
||||||
|
define their own opinionated platform APIs.
|
||||||
|
|
||||||
|
“A Composition” or `Composition` (fixed width) refers to the key Crossplane API
|
||||||
|
type that configures how Crossplane should compose resources into a higher level
|
||||||
|
“composite resource”. A Composition tells Crossplane “when someone creates
|
||||||
|
composite resource X, you should respond by creating resources Y and Z”.
|
||||||
|
|
||||||
|
The latter use of Composition represents a distinct Crossplane API type so
|
||||||
|
Pascal case and fixed width fonts are appropriate. We also tend to capitalise
|
||||||
|
the former use, representing the feature in general, but fixed width fonts are
|
||||||
|
not appropriate in that context.
|
||||||
|
|
||||||
|
> Folks accustomed to Terraform might think of a Composition as a Terraform
|
||||||
|
> module; the HCL code that describes how to take input variables and use them
|
||||||
|
> to create resources in some cloud API. Folks accustomed to Helm might think of
|
||||||
|
> a Composition as a Helm chart’s templates; the moustache templated YAML files
|
||||||
|
> that describe how to take Helm chart values and render Kubernetes resources.
|
||||||
|
|
||||||
|
### Composite Resource
|
||||||
|
|
||||||
|
A “Composite Resource” or “XR” is an API type defined using Crossplane. A
|
||||||
|
composite resource’s API type is arbitrary - dictated by the concept the author
|
||||||
|
wishes to expose as an API, for example an “AcmeCoDB”. A common convention is
|
||||||
|
for types to start with the word “Composite” - e.g. “CompositeAcmeCoDB”.
|
||||||
|
|
||||||
|
We talk about Crossplane being a tool teams can use to define their own
|
||||||
|
opinionated platform APIs. Those APIs are made up of composite resources; when
|
||||||
|
you are interacting with an API that your platform team has defined, you’re
|
||||||
|
interacting with composite resources.
|
||||||
|
|
||||||
|
A composite resource can be thought of as the interface to a Composition. It
|
||||||
|
provides the inputs a Composition uses to compose resources into a higher level
|
||||||
|
concept. In fact, the composite resource _is_ the high level concept.
|
||||||
|
|
||||||
|
The term “Composite Resource” refers to a class of types, so avoid using Pascal
|
||||||
|
case - “Composite Resource” not CompositeResource. Use pascal case when
|
||||||
|
referring to a distinct type of composite resource - e.g. a CompositeAcmeCoDB.
|
||||||
|
|
||||||
|
> Folks accustomed to Terraform might think of a composite resource as a
|
||||||
|
> `tfvars` file that supplies values for the variables a Terraform module uses
|
||||||
|
> to create resources in some cloud API. Folks accustomed to Helm might think of
|
||||||
|
> a composite resource as the `values.yaml` file that supplies inputs to a Helm
|
||||||
|
> chart’s templates.
|
||||||
|
|
||||||
|
### Composite Resource Claim
|
||||||
|
|
||||||
|
A “Composite Resource Claim”, “XRC”, or just “a claim” is also an API type
|
||||||
|
defined using Crossplane. Each type of claim corresponds to a type of composite
|
||||||
|
resource, and the pair have nearly identical schemas. Like composite resources,
|
||||||
|
the type of a claim is arbitrary.
|
||||||
|
|
||||||
|
We talk about Crossplane being a tool platform teams can use to offer
|
||||||
|
opinionated platform APIs to the application teams they support. The platform
|
||||||
|
team offers those APIs using claims. It helps to think of the claim as an
|
||||||
|
application team’s interface to a composite resource. You could also think of
|
||||||
|
claims as the public (app team) facing part of the opinionated platform API,
|
||||||
|
while composite resources are the private (platform team) facing part.
|
||||||
|
|
||||||
|
A common convention is for a claim to be of the same type as its corresponding
|
||||||
|
composite resource, but without the "Composite" prefix. So an "AcmeCoDB" would
|
||||||
|
be a type of claim, and a "CompositeAcmeCoDB" would be the corresponding type of
|
||||||
|
composite resource. This allows claim consumers to be relatively ignorant of
|
||||||
|
Crossplane and composition, and to instead simply think about managing “an
|
||||||
|
AcmeCo DB” while the platform team worries about the implementation details.
|
||||||
|
|
||||||
|
The term “Composite Resource Claim” refers to a class of types, so avoid using
|
||||||
|
Pascal case - “Composite Resource Claim” not CompositeResourceClaim. Use Pascal
|
||||||
|
case when referring to a distinct type of composite resource claim - e.g. an
|
||||||
|
AcmeCoDB.
|
||||||
|
|
||||||
|
> Claims map to the same concepts as described above under the composite
|
||||||
|
> resource heading; i.e. `tfvars` files and Helm `values.yaml` files. Imagine
|
||||||
|
> that some `tfvars` files and some `values.yaml` files were only accessible to
|
||||||
|
> the platform team while others were offered to application teams; that’s the
|
||||||
|
> difference between a composite resource and a claim.
|
||||||
|
|
||||||
|
### Composite Resource Definition
|
||||||
|
|
||||||
|
A “Composite Resource Definition” or “XRD” is the API type used to define new
|
||||||
|
types of composite resources and claims. Types of composite resources and types
|
||||||
|
of claims exist because they were defined into existence by an XRD. The XRD
|
||||||
|
configures Crossplane with support for the composite resources and claims that
|
||||||
|
make up a platform API.
|
||||||
|
|
||||||
|
XRDs are often conflated with composite resources (XRs) - try to avoid this.
|
||||||
|
When someone uses the platform API to create infrastructure they’re not creating
|
||||||
|
XRDs but rather creating composite resources (XRs). It may help to think of a
|
||||||
|
composite resource as a database entry, while an XRD is a database schema. For
|
||||||
|
those familiar with Kubernetes, the relationship is very similar to that between
|
||||||
|
a Custom Resource Definition (CRD) and a Custom Resource (CR).
|
||||||
|
|
||||||
|
A `CompositeResourceDefinition` is a distinct Crossplane API type, so Pascal
|
||||||
|
case and fixed width fonts are appropriate.
|
||||||
|
|
||||||
|
> There isn’t a direct analog to XRDs in the Helm ecosystem, but they’re a
|
||||||
|
> little bit like the variable blocks in a Terraform module that define which
|
||||||
|
> variables exist, whether those variables are strings or integers, whether
|
||||||
|
> they’re required or optional, etc.
|
||||||
|
|
||||||
|
### Managed Resource
|
||||||
|
|
||||||
|
Managed resources are granular, high fidelity Crossplane representations of a
|
||||||
|
resource in an external system - i.e. resources that are managed by Crossplane.
|
||||||
|
Managed resources are what Crossplane enables platform teams to compose into
|
||||||
|
higher level composite resources, forming an opinionated platform API. They're
|
||||||
|
the building blocks of Crossplane.
|
||||||
|
|
||||||
|
You’ll often hear three related terms used in the Crossplane ecosystem; composed
|
||||||
|
resource, managed resource, and external resource. While there are some subtle
|
||||||
|
contextual differences, these all broadly refer to the same thing. Take an
|
||||||
|
RDSInstance for example; it is a managed resource. A distinct resource within
|
||||||
|
the Crossplane API that represents an AWS RDS instance. When we make a
|
||||||
|
distinction between the managed resource and an external resource we’re simply
|
||||||
|
making the distinction between Crossplane’s representation of the thing (the
|
||||||
|
`RDSInstance` in the Kubernetes API), and the actual thing in whatever external
|
||||||
|
system Crossplane is orchestrating (the RDS instance in AWS's API). When we
|
||||||
|
mention composed resources, we mean a managed resource of which a composite
|
||||||
|
resource is composed.
|
||||||
|
|
||||||
|
Managed resources are a class of resource, so avoid using Pascal case - “managed
|
||||||
|
resource” not “ManagedResource”.
|
||||||
|
|
||||||
|
> Managed resources are similar to Terraform resource blocks, or a distinct
|
||||||
|
> Kubernetes resource within a Helm chart.
|
||||||
|
|
||||||
|
### Package
|
||||||
|
|
||||||
|
Packages extend Crossplane, either with support for new kinds of composite
|
||||||
|
resources and claims, or support for new kinds of managed resources. There are
|
||||||
|
two types of Crossplane package; configurations and providers.
|
||||||
|
|
||||||
|
A package is not a distinct type in the Crossplane API, but rather a class of
|
||||||
|
types. Therefore Pascal case is not appropriate.
|
||||||
|
|
||||||
|
### Configuration
|
||||||
|
|
||||||
|
A configuration extends Crossplane by installing conceptually related groups of
|
||||||
|
XRDs and Compositions, as well as dependencies like providers or further
|
||||||
|
configurations. Put otherwise, it configures the opinionated platform API
|
||||||
|
that Crossplane exposes.
|
||||||
|
|
||||||
|
A `Configuration` is a distinct type in the Crossplane API, therefore Pascal
|
||||||
|
case and fixed width fonts are appropriate.
|
||||||
|
|
||||||
|
### Provider
|
||||||
|
|
||||||
|
A provider extends Crossplane by installing controllers for new kinds of managed
|
||||||
|
resources. Providers typically group conceptually related managed resources; for
|
||||||
|
example the AWS provider installs support for AWS managed resources like
|
||||||
|
RDSInstance and S3Bucket.
|
||||||
|
|
||||||
|
A `Provider` is a distinct type in the Crossplane API, therefore Pascal case and
|
||||||
|
fixed width fonts are appropriate. Note that each Provider package has its own
|
||||||
|
configuration type, called a `ProviderConfig`. Don’t confuse the two; the former
|
||||||
|
installs the provider while the latter specifies configuration that is relevant
|
||||||
|
to all of its managed resources.
|
||||||
|
|
||||||
|
> Providers are directly analogous to Terraform providers.
|
||||||
|
|
||||||
|
### Crossplane Resource Model
|
||||||
|
|
||||||
|
The Crossplane Resource Model or XRM is neither a distinct Crossplane API type,
|
||||||
|
or a class of types. Rather it represents the fact that Crossplane has a
|
||||||
|
consistent, opinionated API. The strict definition of the XRM is currently
|
||||||
|
somewhat vague, but it could broadly be interpreted as a catchall term referring
|
||||||
|
to all of the concepts mentioned on this page.
|
||||||
Loading…
Reference in New Issue