crossplane
/
docs
mirror of https://github.com/crossplane/docs.git
1
0
Fork 0
Code Issues Packages Projects Releases Wiki Activity

Compare commits

base: crossplane:master
Branches Tags
crossplane:master
crossplane:provider-version
crossplane:nav-poc
crossplane:jeanduplessis-patch-1-1
crossplane:v1.17-archive
crossplane:v1.16-archive
crossplane:v1.13-archive
crossplane:v1.12-archive
crossplane:v1.11-archive
crossplane:v1.10-architve
crossplane:v1.9-archive
crossplane:v1.8-archive
..
compare: crossplane:v1.16-archive
Branches Tags
crossplane:master
crossplane:provider-version
crossplane:nav-poc
crossplane:jeanduplessis-patch-1-1
crossplane:v1.17-archive
crossplane:v1.16-archive
crossplane:v1.13-archive
crossplane:v1.12-archive
crossplane:v1.11-archive
crossplane:v1.10-architve
crossplane:v1.9-archive
crossplane:v1.8-archive

No commits in common. "master" and "v1.16-archive" have entirely different histories.
master ... v1.16-arch

287 changed files with 11686 additions and 41211 deletions
Show Stats Expand all files Collapse all files

5
.github/ISSUE_TEMPLATE/new_release.md vendored
View File

@ -7,9 +7,8 @@ labels: release
- [ ] Update the `$LATEST_VER` parameter in [netlify_build.sh](https://github.com/crossplane/docs/blob/master/netlify_build.sh#L3)
- [ ] Update `params.latest` in [config.yaml](https://github.com/crossplane/docs/blob/master/config.yaml#L93)
- [ ] Copy Crossplane [cluster/crds](https://github.com/crossplane/crossplane/tree/main/cluster/crds) contents to `/content/master/api/crds`
- [ ] Copy `/content/master` directory to `/content/<new latest>`
- [ ] Update `version` in the `_index.md` file of `/content/<new latest>` from `master` to the correct version.
- [ ] Create a [new release/tag](https://github.com/crossplane/docs/releases/new) named `v<EOL version>-archive` to snapshot EOL'd docs.
- [ ] Copy Crossplane [cluster/crds](https://github.com/crossplane/crossplane/tree/main/cluster/crds) contents to `/content/<new latest>/api/crds`.
- [ ] Create a [new release/tag](https://github.com/crossplane/docs/releases/new) named "v<EOL version>-archive" to snapshot EOL'd docs.
- [ ] Remove EOL'd docs version from "/content" directory and run `hugo` locally to check for broken links.
- [ ] Trigger [Algolia Crawler](https://crawler.algolia.com/) after publishing to reindex results.

20
OWNERS.md
View File

@ -10,23 +10,21 @@ guidelines and responsibilities for the steering committee and maintainers.
The Maintainers and Reviewers mirror the [crossplane/crossplane OWNERS](https://github.com/crossplane/crossplane/blob/main/OWNERS.md) with the following changes:
* Jared Watts <jared@upbound.io> ([jbw976](https://github.com/jbw976)) as a maintainer
* Pete Lumbis <pete@upbound.io> ([plumbis](https://github.com/plumbis)) as a maintainer
* Michael Goff <michael@upbound.io> ([thephred](https://github.com/thephred)) as a maintainer
* Jean du Plessis <jean@upbound.io> ([jeanduplessis](https://github.com/jeanduplessis)) as a maintainer
* Rae Sharp <rae@upbound.io> ([tr0njavolta](https://github.com/tr0njavolta)) as a maintainer
* Jean du Plessis <jean@upbound.io> ([jeanduplessis](https://github.com/jeanduplessis) as a maintainer
## Maintainers
* Nic Cope <negz@upbound.io> ([negz](https://github.com/negz))
* Hasan Turken <hasan@upbound.io> ([turkenh](https://github.com/turkenh))
* Bob Haddleton <bob.haddleton@nokia.com> ([bobh66](https://github.com/bobh66))
* Philippe Scorsolini <philippe.scorsolini@upbound.io> ([phisco](https://github.com/phisco))
* Jared Watts <jared@upbound.io> ([jbw976](https://github.com/jbw976))
* Pete Lumbis <pete@upbound.io> ([plumbis](https://github.com/plumbis))
* Michael Goff <michael@upbound.io> ([thephred](https://github.com/thephred))
* Jean du Plessis <jean@upbound.io> ([jeanduplessis](https://github.com/jeanduplessis))
* Rae Sharp <rae@upbound.io> ([tr0njavolta](https://github.com/tr0njavolta))
* Nic Cope <negz@upbound.io> ([negz](https://github.com/negz))
* Pete Lumbis <pete@upbound.io> ([plumbis](https://github.com/plumbis))
* Muvaffak Onus <monus@upbound.io> ([muvaf](https://github.com/muvaf))
* Hasan Turken <hasan@upbound.io> ([turkenh](https://github.com/turkenh))
* Jean du Plessis <jean@upbound.io> ([jeanduplessis](https://github.com/jeanduplessis)
## Reviewers
@ -34,10 +32,10 @@ The Maintainers and Reviewers mirror the [crossplane/crossplane OWNERS](https://
* Daren Iott <daren@upbound.io> ([nullable-eth](https://github.com/nullable-eth))
* Ezgi Demirel <ezgi@upbound.io> ([ezgidemirel](https://github.com/ezgidemirel))
* Max Blatt ([MisterMX](https://github.com/MisterMX))
* Philippe Scorsolini <philippe.scorsolini@upbound.io> ([phisco](https://github.com/phisco))
* Lovro Sviben <lovro.sviben@upbound.io> ([lsviben](https://github.com/lsviben))
## Emeritus maintainers
* Connor Chan <connor@upbound.io> ([connorchan](https://github.com/connorchan))
* Daniel Mangum <dan@upbound.io> ([hasheddan](https://github.com/hasheddan))
* Muvaffak Onus <monus@upbound.io> ([muvaf](https://github.com/muvaf))
* Daniel Mangum <dan@upbound.io> ([hasheddan](https://github.com/hasheddan))

2
config.yaml
View File

@ -90,7 +90,7 @@ security:
# Global parameters accessible by any Page
params:
# The current "latest" version. Used in the version dropdown
latest: "1.20"
latest: "1.18"
docs: true
anchors:
# Generate heading anchors for any heading between min and max

9
content/contribute/_index.md
View File

@ -11,7 +11,7 @@ The Crossplane Contributing Guide is for anyone interested in contributing to
the Crossplane documentation.
Information on contributing to the Crossplane software project is in the
Crossplane
Crossplane
[`CONTRIBUTING.md`](https://github.com/crossplane/crossplane/blob/main/CONTRIBUTING.md)
file.
@ -24,7 +24,7 @@ Taken directly from the code:
>fostering an open and welcoming community, we pledge to respect all people who
>contribute through reporting issues, posting feature requests, updating
>documentation, submitting pull requests or patches, and other activities.
>
>
>We are committed to making participation in the CNCF community a
>harassment-free experience for everyone, regardless of level of experience,
>gender, gender identity and expression, sexual orientation, disability,
@ -32,16 +32,17 @@ Taken directly from the code:
<!-- vale on -->
## Reporting violations
To report violations contact the Crossplane maintainers at `crossplane-info@lists.cncf.io`
To report violations contact the Crossplane maintainers at `info@crossplane.io`
or the CNCF at `conduct@cncf.io`.
All the information needed to contribute to the Crossplane documentation is
here.
* Read [contributing to the docs]({{< ref "contribute" >}}) for information
about the docs repository, cloning and local development.
* The [writing style guide]({{< ref "writing-style-guide" >}}) describes the
guidelines for language, spelling and language style.
guidelines for language, spelling and language style.
* The [code styling guide]({{< ref "code-style-guide" >}}) covers the Crossplane guidelines
specific to including code blocks in docs to provide the best reader
experience.

2
content/contribute/features.md
View File

@ -195,7 +195,7 @@ without using the
For example,
```markdown
[Go to Crossplane](http://crossplane.io)
[Go to Upbound](http://upbound.io)
```
## Tables

1
content/contribute/infrastructure.md
View File

@ -390,7 +390,6 @@ Expand the tab below to see an annotated `tree` output of the website repository
│   │   │   ├── meta-common.html # <meta> tags used on all pages
│   │   │   ├── ms-clarity.html # Microsoft Clarity tags
│   │   │   ├── old-version-alert.html # Alert box for versions that aren't the latest
│   │   │   ├── preview-version-alert.html # Alert box for preview versions
│   │   │   ├── redirect.html # HTML meta redirect
│   │   │   ├── release-notes.html # Release note summary page generator
│   │   │   ├── rollworks.html # Rollworks analytics tags

197
content/master/api/crds/apiextensions.crossplane.io_usages.yaml
View File

@ -213,200 +213,3 @@ spec:
storage: true
subresources:
status: {}
- additionalPrinterColumns:
- jsonPath: .metadata.annotations.crossplane\.io/usage-details
name: DETAILS
type: string
- jsonPath: .status.conditions[?(@.type=='Ready')].status
name: READY
type: string
- jsonPath: .metadata.creationTimestamp
name: AGE
type: date
name: v1beta1
schema:
openAPIV3Schema:
description: |-
A Usage defines a deletion blocking relationship between two resources.
Usages prevent accidental deletion of a single resource or deletion of
resources with dependent resources.
Read the Crossplane documentation for
[more information about Compositions](https://docs.crossplane.io/latest/concepts/usages).
properties:
apiVersion:
description: |-
APIVersion defines the versioned schema of this representation of an object.
Servers should convert recognized schemas to the latest internal value, and
may reject unrecognized values.
More info: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#resources
type: string
kind:
description: |-
Kind is a string value representing the REST resource this object represents.
Servers may infer this from the endpoint the client submits requests to.
Cannot be updated.
In CamelCase.
More info: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#types-kinds
type: string
metadata:
type: object
spec:
description: UsageSpec defines the desired state of Usage.
properties:
by:
description: By is the resource that is "using the other resource".
properties:
apiVersion:
description: API version of the referent.
type: string
kind:
description: |-
Kind of the referent.
More info: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#types-kinds
type: string
resourceRef:
description: Reference to the resource.
properties:
name:
description: Name of the referent.
type: string
required:
- name
type: object
resourceSelector:
description: |-
Selector to the resource.
This field will be ignored if ResourceRef is set.
properties:
matchControllerRef:
description: |-
MatchControllerRef ensures an object with the same controller reference
as the selecting object is selected.
type: boolean
matchLabels:
additionalProperties:
type: string
description: MatchLabels ensures an object with matching labels
is selected.
type: object
type: object
type: object
x-kubernetes-validations:
- message: either a resource reference or a resource selector should
be set.
rule: has(self.resourceRef) || has(self.resourceSelector)
of:
description: Of is the resource that is "being used".
properties:
apiVersion:
description: API version of the referent.
type: string
kind:
description: |-
Kind of the referent.
More info: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#types-kinds
type: string
resourceRef:
description: Reference to the resource.
properties:
name:
description: Name of the referent.
type: string
required:
- name
type: object
resourceSelector:
description: |-
Selector to the resource.
This field will be ignored if ResourceRef is set.
properties:
matchControllerRef:
description: |-
MatchControllerRef ensures an object with the same controller reference
as the selecting object is selected.
type: boolean
matchLabels:
additionalProperties:
type: string
description: MatchLabels ensures an object with matching labels
is selected.
type: object
type: object
type: object
x-kubernetes-validations:
- message: either a resource reference or a resource selector should
be set.
rule: has(self.resourceRef) || has(self.resourceSelector)
reason:
description: Reason is the reason for blocking deletion of the resource.
type: string
replayDeletion:
description: ReplayDeletion will trigger a deletion on the used resource
during the deletion of the usage itself, if it was attempted to
be deleted at least once.
type: boolean
required:
- of
type: object
x-kubernetes-validations:
- message: either "spec.by" or "spec.reason" must be specified.
rule: has(self.by) || has(self.reason)
status:
description: UsageStatus defines the observed state of Usage.
properties:
conditions:
description: Conditions of the resource.
items:
description: A Condition that may apply to a resource.
properties:
lastTransitionTime:
description: |-
LastTransitionTime is the last time this condition transitioned from one
status to another.
format: date-time
type: string
message:
description: |-
A Message containing details about this condition's last transition from
one status to another, if any.
type: string
observedGeneration:
description: |-
ObservedGeneration represents the .metadata.generation that the condition was set based upon.
For instance, if .metadata.generation is currently 12, but the .status.conditions[x].observedGeneration is 9, the condition is out of date
with respect to the current state of the instance.
format: int64
type: integer
reason:
description: A Reason for this condition's last transition from
one status to another.
type: string
status:
description: Status of this condition; is it currently True,
False, or Unknown?
type: string
type:
description: |-
Type of this condition. At most one of each condition type may apply to
a resource at any point in time.
type: string
required:
- lastTransitionTime
- reason
- status
- type
type: object
type: array
x-kubernetes-list-map-keys:
- type
x-kubernetes-list-type: map
type: object
required:
- spec
type: object
served: true
storage: false
subresources:
status: {}

27
content/master/api/crds/pkg.crossplane.io_configurationrevisions.yaml
View File

@ -146,27 +146,6 @@ spec:
description: PackageRevisionStatus represents the observed state of a
PackageRevision.
properties:
appliedImageConfigRefs:
description: |-
AppliedImageConfigRefs records any image configs that were applied in
reconciling this revision, and what they were used for.
items:
description: |-
ImageConfigRef is a reference to an image config that indicates how the
referenced image config was used by the package manager.
properties:
name:
description: Name is the name of the image config.
type: string
reason:
description: Reason indicates what the image config was used
for.
type: string
required:
- name
- reason
type: object
type: array
conditions:
description: Conditions of the resource.
items:
@ -302,12 +281,6 @@ spec:
- verbs
type: object
type: array
resolvedImage:
description: |-
ResolvedPackage is the name of the package that was installed. It may be
different from spec.image if the package path was rewritten using an
image config.
type: string
type: object
type: object
served: true

27
content/master/api/crds/pkg.crossplane.io_configurations.yaml
View File

@ -138,27 +138,6 @@ spec:
status:
description: ConfigurationStatus represents the observed state of a Configuration.
properties:
appliedImageConfigRefs:
description: |-
AppliedImageConfigRefs records any image configs that were applied in
reconciling this package, and what they were used for.
items:
description: |-
ImageConfigRef is a reference to an image config that indicates how the
referenced image config was used by the package manager.
properties:
name:
description: Name is the name of the image config.
type: string
reason:
description: Reason indicates what the image config was used
for.
type: string
required:
- name
- reason
type: object
type: array
conditions:
description: Conditions of the resource.
items:
@ -220,12 +199,6 @@ spec:
reflect the most up to date revision, whether it has been activated or
not.
type: string
resolvedPackage:
description: |-
ResolvedPackage is the name of the package that was used for version
resolution. It may be different from spec.package if the package path was
rewritten using an image config.
type: string
type: object
type: object
served: true

54
content/master/api/crds/pkg.crossplane.io_functionrevisions.yaml
View File

@ -189,27 +189,6 @@ spec:
description: FunctionRevisionStatus represents the observed state of a
FunctionRevision.
properties:
appliedImageConfigRefs:
description: |-
AppliedImageConfigRefs records any image configs that were applied in
reconciling this revision, and what they were used for.
items:
description: |-
ImageConfigRef is a reference to an image config that indicates how the
referenced image config was used by the package manager.
properties:
name:
description: Name is the name of the image config.
type: string
reason:
description: Reason indicates what the image config was used
for.
type: string
required:
- name
- reason
type: object
type: array
conditions:
description: Conditions of the resource.
items:
@ -350,12 +329,6 @@ spec:
- verbs
type: object
type: array
resolvedImage:
description: |-
ResolvedPackage is the name of the package that was installed. It may be
different from spec.image if the package path was rewritten using an
image config.
type: string
type: object
type: object
served: true
@ -534,27 +507,6 @@ spec:
description: FunctionRevisionStatus represents the observed state of a
FunctionRevision.
properties:
appliedImageConfigRefs:
description: |-
AppliedImageConfigRefs records any image configs that were applied in
reconciling this revision, and what they were used for.
items:
description: |-
ImageConfigRef is a reference to an image config that indicates how the
referenced image config was used by the package manager.
properties:
name:
description: Name is the name of the image config.
type: string
reason:
description: Reason indicates what the image config was used
for.
type: string
required:
- name
- reason
type: object
type: array
conditions:
description: Conditions of the resource.
items:
@ -695,12 +647,6 @@ spec:
- verbs
type: object
type: array
resolvedImage:
description: |-
ResolvedPackage is the name of the package that was installed. It may be
different from spec.image if the package path was rewritten using an
image config.
type: string
type: object
type: object
served: true

54
content/master/api/crds/pkg.crossplane.io_functions.yaml
View File

@ -168,27 +168,6 @@ spec:
status:
description: FunctionStatus represents the observed state of a Function.
properties:
appliedImageConfigRefs:
description: |-
AppliedImageConfigRefs records any image configs that were applied in
reconciling this package, and what they were used for.
items:
description: |-
ImageConfigRef is a reference to an image config that indicates how the
referenced image config was used by the package manager.
properties:
name:
description: Name is the name of the image config.
type: string
reason:
description: Reason indicates what the image config was used
for.
type: string
required:
- name
- reason
type: object
type: array
conditions:
description: Conditions of the resource.
items:
@ -250,12 +229,6 @@ spec:
reflect the most up to date revision, whether it has been activated or
not.
type: string
resolvedPackage:
description: |-
ResolvedPackage is the name of the package that was used for version
resolution. It may be different from spec.package if the package path was
rewritten using an image config.
type: string
type: object
type: object
served: true
@ -413,27 +386,6 @@ spec:
status:
description: FunctionStatus represents the observed state of a Function.
properties:
appliedImageConfigRefs:
description: |-
AppliedImageConfigRefs records any image configs that were applied in
reconciling this package, and what they were used for.
items:
description: |-
ImageConfigRef is a reference to an image config that indicates how the
referenced image config was used by the package manager.
properties:
name:
description: Name is the name of the image config.
type: string
reason:
description: Reason indicates what the image config was used
for.
type: string
required:
- name
- reason
type: object
type: array
conditions:
description: Conditions of the resource.
items:
@ -495,12 +447,6 @@ spec:
reflect the most up to date revision, whether it has been activated or
not.
type: string
resolvedPackage:
description: |-
ResolvedPackage is the name of the package that was used for version
resolution. It may be different from spec.package if the package path was
rewritten using an image config.
type: string
type: object
type: object
served: true

25
content/master/api/crds/pkg.crossplane.io_imageconfigs.yaml
View File

@ -47,19 +47,13 @@ spec:
description: ImageConfigSpec contains the configuration for matching images.
properties:
matchImages:
description: |-
MatchImages is a list of image matching rules. This ImageConfig will
match an image if any one of these rules is satisfied. In the case where
multiple ImageConfigs match an image for a given purpose the one with the
most specific match will be used. If multiple rules of equal specificity
match an arbitrary one will be selected.
description: MatchImages is a list of image matching rules that should
be satisfied.
items:
description: ImageMatch defines a rule for matching image.
properties:
prefix:
description: |-
Prefix is the prefix that should be matched. When multiple prefix rules
match an image path, the longest one takes precedence.
description: Prefix is the prefix that should be matched.
type: string
type:
default: Prefix
@ -101,19 +95,6 @@ spec:
- pullSecretRef
type: object
type: object
rewriteImage:
description: RewriteImage defines how a matched image's path should
be rewritten.
properties:
prefix:
description: |-
Prefix is the prefix that will replace the portion of the image's path
matched by the prefix in the ImageMatch. If multiple prefixes matched,
the longest one will be replaced.
type: string
required:
- prefix
type: object
verification:
description: Verification contains the configuration for verifying
the image.

33
content/master/api/crds/pkg.crossplane.io_locks.yaml
View File

@ -44,9 +44,6 @@ spec:
items:
description: LockPackage is a package that is in the lock.
properties:
apiVersion:
description: APIVersion of the package.
type: string
dependencies:
description: |-
Dependencies are the list of dependencies of this package. The order of
@ -55,39 +52,25 @@ spec:
description: A Dependency is a dependency of a package in the
lock.
properties:
apiVersion:
description: APIVersion of the package.
type: string
constraints:
description: |-
Constraints is a valid semver range or a digest, which will be used to select a valid
dependency version.
type: string
kind:
description: Kind of the package (not the kind of the package
revision).
type: string
package:
description: Package is the OCI image name without a tag or
digest.
type: string
type:
description: |-
Type is the type of package. Can be either Configuration or Provider.
Deprecated: Specify an apiVersion and kind instead.
enum:
- Configuration
- Provider
- Function
description: Type is the type of package. Can be either Configuration
or Provider.
type: string
required:
- constraints
- package
- type
type: object
type: array
kind:
description: Kind of the package (not the kind of the package revision).
type: string
name:
description: Name corresponds to the name of the package revision
for this package.
@ -96,13 +79,8 @@ spec:
description: Source is the OCI image name without a tag or digest.
type: string
type:
description: |-
Type is the type of package.
Deprecated: Specify an apiVersion and kind instead.
enum:
- Configuration
- Provider
- Function
description: Type is the type of package. Can be either Configuration
or Provider.
type: string
version:
description: Version is the tag or digest of the OCI image.
@ -111,6 +89,7 @@ spec:
- dependencies
- name
- source
- type
- version
type: object
type: array

27
content/master/api/crds/pkg.crossplane.io_providerrevisions.yaml
View File

@ -189,27 +189,6 @@ spec:
description: PackageRevisionStatus represents the observed state of a
PackageRevision.
properties:
appliedImageConfigRefs:
description: |-
AppliedImageConfigRefs records any image configs that were applied in
reconciling this revision, and what they were used for.
items:
description: |-
ImageConfigRef is a reference to an image config that indicates how the
referenced image config was used by the package manager.
properties:
name:
description: Name is the name of the image config.
type: string
reason:
description: Reason indicates what the image config was used
for.
type: string
required:
- name
- reason
type: object
type: array
conditions:
description: Conditions of the resource.
items:
@ -345,12 +324,6 @@ spec:
- verbs
type: object
type: array
resolvedImage:
description: |-
ResolvedPackage is the name of the package that was installed. It may be
different from spec.image if the package path was rewritten using an
image config.
type: string
type: object
type: object
served: true

27
content/master/api/crds/pkg.crossplane.io_providers.yaml
View File

@ -170,27 +170,6 @@ spec:
status:
description: ProviderStatus represents the observed state of a Provider.
properties:
appliedImageConfigRefs:
description: |-
AppliedImageConfigRefs records any image configs that were applied in
reconciling this package, and what they were used for.
items:
description: |-
ImageConfigRef is a reference to an image config that indicates how the
referenced image config was used by the package manager.
properties:
name:
description: Name is the name of the image config.
type: string
reason:
description: Reason indicates what the image config was used
for.
type: string
required:
- name
- reason
type: object
type: array
conditions:
description: Conditions of the resource.
items:
@ -252,12 +231,6 @@ spec:
reflect the most up to date revision, whether it has been activated or
not.
type: string
resolvedPackage:
description: |-
ResolvedPackage is the name of the package that was used for version
resolution. It may be different from spec.package if the package path was
rewritten using an image config.
type: string
type: object
type: object
served: true

19
content/master/cli/_index.md
View File

@ -61,21 +61,4 @@ By default the CLI installs from the `XP_CHANNEL` named `stable` and the
For example, to install CLI version `v1.14.0` add `XP_VERSION=v1.14.0` to the
download script curl command:
`curl -sL "https://raw.githubusercontent.com/crossplane/crossplane/main/install.sh" | XP_VERSION=v1.14.0 sh`
## Installing shell autocompletions
The Crossplane CLI supports shell autocompletions for `bash`, `zsh` and `fish`.
You can install the autocompletions with the `completions` command by adding it to
your shell's configuration file.
```shell
source <(crossplane completions)
```
{{<hint "note" >}}
The `completions` command generates the autocompletions for your default shell.
It's not possible to generate autocompletions for a different shell, if you want to
install the autocompletions for a different shell, you have to configure the Crossplane
CLI as the completer manually.
{{< /hint >}}
`curl -sL "https://raw.githubusercontent.com/crossplane/crossplane/main/install.sh" | XP_VERSION=v1.14.0 sh`

43
content/master/cli/command-reference.md
View File

@ -240,6 +240,9 @@ For example,
Include YAML files demonstrating how to use the package with `--examples-root`.
[Upbound Marketplace](https://marketplace.upbound.io/) uses files included with
`--examples-root` as documentation for published packages.
#### Include a runtime image
Functions and Providers require YAML files describing their dependencies and
@ -322,10 +325,10 @@ inside Crossplane.
The `<package-kind>` is either a `configuration`, `function` or `provider`.
For example, to install the latest version of the
[AWS S3 provider](https://github.com/crossplane-contrib/provider-upjet-aws):
For example, to install the latest version of the
[AWS S3 provider](https://marketplace.upbound.io/providers/upbound/provider-aws-s3/):
`crossplane xpkg install provider xpkg.crossplane.io/crossplane-contrib/provider-aws-s3:v1.21.1`
`crossplane xpkg install provider xpkg.upbound.io/upbound/provider-aws-s3:v1`
#### Flags
{{< table "table table-sm table-striped">}}
@ -377,7 +380,11 @@ in the package documentation.
### xpkg login
Use `xpkg login` to authenticate to registries that host Crossplane packages.
Use `xpkg login` to authenticate to `xpkg.upbound.io`, the
[Upbound Marketplace](https://marketplace.upbound.io/) container registry.
[Register with the Upbound Marketplace](https://accounts.upbound.io/register)
to push packages and create private repositories.
#### Flags
@ -444,6 +451,10 @@ Using `crossplane xpkg logout` removes the `session` from the
Push a Crossplane package file to a package registry.
The Crossplane CLI pushes images to the
[Upbound Marketplace](https://marketplace.upbound.io/) at `xpkg.upbound.io` by
default.
{{< hint "note" >}}
Pushing a package may require authentication with
[`crossplane xpkg login`](#xpkg-login)
@ -493,10 +504,13 @@ already installed in Crossplane.
`crossplane xpkg update <package-kind> <registry package name and tag> [<optional-name>]`
For example, to update to the latest version of the
[AWS S3 provider](https://github.com/crossplane-contrib/provider-upjet-aws):
The package file must be an organization, image and tag on the `xpkg.upbound.io`
registry on [Upbound Marketplace](https://marketplace.upbound.io/).
`crossplane xpkg update provider xpkg.crossplane.io/crossplane-contrib/provider-aws-s3:v1.21.1`
For example, to update to the latest version of the
[AWS S3 provider](https://marketplace.upbound.io/providers/upbound/provider-aws-s3/):
`crossplane xpkg update provider xpkg.upbound.io/upbound/provider-aws-s3:v1`
## beta
@ -555,11 +569,11 @@ related pods.
```shell
crossplane beta top
TYPE NAMESPACE NAME CPU(cores) MEMORY
crossplane default crossplane-f98f9ddfd-tnm46 4m 32Mi
crossplane default crossplane-rbac-manager-74ff459b88-94p8p 4m 14Mi
provider default provider-aws-s3-1f1a3fb08cbc-5c49d84447-sggrq 3m 108Mi
provider default crossplane-contrib-provider-family-aws-48b3b5ccf964-76c9686b6-bgg65 2m 89Mi
TYPE NAMESPACE NAME CPU(cores) MEMORY
crossplane default crossplane-f98f9ddfd-tnm46 4m 32Mi
crossplane default crossplane-rbac-manager-74ff459b88-94p8p 4m 14Mi
provider default provider-aws-s3-1f1a3fb08cbc-5c49d84447-sggrq 3m 108Mi
provider default upbound-provider-family-aws-48b3b5ccf964-76c9686b6-bgg65 2m 89Mi
```
{{<hint "important" >}}
@ -902,7 +916,6 @@ A Kubernetes cluster running Crossplane isn't required.
| | `--cache-dir=".crossplane/cache"` | Specify the absolute path to the cache directory to store downloaded schemas. |
| | `--clean-cache` | Clean the cache directory before downloading package schemas. |
| | `--skip-success-results` | Skip printing success results. |
| | `--error-on-missing-schemas` | Return a non zero exit code if any schemas are missing. |
| | `--verbose` | Print verbose logging statements. |
{{< /table >}}
@ -929,7 +942,7 @@ To clear the cache and download the CRD files again use the `--clean-cache` flag
To validate a managed resource against a provider,
first, create a provider manifest file. For example, to validate an IAM role
from Provider AWS, use the
[Provider AWS IAM](https://github.com/crossplane-contrib/provider-upjet-aws)
[Provider AWS IAM](https://marketplace.upbound.io/providers/upbound/provider-aws-iam/v1.0.0)
manifest.
{{<hint "tip" >}}
@ -944,7 +957,7 @@ kind: Provider
metadata:
name: provider-aws-iam
spec:
package: xpkg.crossplane.io/crossplane-contrib/provider-aws-iam:v1.21.1
package: xpkg.upbound.io/upbound/provider-aws-iam:v1
```
Now include the XR or managed resource to validate.

129
content/master/concepts/compositions.md
View File

@ -1,7 +1,7 @@
---
title: Compositions
weight: 30
aliases:
aliases:
- composition
- composition-functions
- /knowledge-base/guides/composition-functions
@ -9,14 +9,14 @@ description: "Compositions are a template for creating Crossplane resources"
---
Compositions are a template for creating multiple managed resources as a single
object.
object.
A Composition _composes_ individual managed resources together into a larger,
reusable, solution.
An example Composition may combine a virtual machine, storage resources and
networking policies. A Composition template links all these individual
resources together.
resources together.
Here's an example Composition. When you create an
{{<hover label="intro" line="8">}}AcmeBucket{{</hover >}} composite resource
@ -57,12 +57,12 @@ Crossplane has four core components that users commonly mix up:
* Compositions - This page. A template to define how to create resources.
* [Composite Resource Definition]({{<ref "./composite-resource-definitions">}})
(`XRD`) - A custom API specification.
(`XRD`) - A custom API specification.
* [Composite Resource]({{<ref "./composite-resources">}}) (`XR`) - Created by
using the custom API defined in a Composite Resource Definition. XRs use the
Composition template to create new managed resources.
Composition template to create new managed resources.
* [Claims]({{<ref "./claims" >}}) (`XRC`) - Like a Composite Resource, but
with namespace scoping.
with namespace scoping.
{{</expand >}}
## Create a Composition
@ -83,8 +83,8 @@ resource (XR).
{{<hint "tip" >}}
The Crossplane community has built lots of functions that let you template
Crossplane resources using
[CUE](https://github.com/crossplane-contrib/function-cue),
[KCL](https://github.com/crossplane-contrib/function-kcl),
[CUE](https://github.com/crossplane-contrib/function-cue),
[KCL](https://github.com/crossplane-contrib/function-kcl),
Helm-like
[Go templates](https://github.com/crossplane-contrib/function-go-templating) or
legacy Crossplane
@ -111,7 +111,7 @@ but the feature is no longer maintained. Crossplane doesn't accept new
See the [CLI documentation]({{<ref "../cli/command-reference#beta-convert">}})
to learn how to use the `crossplane beta convert` command to convert a legacy
`Resources` Composition to the `Pipeline` mode.
`Resources` Composition to the `Pipeline` mode.
{{< /hint >}}
@ -134,7 +134,7 @@ kind: Function
metadata:
name: function-patch-and-transform
spec:
package: xpkg.crossplane.io/crossplane-contrib/function-patch-and-transform:v0.8.2
package: xpkg.upbound.io/crossplane-contrib/function-patch-and-transform:v0.1.4
```
{{< hint "tip" >}}
@ -155,7 +155,7 @@ During the install a Function reports `INSTALLED` as `True` and `HEALTHY` as
```shell {copy-lines="1"}
kubectl get functions
NAME INSTALLED HEALTHY PACKAGE AGE
function-patch-and-transform True Unknown xpkg.crossplane.io/crossplane-contrib/function-patch-and-transform:v0.8.2 10s
function-patch-and-transform True Unknown xpkg.upbound.io/crossplane-contrib/function-patch-and-transform:v0.1.4 10s
```
After the Function install completes and it's ready for use the `HEALTHY` status
@ -174,36 +174,36 @@ composite resource owns.
Crossplane knows what Function to call when a composite resource changes by
looking at the Composition the composite resource uses.
To use composition functions set the Composition
To use composition functions set the Composition
{{<hover label="single" line="6">}}mode{{</hover>}} to
{{<hover label="single" line="6">}}Pipeline{{</hover>}}.
Define a {{<hover label="single" line="7">}}pipeline{{</hover>}} of
{{<hover label="single" line="8">}}steps{{</hover>}}. Each
{{<hover label="single" line="8">}}step{{</hover>}} calls a Function.
Define a {{<hover label="single" line="7">}}pipeline{{</hover>}} of
{{<hover label="single" line="8">}}steps{{</hover>}}. Each
{{<hover label="single" line="8">}}step{{</hover>}} calls a Function.
Each {{<hover label="single" line="8">}}step{{</hover>}} uses a
Each {{<hover label="single" line="8">}}step{{</hover>}} uses a
{{<hover label="single" line="9">}}functionRef{{</hover>}} to reference the
{{<hover label="single" line="10">}}name{{</hover>}} of the Function to call.
{{<hover label="single" line="10">}}name{{</hover>}} of the Function to call.
{{<hint "important" >}}
Compositions using {{<hover label="single" line="6">}}mode: Pipeline{{</hover>}}
can't specify resource templates with a `resources` field.
Compositions using {{<hover label="single" line="6">}}mode: Pipeline{{</hover>}}
can't specify resource templates with a `resources` field.
Use function "Patch and Transform" to create resource templates.
{{< /hint >}}
Some Functions also allow you to specify an
{{<hover label="single" line="11">}}input{{</hover>}}.
Some Functions also allow you to specify an
{{<hover label="single" line="11">}}input{{</hover>}}.
The function defines the
{{<hover label="single" line="13">}}kind{{</hover>}} of input.
This example uses
[Function Patch and Transform]({{<ref "../guides/function-patch-and-transform">}}).
Function Patch and Transform implements Crossplane resource
templates.
The input kind is {{<hover label="single" line="13">}}Resources{{</hover>}},
templates.
The input kind is {{<hover label="single" line="13">}}Resources{{</hover>}},
and it accepts {{<hover label="single" line="14">}}resources{{</hover>}} as input.
```yaml {label="single",copy-lines="none"}
@ -239,7 +239,7 @@ calls them all. It calls them in the order they appear in the pipeline.
Crossplane passes each Function in the pipeline the result of the previous
Function. This enables powerful combinations of Functions. In this example,
Crossplane calls {{<hover label="double" line="10">}}function-cue{{</hover>}} to
create an S3 bucket. Crossplane then passes the bucket to
create an S3 bucket. Crossplane then passes the bucket to
{{<hover label="double" line="23">}}function-auto-ready{{</hover>}}, which marks the
composite resource as ready when the bucket becomes ready.
@ -272,22 +272,22 @@ spec:
### Enable composite resources
A Composition is only a template defining how to create managed
A Composition is only a template defining how to create managed
resources. A Composition limits which Composite Resources can use this
template.
template.
A Composition's {{<hover label="typeref" line="6">}}compositeTypeRef{{</hover>}}
defines which Composite Resource type can use this Composition.
A Composition's {{<hover label="typeref" line="6">}}compositeTypeRef{{</hover>}}
defines which Composite Resource type can use this Composition.
{{<hint "note" >}}
Read more about Composite Resources in the
[Composite Resources page]({{<ref "./composite-resources" >}}).
Read more about Composite Resources in the
[Composite Resources page]({{<ref "./composite-resources" >}}).
{{< /hint >}}
Inside a Composition's
Inside a Composition's
{{<hover label="typeref" line="5">}}spec{{</hover>}}
define the Composite Resource
{{<hover label="typeref" line="7">}}apiVersion{{</hover>}} and
define the Composite Resource
{{<hover label="typeref" line="7">}}apiVersion{{</hover>}} and
{{<hover label="typeref" line="8">}}kind{{</hover>}}
that the Composition allows to use this template.
@ -306,26 +306,26 @@ spec:
### Store connection details
Some managed resources generate unique details like usernames, passwords, IP
addresses, ports or other connection details.
addresses, ports or other connection details.
When resources inside a Composition create connection details Crossplane creates
a Kubernetes secret object for each managed resource generating connection
details.
details.
{{<hint "note">}}
This section discusses creating Kubernetes secrets.
This section discusses creating Kubernetes secrets.
Crossplane also supports using external secret stores like
[HashiCorp Vault](https://www.vaultproject.io/).
[HashiCorp Vault](https://www.vaultproject.io/).
Read the [external secrets store guide]({{<ref "../guides/vault-as-secret-store">}}) for more information on using Crossplane
with an external secret store.
with an external secret store.
{{</hint >}}
#### Composite resource combined secret
Crossplane can combine all the secrets generated by the resources inside a
Composition into a single Kubernetes secret and optionally copy the secret
object for claims.
object for claims.
Set the value of `writeConnectionSecretsToNamespace` to the namespace where
Crossplane should store the combined secret object.
@ -344,7 +344,7 @@ spec:
Inside the `spec` of each resource producing connection details, define the
`writeConnectionSecretToRef`, with a `namespace` and `name` of the secret object
for the resource.
for the resource.
If a `writeConnectionSecretToRef` isn't defined, Crossplane doesn't write any
keys to the secret.
@ -389,10 +389,10 @@ Remember to create a unique name for each secret.
#### External secret stores
Crossplane
[External Secret Stores]({{<ref "../guides/vault-as-secret-store" >}})
Crossplane
[External Secret Stores]({{<ref "../guides/vault-as-secret-store" >}})
write secrets and connection details to external secret stores like HashiCorp
Vault.
Vault.
{{<hint "important" >}}
External Secret Stores are an alpha feature.
@ -403,7 +403,7 @@ Stores by default.
Use `publishConnectionDetailsWithStoreConfigRef` in place of
`writeConnectionSecretsToNamespace` to define the `StoreConfig` to save
connection details to.
connection details to.
For example, using a `StoreConfig` with the `name` "vault," use
`publishConnectionDetailsWithStoreConfigRef.name` matching the
@ -421,13 +421,13 @@ apiVersion: apiextensions.crossplane.io/v1
kind: Composition
# Removed for Brevity
spec:
publishConnectionDetailsWithStoreConfigRef:
publishConnectionDetailsWithStoreConfigRef:
name: vault
# Removed for brevity
```
For more details read the
[External Secret Stores]({{<ref "../guides/vault-as-secret-store" >}})
[External Secret Stores]({{<ref "../guides/vault-as-secret-store" >}})
integration guide.
## Test a composition
@ -451,7 +451,7 @@ Running `crossplane render` requires [Docker](https://www.docker.com).
{{< /hint >}}
Provide a composite resource, composition and composition functions to render
the output locally.
the output locally.
```shell
crossplane render xr.yaml composition.yaml functions.yaml
@ -545,7 +545,7 @@ kind: Function
metadata:
name: function-patch-and-transform
spec:
package: xpkg.crossplane.io/crossplane-contrib/function-patch-and-transform:v0.8.2
package: xpkg.upbound.io/crossplane-contrib/function-patch-and-transform:v0.1.4
```
{{</expand>}}
@ -576,7 +576,7 @@ metadata:
annotations:
render.crossplane.io/runtime: Development
spec:
package: xpkg.crossplane.io/crossplane-contrib/function-patch-and-transform:v0.8.2
package: xpkg.upbound.io/crossplane-contrib/function-patch-and-transform:v0.1.4
```
{{<hint "tip">}}
@ -599,11 +599,6 @@ the container, and `Orphan`, to leave it running.
`Development` runtime this annotation tells the CLI to connect to a Function
running at the specified target. It uses
[gRPC target syntax](https://github.com/grpc/grpc/blob/v1.59.1/doc/naming.md).
* `render.crossplane.io/runtime-docker-env` - When using the `Docker` runtime this
annotation specifies the environment variables that will be used for the
container. This is helpful to e.g. control KCL registry access to use a different
registry. The annotations value is a comma separated string of key=value pairs
e.g. "key1=value1,key2=value2".
## Verify a Composition
@ -621,18 +616,18 @@ xsqlinstances.aws.platformref.upbound.io XSQLInstance aws.platformref.upboun
```
The `XR-KIND` lists the Composite Resource `kind` that's allowed to use the
Composition template.
Composition template.
The `XR-APIVERSION` lists the Composite Resource API versions allowed to use the
Composition template.
Composition template.
{{<hint "note" >}}
The output of `kubectl get composition` is different than `kubectl get
composite`.
composite`.
`kubectl get composition` lists all available Compositions.
`kubectl get composite` lists all created Composite Resources and their related
Composition.
Composition.
{{< /hint >}}
## Composition validation
@ -662,18 +657,18 @@ If using `mode: Pipeline` (Composition Functions):
### Composition schema aware validation
Crossplane also performs schema aware
validation of Compositions. Schema validation checks that `patches`,
`readinessChecks` and `connectionDetails` are valid according to the resource
schemas. For example, checking that the source and destination fields of a patch
validation of Compositions. Schema validation checks that `patches`,
`readinessChecks` and `connectionDetails` are valid according to the resource
schemas. For example, checking that the source and destination fields of a patch
are valid according to the source and destination resource schema.
{{<hint "note" >}}
Composition schema aware validation is a beta feature. Crossplane enables
beta features by default.
beta features by default.
Disable schema aware validation by setting the
`--enable-composition-webhook-schema-validation=false` flag on the Crossplane
pod.
pod.
The [Crossplane Pods]({{<ref "./pods#edit-the-deployment">}}) page has
more information on enabling Crossplane flags.
@ -703,12 +698,12 @@ The following modes are available:
{{< /table >}}
Change the validation mode for a Composition with the
{{<hover label="mode" line="5">}}crossplane.io/composition-schema-aware-validation-mode{{</hover>}}
{{<hover label="mode" line="5">}}crossplane.io/composition-schema-aware-validation-mode{{</hover>}}
annotation.
If not specified, the default mode is `warn`.
For example, to enable `loose` mode checking set the annotation value to
For example, to enable `loose` mode checking set the annotation value to
{{<hover label="mode" line="5">}}loose{{</hover>}}.
```yaml {copy-lines="none",label="mode"}
@ -832,7 +827,7 @@ Crossplane errors if stability isn't reached after 5 iterations.
A _composed_ resource is a resource created by a composite resource. Composed
resources are usually Crossplane managed resources (MRs), but they can be any
kind of Crossplane resource. For example a composite resource could also create
a ProviderConfig, or another kind of composite resource.
a ProviderConfig, or another kind of composite resource.
<!-- vale write-good.Weasel = YES -->
{{</hint>}}
@ -991,4 +986,4 @@ context.
Crossplane can write context too. If you enable the alpha
[composition environment]({{<ref "environment-configs">}}) feature Crossplane
writes the environment to the top-level context field
`apiextensions.crossplane.io/environment`.
`apiextensions.crossplane.io/environment`.

11
content/master/concepts/connection-details.md
View File

@ -49,7 +49,7 @@ All the following examples use the same set of Compositions,
CompositeResourceDefinitions and Claims.
All examples rely on
[provider-aws-iam](https://github.com/crossplane-contrib/provider-upjet-aws)
[Upbound provider-aws-iam](https://marketplace.upbound.io/providers/upbound/provider-aws-iam/)
to create resources.
{{<expand "Reference Composition" >}}
@ -534,10 +534,11 @@ the secret key names to create. Crossplane only adds the keys listed to the
combined secret.
{{<hint "warning">}}
When changing the {{<hover label="xrd" line="4">}}connectionSecretKeys{{</hover>}} of an XRD the change isn't immediately reflected.
You have two options to change the keys in the combined secret object.
- Delete and recreate the XRD. This only makes sense if the XRD isn't used as it leads to the deletion of XRs.
- Restart the XR reconciler, which can be done by restarting the Crossplane pod.
You can't change the
{{<hover label="xrd" line="4">}}connectionSecretKeys{{</hover>}} of an XRD.
You must delete and
recreate the XRD to change the
{{<hover label="xrd" line="4">}}connectionSecretKeys{{</hover>}}.
{{</hint >}}
For example, an XRD may restrict the secrets to only the

193
content/master/concepts/image-configs.md
View File

@ -10,35 +10,6 @@ description: "Image Configs is an API for centralized control of the configurati
Crossplane package images. It allows you to configure package manager behavior
for images globally, without needing to be referenced by other objects.
## Matching image references
`spec.matchImages` is a list of image references that the `ImageConfig` applies
to. Each item in the list specifies the type and configuration of the image
reference to match. The only supported type is `Prefix`, which matches the
prefix of the image reference. No wildcards are supported. The `type` defaults
to `Prefix` and can be omitted.
When there are multiple `ImageConfigs` matching an image reference, the one with
the longest matching prefix is selected. If there are multiple `ImageConfigs`
with the same longest matching prefix, one of them is selected
arbitrarily. Please note that this situation occurs only if there are
overlapping prefixes in the `matchImages` lists of different `ImageConfig`
resources, which should be avoided.
The default registry isn't taken into account for `ImageConfig` matching. That
is, an `ImageConfig` matching the prefix `xpkg.crossplane.io/crossplane-contrib`
doesn't match the following provider, even if the default registry is
`xpkg.crossplane.io`:
```yaml
apiVersion: pkg.crossplane.io/v1
kind: Provider
metadata:
name: provider-nop
spec:
package: crossplane-contrib/provider-nop:v0.4.0
```
## Configuring a pull secret
You can use `ImageConfig` to inject a pull secret into the Crossplane package
@ -75,6 +46,43 @@ following command:
kubectl -n crossplane-system create secret docker-registry acme-registry-credentials --docker-server=registry1.com --docker-username=<user> --docker-password=<password>
```
### Matching image references
`spec.matchImages` is a list of image references that the `ImageConfig` applies
to. Each item in the list specifies the type and configuration of the image
reference to match. The only supported type is `Prefix`, which matches the
prefix of the image reference. No wildcards are supported. The `type` defaults
to `Prefix` and can be omitted.
When there are multiple `ImageConfigs` matching an image reference, the one
with the longest matching prefix is selected. If there are multiple
`ImageConfigs` with the same longest matching prefix, one of them is selected
arbitrarily. Please note that this situation occurs only if there are
overlapping prefixes in the `matchImages` lists of different `ImageConfig`
resources, which should be avoided.
### Debugging
When the package manager selects an `ImageConfig` for a package, it throws an
event with the reason `ImageConfigSelection` and the name of the selected
`ImageConfig` and injected pull secret. You can find these events both on the
package and package revision resources.
For example, the following event indicates that the `ImageConfig` named
`acme-packages` was selected for the configuration named `acme-configuration-foo`:
```shell
$ kubectl describe configuration acme-configuration-foo
...
Events:
Type Reason Age From Message
---- ------ ---- ---- -------
Normal ImageConfigSelection 45s packages/configuration.pkg.crossplane.io Selected pullSecret "acme-registry-credentials" from ImageConfig "acme-packages" for registry authentication
```
If you can't find the expected event, ensure the prefix of the image reference
matches the `matchImages` list of any `ImageConfig` resources in the cluster.
## Configuring signature verification
{{<hint "important" >}}
@ -203,129 +211,4 @@ If you can't see this condition on the package revision resource, namely
`ProviderRevision`, `ConfigurationRevision`, or `FunctionRevision`, ensure that
the feature is enabled.
## Rewriting image paths
You can use an `ImageConfig` to pull package images from an alternative location
such as a private registry. `spec.rewriteImages` specifies how to rewrite the
paths of matched images.
Only prefix replacement is supported. The prefix specified in
`spec.rewriteImage.prefix` replaces the matched prefix from `matchImages`. For
example, the following `ImageConfig` replaces `xpkg.crossplane.io` with
`registry1.com` for any image with the prefix `xpkg.crossplane.io`.
```yaml
apiVersion: pkg.crossplane.io/v1beta1
kind: ImageConfig
metadata:
name: private-registry-rewrite
spec:
matchImages:
- prefix: xpkg.crossplane.io
rewriteImage:
prefix: registry1.com
```
In this example, installing the provider package
`xpkg.crossplane.io/crossplane-contrib/provider-nop:v0.4.0` will result in the
package manager pulling the provider from
`registry1.com/crossplane-contrib/provider-nop:v0.4.0`.
Rewriting image paths via `ImageConfig` is useful when mirroring packages to a
private registry, because it allows a package and all its dependencies to be
pulled from the same registry. For example, the provider
`xpkg.crossplane.io/crossplane-contrib/provider-aws-s3` has a dependency on
`xpkg.crossplane.io/crossplane-contrib/provider-family-aws`. If you mirror the
packages to your own registry at `registry1.com` and install them without an
`ImageConfig`, the package manager still attempts to pull the dependency from
`xpkg.crossplane.io`. With the preceding `ImageConfig`, the dependency is pulled
from `registry1.com`.
Rewriting an image path with `ImageConfig` doesn't change the `spec.package`
field of the package resource. The rewritten path is recorded in the
`status.resolvedPackage` field. The preceding example results in the following:
```shell
kubectl describe provider crossplane-contrib-provider-family-aws
...
Spec:
...
Package: xpkg.crossplane.io/crossplane-contrib/provider-family-aws:v1.22.0
Status:
...
Resolved Package: registry1.com/crossplane-contrib/provider-family-aws:v1.22.0
```
### Interaction with other operations
{{<hint "tip" >}}
Image rewriting is always done before other `ImageConfig` operations. If you
wish to configure pull secrets or signature verification as well as rewriting,
additional `ImageConfig` resources must match the rewritten image path.
{{< /hint >}}
For example, if you are mirroring packages from `xpkg.crossplane.io` to
`registry1.com` and need to configure pull secrets for `registry1.com`, two
`ImageConfig` resources are necessary:
```yaml
# Rewrite xpkg.crossplane.io -> registry1.com
---
apiVersion: pkg.crossplane.io/v1beta1
kind: ImageConfig
metadata:
name: private-registry-rewrite
spec:
matchImages:
- prefix: xpkg.crossplane.io
rewriteImage:
prefix: registry1.com
# Configure pull secrets for registry1.com
---
apiVersion: pkg.crossplane.io/v1beta1
kind: ImageConfig
metadata:
name: private-registry-auth
spec:
matchImages:
- type: Prefix
prefix: registry1.com
registry:
authentication:
pullSecretRef:
name: private-registry-credentials
```
## Debugging
When the package manager selects an `ImageConfig` for a package, it throws an
event with the reason `ImageConfigSelection` and the name of the selected
`ImageConfig` and injected pull secret. You can find these events both on the
package and package revision resources. The package manager also updates the
`appliedImageConfigRefs` field in the package status to show the purpose for
which each `ImageConfig` was selected.
For example, the following event and status show that the `ImageConfig` named
`acme-packages` was used to provide a pull secret for the configuration named
`acme-configuration-foo`:
```shell
kubectl describe configuration acme-configuration-foo
...
Status:
Applied Image Config Refs:
Name: acme-packages
Reason: SetImagePullSecret
...
Events:
Type Reason Age From Message
---- ------ ---- ---- -------
Normal ImageConfigSelection 45s packages/configuration.pkg.crossplane.io Selected pullSecret "acme-registry-credentials" from ImageConfig "acme-packages" for registry authentication
```
If you can't find the expected event and `appliedImageConfigRefs` entry, ensure
the prefix of the image reference matches the `matchImages` list of any
`ImageConfig` resources in the cluster.
<!-- vale write-good.Passive = YES -->
<!-- vale write-good.Passive = YES -->

10
content/master/concepts/managed-resources.md
View File

@ -15,9 +15,9 @@ external object inside the Provider an _external resource_.
{{< /hint >}}
Examples of managed resources include:
* Amazon AWS EC2 `Instance` defined in [provider-upjet-aws](https://github.com/crossplane-contrib/provider-upjet-aws).
* Google Cloud GKE `Cluster` defined in [provider-upjet-gcp](https://github.com/crossplane-contrib/provider-upjet-gcp).
* Microsoft Azure PostgreSQL `Database` defined in [provider-upjet-azure](https://github.com/crossplane-contrib/provider-upjet-azure).
* Amazon AWS EC2 [`Instance`](https://marketplace.upbound.io/providers/upbound/provider-aws/latest/resources/ec2.aws.upbound.io/Instance/v1beta1)
* Google Cloud GKE [`Cluster`](https://marketplace.upbound.io/providers/upbound/provider-gcp/latest/resources/container.gcp.upbound.io/Cluster/v1beta1)
* Microsoft Azure PostgreSQL [`Database`](https://marketplace.upbound.io/providers/upbound/provider-azure/latest/resources/dbforpostgresql.azure.upbound.io/Database/v1beta1)
{{< hint "tip" >}}
@ -35,7 +35,7 @@ Provider also define the available settings of a managed resource.
Each managed resource is a unique API endpoint with their own
group, kind and version.
For example the [AWS Provider](https://github.com/crossplane-contrib/provider-upjet-aws)
For example the [Upbound AWS Provider](https://marketplace.upbound.io/providers/upbound/provider-aws/latest/)
defines the {{<hover label="gkv" line="2">}}Instance{{</hover>}} kind from the
group {{<hover label="gkv" line="1">}}ec2.aws.upbound.io{{</hover>}}
@ -529,7 +529,7 @@ Crossplane stores these details in a Kubernetes Secret object specified by the
`writeConnectionSecretToRef` values.
For example, when creating an AWS RDS database instance with the Crossplane
[community AWS provider](https://github.com/crossplane-contrib/provider-aws)
[community AWS provider](https://marketplace.upbound.io/providers/crossplane-contrib/provider-aws/v0.40.0)
generates an endpoint, password, port and username data. The Provider saves
these variables in the Kubernetes secret
{{<hover label="secretname" line="9" >}}rds-secret{{</hover>}}, referenced by

248
content/master/concepts/packages.md
View File

@ -5,52 +5,53 @@ altTitle: "Crossplane Packages"
weight: 200
---
A _Configuration_ package is an
A _Configuration_ package is an
[OCI container image](https://opencontainers.org/) containing a collection of
[Compositions]({{<ref "./compositions" >}}),
[Compositions]({{<ref "./compositions" >}}),
[Composite Resource Definitions]({{<ref "./composite-resource-definitions" >}})
and any required [Providers]({{<ref "./providers">}}) or
and any required [Providers]({{<ref "./providers">}}) or
[Functions]({{<ref "./compositions" >}}).
Configuration packages make your Crossplane configuration fully portable.
Configuration packages make your Crossplane configuration fully portable.
{{<hint "important" >}}
Crossplane [Providers]({{<ref "./providers">}}) and
[Functions]({{<ref "./compositions">}}) are also Crossplane packages.
Crossplane [Providers]({{<ref "./providers">}}) and
[Functions]({{<ref "./compositions">}}) are also Crossplane packages.
This document describes how to install and manage configuration packages.
This document describes how to install and manage configuration packages.
Refer to the
[Provider]({{<ref "./providers">}}) and
Refer to the
[Provider]({{<ref "./providers">}}) and
[Composition Functions]({{<ref "./compositions">}}) chapters for
details on their usage of packages.
details on their usage of packages.
{{< /hint >}}
## Install a Configuration
Install a Configuration with a Crossplane
{{<hover line="2" label="install">}}Configuration{{</hover>}} object by setting
Install a Configuration with a Crossplane
{{<hover line="2" label="install">}}Configuration{{</hover>}} object by setting
the {{<hover line="6" label="install">}}spec.package{{</hover>}} value to the
location of the configuration package.
{{< hint "important" >}}
Beginning with Crossplane version 1.20.0 Crossplane uses the [crossplane-contrib](https://github.com/orgs/crossplane-contrib/packages) GitHub Container Registry at `xpkg.crossplane.io` by default for downloading and
installing packages.
Beginning with Crossplane version 1.15.0 Crossplane uses the Upbound Marketplace
Crossplane package registry at `xpkg.upbound.io` by default for downloading and
installing packages.
Specify the full domain name with the `package` or change the default Crossplane
registry with the `--registry` flag on the [Crossplane pod]({{<ref "./pods">}})
{{< /hint >}}
For example to install the
[Getting Started Configuration](https://github.com/crossplane-contrib/configuration-quickstart),
For example to install the
[Upbound AWS reference platform](https://marketplace.upbound.io/configurations/upbound/platform-ref-aws/v0.6.0).
```yaml {label="install"}
apiVersion: pkg.crossplane.io/v1
kind: Configuration
metadata:
name: configuration-quickstart
name: platform-ref-aws
spec:
package: xpkg.crossplane.io/crossplane-contrib/configuration-quickstart:v0.1.0
package: xpkg.upbound.io/upbound/platform-ref-aws:v0.6.0
```
{{<hint "tip" >}}
@ -61,14 +62,14 @@ and repeatable installations.
apiVersion: pkg.crossplane.io/v1
kind: Configuration
metadata:
name: configuration-quickstart
name: platform-ref-aws
spec:
package: xpkg.crossplane.io/crossplane-contrib/configuration-quickstart@sha256:ef9795d146190637351a5c5848e0bab5e0c190fec7780f6c426fbffa0cb68358
package: xpkg.upbound.io/upbound/platform-ref-aws@sha256:a30ad655c7699218d9234285d838d85582f015d02f7f061f8486b28248fd7db7
```
{{< /hint >}}
Crossplane installs the Compositions, Composite Resource Definitions and
Providers listed in the Configuration.
Providers listed in the Configuration.
### Install with Helm
@ -79,21 +80,21 @@ Use the
{{<hover label="helm" line="5" >}}--set configuration.packages{{</hover >}}
argument with `helm install`.
For example, to install the Getting Started configuration,
For example, to install the Upbound AWS reference platform,
```shell {label="helm"}
helm install crossplane \
crossplane-stable/crossplane \
--namespace crossplane-system \
--create-namespace \
--set configuration.packages='{xpkg.crossplane.io/crossplane-contrib/configuration-quickstart:v0.1.0}'
--set configuration.packages='{xpkg.upbound.io/upbound/platform-ref-aws:v0.6.0}'
```
### Install offline
Installing Crossplane packages offline requires a local container registry, such as
[Harbor](https://goharbor.io/) to host the packages. Crossplane only
supports installing packages from a container registry.
supports installing packages from a container registry.
Crossplane doesn't support installing packages directly from Kubernetes
volumes.
@ -101,39 +102,39 @@ volumes.
### Installation options
Configurations support multiple options to change configuration package related
settings.
settings.
#### Configuration revisions
When installing a newer version of an existing Configuration Crossplane creates
a new configuration revision.
a new configuration revision.
View the configuration revisions with
View the configuration revisions with
{{<hover label="rev" line="1">}}kubectl get configurationrevisions{{</hover>}}.
```shell {label="rev",copy-lines="1"}
kubectl get configurationrevisions
NAME HEALTHY REVISION IMAGE STATE DEP-FOUND DEP-INSTALLED AGE
platform-ref-aws-1735d56cd88d True 2 xpkg.crossplane.io/crossplane-contrib/platform-ref-aws:v0.5.0 Active 2 2 46s
platform-ref-aws-3ac761211893 True 1 xpkg.crossplane.io/crossplane-contrib/platform-ref-aws:v0.4.1 Inactive 5m13s
platform-ref-aws-1735d56cd88d True 2 xpkg.upbound.io/upbound/platform-ref-aws:v0.5.0 Active 2 2 46s
platform-ref-aws-3ac761211893 True 1 xpkg.upbound.io/upbound/platform-ref-aws:v0.4.1 Inactive 5m13s
```
Only a single revision is active at a time. The active revision determines the
available resources, including Compositions and Composite Resource Definitions.
available resources, including Compositions and Composite Resource Definitions.
By default Crossplane keeps only a single _Inactive_ revision.
Change the number of revisions Crossplane maintains with a Configuration package
{{<hover label="revHistory" line="6">}}revisionHistoryLimit{{</hover>}}.
Change the number of revisions Crossplane maintains with a Configuration package
{{<hover label="revHistory" line="6">}}revisionHistoryLimit{{</hover>}}.
The {{<hover label="revHistory" line="6">}}revisionHistoryLimit{{</hover>}}
field is an integer.
The default value is `1`.
Disable storing revisions by setting
field is an integer.
The default value is `1`.
Disable storing revisions by setting
{{<hover label="revHistory" line="6">}}revisionHistoryLimit{{</hover>}} to `0`.
For example, to change the default setting and store 10 revisions use
For example, to change the default setting and store 10 revisions use
{{<hover label="revHistory" line="6">}}revisionHistoryLimit: 10{{</hover>}}.
```yaml {label="revHistory"}
@ -152,26 +153,26 @@ Use a {{<hover label="pullpolicy" line="6">}}packagePullPolicy{{</hover>}} to
define when Crossplane should download the Configuration package to the local
Crossplane package cache.
The `packagePullPolicy` options are:
The `packagePullPolicy` options are:
* `IfNotPresent` - (**default**) Only download the package if it isn't in the cache.
* `Always` - Check for new packages every minute and download any matching
package that isn't in the cache.
* `Never` - Never download the package. Packages are only installed from the
local package cache.
local package cache.
{{<hint "tip" >}}
The Crossplane
The Crossplane
{{<hover label="pullpolicy" line="6">}}packagePullPolicy{{</hover>}} works
like the Kubernetes container image
[image pull policy](https://kubernetes.io/docs/concepts/containers/images/#image-pull-policy).
like the Kubernetes container image
[image pull policy](https://kubernetes.io/docs/concepts/containers/images/#image-pull-policy).
Crossplane supports the use of tags and package digest hashes like
Kubernetes images.
Kubernetes images.
{{< /hint >}}
For example, to `Always` download a given Configuration package use the
For example, to `Always` download a given Configuration package use the
{{<hover label="pullpolicy" line="6">}}packagePullPolicy: Always{{</hover>}}
configuration.
configuration.
```yaml {label="pullpolicy",copy-lines="6"}
apiVersion: pkg.crossplane.io/v1
@ -186,20 +187,20 @@ spec:
#### Revision activation policy
The `Active` package revision
is the package controller actively reconciling resources.
is the package controller actively reconciling resources.
By default Crossplane sets the most recently installed package revision as
By default Crossplane sets the most recently installed package revision as
`Active`.
Control the Configuration upgrade behavior with a
{{<hover label="revision" line="6">}}revisionActivationPolicy{{</hover>}}.
The {{<hover label="revision" line="6">}}revisionActivationPolicy{{</hover>}}
The {{<hover label="revision" line="6">}}revisionActivationPolicy{{</hover>}}
options are:
* `Automatic` - (**default**) Automatically activate the last installed configuration.
* `Manual` - Don't automatically activate a configuration.
* `Manual` - Don't automatically activate a configuration.
For example, to change the upgrade behavior to require manual upgrades, set
For example, to change the upgrade behavior to require manual upgrades, set
{{<hover label="revision" line="6">}}revisionActivationPolicy: Manual{{</hover>}}.
```yaml {label="revision"}
@ -215,14 +216,14 @@ spec:
#### Install a Configuration from a private registry
Like Kubernetes uses `imagePullSecrets` to
[install images from private registries](https://kubernetes.io/docs/tasks/configure-pod-container/pull-image-private-registry/),
Crossplane uses `packagePullSecrets` to install Configuration packages from a
private registry.
Like Kubernetes uses `imagePullSecrets` to
[install images from private registries](https://kubernetes.io/docs/tasks/configure-pod-container/pull-image-private-registry/),
Crossplane uses `packagePullSecrets` to install Configuration packages from a
private registry.
Use {{<hover label="pps" line="6">}}packagePullSecrets{{</hover>}} to provide a
Kubernetes secret to use for authentication when downloading a Configuration
package.
Kubernetes secret to use for authentication when downloading a Configuration
package.
{{<hint "important" >}}
The Kubernetes secret must be in the same namespace as Crossplane.
@ -232,7 +233,7 @@ The {{<hover label="pps" line="6">}}packagePullSecrets{{</hover>}} is a list of
secrets.
For example, to use the secret named
{{<hover label="pps" line="6">}}example-secret{{</hover>}} configure a
{{<hover label="pps" line="6">}}example-secret{{</hover>}} configure a
{{<hover label="pps" line="6">}}packagePullSecrets{{</hover>}}.
```yaml {label="pps"}
@ -241,7 +242,7 @@ kind: Configuration
metadata:
name: platform-ref-aws
spec:
packagePullSecrets:
packagePullSecrets:
- name: example-secret
# Removed for brevity
```
@ -249,19 +250,19 @@ spec:
#### Ignore dependencies
By default Crossplane installs any [dependencies](#manage-dependencies) listed
in a Configuration package.
in a Configuration package.
Crossplane can ignore a Configuration package's dependencies with
Crossplane can ignore a Configuration package's dependencies with
{{<hover label="pkgDep" line="6" >}}skipDependencyResolution{{</hover>}}.
{{< hint "warning" >}}
Most Configurations include dependencies for the required Providers.
Most Configurations include dependencies for the required Providers.
If a Configuration ignores dependencies, the required Providers must be
If a Configuration ignores dependencies, the required Providers must be
manually installed.
{{< /hint >}}
For example, to disable dependency resolution configure
For example, to disable dependency resolution configure
{{<hover label="pkgDep" line="6" >}}skipDependencyResolution: true{{</hover>}}.
```yaml {label="pkgDep"}
@ -274,58 +275,17 @@ spec:
# Removed for brevity
```
#### Automatically update dependency versions
Crossplane can automatically upgrade a package's dependency version to the minimum
valid version that satisfies all the constraints. It's an alpha feature that
requires enabling with the `--enable-dependency-version-upgrades` flag.
In some cases, dependency version downgrade is required for proceeding with
installations. Suppose configuration A, which depends on package X with the
constraint`>=v0.0.0`, is installed on the control plane. In this case, the package
manager installs the latest version of package X, such as `v3.0.0`. Later, you decide
to install configuration B, which depends on package X with the constraint `<=v2.0.0`.
Since version `v2.0.0` satisfies both conditions, package X must be downgraded to
allow the installation of configuration B which is disabled by default.
Automatic dependency version downgrades is also an alpha feature that can be
enabled with the `--enable-dependency-version-downgrades` flag. Downgrading a
package can cause unexpected behavior, therefore, this option is disabled by
default. After enabling this option, the package manager will automatically
downgrade a package's dependency version to the maximum valid version that
satisfies the constraints.
{{<hint "note" >}}
This configuration requires the `--enable-dependency-version-upgrades` flag.
Please check the
[configuration options]({{<ref "../software/install#customize-the-crossplane-helm-chart">}})
and
[feature flags]({{<ref "../software/install#feature-flags">}})
are available in the
[Crossplane Install]({{<ref "../software/install">}})
section for more details.
{{</hint >}}
{{<hint "important" >}}
Enabling automatic dependency downgrades may have unintended consequences, such as:
1) CRDs missing in the downgraded version, possibly leaving orphaned MRs without
controllers to reconcile them.
2) Loss of data if downgraded CRD versions omit fields that were set before.
3) Changes in the CRD storage version, which may prevent package version update.
{{</hint >}}
#### Ignore Crossplane version requirements
A Configuration package may require a specific or minimum Crossplane version
before installing. By default, Crossplane doesn't install a Configuration if
the Crossplane version doesn't meet the required version.
A Configuration package may require a specific or minimum Crossplane version
before installing. By default, Crossplane doesn't install a Configuration if
the Crossplane version doesn't meet the required version.
Crossplane can ignore the required version with
Crossplane can ignore the required version with
{{<hover label="xpVer" line="6">}}ignoreCrossplaneConstraints{{</hover>}}.
For example, to install a Configuration package into an unsupported Crossplane
version, configure
version, configure
{{<hover label="xpVer" line="6">}}ignoreCrossplaneConstraints: true{{</hover>}}.
```yaml {label="xpVer"}
@ -341,7 +301,7 @@ spec:
### Verify a Configuration
Verify a Configuration with
Verify a Configuration with
{{<hover label="verify" line="1">}}kubectl get configuration{{</hover >}}.
A working configuration reports `Installed` and `Healthy` as `True`.
@ -349,27 +309,27 @@ A working configuration reports `Installed` and `Healthy` as `True`.
```shell {label="verify",copy-lines="1"}
kubectl get configuration
NAME INSTALLED HEALTHY PACKAGE AGE
platform-ref-aws True True xpkg.crossplane.io/crossplane-contrib/configuration-quickstart:v0.1.0 54s
platform-ref-aws True True xpkg.upbound.io/upbound/platform-ref-aws:v0.6.0 54s
```
### Manage dependencies
Configuration packages may include dependencies on other packages including
Functions, Providers or other Configurations.
Functions, Providers or other Configurations.
If Crossplane can't meet the dependencies of a Configuration the Configuration
reports `HEALTHY` as `False`.
reports `HEALTHY` as `False`.
For example, this installation of the Getting Started Configuration is
For example, this installation of the Upbound AWS reference platform is
`HEALTHY: False`.
```shell {copy-lines="1"}
kubectl get configuration
NAME INSTALLED HEALTHY PACKAGE AGE
platform-ref-aws True False xpkg.crossplane.io/crossplane-contrib/configuration-quickstart:v0.1.0 71s
platform-ref-aws True False xpkg.upbound.io/upbound/platform-ref-aws:v0.6.0 71s
```
To see more information on why the Configuration isn't `HEALTHY` use
To see more information on why the Configuration isn't `HEALTHY` use
{{<hover label="depend" line="1">}}kubectl describe configurationrevisions{{</hover>}}.
```yaml {copy-lines="1",label="depend"}
@ -380,7 +340,7 @@ Kind: ConfigurationRevision
# Removed for brevity
Spec:
Desired State: Active
Image: xpkg.crossplane.io/crossplane-contrib/configuration-quickstart:v0.1.0
Image: xpkg.upbound.io/upbound/platform-ref-aws:v0.6.0
Revision: 1
Status:
Conditions:
@ -396,64 +356,64 @@ Events:
Warning LintPackage 29s (x2 over 29s) packages/configurationrevision.pkg.crossplane.io incompatible Crossplane version: package isn't compatible with Crossplane version (v1.12.0)
```
The {{<hover label="depend" line="18">}}Events{{</hover>}} show a
The {{<hover label="depend" line="18">}}Events{{</hover>}} show a
{{<hover label="depend" line="21">}}Warning{{</hover>}} with a message that the
current version of Crossplane doesn't meet the Configuration package
current version of Crossplane doesn't meet the Configuration package
requirements.
## Create a Configuration
Crossplane Configuration packages are
Crossplane Configuration packages are
[OCI container images](https://opencontainers.org/) containing one or more YAML
files.
files.
{{<hint "important" >}}
Configuration packages are fully OCI compliant. Any tool that builds OCI images
can build Configuration packages.
can build Configuration packages.
It's strongly recommended to use the Crossplane command-line tool to
provide error checking and formatting to Crossplane package builds.
provide error checking and formatting to Crossplane package builds.
Read the
[Crossplane package specification](https://github.com/crossplane/crossplane/blob/main/contributing/specifications/xpkg.md)
Read the
[Crossplane package specification](https://github.com/crossplane/crossplane/blob/main/contributing/specifications/xpkg.md)
for package requirements when building packages with third-party tools.
{{</hint >}}
A Configuration package requires a `crossplane.yaml` file and may include
Composition and CompositeResourceDefinition files.
Composition and CompositeResourceDefinition files.
<!-- vale Google.Headings = NO -->
### The crossplane.yaml file
<!-- vale Google.Headings = YES -->
To build a Configuration package using the Crossplane CLI, create a file
named
{{<hover label="cfgMeta" line="1">}}crossplane.yaml{{</hover>}}.
The
named
{{<hover label="cfgMeta" line="1">}}crossplane.yaml{{</hover>}}.
The
{{<hover label="cfgMeta" line="1">}}crossplane.yaml{{</hover>}}
file defines the requirements and name of the
file defines the requirements and name of the
Configuration.
{{<hint "important" >}}
The Crossplane CLI only supports a file named `crossplane.yaml`.
{{< /hint >}}
Configuration package uses the
Configuration package uses the
{{<hover label="cfgMeta" line="2">}}meta.pkg.crossplane.io{{</hover>}}
Crossplane API group.
Specify any other Configurations, Functions or Providers in the
{{<hover label="cfgMeta" line="7">}}dependsOn{{</hover>}} list.
Optionally, you can require a specific or minimum package version with the
Specify any other Configurations, Functions or Providers in the
{{<hover label="cfgMeta" line="7">}}dependsOn{{</hover>}} list.
Optionally, you can require a specific or minimum package version with the
{{<hover label="cfgMeta" line="9">}}version{{</hover>}} option.
You can also define a specific or minimum version of Crossplane for this
Configuration with the
{{<hover label="cfgMeta" line="11">}}crossplane.version{{</hover>}} option.
Configuration with the
{{<hover label="cfgMeta" line="11">}}crossplane.version{{</hover>}} option.
{{<hint "note" >}}
Defining the {{<hover label="cfgMeta" line="10">}}crossplane{{</hover>}} object
or required versions is optional.
Defining the {{<hover label="cfgMeta" line="10">}}crossplane{{</hover>}} object
or required versions is optional.
{{< /hint >}}
```yaml {label="cfgMeta",copy-lines="all"}
@ -466,7 +426,7 @@ spec:
dependsOn:
- apiVersion: pkg.crossplane.io/v1
kind: Provider
package: xpkg.crossplane.io/crossplane-contrib/provider-aws
package: xpkg.upbound.io/crossplane-contrib/provider-aws
version: ">=v0.36.0"
crossplane:
version: ">=v1.12.1-0"
@ -474,8 +434,8 @@ spec:
### Build the package
Create the package using the
[Crossplane CLI]({{<ref "../cli">}}) command
Create the package using the
[Crossplane CLI]({{<ref "../cli">}}) command
`crossplane xpkg build --package-root=<directory>`.
Where the `<directory>` is the directory containing the `crossplane.yaml` file
@ -485,19 +445,19 @@ The CLI recursively searches for `.yml` or `.yaml` files in the directory to
include in the package.
{{<hint "important" >}}
You must ignore any other YAML files with `--ignore=<file_list>`.
You must ignore any other YAML files with `--ignore=<file_list>`.
For
example, `crossplane xpkg build --package-root=test-directory --ignore=".tmp/*"`.
Including YAML files that aren't Compositions or CompositeResourceDefinitions,
Including YAML files that aren't Compositions or CompositeResourceDefinitions,
including Claims isn't supported.
{{</hint >}}
By default, Crossplane creates a `.xpkg` file of the Configuration name and
By default, Crossplane creates a `.xpkg` file of the Configuration name and
a SHA-256 hash of the package contents.
For example, a {{<hover label="xpkgName" line="2">}}Configuration{{</hover>}}
named {{<hover label="xpkgName" line="4">}}test-configuration{{</hover>}}.
named {{<hover label="xpkgName" line="4">}}test-configuration{{</hover>}}.
The
Crossplane CLI builds a package named `test-configuration-e8c244f6bf21.xpkg`.

2
content/master/concepts/pods.md
View File

@ -350,7 +350,7 @@ the Helm `values.yml` file or after installation by editing the `Deployment`.
The full list of
[configuration options]({{<ref "../software/install#customize-the-crossplane-helm-chart">}})
and
[feature flags]({{<ref "../software/install#feature-flags">}})
[feature flags]({{<ref "../software/install#customize-the-crossplane-helm-chart">}})
are available in the
[Crossplane Install]({{<ref "../software/install">}})
section.

198
content/master/concepts/providers.md
View File

@ -21,10 +21,14 @@ Examples of providers include:
* [Provider GCP](https://github.com/upbound/provider-gcp)
* [Provider Kubernetes](https://github.com/crossplane-contrib/provider-kubernetes)
{{< hint "tip" >}}
Find more providers in Crossplane's [public package registries](https://www.crossplane.io/registries).
{{< /hint >}}
<!-- vale write-good.Passive = NO -->
<!-- "are Managed" isn't passive in this context -->
Providers define every external resource they can create in Kubernetes as a
Kubernetes API endpoint.
Kubernetes API endpoint.
These endpoints are
[_Managed Resources_]({{<ref "managed-resources" >}}).
<!-- vale write-good.Passive = YES -->
@ -32,10 +36,10 @@ These endpoints are
## Install a Provider
Installing a provider creates new Kubernetes resources representing the
Provider's APIs. Installing a provider also creates a Provider pod that's
responsible for reconciling the Provider's APIs into the Kubernetes cluster.
Providers constantly watch the state of the desired managed resources and create
Installing a provider creates new Kubernetes resources representing the
Provider's APIs. Installing a provider also creates a Provider pod that's
responsible for reconciling the Provider's APIs into the Kubernetes cluster.
Providers constantly watch the state of the desired managed resources and create
any external resources that are missing.
Install a Provider with a Crossplane
@ -44,8 +48,9 @@ Install a Provider with a Crossplane
location of the provider package.
{{< hint "important" >}}
Beginning with Crossplane version 1.20.0 Crossplane uses the [crossplane-contrib](https://github.com/orgs/crossplane-contrib/packages) GitHub Container Registry at `xpkg.crossplane.io` by default for downloading and
installing packages.
Beginning with Crossplane version 1.15.0 Crossplane uses the Upbound Marketplace
Crossplane package registry at `xpkg.upbound.io` by default for downloading and
installing packages.
Specify the full domain name with the `package` or change the default Crossplane
registry with the `--registry` flag on the [Crossplane pod]({{<ref "./pods">}})
@ -60,26 +65,26 @@ kind: Provider
metadata:
name: provider-aws
spec:
package: xpkg.crossplane.io/crossplane-contrib/provider-aws:v0.39.0
package: xpkg.upbound.io/crossplane-contrib/provider-aws:v0.39.0
```
By default, the Provider pod installs in the same namespace as Crossplane
(`crossplane-system`).
{{<hint "note" >}}
Providers are part of the
{{<hover label="install" line="1">}}pkg.crossplane.io{{</hover>}} group.
Providers are part of the
{{<hover label="install" line="1">}}pkg.crossplane.io{{</hover>}} group.
The {{<hover label="meta-pkg" line="1">}}meta.pkg.crossplane.io{{</hover>}}
group is for creating Provider packages.
group is for creating Provider packages.
Instructions on building Providers are outside of the scope of this
document.
Read the Crossplane contributing
document.
Read the Crossplane contributing
[Provider Development Guide](https://github.com/crossplane/crossplane/blob/main/contributing/guide-provider-development.md)
for more information.
For information on the specification of Provider packages read the
For information on the specification of Provider packages read the
[Crossplane Provider Package specification](https://github.com/crossplane/crossplane/blob/main/contributing/specifications/xpkg.md#provider-package-requirements).
```yaml {label="meta-pkg"}
@ -108,14 +113,14 @@ helm install crossplane \
crossplane-stable/crossplane \
--namespace crossplane-system \
--create-namespace \
--set provider.packages='{xpkg.crossplane.io/crossplane-contrib/provider-aws:v0.39.0}'
--set provider.packages='{xpkg.upbound.io/crossplane-contrib/provider-aws:v0.39.0}'
```
### Install offline
Installing Crossplane Providers offline requires a local container registry like
Installing Crossplane Providers offline requires a local container registry like
[Harbor](https://goharbor.io/) to host Provider packages. Crossplane only
supports installing Provider packages from a container registry.
supports installing Provider packages from a container registry.
Crossplane doesn't support installing Provider packages directly from Kubernetes
volumes.
@ -123,11 +128,11 @@ volumes.
### Installation options
Providers support multiple configuration options to change installation related
settings.
settings.
{{<hint "tip" >}}
Crossplane supports installations with image digests instead of tags to get deterministic
and repeatable installations.
and repeatable installations.
```yaml {label="digest"}
apiVersion: pkg.crossplane.io/v1
@ -135,7 +140,7 @@ kind: Provider
metadata:
name: provider-aws
spec:
package: xpkg.crossplane.io/crossplane-contrib/provider-aws@sha256:ee6bece46dbb54cc3f0233961f5baac317fa4e4a81b41198bdc72fc472d113d0
package: xpkg.upbound.io/crossplane-contrib/provider-aws@sha256:ee6bece46dbb54cc3f0233961f5baac317fa4e4a81b41198bdc72fc472d113d0
```
{{< /hint >}}
@ -145,26 +150,26 @@ Use a {{<hover label="pullpolicy" line="6">}}packagePullPolicy{{</hover>}} to
define when Crossplane should download the Provider package to the local
Crossplane package cache.
The `packagePullPolicy` options are:
The `packagePullPolicy` options are:
* `IfNotPresent` - (**default**) Only download the package if it isn't in the cache.
* `Always` - Check for new packages every minute and download any matching
package that isn't in the cache.
* `Never` - Never download the package. Packages are only installed from the
local package cache.
local package cache.
{{<hint "tip" >}}
The Crossplane
The Crossplane
{{<hover label="pullpolicy" line="6">}}packagePullPolicy{{</hover>}} works
like the Kubernetes container image
[image pull policy](https://kubernetes.io/docs/concepts/containers/images/#image-pull-policy).
like the Kubernetes container image
[image pull policy](https://kubernetes.io/docs/concepts/containers/images/#image-pull-policy).
Crossplane supports the use of tags and package digest hashes like
Kubernetes images.
Kubernetes images.
{{< /hint >}}
For example, to `Always` download a given Provider package use the
For example, to `Always` download a given Provider package use the
{{<hover label="pullpolicy" line="6">}}packagePullPolicy: Always{{</hover>}}
configuration.
configuration.
```yaml {label="pullpolicy",copy-lines="6"}
apiVersion: pkg.crossplane.io/v1
@ -179,20 +184,20 @@ spec:
#### Revision activation policy
The `Active` package revision
is the package controller actively reconciling resources.
is the package controller actively reconciling resources.
By default Crossplane sets the most recently installed package revision as
By default Crossplane sets the most recently installed package revision as
`Active`.
Control the Provider upgrade behavior with a
{{<hover label="revision" line="6">}}revisionActivationPolicy{{</hover>}}.
The {{<hover label="revision" line="6">}}revisionActivationPolicy{{</hover>}}
The {{<hover label="revision" line="6">}}revisionActivationPolicy{{</hover>}}
options are:
* `Automatic` - (**default**) Automatically activate the last installed Provider.
* `Manual` - Don't automatically activate a Provider.
For example, to change the upgrade behavior to require manual upgrades, set
For example, to change the upgrade behavior to require manual upgrades, set
{{<hover label="revision" line="6">}}revisionActivationPolicy: Manual{{</hover>}}.
```yaml {label="revision"}
@ -207,26 +212,26 @@ spec:
#### Package revision history limit
When Crossplane installs a different version of the same Provider package
Crossplane creates a new _revision_.
When Crossplane installs a different version of the same Provider package
Crossplane creates a new _revision_.
By default Crossplane maintains one _Inactive_ revision.
By default Crossplane maintains one _Inactive_ revision.
{{<hint "note" >}}
Read the [Provider upgrade](#upgrade-a-provider) section for
more information on the use of package revisions.
{{< /hint >}}
Change the number of revisions Crossplane maintains with a Provider Package
{{<hover label="revHistoryLimit" line="6">}}revisionHistoryLimit{{</hover>}}.
Change the number of revisions Crossplane maintains with a Provider Package
{{<hover label="revHistoryLimit" line="6">}}revisionHistoryLimit{{</hover>}}.
The {{<hover label="revHistoryLimit" line="6">}}revisionHistoryLimit{{</hover>}}
field is an integer.
The default value is `1`.
Disable storing revisions by setting
field is an integer.
The default value is `1`.
Disable storing revisions by setting
{{<hover label="revHistoryLimit" line="6">}}revisionHistoryLimit{{</hover>}} to `0`.
For example, to change the default setting and store 10 revisions use
For example, to change the default setting and store 10 revisions use
{{<hover label="revHistoryLimit" line="6">}}revisionHistoryLimit: 10{{</hover>}}.
```yaml {label="revHistoryLimit"}
@ -241,13 +246,13 @@ spec:
#### Install a provider from a private registry
Like Kubernetes uses `imagePullSecrets` to
[install images from private registries](https://kubernetes.io/docs/tasks/configure-pod-container/pull-image-private-registry/),
Like Kubernetes uses `imagePullSecrets` to
[install images from private registries](https://kubernetes.io/docs/tasks/configure-pod-container/pull-image-private-registry/),
Crossplane uses `packagePullSecrets` to install Provider packages from a private
registry.
registry.
Use {{<hover label="pps" line="6">}}packagePullSecrets{{</hover>}} to provide a
Kubernetes secret to use for authentication when downloading a Provider package.
Kubernetes secret to use for authentication when downloading a Provider package.
{{<hint "important" >}}
The Kubernetes secret must be in the same namespace as Crossplane.
@ -257,7 +262,7 @@ The {{<hover label="pps" line="6">}}packagePullSecrets{{</hover>}} is a list of
secrets.
For example, to use the secret named
{{<hover label="pps" line="6">}}example-secret{{</hover>}} configure a
{{<hover label="pps" line="6">}}example-secret{{</hover>}} configure a
{{<hover label="pps" line="6">}}packagePullSecrets{{</hover>}}.
```yaml {label="pps"}
@ -266,25 +271,25 @@ kind: Provider
metadata:
name: provider-aws
spec:
packagePullSecrets:
packagePullSecrets:
- name: example-secret
# Removed for brevity
```
{{<hint "note" >}}
Configured `packagePullSecrets` aren't passed to any Provider package
dependencies.
dependencies.
{{< /hint >}}
#### Ignore dependencies
By default Crossplane installs any [dependencies](#manage-dependencies) listed
in a Provider package.
in a Provider package.
Crossplane can ignore a Provider package's dependencies with
Crossplane can ignore a Provider package's dependencies with
{{<hover label="pkgDep" line="6" >}}skipDependencyResolution{{</hover>}}.
For example, to disable dependency resolution configure
For example, to disable dependency resolution configure
{{<hover label="pkgDep" line="6" >}}skipDependencyResolution: true{{</hover>}}.
```yaml {label="pkgDep"}
@ -297,58 +302,17 @@ spec:
# Removed for brevity
```
#### Automatically update dependency versions
Crossplane can automatically upgrade a package's dependency version to the minimum
valid version that satisfies all the constraints. It's an alpha feature that
requires enabling with the `--enable-dependency-version-upgrades` flag.
In some cases, dependency version downgrade is required for proceeding with
installations. Suppose configuration A, which depends on package X with the
constraint`>=v0.0.0`, is installed on the control plane. In this case, the package
manager installs the latest version of package X, such as `v3.0.0`. Later, you decide
to install configuration B, which depends on package X with the constraint `<=v2.0.0`.
Since version `v2.0.0` satisfies both conditions, package X must be downgraded to
allow the installation of configuration B which is disabled by default.
Automatic dependency version downgrades is also an alpha feature that can be
enabled with the `--enable-dependency-version-downgrades` flag. Downgrading a
package can cause unexpected behavior, therefore, this option is disabled by
default. After enabling this option, the package manager will automatically
downgrade a package's dependency version to the maximum valid version that
satisfies the constraints.
{{<hint "note" >}}
This configuration requires the `--enable-dependency-version-upgrades` flag.
Please check the
[configuration options]({{<ref "../software/install#customize-the-crossplane-helm-chart">}})
and
[feature flags]({{<ref "../software/install#feature-flags">}})
are available in the
[Crossplane Install]({{<ref "../software/install">}})
section for more details.
{{</hint >}}
{{<hint "important" >}}
Enabling automatic dependency downgrades may have unintended consequences, such as:
1) CRDs missing in the downgraded version, possibly leaving orphaned MRs without
controllers to reconcile them.
2) Loss of data if downgraded CRD versions omit fields that were set before.
3) Changes in the CRD storage version, which may prevent package version update.
{{</hint >}}
#### Ignore Crossplane version requirements
A Provider package may require a specific or minimum Crossplane version before
installing. By default, Crossplane doesn't install a Provider if the Crossplane
version doesn't meet the required version.
version doesn't meet the required version.
Crossplane can ignore the required version with
Crossplane can ignore the required version with
{{<hover label="xpVer" line="6">}}ignoreCrossplaneConstraints{{</hover>}}.
For example, to install a Provider package into an unsupported Crossplane
version, configure
version, configure
{{<hover label="xpVer" line="6">}}ignoreCrossplaneConstraints: true{{</hover>}}.
```yaml {label="xpVer"}
@ -364,21 +328,21 @@ spec:
### Manage dependencies
Providers packages may include dependencies on other packages including
Configurations or other Providers.
Configurations or other Providers.
If Crossplane can't meet the dependencies of a Provider package the Provider
reports `HEALTHY` as `False`.
reports `HEALTHY` as `False`.
For example, this installation of the Getting Started Configuration is
For example, this installation of the Upbound AWS reference platform is
`HEALTHY: False`.
```shell {copy-lines="1"}
kubectl get providers
NAME INSTALLED HEALTHY PACKAGE AGE
provider-aws-s3 True False xpkg.crossplane.io/crossplane-contrib/provider-aws-s3:v1.21.1 12s
provider-aws-s3 True False xpkg.upbound.io/upbound/provider-aws-s3:v1.0.0 12s
```
To see more information on why the Provider isn't `HEALTHY` use
To see more information on why the Provider isn't `HEALTHY` use
{{<hover label="depend" line="1">}}kubectl describe providerrevisions{{</hover>}}.
```yaml {copy-lines="1",label="depend"}
@ -388,7 +352,7 @@ API Version: pkg.crossplane.io/v1
Kind: ProviderRevision
Spec:
Desired State: Active
Image: xpkg.crossplane.io/crossplane-contrib/provider-aws-s3:v1.21.1
Image: xpkg.upbound.io/upbound/provider-aws-s3:v1.0.0
Revision: 1
Status:
Conditions:
@ -404,9 +368,9 @@ Events:
Warning LintPackage 41s (x3 over 47s) packages/providerrevision.pkg.crossplane.io incompatible Crossplane version: package isn't compatible with Crossplane version (v1.10.0)
```
The {{<hover label="depend" line="17">}}Events{{</hover>}} show a
The {{<hover label="depend" line="17">}}Events{{</hover>}} show a
{{<hover label="depend" line="20">}}Warning{{</hover>}} with a message that the
current version of Crossplane doesn't meet the Configuration package
current version of Crossplane doesn't meet the Configuration package
requirements.
## Upgrade a Provider
@ -420,30 +384,30 @@ Crossplane installs the new image and creates a new `ProviderRevision`.
The `ProviderRevision` allows Crossplane to store deprecated Provider CRDs
without removing them until you decide.
View the `ProviderRevisions` with
View the `ProviderRevisions` with
{{<hover label="getPR" line="1">}}kubectl get providerrevisions{{</hover>}}
```shell {label="getPR",copy-lines="1"}
kubectl get providerrevisions
NAME HEALTHY REVISION IMAGE STATE DEP-FOUND DEP-INSTALLED AGE
provider-aws-s3-dbc7f981d81f True 1 xpkg.crossplane.io/crossplane-contrib/provider-aws-s3:v1.21.1 Active 1 1 10d
provider-nop-552a394a8acc True 2 xpkg.crossplane.io/crossplane-contrib/provider-nop:v0.3.0 Active 11d
provider-nop-7e62d2a1a709 True 1 xpkg.crossplane.io/crossplane-contrib/provider-nop:v0.2.0 Inactive 13d
crossplane-contrib-provider-family-aws-710d8cfe9f53 True 1 xpkg.crossplane.io/crossplane-contrib/provider-family-aws:v1.21.1 Active 10d
provider-aws-s3-dbc7f981d81f True 1 xpkg.upbound.io/upbound/provider-aws-s3:v1.0.0 Active 1 1 10d
provider-nop-552a394a8acc True 2 xpkg.upbound.io/crossplane-contrib/provider-nop:v0.3.0 Active 11d
provider-nop-7e62d2a1a709 True 1 xpkg.upbound.io/crossplane-contrib/provider-nop:v0.2.0 Inactive 13d
upbound-provider-family-aws-710d8cfe9f53 True 1 xpkg.upbound.io/upbound/provider-family-aws:v1.0.0 Active 10d
```
By default Crossplane keeps a single
By default Crossplane keeps a single
{{<hover label="getPR" line="5">}}Inactive{{</hover>}} Provider.
Read the [revision history limit](#package-revision-history-limit) section to
change the default value.
change the default value.
Only a single revision of a Provider is
Only a single revision of a Provider is
{{<hover label="getPR" line="4">}}Active{{</hover>}} at a time.
## Remove a Provider
Remove a Provider by deleting the Provider object with
Remove a Provider by deleting the Provider object with
`kubectl delete provider`.
{{< hint "warning" >}}
@ -472,7 +436,7 @@ During the install a Provider report `INSTALLED` as `True` and `HEALTHY` as
```shell {copy-lines="1"}
kubectl get providers
NAME INSTALLED HEALTHY PACKAGE AGE
crossplane-contrib-provider-aws True Unknown xpkg.crossplane.io/crossplane-contrib/provider-aws:v0.39.0 63s
crossplane-contrib-provider-aws True Unknown xpkg.upbound.io/crossplane-contrib/provider-aws:v0.39.0 63s
```
After the Provider install completes and it's ready for use the `HEALTHY` status
@ -481,7 +445,7 @@ reports `True`.
```shell {copy-lines="1"}
kubectl get providers
NAME INSTALLED HEALTHY PACKAGE AGE
crossplane-contrib-provider-aws True True xpkg.crossplane.io/crossplane-contrib/provider-aws:v0.39.0 88s
crossplane-contrib-provider-aws True True xpkg.upbound.io/crossplane-contrib/provider-aws:v0.39.0 88s
```
{{<hint "important" >}}
@ -495,7 +459,7 @@ The Crossplane community has more
### Provider conditions
Crossplane uses a standard set of `Conditions` for Providers.
Crossplane uses a standard set of `Conditions` for Providers.
View the conditions of a provider under their `Status` with
`kubectl describe provider`.
@ -622,7 +586,7 @@ Providers have two different types of configurations:
an external provider. For example, cloud provider authentication.
{{<hint "important" >}}
Apply `ControllerConfig` objects to Providers.
Apply `ControllerConfig` objects to Providers.
Apply `ProviderConfig` objects to managed resources.
{{< /hint >}}
@ -689,7 +653,7 @@ kind: Provider
metadata:
name: provider-gcp-iam
spec:
package: xpkg.crossplane.io/crossplane-contrib/provider-gcp-iam:v1.12.1
package: xpkg.upbound.io/upbound/provider-gcp-iam:v1
runtimeConfigRef:
name: enable-ess
---

10
content/master/getting-started/install-crossplane-include.md
View File

@ -71,7 +71,7 @@ function:
hostNetwork: false
image:
pullPolicy: IfNotPresent
repository: xpkg.crossplane.io/crossplane/crossplane
repository: xpkg.upbound.io/crossplane/crossplane
tag: ""
imagePullSecrets: {}
leaderElection: true
@ -840,7 +840,7 @@ spec:
serviceAccountName: crossplane
hostNetwork: false
initContainers:
- image: "xpkg.crossplane.io/crossplane/crossplane:v1.15.0"
- image: "xpkg.upbound.io/crossplane/crossplane:v1.15.0"
args:
- core
- init
@ -894,7 +894,7 @@ spec:
- name: "TLS_CLIENT_SECRET_NAME"
value: crossplane-tls-client
containers:
- image: "xpkg.crossplane.io/crossplane/crossplane:v1.15.0"
- image: "xpkg.upbound.io/crossplane/crossplane:v1.15.0"
args:
- core
- start
@ -1011,7 +1011,7 @@ spec:
spec:
serviceAccountName: rbac-manager
initContainers:
- image: "xpkg.crossplane.io/crossplane/crossplane:v1.15.0"
- image: "xpkg.upbound.io/crossplane/crossplane:v1.15.0"
args:
- rbac
- init
@ -1041,7 +1041,7 @@ spec:
containerName: crossplane-init
resource: limits.memory
containers:
- image: "xpkg.crossplane.io/crossplane/crossplane:v1.15.0"
- image: "xpkg.upbound.io/crossplane/crossplane:v1.15.0"
args:
- rbac
- start

17
content/master/getting-started/introduction.md
View File

@ -86,9 +86,9 @@ The following sections describe the functions of some of these CRDs.
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)
[AWS](https://marketplace.upbound.io/providers/upbound/provider-aws),
[Azure](https://marketplace.upbound.io/providers/upbound/provider-azure)
and [GCP](https://marketplace.upbound.io/providers/upbound/provider-gcp)
are different providers for each cloud service.
{{< hint "tip" >}}
@ -100,16 +100,19 @@ 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)
For example, the
[Upbound Provider AWS](https://marketplace.upbound.io/providers/upbound/provider-aws/)
defines a
[`bucket`](https://github.com/crossplane-contrib/provider-upjet-aws/blob/release-1.20/package/crds/s3.aws.upbound.io_buckets.yaml)
[`bucket`](https://marketplace.upbound.io/providers/upbound/provider-aws/v0.25.0/resources/s3.aws.upbound.io/Bucket/v1beta1)
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)
[`spec.forProvider.region`](https://marketplace.upbound.io/providers/upbound/provider-aws/v0.25.0/resources/s3.aws.upbound.io/Bucket/v1beta1#doc:spec-forProvider-region)
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.

156
content/master/getting-started/provider-aws-part-2.md
View File

@ -7,7 +7,7 @@ aliases:
---
{{< hint "important" >}}
This guide is part 2 of a series.
This guide is part 2 of a series.
[**Part 1**]({{<ref "provider-aws" >}}) covers
to installing Crossplane and connect your Kubernetes cluster to AWS.
@ -36,7 +36,7 @@ crossplane-stable/crossplane \
```
2. When the Crossplane pods finish installing and are ready, apply the AWS Provider
```yaml {label="provider",copy-lines="all"}
cat <<EOF | kubectl apply -f -
apiVersion: pkg.crossplane.io/v1
@ -44,7 +44,7 @@ kind: Provider
metadata:
name: provider-aws-s3
spec:
package: xpkg.crossplane.io/crossplane-contrib/provider-aws-s3:v1.21.1
package: xpkg.upbound.io/upbound/provider-aws-s3:v1
EOF
```
@ -83,11 +83,11 @@ EOF
## Install the DynamoDB Provider
Part 1 only installed the AWS S3 Provider. This section deploys an S3 bucket
along with a DynamoDB Table.
Deploying a DynamoDB Table requires the DynamoDB Provider as well.
Part 1 only installed the AWS S3 Provider. This section deploys an S3 bucket
along with a DynamoDB Table.
Deploying a DynamoDB Table requires the DynamoDB Provider as well.
Add the new Provider to the cluster.
Add the new Provider to the cluster.
```yaml
cat <<EOF | kubectl apply -f -
@ -96,7 +96,7 @@ kind: Provider
metadata:
name: provider-aws-dynamodb
spec:
package: xpkg.crossplane.io/crossplane-contrib/provider-aws-dynamodb:v1.21.1
package: xpkg.upbound.io/upbound/provider-aws-dynamodb:v1
EOF
```
@ -105,10 +105,10 @@ View the new DynamoDB provider with `kubectl get providers`.
```shell {copy-lines="1"}
kubectl get providers
NAME INSTALLED HEALTHY PACKAGE AGE
crossplane-contrib-provider-family-aws True True xpkg.crossplane.io/crossplane-contrib/provider-family-aws:v1.21.1 15m
provider-aws-dynamodb True True xpkg.crossplane.io/crossplane-contrib/provider-aws-dynamodb:v1.21.1 22s
provider-aws-s3 True True xpkg.crossplane.io/crossplane-contrib/provider-aws-s3:v1.21.1 15m
NAME INSTALLED HEALTHY PACKAGE AGE
provider-aws-dynamodb True True xpkg.upbound.io/upbound/provider-aws-dynamodb:v1.0.0 3m55s
provider-aws-s3 True True xpkg.upbound.io/upbound/provider-aws-s3:v1.0.0 13m
upbound-provider-family-aws True True xpkg.upbound.io/upbound/provider-family-aws:v1.0.0 13m
```
## Create a custom API
@ -116,10 +116,10 @@ provider-aws-s3 True True xpkg.crossplane.i
<!-- vale alex.Condescending = NO -->
Crossplane allows you to build your own custom APIs for your users, abstracting
away details about the cloud provider and their resources. You can make your API
as complex or simple as you wish.
as complex or simple as you wish.
<!-- vale alex.Condescending = YES -->
The custom API is a Kubernetes object.
The custom API is a Kubernetes object.
Here is an example custom API.
```yaml {label="exAPI"}
@ -127,39 +127,39 @@ apiVersion: database.example.com/v1alpha1
kind: NoSQL
metadata:
name: my-nosql-database
spec:
spec:
location: "US"
```
Like any Kubernetes object the API has a
{{<hover label="exAPI" line="1">}}version{{</hover>}},
{{<hover label="exAPI" line="2">}}kind{{</hover>}} and
Like any Kubernetes object the API has a
{{<hover label="exAPI" line="1">}}version{{</hover>}},
{{<hover label="exAPI" line="2">}}kind{{</hover>}} and
{{<hover label="exAPI" line="5">}}spec{{</hover>}}.
### Define a group and version
To create your own API start by defining an
[API group](https://kubernetes.io/docs/reference/using-api/#api-groups) and
[version](https://kubernetes.io/docs/reference/using-api/#api-versioning).
To create your own API start by defining an
[API group](https://kubernetes.io/docs/reference/using-api/#api-groups) and
[version](https://kubernetes.io/docs/reference/using-api/#api-versioning).
The _group_ can be any value, but common convention is to map to a fully
qualified domain name.
qualified domain name.
<!-- vale gitlab.SentenceLength = NO -->
The version shows how mature or stable the API is and increments when changing,
adding or removing fields in the API.
<!-- vale gitlab.SentenceLength = YES -->
Crossplane doesn't require specific versions or a specific version naming
convention, but following
Crossplane doesn't require specific versions or a specific version naming
convention, but following
[Kubernetes API versioning guidelines](https://kubernetes.io/docs/reference/using-api/#api-versioning)
is strongly recommended.
is strongly recommended.
* `v1alpha1` - A new API that may change at any time.
* `v1beta1` - An existing API that's considered stable. Breaking changes are
strongly discouraged.
* `v1` - A stable API that doesn't have breaking changes.
* `v1` - A stable API that doesn't have breaking changes.
This guide uses the group
This guide uses the group
{{<hover label="version" line="1">}}database.example.com{{</hover>}}.
Because this is the first version of the API, this guide uses the version
@ -176,10 +176,10 @@ individual kinds representing different resources.
For example a `database` group may have a `Relational` and `NoSQL` kinds.
The `kind` can be anything, but it must be
The `kind` can be anything, but it must be
[UpperCamelCased](https://kubernetes.io/docs/contribute/style/style-guide/#use-upper-camel-case-for-api-objects).
This API's kind is
This API's kind is
{{<hover label="kind" line="2">}}NoSQL{{</hover>}}
```yaml {label="kind",copy-lines="none"}
@ -190,51 +190,51 @@ kind: NoSQL
### Define a spec
The most important part of an API is the schema. The schema defines the inputs
accepted from users.
accepted from users.
This API allows users to provide a
{{<hover label="spec" line="4">}}location{{</hover>}} of where to run their
This API allows users to provide a
{{<hover label="spec" line="4">}}location{{</hover>}} of where to run their
cloud resources.
All other resource settings can't be configurable by the users. This allows
Crossplane to enforce any policies and standards without worrying about
user errors.
user errors.
```yaml {label="spec",copy-lines="none"}
apiVersion: database.example.com/v1alpha1
kind: NoSQL
spec:
spec:
location: "US"
```
### Apply the API
Crossplane uses
{{<hover label="xrd" line="3">}}Composite Resource Definitions{{</hover>}}
Crossplane uses
{{<hover label="xrd" line="3">}}Composite Resource Definitions{{</hover>}}
(also called an `XRD`) to install your custom API in
Kubernetes.
Kubernetes.
The XRD {{<hover label="xrd" line="6">}}spec{{</hover>}} contains all the
information about the API including the
information about the API including the
{{<hover label="xrd" line="7">}}group{{</hover>}},
{{<hover label="xrd" line="12">}}version{{</hover>}},
{{<hover label="xrd" line="9">}}kind{{</hover>}} and
{{<hover label="xrd" line="9">}}kind{{</hover>}} and
{{<hover label="xrd" line="13">}}schema{{</hover>}}.
The XRD's {{<hover label="xrd" line="5">}}name{{</hover>}} must be the
combination of the {{<hover label="xrd" line="9">}}plural{{</hover>}} and
combination of the {{<hover label="xrd" line="9">}}plural{{</hover>}} and
{{<hover label="xrd" line="7">}}group{{</hover>}}.
The {{<hover label="xrd" line="13">}}schema{{</hover>}} uses the
{{<hover label="xrd" line="14">}}OpenAPIv3{{</hover>}} specification to define
the API {{<hover label="xrd" line="17">}}spec{{</hover>}}.
the API {{<hover label="xrd" line="17">}}spec{{</hover>}}.
The API defines a {{<hover label="xrd" line="20">}}location{{</hover>}} that
must be {{<hover label="xrd" line="22">}}oneOf{{</hover>}} either
{{<hover label="xrd" line="23">}}EU{{</hover>}} or
must be {{<hover label="xrd" line="22">}}oneOf{{</hover>}} either
{{<hover label="xrd" line="23">}}EU{{</hover>}} or
{{<hover label="xrd" line="24">}}US{{</hover>}}.
Apply this XRD to create the custom API in your Kubernetes cluster.
Apply this XRD to create the custom API in your Kubernetes cluster.
```yaml {label="xrd",copy-lines="all"}
cat <<EOF | kubectl apply -f -
@ -272,20 +272,20 @@ EOF
```
Adding the {{<hover label="xrd" line="29">}}claimNames{{</hover>}} allows users
to access this API either at the cluster level with the
to access this API either at the cluster level with the
{{<hover label="xrd" line="9">}}nosql{{</hover>}} endpoint or in a namespace
with the
{{<hover label="xrd" line="29">}}nosqlclaim{{</hover>}} endpoint.
with the
{{<hover label="xrd" line="29">}}nosqlclaim{{</hover>}} endpoint.
The namespace scoped API is a Crossplane _Claim_.
{{<hint "tip" >}}
For more details on the fields and options of Composite Resource Definitions
read the
[XRD documentation]({{<ref "../concepts/composite-resource-definitions">}}).
read the
[XRD documentation]({{<ref "../concepts/composite-resource-definitions">}}).
{{< /hint >}}
View the installed XRD with `kubectl get xrd`.
View the installed XRD with `kubectl get xrd`.
```shell {copy-lines="1"}
kubectl get xrd
@ -307,20 +307,20 @@ When users access the custom API Crossplane takes their inputs and combines them
with a template describing what infrastructure to deploy. Crossplane calls this
template a _Composition_.
The {{<hover label="comp" line="3">}}Composition{{</hover>}} defines all the
The {{<hover label="comp" line="3">}}Composition{{</hover>}} defines all the
cloud resources to deploy. Each entry in the template is a full resource
definition, defining all the resource settings and metadata like labels and
annotations.
annotations.
This template creates an AWS
This template creates an AWS
{{<hover label="comp" line="13">}}S3{{</hover>}}
{{<hover label="comp" line="14">}}Bucket{{</hover>}} and a
{{<hover label="comp" line="14">}}Bucket{{</hover>}} and a
{{<hover label="comp" line="33">}}DynamoDB{{</hover>}}
{{<hover label="comp" line="34">}}Table{{</hover>}}.
This Composition takes the user's
{{<hover label="comp" line="21">}}location{{</hover>}} input and uses it as the
{{<hover label="comp" line="16">}}region{{</hover>}} used in the individual
This Composition takes the user's
{{<hover label="comp" line="21">}}location{{</hover>}} input and uses it as the
{{<hover label="comp" line="16">}}region{{</hover>}} used in the individual
resource.
{{<hint "important" >}}
@ -336,7 +336,7 @@ Read the [Composition documentation]({{<ref "../concepts/compositions">}}) for
more information on configuring Compositions and all the available options.
{{< /hint >}}
Apply this Composition to your cluster.
Apply this Composition to your cluster.
```yaml {label="comp",copy-lines="all"}
cat <<EOF | kubectl apply -f -
@ -358,6 +358,8 @@ spec:
base:
apiVersion: s3.aws.upbound.io/v1beta1
kind: Bucket
metadata:
name: crossplane-quickstart-bucket
spec:
forProvider:
region: us-east-2
@ -369,13 +371,15 @@ spec:
toFieldPath: "spec.forProvider.region"
transforms:
- type: map
map:
map:
EU: "eu-north-1"
US: "us-east-2"
- name: dynamoDB
base:
apiVersion: dynamodb.aws.upbound.io/v1beta1
kind: Table
metadata:
name: crossplane-quickstart-database
spec:
forProvider:
region: "us-east-2"
@ -391,7 +395,7 @@ spec:
toFieldPath: "spec.forProvider.region"
transforms:
- type: map
map:
map:
EU: "eu-north-1"
US: "us-east-2"
compositeTypeRef:
@ -417,7 +421,7 @@ kind: Function
metadata:
name: function-patch-and-transform
spec:
package: xpkg.crossplane.io/crossplane-contrib/function-patch-and-transform:v0.8.2
package: xpkg.upbound.io/crossplane-contrib/function-patch-and-transform:v0.1.4
EOF
```
@ -425,8 +429,8 @@ EOF
Read the [Composition documentation]({{<ref "../concepts/compositions">}}) for
more information on configuring Compositions and all the available options.
Read the
[Patch and Transform function documentation]({{<ref "../guides/function-patch-and-transform">}})
Read the
[Patch and Transform function documentation]({{<ref "../guides/function-patch-and-transform">}})
for more information on how it uses patches to map user inputs to Composition
resource templates.
{{< /hint >}}
@ -455,7 +459,7 @@ apiVersion: database.example.com/v1alpha1
kind: NoSQL
metadata:
name: my-nosql-database
spec:
spec:
location: "US"
EOF
```
@ -468,10 +472,10 @@ NAME SYNCED READY COMPOSITION AGE
my-nosql-database True True dynamo-with-bucket 14s
```
This object is a Crossplane _composite resource_ (also called an `XR`).
This object is a Crossplane _composite resource_ (also called an `XR`).
It's a
single object representing the collection of resources created from the
Composition template.
Composition template.
View the individual resources with `kubectl get managed`
@ -504,17 +508,17 @@ No resources found
## Using the API with namespaces
Accessing the API `nosql` happens at the cluster scope.
Accessing the API `nosql` happens at the cluster scope.
Most organizations
isolate their users into namespaces.
isolate their users into namespaces.
A Crossplane _Claim_ is the custom API in a namespace.
Creating a _Claim_ is just like accessing the custom API endpoint, but with the
{{<hover label="claim" line="3">}}kind{{</hover>}}
{{<hover label="claim" line="3">}}kind{{</hover>}}
from the custom API's `claimNames`.
Create a new namespace to test create a Claim in.
Create a new namespace to test create a Claim in.
```shell
kubectl create namespace crossplane-test
@ -529,7 +533,7 @@ kind: NoSQLClaim
metadata:
name: my-nosql-database
namespace: crossplane-test
spec:
spec:
location: "US"
EOF
```
@ -542,7 +546,7 @@ my-nosql-database True True 17s
```
The Claim automatically creates a composite resource, which creates the managed
resources.
resources.
View the Crossplane created composite resource with `kubectl get composite`.
@ -591,9 +595,9 @@ No resources found
```
## Next steps
* Explore AWS resources that Crossplane can configure in the
[provider CRD reference](https://github.com/crossplane-contrib/provider-upjet-aws/blob/main/package/crds).
* Join the [Crossplane Slack](https://slack.crossplane.io/) and connect with
* Explore AWS resources that Crossplane can configure in the
[Provider CRD reference](https://marketplace.upbound.io/providers/upbound/provider-family-aws/).
* Join the [Crossplane Slack](https://slack.crossplane.io/) and connect with
Crossplane users and contributors.
* Read more about the [Crossplane concepts]({{<ref "../concepts">}}) to find out what else you can do
with Crossplane.
with Crossplane.

28
content/master/getting-started/provider-aws.md
View File

@ -4,8 +4,8 @@ weight: 100
---
Connect Crossplane to AWS to create and manage cloud resources from Kubernetes
with
[provider-upjet-aws](https://github.com/crossplane-contrib/provider-upjet-aws).
with the
[Upbound AWS Provider](https://marketplace.upbound.io/providers/upbound/provider-family-aws).
This guide is in two parts:
* Part 1 walks through installing Crossplane, configuring the provider to
@ -37,7 +37,7 @@ kind: Provider
metadata:
name: provider-aws-s3
spec:
package: xpkg.crossplane.io/crossplane-contrib/provider-aws-s3:v1.21.1
package: xpkg.upbound.io/upbound/provider-aws-s3:v1
EOF
```
@ -51,13 +51,13 @@ Verify the provider installed with `kubectl get providers`.
```shell {copy-lines="1",label="getProvider"}
kubectl get providers
NAME INSTALLED HEALTHY PACKAGE AGE
crossplane-contrib-provider-family-aws True True xpkg.crossplane.io/crossplane-contrib/provider-family-aws:v1.21.1 30s
provider-aws-s3 True True xpkg.crossplane.io/crossplane-contrib/provider-aws-s3:v1.21.1 34s
NAME INSTALLED HEALTHY PACKAGE AGE
provider-aws-s3 True True xpkg.upbound.io/upbound/provider-aws-s3:1.0.0 97s
upbound-provider-family-aws True True xpkg.upbound.io/upbound/provider-family-aws:1.0.0 88s
```
The S3 Provider installs a second Provider, the
{{<hover label="getProvider" line="4">}}crossplane-contrib-provider-family-aws{{</hover >}}.
{{<hover label="getProvider" line="4">}}upbound-provider-family-aws{{</hover >}}.
The family provider manages authentication to AWS across all AWS family
Providers.
@ -67,7 +67,7 @@ Every CRD maps to a unique AWS service Crossplane can provision and manage.
{{< hint type="tip" >}}
See details about all the supported CRDs in the
[provider examples](https://github.com/crossplane-contrib/provider-upjet-aws/tree/main/examples).
[Upbound Marketplace](https://marketplace.upbound.io/providers/upbound/provider-aws-s3/v1.1.0).
{{< /hint >}}
## Create a Kubernetes secret for AWS
@ -197,16 +197,16 @@ spec:
EOF
```
The {{< hover label="xr" line="2">}}apiVersion{{< /hover >}} and
{{< hover label="xr" line="3">}}kind{{</hover >}} are from the provider's CRDs.
The {{< hover label="xr" line="3">}}apiVersion{{< /hover >}} and
{{< hover label="xr" line="4">}}kind{{</hover >}} are from the provider's CRDs.
The {{< hover label="xr" line="5">}}metadata.generateName{{< /hover >}} value is the
The {{< hover label="xr" line="6">}}metadata.name{{< /hover >}} value is the
name of the created S3 bucket in AWS.
This example uses the generated name `crossplane-bucket-<hash>` in the
{{< hover label="xr" line="5">}}$bucket{{</hover >}} variable.
{{< hover label="xr" line="6">}}$bucket{{</hover >}} variable.
The {{< hover label="xr" line="8">}}spec.forProvider.region{{< /hover >}} tells
The {{< hover label="xr" line="9">}}spec.forProvider.region{{< /hover >}} tells
AWS which AWS region to use when deploying resources.
The region can be any
@ -239,6 +239,6 @@ bucket.s3.aws.upbound.io "crossplane-bucket-hhdzh" deleted
* [**Continue to part 2**]({{< ref "provider-aws-part-2">}}) to create and use a
custom API with Crossplane.
* Explore AWS resources that Crossplane can configure in the
[provider CRD reference](https://github.com/crossplane-contrib/provider-upjet-aws/blob/main/package/crds).
[Provider CRD reference](https://marketplace.upbound.io/providers/upbound/provider-family-aws/).
* Join the [Crossplane Slack](https://slack.crossplane.io/) and connect with
Crossplane users and contributors.

160
content/master/getting-started/provider-azure-part-2.md
View File

@ -7,7 +7,7 @@ aliases:
---
{{< hint "important" >}}
This guide is part 2 of a series.
This guide is part 2 of a series.
[**Part 1**]({{<ref "provider-azure" >}}) covers
to installing Crossplane and connect your Kubernetes cluster to Azure.
@ -35,9 +35,9 @@ crossplane-stable/crossplane \
--create-namespace
```
2. When the Crossplane pods finish installing and are ready, apply the Azure
2. When the Crossplane pods finish installing and are ready, apply the Azure
Provider
```yaml {label="provider",copy-lines="all"}
cat <<EOF | kubectl apply -f -
apiVersion: pkg.crossplane.io/v1
@ -45,11 +45,11 @@ kind: Provider
metadata:
name: provider-azure-network
spec:
package: xpkg.crossplane.io/crossplane-contrib/provider-azure-network:v1.11.2
package: xpkg.upbound.io/upbound/provider-azure-network:v1
EOF
```
3. Use the Azure CLI to create a service principal and save the JSON output as
3. Use the Azure CLI to create a service principal and save the JSON output as
`azure-crednetials.json`
{{< editCode >}}
```console
@ -91,10 +91,10 @@ EOF
<!-- vale alex.Condescending = NO -->
Crossplane allows you to build your own custom APIs for your users, abstracting
away details about the cloud provider and their resources. You can make your API
as complex or simple as you wish.
as complex or simple as you wish.
<!-- vale alex.Condescending = YES -->
The custom API is a Kubernetes object.
The custom API is a Kubernetes object.
Here is an example custom API.
```yaml {label="exAPI"}
@ -102,39 +102,39 @@ apiVersion: compute.example.com/v1alpha1
kind: VirtualMachine
metadata:
name: my-vm
spec:
spec:
location: "US"
```
Like any Kubernetes object the API has a
{{<hover label="exAPI" line="1">}}version{{</hover>}},
{{<hover label="exAPI" line="2">}}kind{{</hover>}} and
Like any Kubernetes object the API has a
{{<hover label="exAPI" line="1">}}version{{</hover>}},
{{<hover label="exAPI" line="2">}}kind{{</hover>}} and
{{<hover label="exAPI" line="5">}}spec{{</hover>}}.
### Define a group and version
To create your own API start by defining an
[API group](https://kubernetes.io/docs/reference/using-api/#api-groups) and
[version](https://kubernetes.io/docs/reference/using-api/#api-versioning).
To create your own API start by defining an
[API group](https://kubernetes.io/docs/reference/using-api/#api-groups) and
[version](https://kubernetes.io/docs/reference/using-api/#api-versioning).
The _group_ can be any value, but common convention is to map to a fully
qualified domain name.
qualified domain name.
<!-- vale gitlab.SentenceLength = NO -->
The version shows how mature or stable the API is and increments when changing,
adding or removing fields in the API.
<!-- vale gitlab.SentenceLength = YES -->
Crossplane doesn't require specific versions or a specific version naming
convention, but following
Crossplane doesn't require specific versions or a specific version naming
convention, but following
[Kubernetes API versioning guidelines](https://kubernetes.io/docs/reference/using-api/#api-versioning)
is strongly recommended.
is strongly recommended.
* `v1alpha1` - A new API that may change at any time.
* `v1beta1` - An existing API that's considered stable. Breaking changes are
strongly discouraged.
* `v1` - A stable API that doesn't have breaking changes.
* `v1` - A stable API that doesn't have breaking changes.
This guide uses the group
This guide uses the group
{{<hover label="version" line="1">}}compute.example.com{{</hover>}}.
Because this is the first version of the API, this guide uses the version
@ -151,10 +151,10 @@ individual kinds representing different resources.
For example a `compute` group may have a `VirtualMachine` and `BareMetal` kinds.
The `kind` can be anything, but it must be
The `kind` can be anything, but it must be
[UpperCamelCased](https://kubernetes.io/docs/contribute/style/style-guide/#use-upper-camel-case-for-api-objects).
This API's kind is
This API's kind is
{{<hover label="kind" line="2">}}VirtualMachine{{</hover>}}
```yaml {label="kind",copy-lines="none"}
@ -165,51 +165,51 @@ kind: VirtualMachine
### Define a spec
The most important part of an API is the schema. The schema defines the inputs
accepted from users.
accepted from users.
This API allows users to provide a
{{<hover label="spec" line="4">}}location{{</hover>}} of where to run their
This API allows users to provide a
{{<hover label="spec" line="4">}}location{{</hover>}} of where to run their
cloud resources.
All other resource settings can't be configurable by the users. This allows
Crossplane to enforce any policies and standards without worrying about
user errors.
user errors.
```yaml {label="spec",copy-lines="none"}
apiVersion: compute.example.com/v1alpha1
kind: VirtualMachine
spec:
spec:
location: "US"
```
### Apply the API
Crossplane uses
{{<hover label="xrd" line="3">}}Composite Resource Definitions{{</hover>}}
Crossplane uses
{{<hover label="xrd" line="3">}}Composite Resource Definitions{{</hover>}}
(also called an `XRD`) to install your custom API in
Kubernetes.
Kubernetes.
The XRD {{<hover label="xrd" line="6">}}spec{{</hover>}} contains all the
information about the API including the
information about the API including the
{{<hover label="xrd" line="7">}}group{{</hover>}},
{{<hover label="xrd" line="12">}}version{{</hover>}},
{{<hover label="xrd" line="9">}}kind{{</hover>}} and
{{<hover label="xrd" line="9">}}kind{{</hover>}} and
{{<hover label="xrd" line="13">}}schema{{</hover>}}.
The XRD's {{<hover label="xrd" line="5">}}name{{</hover>}} must be the
combination of the {{<hover label="xrd" line="10">}}plural{{</hover>}} and
combination of the {{<hover label="xrd" line="10">}}plural{{</hover>}} and
{{<hover label="xrd" line="7">}}group{{</hover>}}.
The {{<hover label="xrd" line="13">}}schema{{</hover>}} uses the
{{<hover label="xrd" line="14">}}OpenAPIv3{{</hover>}} specification to define
the API {{<hover label="xrd" line="17">}}spec{{</hover>}}.
the API {{<hover label="xrd" line="17">}}spec{{</hover>}}.
The API defines a {{<hover label="xrd" line="20">}}location{{</hover>}} that
must be {{<hover label="xrd" line="22">}}oneOf{{</hover>}} either
{{<hover label="xrd" line="23">}}EU{{</hover>}} or
must be {{<hover label="xrd" line="22">}}oneOf{{</hover>}} either
{{<hover label="xrd" line="23">}}EU{{</hover>}} or
{{<hover label="xrd" line="24">}}US{{</hover>}}.
Apply this XRD to create the custom API in your Kubernetes cluster.
Apply this XRD to create the custom API in your Kubernetes cluster.
```yaml {label="xrd",copy-lines="all"}
cat <<EOF | kubectl apply -f -
@ -247,20 +247,20 @@ EOF
```
Adding the {{<hover label="xrd" line="29">}}claimNames{{</hover>}} allows users
to access this API either at the cluster level with the
to access this API either at the cluster level with the
{{<hover label="xrd" line="9">}}VirtualMachine{{</hover>}} endpoint or in a namespace
with the
{{<hover label="xrd" line="30">}}VirtualMachineClaim{{</hover>}} endpoint.
with the
{{<hover label="xrd" line="30">}}VirtualMachineClaim{{</hover>}} endpoint.
The namespace scoped API is a Crossplane _Claim_.
{{<hint "tip" >}}
For more details on the fields and options of Composite Resource Definitions
read the
[XRD documentation]({{<ref "../concepts/composite-resource-definitions">}}).
read the
[XRD documentation]({{<ref "../concepts/composite-resource-definitions">}}).
{{< /hint >}}
View the installed XRD with `kubectl get xrd`.
View the installed XRD with `kubectl get xrd`.
```shell {copy-lines="1"}
kubectl get xrd
@ -282,22 +282,22 @@ When users access the custom API Crossplane takes their inputs and combines them
with a template describing what infrastructure to deploy. Crossplane calls this
template a _Composition_.
The {{<hover label="comp" line="3">}}Composition{{</hover>}} defines all the
The {{<hover label="comp" line="3">}}Composition{{</hover>}} defines all the
cloud resources to deploy.
Each entry in the template
is a full resource definitions, defining all the resource settings and metadata
like labels and annotations.
like labels and annotations.
This template creates an Azure
{{<hover label="comp" line="11">}}LinuxVirtualMachine{{</hover>}}
{{<hover label="comp" line="46">}}NetworkInterface{{</hover>}},
{{<hover label="comp" line="46">}}NetworkInterface{{</hover>}},
{{<hover label="comp" line="69">}}Subnet{{</hover>}}
{{<hover label="comp" line="90">}}VirtualNetwork{{</hover>}} and
{{<hover label="comp" line="110">}}ResourceGroup{{</hover>}}.
This Composition takes the user's
{{<hover label="comp" line="36">}}location{{</hover>}} input and uses it as the
{{<hover label="comp" line="37">}}location{{</hover>}} used in the individual
This Composition takes the user's
{{<hover label="comp" line="36">}}location{{</hover>}} input and uses it as the
{{<hover label="comp" line="37">}}location{{</hover>}} used in the individual
resource.
{{<hint "important" >}}
@ -313,7 +313,7 @@ Read the [Composition documentation]({{<ref "../concepts/compositions">}}) for
more information on configuring Compositions and all the available options.
{{< /hint >}}
Apply this Composition to your cluster.
Apply this Composition to your cluster.
```yaml {label="comp",copy-lines="all"}
cat <<EOF | kubectl apply -f -
@ -363,7 +363,7 @@ spec:
toFieldPath: "spec.forProvider.location"
transforms:
- type: map
map:
map:
EU: "Sweden Central"
US: "Central US"
- name: quickstart-nic
@ -386,9 +386,9 @@ spec:
toFieldPath: "spec.forProvider.location"
transforms:
- type: map
map:
map:
EU: "Sweden Central"
US: "Central US"
US: "Central US"
- name: quickstart-subnet
base:
apiVersion: network.azure.upbound.io/v1beta1
@ -418,7 +418,7 @@ spec:
toFieldPath: "spec.forProvider.location"
transforms:
- type: map
map:
map:
EU: "Sweden Central"
US: "Central US"
- name: crossplane-resourcegroup
@ -434,7 +434,7 @@ spec:
toFieldPath: "spec.forProvider.location"
transforms:
- type: map
map:
map:
EU: "Sweden Central"
US: "Central US"
compositeTypeRef:
@ -460,7 +460,7 @@ kind: Function
metadata:
name: function-patch-and-transform
spec:
package: xpkg.crossplane.io/crossplane-contrib/function-patch-and-transform:v0.8.2
package: xpkg.upbound.io/crossplane-contrib/function-patch-and-transform:v0.1.4
EOF
```
@ -468,8 +468,8 @@ EOF
Read the [Composition documentation]({{<ref "../concepts/compositions">}}) for
more information on configuring Compositions and all the available options.
Read the
[Patch and Transform function documentation]({{<ref "../guides/function-patch-and-transform">}})
Read the
[Patch and Transform function documentation]({{<ref "../guides/function-patch-and-transform">}})
for more information on how it uses patches to map user inputs to Composition
resource templates.
{{< /hint >}}
@ -485,9 +485,9 @@ crossplane-quickstart-vm-with-network XVirtualMachine custom-api.example.org
## Install the Azure virtual machine provider
Part 1 only installed the Azure Virtual Network Provider. To deploying virtual
machines requires the Azure Compute provider as well.
machines requires the Azure Compute provider as well.
Add the new Provider to the cluster.
Add the new Provider to the cluster.
```yaml
cat <<EOF | kubectl apply -f -
@ -496,7 +496,7 @@ kind: Provider
metadata:
name: provider-azure-compute
spec:
package: xpkg.crossplane.io/crossplane-contrib/provider-azure-compute:v1.11.2
package: xpkg.upbound.io/upbound/provider-azure-compute:v1
EOF
```
@ -505,10 +505,10 @@ View the new Compute provider with `kubectl get providers`.
```shell {copy-lines="1"}
kubectl get providers
NAME INSTALLED HEALTHY PACKAGE AGE
crossplane-contrib-provider-family-azure True True xpkg.crossplane.io/crossplane-contrib/provider-family-azure:v1.11.2 23m
provider-azure-compute True True xpkg.crossplane.io/crossplane-contrib/provider-azure-compute:v1.11.2 2m54s
provider-azure-network True True xpkg.crossplane.io/crossplane-contrib/provider-azure-network:v1.11.2 23m
NAME INSTALLED HEALTHY PACKAGE AGE
provider-azure-compute True True xpkg.upbound.io/upbound/provider-azure-compute:v1.0.0 25s
provider-azure-network True True xpkg.upbound.io/upbound/provider-azure-network:v1.0.0 3h
upbound-provider-family-azure True True xpkg.upbound.io/upbound/provider-family-azure:v1.0.0 3h
```
## Access the custom API
@ -516,7 +516,7 @@ provider-azure-network True True xpkg.crossplane
With the custom API (XRD) installed and associated to a resource template
(Composition) users can access the API to create resources.
Create a {{<hover label="xr" line="3">}}VirtualMachine{{</hover>}} object to
Create a {{<hover label="xr" line="3">}}VirtualMachine{{</hover>}} object to
create the cloud resources.
```yaml {copy-lines="all",label="xr"}
@ -525,7 +525,7 @@ apiVersion: compute.example.com/v1alpha1
kind: VirtualMachine
metadata:
name: my-vm
spec:
spec:
location: "EU"
EOF
```
@ -542,10 +542,10 @@ NAME SYNCED READY COMPOSITION AGE
my-vm True True crossplane-quickstart-vm-with-network 3m3s
```
This object is a Crossplane _composite resource_ (also called an `XR`).
This object is a Crossplane _composite resource_ (also called an `XR`).
It's a
single object representing the collection of resources created from the
Composition template.
Composition template.
View the individual resources with `kubectl get managed`
@ -568,7 +568,7 @@ virtualnetwork.network.azure.upbound.io/my-vm-pd2sw True True my-vm-pd2
```
Accessing the API created all five resources defined in the template and linked
them together.
them together.
Look at a specific resource to see it's created in the location used in the API.
@ -598,17 +598,17 @@ No resources found
## Using the API with namespaces
Accessing the API `VirtualMachine` happens at the cluster scope.
Accessing the API `VirtualMachine` happens at the cluster scope.
Most organizations
isolate their users into namespaces.
isolate their users into namespaces.
A Crossplane _Claim_ is the custom API in a namespace.
Creating a _Claim_ is just like accessing the custom API endpoint, but with the
{{<hover label="claim" line="3">}}kind{{</hover>}}
{{<hover label="claim" line="3">}}kind{{</hover>}}
from the custom API's `claimNames`.
Create a new namespace to test create a Claim in.
Create a new namespace to test create a Claim in.
```shell
kubectl create namespace crossplane-test
@ -623,7 +623,7 @@ kind: VirtualMachineClaim
metadata:
name: my-namespaced-vm
namespace: crossplane-test
spec:
spec:
location: "EU"
EOF
```
@ -636,7 +636,7 @@ my-namespaced-vm True True 5m11s
```
The Claim automatically creates a composite resource, which creates the managed
resources.
resources.
View the Crossplane created composite resource with `kubectl get composite`.
@ -693,9 +693,9 @@ No resources found
```
## Next steps
* Explore Azure resources that Crossplane can configure in the
[Provider CRD reference](https://github.com/crossplane-contrib/provider-upjet-azure/tree/main/package/crds).
* Join the [Crossplane Slack](https://slack.crossplane.io/) and connect with
* Explore Azure resources that Crossplane can configure in the
[Provider CRD reference](https://marketplace.upbound.io/providers/upbound/provider-family-azure/).
* Join the [Crossplane Slack](https://slack.crossplane.io/) and connect with
Crossplane users and contributors.
* Read more about the [Crossplane concepts]({{<ref "../concepts">}}) to find out
what else you can do with Crossplane.
what else you can do with Crossplane.

18
content/master/getting-started/provider-azure.md
View File

@ -4,8 +4,8 @@ weight: 110
---
Connect Crossplane to Azure to create and manage cloud resources from Kubernetes
with
[provider-upjet-azure](https://github.com/crossplane-contrib/provider-upjet-azure).
with the
[Upbound Azure Provider](https://marketplace.upbound.io/providers/upbound/provider-family-azure/).
This guide is in two parts:
* Part 1 walks through installing Crossplane, configuring the provider to
@ -39,7 +39,7 @@ kind: Provider
metadata:
name: provider-azure-network
spec:
package: xpkg.crossplane.io/crossplane-contrib/provider-azure-network:v1.11.2
package: xpkg.upbound.io/upbound/provider-azure-network:v1
EOF
```
@ -53,13 +53,13 @@ Verify the provider installed with `kubectl get providers`.
```shell {copy-lines="1",label="getProvider"}
kubectl get providers
NAME INSTALLED HEALTHY PACKAGE AGE
crossplane-contrib-provider-family-azure True True xpkg.crossplane.io/crossplane-contrib/provider-family-azure:v1.11.2 2m18s
provider-azure-network True True xpkg.crossplane.io/crossplane-contrib/provider-azure-network:v1.11.2 2m23s
NAME INSTALLED HEALTHY PACKAGE AGE
provider-azure-network True True xpkg.upbound.io/upbound/provider-azure-network:v1.0.0 38s
upbound-provider-family-azure True True xpkg.upbound.io/upbound/provider-family-azure:v1.0.0 26s
```
The Network Provider installs a second Provider, the
{{<hover label="getProvider" line="4">}}crossplane-contrib-provider-family-azure{{</hover>}}
{{<hover label="getProvider" line="4">}}upbound-provider-family-azure{{</hover>}}
provider.
The family provider manages authentication to Azure across all Azure family
Providers.
@ -69,7 +69,7 @@ Every CRD maps to a unique Azure service Crossplane can provision and manage.
{{< hint type="tip" >}}
See details about all the supported CRDs in the
[provider examples](https://github.com/crossplane-contrib/provider-upjet-azure/tree/main/examples).
[Upbound Marketplace](https://marketplace.upbound.io/providers/upbound/provider-family-azure/v0.42.1).
{{< /hint >}}
@ -234,6 +234,6 @@ virtualnetwork.network.azure.upbound.io "crossplane-quickstart-network" deleted
* [**Continue to part 2**]({{< ref "provider-azure-part-2">}}) to create and use
a custom API with Crossplane.
* Explore Azure resources that Crossplane can configure in the
[Provider CRD reference](https://github.com/crossplane-contrib/provider-upjet-azure/tree/main/package/crds).
[Provider CRD reference](https://marketplace.upbound.io/providers/upbound/provider-family-azure/).
* Join the [Crossplane Slack](https://slack.crossplane.io/) and connect with
Crossplane users and contributors.

168
content/master/getting-started/provider-gcp-part-2.md
View File

@ -7,20 +7,20 @@ aliases:
---
{{< hint "important" >}}
This guide is part 2 of a series.
This guide is part 2 of a series.
[**Part 1**]({{<ref "provider-gcp" >}}) covers
to installing Crossplane and connect your Kubernetes cluster to GCP.
{{< /hint >}}
This guide walks you through building and accessing a custom API with
This guide walks you through building and accessing a custom API with
Crossplane.
## Prerequisites
* Complete [quickstart part 1]({{<ref "provider-gcp" >}}) connecting Kubernetes
to GCP.
* a GCP account with permissions to create a GCP
* a GCP account with permissions to create a GCP
[storage bucket](https://cloud.google.com/storage) and a
[Pub/Sub topic](https://cloud.google.com/pubsub).
@ -37,9 +37,9 @@ crossplane-stable/crossplane \
--create-namespace
```
2. When the Crossplane pods finish installing and are ready, apply the GCP
2. When the Crossplane pods finish installing and are ready, apply the GCP
Provider.
```yaml {label="provider",copy-lines="all"}
cat <<EOF | kubectl apply -f -
apiVersion: pkg.crossplane.io/v1
@ -47,16 +47,16 @@ kind: Provider
metadata:
name: provider-gcp-storage
spec:
package: xpkg.crossplane.io/crossplane-contrib/provider-gcp-storage:v1.12.1
package: xpkg.upbound.io/upbound/provider-gcp-storage:v1
EOF
```
3. Create a file called `gcp-credentials.json` with your GCP service account
3. Create a file called `gcp-credentials.json` with your GCP service account
JSON file.
{{< hint "tip" >}}
The
[GCP documentation](https://cloud.google.com/iam/docs/creating-managing-service-account-keys)
The
[GCP documentation](https://cloud.google.com/iam/docs/creating-managing-service-account-keys)
provides information on how to generate a service account JSON file.
{{< /hint >}}
@ -69,12 +69,12 @@ generic gcp-secret \
```
5. Create a _ProviderConfig_
Include your
Include your
{{< hover label="providerconfig" line="7" >}}GCP project ID{{< /hover >}} in the
_ProviderConfig_ settings.
{{< hint type="tip" >}}
Find your GCP project ID from the `project_id` field of the
Find your GCP project ID from the `project_id` field of the
`gcp-credentials.json` file.
{{< /hint >}}
@ -101,11 +101,11 @@ EOF
## Install the PubSub Provider
Part 1 only installed the GCP Storage Provider. This section deploys a
PubSub Topic along with a GCP storage bucket.
Part 1 only installed the GCP Storage Provider. This section deploys a
PubSub Topic along with a GCP storage bucket.
First install the GCP PubSub Provider.
Add the new Provider to the cluster.
Add the new Provider to the cluster.
```yaml
cat <<EOF | kubectl apply -f -
@ -114,7 +114,7 @@ kind: Provider
metadata:
name: provider-gcp-pubsub
spec:
package: xpkg.crossplane.io/crossplane-contrib/provider-gcp-pubsub:v1.12.1
package: xpkg.upbound.io/upbound/provider-gcp-pubsub:v1
EOF
```
@ -122,10 +122,10 @@ View the new PubSub provider with `kubectl get providers`.
```shell {copy-lines="1"}
kubectl get providers
NAME INSTALLED HEALTHY PACKAGE AGE
crossplane-contrib-provider-family-gcp True True xpkg.crossplane.io/crossplane-contrib/provider-family-gcp:v1.12.1 48m
provider-gcp-pubsub True True xpkg.crossplane.io/crossplane-contrib/provider-gcp-pubsub:v1.12.1 14s
provider-gcp-storage True True xpkg.crossplane.io/crossplane-contrib/provider-gcp-storage:v1.12.1 48m
NAME INSTALLED HEALTHY PACKAGE AGE
provider-gcp-pubsub True True xpkg.upbound.io/upbound/provider-gcp-pubsub:v1.0.0 39s
provider-gcp-storage True True xpkg.upbound.io/upbound/provider-gcp-storage:v1.0.0 13m
upbound-provider-family-gcp True True xpkg.upbound.io/upbound/provider-family-gcp:v1.0.0 12m
```
@ -134,10 +134,10 @@ provider-gcp-storage True True xpkg.crossplane.i
<!-- vale alex.Condescending = NO -->
Crossplane allows you to build your own custom APIs for your users, abstracting
away details about the cloud provider and their resources. You can make your API
as complex or simple as you wish.
as complex or simple as you wish.
<!-- vale alex.Condescending = YES -->
The custom API is a Kubernetes object.
The custom API is a Kubernetes object.
Here is an example custom API.
```yaml {label="exAPI"}
@ -145,39 +145,39 @@ apiVersion: database.example.com/v1alpha1
kind: NoSQL
metadata:
name: my-nosql-database
spec:
spec:
location: "US"
```
Like any Kubernetes object the API has a
{{<hover label="exAPI" line="1">}}version{{</hover>}},
{{<hover label="exAPI" line="2">}}kind{{</hover>}} and
Like any Kubernetes object the API has a
{{<hover label="exAPI" line="1">}}version{{</hover>}},
{{<hover label="exAPI" line="2">}}kind{{</hover>}} and
{{<hover label="exAPI" line="5">}}spec{{</hover>}}.
### Define a group and version
To create your own API start by defining an
[API group](https://kubernetes.io/docs/reference/using-api/#api-groups) and
[version](https://kubernetes.io/docs/reference/using-api/#api-versioning).
To create your own API start by defining an
[API group](https://kubernetes.io/docs/reference/using-api/#api-groups) and
[version](https://kubernetes.io/docs/reference/using-api/#api-versioning).
The _group_ can be any value, but common convention is to map to a fully
qualified domain name.
qualified domain name.
<!-- vale gitlab.SentenceLength = NO -->
The version shows how mature or stable the API is and increments when changing,
adding or removing fields in the API.
<!-- vale gitlab.SentenceLength = YES -->
Crossplane doesn't require specific versions or a specific version naming
convention, but following
Crossplane doesn't require specific versions or a specific version naming
convention, but following
[Kubernetes API versioning guidelines](https://kubernetes.io/docs/reference/using-api/#api-versioning)
is strongly recommended.
is strongly recommended.
* `v1alpha1` - A new API that may change at any time.
* `v1beta1` - An existing API that's considered stable. Breaking changes are
strongly discouraged.
* `v1` - A stable API that doesn't have breaking changes.
* `v1` - A stable API that doesn't have breaking changes.
This guide uses the group
This guide uses the group
{{<hover label="version" line="1">}}database.example.com{{</hover>}}.
Because this is the first version of the API, this guide uses the version
@ -194,10 +194,10 @@ individual kinds representing different resources.
For example a `queue` group may have a `PubSub` and `CloudTask` kinds.
The `kind` can be anything, but it must be
The `kind` can be anything, but it must be
[UpperCamelCased](https://kubernetes.io/docs/contribute/style/style-guide/#use-upper-camel-case-for-api-objects).
This API's kind is
This API's kind is
{{<hover label="kind" line="2">}}PubSub{{</hover>}}
```yaml {label="kind",copy-lines="none"}
@ -208,51 +208,51 @@ kind: PubSub
### Define a spec
The most important part of an API is the schema. The schema defines the inputs
accepted from users.
accepted from users.
This API allows users to provide a
{{<hover label="spec" line="4">}}location{{</hover>}} of where to run their
This API allows users to provide a
{{<hover label="spec" line="4">}}location{{</hover>}} of where to run their
cloud resources.
All other resource settings can't be configurable by the users. This allows
Crossplane to enforce any policies and standards without worrying about
user errors.
user errors.
```yaml {label="spec",copy-lines="none"}
apiVersion: queue.example.com/v1alpha1
kind: PubSub
spec:
spec:
location: "US"
```
### Apply the API
Crossplane uses
{{<hover label="xrd" line="3">}}Composite Resource Definitions{{</hover>}}
Crossplane uses
{{<hover label="xrd" line="3">}}Composite Resource Definitions{{</hover>}}
(also called an `XRD`) to install your custom API in
Kubernetes.
Kubernetes.
The XRD {{<hover label="xrd" line="6">}}spec{{</hover>}} contains all the
information about the API including the
information about the API including the
{{<hover label="xrd" line="7">}}group{{</hover>}},
{{<hover label="xrd" line="12">}}version{{</hover>}},
{{<hover label="xrd" line="9">}}kind{{</hover>}} and
{{<hover label="xrd" line="9">}}kind{{</hover>}} and
{{<hover label="xrd" line="13">}}schema{{</hover>}}.
The XRD's {{<hover label="xrd" line="5">}}name{{</hover>}} must be the
combination of the {{<hover label="xrd" line="9">}}plural{{</hover>}} and
combination of the {{<hover label="xrd" line="9">}}plural{{</hover>}} and
{{<hover label="xrd" line="7">}}group{{</hover>}}.
The {{<hover label="xrd" line="13">}}schema{{</hover>}} uses the
{{<hover label="xrd" line="14">}}OpenAPIv3{{</hover>}} specification to define
the API {{<hover label="xrd" line="17">}}spec{{</hover>}}.
the API {{<hover label="xrd" line="17">}}spec{{</hover>}}.
The API defines a {{<hover label="xrd" line="20">}}location{{</hover>}} that
must be {{<hover label="xrd" line="22">}}oneOf{{</hover>}} either
{{<hover label="xrd" line="23">}}EU{{</hover>}} or
must be {{<hover label="xrd" line="22">}}oneOf{{</hover>}} either
{{<hover label="xrd" line="23">}}EU{{</hover>}} or
{{<hover label="xrd" line="24">}}US{{</hover>}}.
Apply this XRD to create the custom API in your Kubernetes cluster.
Apply this XRD to create the custom API in your Kubernetes cluster.
```yaml {label="xrd",copy-lines="all"}
cat <<EOF | kubectl apply -f -
@ -290,20 +290,20 @@ EOF
```
Adding the {{<hover label="xrd" line="29">}}claimNames{{</hover>}} allows users
to access this API either at the cluster level with the
to access this API either at the cluster level with the
{{<hover label="xrd" line="9">}}pubsub{{</hover>}} endpoint or in a namespace
with the
{{<hover label="xrd" line="29">}}pubsubclaim{{</hover>}} endpoint.
with the
{{<hover label="xrd" line="29">}}pubsubclaim{{</hover>}} endpoint.
The namespace scoped API is a Crossplane _Claim_.
{{<hint "tip" >}}
For more details on the fields and options of Composite Resource Definitions
read the
[XRD documentation]({{<ref "../concepts/composite-resource-definitions">}}).
read the
[XRD documentation]({{<ref "../concepts/composite-resource-definitions">}}).
{{< /hint >}}
View the installed XRD with `kubectl get xrd`.
View the installed XRD with `kubectl get xrd`.
```shell {copy-lines="1"}
kubectl get xrd
@ -325,21 +325,21 @@ When users access the custom API Crossplane takes their inputs and combines them
with a template describing what infrastructure to deploy. Crossplane calls this
template a _Composition_.
The {{<hover label="comp" line="3">}}Composition{{</hover>}} defines all the
The {{<hover label="comp" line="3">}}Composition{{</hover>}} defines all the
cloud resources to deploy.
Each entry in the template
is a full resource definitions, defining all the resource settings and metadata
like labels and annotations.
like labels and annotations.
This template creates a GCP
{{<hover label="comp" line="10">}}Storage{{</hover>}}
{{<hover label="comp" line="11">}}Bucket{{</hover>}} and a
{{<hover label="comp" line="11">}}Bucket{{</hover>}} and a
{{<hover label="comp" line="25">}}PubSub{{</hover>}}
{{<hover label="comp" line="26">}}Topic{{</hover>}}.
This Composition takes the user's
{{<hover label="comp" line="16">}}location{{</hover>}} input and uses it as the
{{<hover label="comp" line="14">}}location{{</hover>}} used in the individual
This Composition takes the user's
{{<hover label="comp" line="16">}}location{{</hover>}} input and uses it as the
{{<hover label="comp" line="14">}}location{{</hover>}} used in the individual
resource.
{{<hint "important" >}}
@ -355,7 +355,7 @@ Read the [Composition documentation]({{<ref "../concepts/compositions">}}) for
more information on configuring Compositions and all the available options.
{{< /hint >}}
Apply this Composition to your cluster.
Apply this Composition to your cluster.
```yaml {label="comp",copy-lines="all"}
cat <<EOF | kubectl apply -f -
@ -385,7 +385,7 @@ spec:
toFieldPath: "spec.forProvider.location"
transforms:
- type: map
map:
map:
EU: "EU"
US: "US"
- name: crossplane-quickstart-topic
@ -395,14 +395,14 @@ spec:
spec:
forProvider:
messageStoragePolicy:
- allowedPersistenceRegions:
- allowedPersistenceRegions:
- "us-central1"
patches:
- fromFieldPath: "spec.location"
toFieldPath: "spec.forProvider.messageStoragePolicy[0].allowedPersistenceRegions[0]"
transforms:
- type: map
map:
map:
EU: "europe-central2"
US: "us-central1"
compositeTypeRef:
@ -428,7 +428,7 @@ kind: Function
metadata:
name: function-patch-and-transform
spec:
package: xpkg.crossplane.io/crossplane-contrib/function-patch-and-transform:v0.8.2
package: xpkg.upbound.io/crossplane-contrib/function-patch-and-transform:v0.1.4
EOF
```
@ -436,8 +436,8 @@ EOF
Read the [Composition documentation]({{<ref "../concepts/compositions">}}) for
more information on configuring Compositions and all the available options.
Read the
[Patch and Transform function documentation]({{<ref "../guides/function-patch-and-transform">}})
Read the
[Patch and Transform function documentation]({{<ref "../guides/function-patch-and-transform">}})
for more information on how it uses patches to map user inputs to Composition
resource templates.
{{< /hint >}}
@ -464,7 +464,7 @@ apiVersion: queue.example.com/v1alpha1
kind: PubSub
metadata:
name: my-pubsub-queue
spec:
spec:
location: "US"
EOF
```
@ -477,10 +477,10 @@ NAME SYNCED READY COMPOSITION AGE
my-pubsub-queue True True topic-with-bucket 2m12s
```
This object is a Crossplane _composite resource_ (also called an `XR`).
This object is a Crossplane _composite resource_ (also called an `XR`).
It's a
single object representing the collection of resources created from the
Composition template.
Composition template.
View the individual resources with `kubectl get managed`
@ -513,17 +513,17 @@ No resources found
## Using the API with namespaces
Accessing the API `pubsub` happens at the cluster scope.
Accessing the API `pubsub` happens at the cluster scope.
Most organizations
isolate their users into namespaces.
isolate their users into namespaces.
A Crossplane _Claim_ is the custom API in a namespace.
Creating a _Claim_ is just like accessing the custom API endpoint, but with the
{{<hover label="claim" line="3">}}kind{{</hover>}}
{{<hover label="claim" line="3">}}kind{{</hover>}}
from the custom API's `claimNames`.
Create a new namespace to test create a Claim in.
Create a new namespace to test create a Claim in.
```shell
kubectl create namespace crossplane-test
@ -535,10 +535,10 @@ Then create a Claim in the `crossplane-test` namespace.
cat <<EOF | kubectl apply -f -
apiVersion: queue.example.com/v1alpha1
kind: PubSubClaim
metadata:
metadata:
name: my-pubsub-queue
namespace: crossplane-test
spec:
spec:
location: "US"
EOF
```
@ -551,7 +551,7 @@ my-pubsub-queue True True 2m10s
```
The Claim automatically creates a composite resource, which creates the managed
resources.
resources.
View the Crossplane created composite resource with `kubectl get composite`.
@ -600,9 +600,9 @@ No resources found
```
## Next steps
* Explore AWS resources that Crossplane can configure in the
[provider CRD reference](https://github.com/crossplane-contrib/provider-upjet-aws/blob/main/package/crds).
* Join the [Crossplane Slack](https://slack.crossplane.io/) and connect with
* Explore AWS resources that Crossplane can configure in the
[Provider CRD reference](https://marketplace.upbound.io/providers/upbound/provider-family-aws/).
* Join the [Crossplane Slack](https://slack.crossplane.io/) and connect with
Crossplane users and contributors.
* Read more about the [Crossplane concepts]({{<ref "../concepts">}}) to find out what else you can do
with Crossplane.
with Crossplane.

18
content/master/getting-started/provider-gcp.md
View File

@ -4,8 +4,8 @@ weight: 140
---
Connect Crossplane to GCP to create and manage cloud resources from Kubernetes
with
[provider-upjet-gcp](https://github.com/crossplane-contrib/provider-upjet-gcp).
with the
[Upbound GCP Provider](https://marketplace.upbound.io/providers/upbound/provider-family-gcp/).
This guide is in two parts:
* Part 1 walks through installing Crossplane, configuring the provider to
@ -36,7 +36,7 @@ kind: Provider
metadata:
name: provider-gcp-storage
spec:
package: xpkg.crossplane.io/crossplane-contrib/provider-gcp-storage:v1.12.1
package: xpkg.upbound.io/upbound/provider-gcp-storage:v1
EOF
```
@ -50,13 +50,13 @@ Verify the provider installed with `kubectl get providers`.
```shell {copy-lines="1",label="getProvider"}
kubectl get providers
NAME INSTALLED HEALTHY PACKAGE AGE
crossplane-contrib-provider-family-gcp True True xpkg.crossplane.io/crossplane-contrib/provider-family-gcp:v1.12.1 33s
provider-gcp-storage True True xpkg.crossplane.io/crossplane-contrib/provider-gcp-storage:v1.12.1 37s
NAME INSTALLED HEALTHY PACKAGE AGE
provider-gcp-storage True True xpkg.upbound.io/upbound/provider-gcp-storage:v1.0.0 36s
upbound-provider-family-gcp True True xpkg.upbound.io/upbound/provider-family-gcp:v1.0.0 29s
```
The Storage Provider installs a second Provider, the
{{<hover label="getProvider" line="4">}}crossplane-contrib-provider-family-gcp{{</hover>}}
{{<hover label="getProvider" line="4">}}upbound-provider-family-gcp{{</hover>}}
provider.
The family provider manages authentication to GCP across all GCP family
Providers.
@ -66,7 +66,7 @@ Every CRD maps to a unique GCP service Crossplane can provision and manage.
{{< hint "tip" >}}
See details about all the supported CRDs in the
[provider examples](https://github.com/crossplane-contrib/provider-upjet-gcp/tree/main/examples).
[Upbound Marketplace](https://marketplace.upbound.io/providers/upbound/provider-family-gcp/).
{{< /hint >}}
@ -246,6 +246,6 @@ bucket.storage.gcp.upbound.io "crossplane-bucket-8b7gw" deleted
* [**Continue to part 2**]({{< ref "provider-gcp-part-2">}}) to create a
Crossplane _Composite Resource_ and _Claim_.
* Explore GCP resources that can Crossplane can configure in the
[Provider CRD reference](https://github.com/crossplane-contrib/provider-upjet-gcp/tree/main/package/crds).
[Provider CRD reference](https://marketplace.upbound.io/providers/upbound/provider-family-gcp/).
* Join the [Crossplane Slack](https://slack.crossplane.io/) and connect with
Crossplane users and contributors.

271
content/master/guides/change-logs.md
View File

@ -1,271 +0,0 @@
---
title: Change Logs
weight: 210
description: "Change logs help you audit all changes made to your resources"
state: alpha
alphaVersion: "1.17"
---
The "change logs" feature is designed to help users of Crossplane Providers to
understand what changes a provider is making to the resources it's managing.
Whenever a provider creates, updates, or deletes a managed resource, an entry
explaining the details of the change is recorded in the provider's change log.
Change logs are important for awareness of the changes that a provider is
making to its managed resources. Due to the nature of Crossplane's active
reconciliation, it's possible for a provider to make changes to managed
resources without any user interaction. Consider the scenario when someone
updates a resource outside of Crossplane, for example via the AWS console or
`gcloud` CLI. When Crossplane detects this configuration drift it will
enforce its source of truth to eventually correct this unexpected change
without any user interaction.
With Crossplane acting continuously and autonomously to update critical
infrastructure, it's vital for users to have insight into the operations being
performed, so they can build and maintain a strong sense of confidence and trust
in their control planes. Change logs provide details about all changes the
provider makes, so users can remain aware of any changes, even when they aren't
explicitly expecting any.
{{<hint "tip">}} Change logs help you understand all the changes a provider is
making to your resources, even when changes weren't explicitly requested, for
example as a result of Crossplane's automatic correction of configuration drift.
{{</hint>}}
## Enabling Change Logs
{{<hint "important" >}} Change logs are an alpha feature and must be explicitly
enabled for each provider through the use of a `DeploymentRuntimeConfig`.
{{</hint >}}
To enable change logs for a provider, use a `DeploymentRuntimeConfig` to
configure each provider pod that should start producing change logs. The
`DeploymentRuntimeConfig` has a few important configuration details:
1. A command line argument to the provider container that enables the change
logs feature, for example `--enable-changelogs`.
1. A [side car container](https://github.com/crossplane/changelogs-sidecar) that
collects change events and produces change log entries to the provider's pod
logs.
1. A shared volume mounted to both the provider and sidecar containers that
enables communication of change events between the two containers.
### Prerequisites
This guide assumes you have a control plane with [Crossplane installed]({{<ref "../software/install">}}).
It also assumes you have the [`jq` tool installed](https://jqlang.org/download/),
to perform lightweight querying and filtering of the content in the change logs.
The only other prerequisite for enabling change logs is that the provider must
have added support for the change logs feature. This is optional and not all
providers in the Crossplane ecosystem have added this support yet.
{{<hint "tip">}} Not all providers support the change logs feature. Check with
your provider of choice to confirm it has added support for change logs.
{{</hint>}}
This guide walks through a full example of generating change logs with
[`provider-kubernetes`](https://github.com/crossplane-contrib/provider-kubernetes).
### Create a `DeploymentRuntimeConfig`
Create a `DeploymentRuntimeConfig` that will enable change logs for
the provider when it's installed by performing the necessary configuration
steps:
1. The {{<hover label="drc" line="15">}}--enable-changelogs{{</hover>}} flag is
set on the provider.
1. The {{<hover label="drc" line="19">}}sidecar container{{</hover>}} is added
to the provider pod.
1. A {{<hover label="drc" line="24">}}shared volume{{</hover>}} is declared and
then mounted in the {{<hover label="drc" line="16">}}provider
container{{</hover>}} and the {{<hover label="drc" line="21">}}sidecar
container{{</hover>}}.
```yaml {label="drc",copy-lines="all"}
cat <<EOF | kubectl apply -f -
apiVersion: pkg.crossplane.io/v1beta1
kind: DeploymentRuntimeConfig
metadata:
name: enable-changelogs
spec:
deploymentTemplate:
spec:
selector: {}
template:
spec:
containers:
- name: package-runtime
args:
- --enable-changelogs
volumeMounts:
- name: changelogs-vol
mountPath: /var/run/changelogs
- name: changelogs-sidecar
image: xpkg.crossplane.io/crossplane/changelogs-sidecar:v0.0.1
volumeMounts:
- name: changelogs-vol
mountPath: /var/run/changelogs
volumes:
- name: changelogs-vol
emptyDir: {}
serviceAccountTemplate:
metadata:
name: provider-kubernetes
EOF
```
### Install the provider
Install the {{<hover label="provider" line="7">}}provider{{</hover>}} and
instruct it to use the {{<hover label="provider" line="8">}}DeploymentRuntimeConfig{{</hover>}}
that was just created.
```yaml {label="provider",copy-lines="all"}
cat <<EOF | kubectl apply -f -
apiVersion: pkg.crossplane.io/v1
kind: Provider
metadata:
name: provider-kubernetes
spec:
package: xpkg.crossplane.io/crossplane-contrib/provider-kubernetes:v0.18.0
runtimeConfigRef:
apiVersion: pkg.crossplane.io/v1beta1
kind: DeploymentRuntimeConfig
name: enable-changelogs
EOF
```
### Configure permissions
In order for the provider to create Kubernetes resources within the control
plane, it must be granted the appropriate permissions. This guide only creates a
`ConfigMap`, so only permissions for that resource type are needed.
{{<hint "important">}} This guide grants specific permissions to the provider
for example purposes. This approach isn't intended to be representative of a
production environment. More examples on configuring `provider-kubernetes` can
be found in its [examples directory](https://github.com/crossplane-contrib/provider-kubernetes/tree/main/examples/provider).
{{</hint>}}
```yaml {label="rbac",copy-lines="all"}
cat <<EOF | kubectl apply -f -
apiVersion: rbac.authorization.k8s.io/v1
kind: ClusterRole
metadata:
name: configmap-edit
rules:
- apiGroups:
- ""
resources:
- configmaps
verbs:
- "*"
---
apiVersion: rbac.authorization.k8s.io/v1
kind: ClusterRoleBinding
metadata:
name: provider-kubernetes-configmap-edit
subjects:
- kind: ServiceAccount
name: provider-kubernetes
namespace: crossplane-system
roleRef:
kind: ClusterRole
name: configmap-edit
apiGroup: rbac.authorization.k8s.io
---
apiVersion: kubernetes.crossplane.io/v1alpha1
kind: ProviderConfig
metadata:
name: default
spec:
credentials:
source: InjectedIdentity
EOF
```
### Create a resource
Now that the provider is installed and configured with change logs enabled,
create a resource that will generate change logs entries reflecting the actions
the control plane is taking.
```yaml {label="provider",copy-lines="all"}
cat <<EOF | kubectl apply -f -
apiVersion: kubernetes.crossplane.io/v1alpha2
kind: Object
metadata:
name: configmap-for-changelogs
spec:
forProvider:
manifest:
apiVersion: v1
kind: ConfigMap
metadata:
namespace: default
name: configmap-for-changelogs
data:
key-1: cool-value-1
EOF
```
### Examine the change logs
Check to see that the resource creation operation was recorded in the change
logs. Examine the pod logs for `provider-kubernetes`, specifically at the
`changelogs-sidecar` container:
```shell {label="changelogs-output-full",copy-lines="1"}
kubectl -n crossplane-system logs -l pkg.crossplane.io/provider=provider-kubernetes -c changelogs-sidecar | jq
{
"timestamp": "2025-04-25T08:23:34Z",
"provider": "provider-kubernetes:v0.18.0",
"apiVersion": "kubernetes.crossplane.io/v1alpha2",
"kind": "Object",
"name": "configmap-for-changelogs",
"externalName": "configmap-for-changelogs",
"operation": "OPERATION_TYPE_CREATE",
"snapshot": {
...(omitted for brevity)...
```
Each change log entry contains rich information about the state of the resource
when the change operation occurred. Since each entry is a structured `JSON`
object, they can be filtered and queried to find any subset of information you
are interested in:
```shell {label="changelogs-output-scoped",copy-lines="1-2"}
kubectl -n crossplane-system logs -l pkg.crossplane.io/provider=provider-kubernetes -c changelogs-sidecar \
| jq '.timestamp + " " + .provider + " " + .kind + " " + .name + " " + .operation'
"2025-04-25T08:23:34Z provider-kubernetes:v0.18.0 Object configmap-for-changelogs OPERATION_TYPE_CREATE"
```
### Full lifecycle operations
In addition to change log entries that record the creation of resources, update
and delete operations will also generate corresponding change log entries.
Update the resource by patching its data field `key-1` with a new value
`cooler-value-2`:
```shell {label="object-patch",copy-lines="1-2"}
kubectl patch object configmap-for-changelogs --type=json \
-p='[{"op": "replace", "path": "/spec/forProvider/manifest/data/key-1", "value": "cooler-value-2"}]'
object.kubernetes.crossplane.io/configmap-for-changelogs patched
```
Then, delete the object entirely:
```shell {label="object-delete",copy-lines="1"}
kubectl delete object configmap-for-changelogs
object.kubernetes.crossplane.io "configmap-for-changelogs" deleted
```
Check the change logs again to verify that both the update and delete operations
were recorded, and the full lifecycle of the object has been captured in the
change logs:
```shell {label="changelogs-output-final",copy-lines="1-2"}
kubectl -n crossplane-system logs -l pkg.crossplane.io/provider=provider-kubernetes -c changelogs-sidecar \
| jq '.timestamp + " " + .provider + " " + .kind + " " + .name + " " + .operation'
"2025-04-25T08:23:34Z provider-kubernetes:v0.18.0 Object configmap-for-changelogs OPERATION_TYPE_CREATE"
"2025-04-25T08:24:21Z provider-kubernetes:v0.18.0 Object configmap-for-changelogs OPERATION_TYPE_UPDATE"
"2025-04-25T08:24:25Z provider-kubernetes:v0.18.0 Object configmap-for-changelogs OPERATION_TYPE_DELETE"
```

305
content/master/guides/extensions-release-process.md
View File

@ -1,305 +0,0 @@
---
title: Releasing Crossplane Extensions
weight: 80
description: "Configuring build pipelines for Crossplane extensions with GitHub
Actions"
---
## Distributing Crossplane extensions
Crossplane provides a packaging specification for extending a Crossplane
instance with APIs and business logic for composing resources.
Building a Crossplane extension involves creating OCI images in the [xpkg]
format. Authors and maintainers of Crossplane extensions must push their
packages to an OCI registry before users can reference and use them.
The release process for Crossplane extensions grew organically in the community
and developed its own conventions and common configurations. Authors of these
extensions should follow this guide to enable automation for building
and pushing their packages as part of their git workflow.
This guide provides step-by-step instructions for configuring automated
CI pipelines in GitHub Actions for pushing your Crossplane extensions to
`xpkg.crossplane.io`, the main registry that the Crossplane community
uses today.
{{< hint "tip" >}}
For more information about Crossplane packages, review the
[xpkg concepts]({{<ref "../concepts/packages" >}}).
{{< /hint >}}
## Typical workflow
A typical GitHub workflow definition to build and release an extension
contains the following steps:
1. Fetching the source repository
2. Authenticating to a remote registry
3. Building and packaging artifacts
4. Pushing (publishing) the artifact
{{< hint "warning" >}}
The supplied credentials for the remote registry require read and write access
as upload requests to the registry specify `push` authorization scope.
{{< /hint >}}
## Quickstart: Releasing a Provider to `xpkg.crossplane.io`
### Prerequisites
- A GitHub repository, for example created from the
[Upjet template](https://github.com/crossplane/upjet-provider-template)
### Steps
1. Create a new YAML file under `.github/workflows`. By convention, name this
file `publish-provider-package.yaml`.
2. Copy the following workflow definition into the file, replacing
`<REPOSITORY NAME>` with the desired name of the repository in the registry.
```yaml
name: Publish Provider Package
on:
workflow_dispatch:
inputs:
version:
description: "Version string to use while publishing the package (e.g. v1.0.0-alpha.1)"
default: ''
required: false
go-version:
description: 'Go version to use if building needs to be done'
default: '1.23'
required: false
jobs:
publish-provider-package:
uses: crossplane-contrib/provider-workflows/.github/workflows/publish-provider-non-family.yml@main
with:
repository: <REPOSITORY NAME>
version: ${{ github.event.inputs.version }}
go-version: ${{ github.event.inputs.go-version }}
cleanup-disk: true
secrets:
GHCR_PAT: ${{ secrets.GITHUB_TOKEN }}
```
3. Commit the workflow file to the default branch of the GitHub repository.
4. The workflow should now be available to trigger via the GitHub UI in the
`Actions` tab.
5. Create a release branch with the `release-` prefix in the name in the GitHub UI. For example, `release-0.1`.
6. Tag the desired commit on release branch with a valid semver release tag.
For example, `v0.1.0`. By default, this is the inferred reference pushed to the registry.
7. Manually run the workflow in the GitHub UI, targeting the release branch from step 5.
See [branching conventions](#branching-conventions) for more details on tagging
practices and optionally overriding the inferred git tag version.
## Quickstart: Releasing a Function to `xpkg.crossplane.io`
The template repository for [functions] provides a functional GitHub Action
YAML file that pushes to `xpkg.crossplane.io` without extra configuration.
To build and push a new release to the registry:
1. Cut a release branch with the `release-` prefix in the name in the GitHub UI. For example, `release-0.1`.
2. Tag the desired commit on release branch with a valid semver release tag for a corresponding
GitHub Release. For example, `v0.1.0`.
3. Manually run the workflow in the GitHub UI, targeting the release branch from step 1.
The workflow generates a default version string if user input isn't provided.
See [branching conventions](#branching-conventions) for more details on tagging
practices and optionally overriding the inferred git tag version.
## Common Configuration
While the reusable workflows referenced in the quickstart guides are for
convenience, users may choose to write their own custom GitHub Actions.
This and following sections provide more detailed information
about common configuration options and conventions to implement the release
process.
All workflows require references to credentials for a remote registry.
Typically, users configure them as [GitHub Actions Secrets], and the workflow
performs authentication via the`docker/login-action`
[action](http://github.com/docker/login-action).
For example, adding the following step to a pipeline authenticates
the job to `ghcr.io` using the workflow's ephemeral GitHub OIDC token.
```yaml
- name: Login to GHCR
uses: docker/login-action@v3
with:
registry: ghcr.io
username: ${{ github.repository_owner }}
password: ${{ secrets.GITHUB_TOKEN }}
```
{{< hint "important" >}}
By default, the job's OIDC token doesn't have permission to write packages
to `ghcr.io`. Permissions are configurable in the GitHub repository's settings
or declared
[explicitly](https://docs.github.com/en/actions/writing-workflows/choosing-what-your-workflow-does/controlling-permissions-for-github_token)
in the workflow definition YAML file.
Writing packages requires a `permissions` block with `packages: write` if it
isn't configured elsewhere for the repository.
{{< /hint >}}
For other registries, it's still best practice to reference credentials as
custom Secret variables. For example:
```yaml
- name: Login to Another Registry
uses: docker/login-action@v3
with:
registry: my-registry.io
username: ${{ env.REGISTRY_USER }}
password: ${{ secrets.REGISTRY_PASSWORD }}
```
## Branching conventions
Repositories for Crossplane extensions follow similar branching conventions
to upstream Crossplane, where the release process assumes the workflow
executing in branches with the `release-*` prefix. `main` is often included,
though a conventional release process would not build and push off of tags on
`main`.
```yaml
on:
push:
branches:
- main
- release-*
```
For example, when releasing `v0.1.0` of an extension, the conventional
process is to cut a release branch `release-0.1` at the git commit
where it builds from, and tag it as `v0.1.0`.
{{< hint "note" >}}
Some custom workflows may accept an explicit input for the remote reference instead of
inferring it from a git ref. The [`ci.yml`](https://github.com/crossplane-contrib/function-python/blob/main/.github/workflows/ci.yml)
file for `crossplane-contrib/function-python` is a good example.
{{< /hint >}}
## Configuring workflows for function packages
Function workflow definitions differ based on the base language the
function implementation uses. For example, a Python function requires
a Python environment in the GitHub Action runner:
```yaml
- name: Setup Python
uses: actions/setup-python@v5
with:
python-version: ${{ env.PYTHON_VERSION }}
- name: Setup Hatch
run: pipx install hatch==1.7.0
- name: Lint
run: hatch run lint:check
```
While the template repository provides a working pipeline definition, users may
choose to customize their environment with different tooling.
Functions also require a runtime image of the core business logic to
build and embed into the Function package. The default workflow definition
builds for two platforms: `linux/amd64` and `linux/arm64`.
```yaml
- name: Build Runtime
id: image
uses: docker/build-push-action@v6
with:
context: .
platforms: linux/${{ matrix.arch }}
cache-from: type=gha
cache-to: type=gha,mode=max
target: image
build-args:
PYTHON_VERSION=${{ env.PYTHON_VERSION }}
outputs: type=docker,dest=runtime-${{ matrix.arch }}.tar
```
## Configuring workflows for provider packages
Providers, unlike Functions, use custom `make` targets in the [build submodule]
for building and pushing Crossplane Provider packages.
Configuring the workflow for a specific registry involves two steps:
1. Updating the registry variables in the top-level `Makefile`.
2. Referencing GitHub Actions Secrets for authorized credentials to the
registry.
### Configure target registry
The provider template repository includes a top-level [`Makefile`](https://github.com/crossplane/upjet-provider-template/blob/main/Makefile).
Edit the following variables to define the target registry:
1. `XPKG_REG_ORGS` - a space-delimited list of target repositories.
2. `XPKG_REG_ORGS_NO_PROMOTE` - for registries that don't use or infer
channel tags.
For example, the following dual-pushes to `xpkg.crossplane.io` as well as
`index.docker.io`:
```make
XPKG_REG_ORGS ?= xpkg.crossplane.io/crossplane-contrib index.docker.io/crossplanecontrib
XPKG_REG_ORGS_NO_PROMOTE ?= xpkg.crossplane.io/crossplane-contrib
```
## Reusable workflows
The [crossplane-contrib/provider-workflows] repository provide reusable
workflow definitions that are callable from a custom CI pipeline.
For example, the following snippet references the callable workflow to
build and push the `provider-kubernetes` package to `xpkg.crossplane.io`:
```yaml
jobs:
publish-provider-package:
uses: crossplane-contrib/provider-workflows/.github/workflows/publish-provider-non-family.yml@main
with:
repository: provider-kubernetes
version: ${{ github.event.inputs.version }}
go-version: ${{ github.event.inputs.go-version }}
cleanup-disk: true
secrets:
GHCR_PAT: ${{ secrets.GITHUB_TOKEN }}
```
{{< hint "tip" >}}
The reusable workflows referenced here publish to `ghcr.io` by default.
Ensure that the default GitHub Actions OIDC token inherits the
`packages: write` permission.
{{< /hint >}}
## Troubleshooting
{{< expand "Why is my workflow is failing with a 404 error code?" >}}
Ensure the target repository exists in the registry. You need to create
it if it doesn't already exist.
{{</expand >}}
{{< expand "Why is my workflow failing with a 401 error code?" >}}
Ensure the credentials used during the registry login step has authorization to
pull and push, and that the `{{ secrets.* }}` variable substitutions match
what's configured in GitHub.
{{</expand >}}
<!-- Named Links -->
[xpkg]: https://github.com/crossplane/crossplane/blob/main/contributing/specifications/xpkg.md
[functions]: https://github.com/crossplane/function-template-go/blob/main/.github/workflows/ci.yml
[GitHub Actions Secrets]: https://docs.github.com/en/actions/security-for-github-actions/security-guides/using-secrets-in-github-actions
[build submodule]: https://github.com/crossplane/build
[crossplane-contrib/provider-workflows]: https://github.com/crossplane-contrib/provider-workflows/blob/main/.github/workflows

8
content/master/guides/function-patch-and-transform.md
View File

@ -92,7 +92,7 @@ kind: Function
metadata:
name: function-patch-and-transform
spec:
package: xpkg.crossplane.io/crossplane-contrib/function-patch-and-transform:v0.8.2
package: xpkg.upbound.io/crossplane-contrib/function-patch-and-transform:v0.1.4
```
{{<hint "tip" >}}
@ -122,7 +122,7 @@ The contents of the `base` are identical to creating a standalone
[managed resource]({{<ref "../concepts/managed-resources">}}).
This example uses
[provider-upjet-aws](https://github.com/crossplane-contrib/provider-upjet-aws)
[Upbound's Provider AWS](https://marketplace.upbound.io/providers/upbound/provider-family-aws/v1.17.0)
to define a S3 storage `Bucket` and EC2 compute `Instance`.
After defining the `apiVersion` and `kind`, define the `spec.forProvider` fields
@ -507,8 +507,8 @@ All the following examples use the same set of Compositions,
CompositeResourceDefinitions, Claims and EnvironmentConfigs.
Only the applied patches change between examples.
All examples rely on
[provider-aws-s3](https://github.com/crossplane-contrib/provider-upjet-aws)
All examples rely on Upbound
[provider-aws-s3](https://marketplace.upbound.io/providers/upbound/provider-aws-s3/)
to create resources.
{{< expand "Reference Composition" >}}

6
content/master/guides/import-existing-resources.md
View File

@ -5,7 +5,7 @@ weight: 200
If you have resources that are already provisioned in a Provider,
you can import them as managed resources and let Crossplane manage them.
A managed resource's [`managementPolicies`]({{<ref "../concepts/managed-resources#managementpolicies">}})
A managed resource's [`managementPolicies`]({{<ref "/v1.16/concepts/managed-resources#managementpolicies">}})
field enables importing external resources into Crossplane.
Crossplane can import resources either [manually]({{<ref "#import-resources-manually">}})
@ -84,7 +84,7 @@ managed resource `spec` changes the external resource.
## Import resources automatically
Automatically import external resources with an `Observe` [management policy]({{<ref "../concepts/managed-resources#managementpolicies">}}).
Automatically import external resources with an `Observe` [management policy]({{<ref "/v1.16/concepts/managed-resources#managementpolicies">}}).
Crossplane imports observe only resources but never changes or deletes the
resources.
@ -282,4 +282,4 @@ status:
```
Crossplane now fully manages the imported resource. Crossplane applies any
changes to the managed resource in the Provider's external resource.
changes to the managed resource in the Provider's external resource.

6
content/master/guides/multi-tenant.md
View File

@ -315,9 +315,9 @@ dedicated control planes to many tenants within a single organization.
[Multiple Source Field patching]: https://github.com/crossplane/crossplane/pull/2093
[Configuration packages]: {{<ref "../../master/concepts/packages" >}}
[OCI images]: https://github.com/opencontainers/image-spec
[EKS Cluster]: https://github.com/crossplane-contrib/provider-upjet-aws/blob/main/examples/eks/v1beta2/cluster.yaml
[provider-aws]: https://github.com/crossplane-contrib/provider-upjet-aws
[provider-helm]: https://github.com/crossplane-contrib/provider-helm
[EKS Cluster]: https://marketplace.upbound.io/providers/crossplane-contrib/provider-aws/latest/resources/eks.aws.crossplane.io/Cluster/v1beta1
[provider-aws]: https://marketplace.upbound.io/providers/crossplane-contrib/provider-aws
[provider-helm]: https://marketplace.upbound.io/providers/crossplane-contrib/provider-helm/
[Open Service Broker API]: https://github.com/openservicebrokerapi/servicebroker
[Crossplane Service Broker]: https://github.com/vshn/crossplane-service-broker
[Cloudfoundry]: https://www.cloudfoundry.org/

8
content/master/guides/troubleshoot-crossplane.md
View File

@ -5,8 +5,8 @@ weight: 306
## Requested Resource Not Found
If you use the Crossplane CLI to install a `Provider` or
`Configuration` (for example, `crossplane xpkg install provider
xpkg.crossplane.io/crossplane-contrib/provider-aws-s3:v1.21.1`) and get `the server
`Configuration` (for example, `crossplane install provider
xpkg.upbound.io/crossplane-contrib/provider-aws:v0.33.0`) and get `the server
could not find the requested resource` error, more often than not, that's an
indicator that the Crossplane CLI you're using is outdated. In other words
some Crossplane API has been graduated from alpha to beta or stable and the old
@ -103,7 +103,7 @@ kind: Provider
metadata:
name: provider-aws
spec:
package: xpkg.crossplane.io/crossplane-contrib/provider-aws:v0.33.0
package: xpkg.upbound.io/crossplane-contrib/provider-aws:v0.33.0
runtimeConfigRef:
apiVersion: pkg.crossplane.io/v1beta1
kind: DeploymentRuntimeConfig
@ -365,7 +365,7 @@ kind: Provider
metadata:
name: provider-aws
spec:
package: xpkg.crossplane.io/crossplane-contrib/provider-aws:v0.33.0
package: xpkg.upbound.io/crossplane-contrib/provider-aws:v0.33.0
runtimeConfigRef:
apiVersion: pkg.crossplane.io/v1beta1
kind: DeploymentRuntimeConfig

6
content/master/guides/vault-as-secret-store.md
View File

@ -217,7 +217,7 @@ Next, install the Crossplane ESS Plugin pod to the `crossplane-system` namespace
and apply the Vault annotations.
```shell
helm upgrade --install ess-plugin-vault oci://xpkg.crossplane.io/crossplane-contrib/ess-plugin-vault --namespace crossplane-system -f values.yaml
helm upgrade --install ess-plugin-vault oci://xpkg.upbound.io/crossplane-contrib/ess-plugin-vault --namespace crossplane-system -f values.yaml
```
## Configure Crossplane
@ -255,7 +255,7 @@ kind: Provider
metadata:
name: provider-gcp
spec:
package: xpkg.crossplane.io/crossplane-contrib/provider-gcp:v0.23.0-rc.0.19.ge9b75ee5
package: xpkg.upbound.io/crossplane-contrib/provider-gcp:v0.23.0-rc.0.19.ge9b75ee5
controllerConfigRef:
name: vault-config" | kubectl apply -f -
```
@ -341,7 +341,7 @@ Check that Crossplane installed the Provider and the Provider is healthy.
```shell {copy-lines="1"}
kubectl get providers
NAME INSTALLED HEALTHY PACKAGE AGE
provider-gcp True True xpkg.crossplane.io/crossplane-contrib/provider-gcp:v0.23.0-rc.0.19.ge9b75ee5 10m
provider-gcp True True xpkg.upbound.io/crossplane-contrib/provider-gcp:v0.23.0-rc.0.19.ge9b75ee5 10m
```
### Create a CompositeResourceDefinition

8
content/master/guides/vault-injection.md
View File

@ -310,7 +310,7 @@ kind: Provider
metadata:
name: provider-gcp
spec:
package: xpkg.crossplane.io/crossplane-contrib/provider-gcp:v0.22.0
package: xpkg.upbound.io/crossplane-contrib/provider-gcp:v0.22.0
controllerConfigRef:
name: vault-config" | kubectl apply -f -
```
@ -418,7 +418,7 @@ kind: Provider
metadata:
name: provider-aws
spec:
package: xpkg.crossplane.io/crossplane-contrib/provider-aws:v0.33.0
package: xpkg.upbound.io/crossplane-contrib/provider-aws:v0.33.0
controllerConfigRef:
name: aws-vault-config" | kubectl apply -f -
```
@ -491,8 +491,8 @@ kubectl get bucket -w
[Vault Kubernetes Sidecar]: https://learn.hashicorp.com/tutorials/vault/kubernetes-sidecar
[Vault]: https://www.vaultproject.io/
[Vault Kubernetes Sidecar]: https://www.vaultproject.io/docs/platform/k8s/injector
[provider-gcp]: https://github.com/crossplane-contrib/provider-upjet-gcp
[provider-aws]: https://github.com/crossplane-contrib/provider-upjet-aws
[provider-gcp]: https://marketplace.upbound.io/providers/crossplane-contrib/provider-gcp
[provider-aws]: https://marketplace.upbound.io/providers/crossplane-contrib/provider-aws
[AWS]: https://www.vaultproject.io/docs/secrets/aws
[Azure]: https://www.vaultproject.io/docs/secrets/azure
[GCP]: https://www.vaultproject.io/docs/secrets/gcp

13
content/master/guides/write-a-composition-function-in-go.md
View File

@ -425,7 +425,7 @@ This code:
1. Adds one desired S3 bucket for each bucket name.
1. Returns the desired S3 buckets in a `RunFunctionResponse`.
The code uses the `v1beta1.Bucket` type from the [AWS S3 provider](https://github.com/crossplane-contrib/provider-upjet-aws).
The code uses the `v1beta1.Bucket` type from [Upbound's AWS S3 provider](https://github.com/crossplane-contrib/provider-upjet-aws).
One advantage of writing a function in Go is that you can compose resources
using the same strongly typed structs Crossplane uses in its providers.
@ -671,7 +671,7 @@ metadata:
spec:
# The CLI ignores this package when using the Development runtime.
# You can set it to any value.
package: xpkg.crossplane.io/negz/function-xbuckets:v0.1.0
package: xpkg.upbound.io/negz/function-xbuckets:v0.1.0
```
{{</expand>}}
@ -783,7 +783,7 @@ Read the composition functions documentation to learn more about
You build a function in two stages. First you build the function's runtime. This
is the Open Container Initiative (OCI) image Crossplane uses to run your
function. You then embed that runtime in a package, and push it to a package
registry. The Crossplane CLI uses `xpkg.crossplane.io` as its default package
registry. The Crossplane CLI uses `xpkg.upbound.io` as its default package
registry.
A function supports a single platform, like `linux/amd64`, by default. You can
@ -863,4 +863,11 @@ up continuous integration (CI) using
[GitHub Actions](https://github.com/features/actions). The CI workflow will
lint, test, and build your function. You can see how the template configures CI
by reading `.github/workflows/ci.yaml`.
The CI workflow can automatically push packages to `xpkg.upbound.io`. For this
to work you must create a repository at https://marketplace.upbound.io. Give the
CI workflow access to push to the Marketplace by creating an API token and
[adding it to your repository](https://docs.github.com/en/actions/security-guides/using-secrets-in-github-actions#creating-secrets-for-a-repository).
Save your API token access ID as a secret named `XPKG_ACCESS_ID` and your API
token as a secret named `XPKG_TOKEN`.
{{</hint>}}

11
content/master/guides/write-a-composition-function-in-python.md
View File

@ -533,7 +533,7 @@ metadata:
spec:
# The CLI ignores this package when using the Development runtime.
# You can set it to any value.
package: xpkg.crossplane.io/negz/function-xbuckets:v0.1.0
package: xpkg.upbound.io/negz/function-xbuckets:v0.1.0
```
{{</expand>}}
@ -644,7 +644,7 @@ Read the composition functions documentation to learn more about
You build a function in two stages. First you build the function's runtime. This
is the Open Container Initiative (OCI) image Crossplane uses to run your
function. You then embed that runtime in a package, and push it to a package
registry. The Crossplane CLI uses `xpkg.crossplane.io` as its default package
registry. The Crossplane CLI uses `xpkg.upbound.io` as its default package
registry.
A function supports a single platform, like `linux/amd64`, by default. You can
@ -732,4 +732,11 @@ up continuous integration (CI) using
[GitHub Actions](https://github.com/features/actions). The CI workflow will
lint, test, and build your function. You can see how the template configures CI
by reading `.github/workflows/ci.yaml`.
The CI workflow can automatically push packages to `xpkg.upbound.io`. For this
to work you must create a repository at https://marketplace.upbound.io. Give the
CI workflow access to push to the Marketplace by creating an API token and
[adding it to your repository](https://docs.github.com/en/actions/security-guides/using-secrets-in-github-actions#creating-secrets-for-a-repository).
Save your API token access ID as a secret named `XPKG_ACCESS_ID` and your API
token as a secret named `XPKG_TOKEN`.
{{</hint>}}

2
content/master/learn/_index.md
View File

@ -28,7 +28,7 @@ If you have any questions, please drop us a note on [Crossplane Slack][join-cros
- Subscribe to our [YouTube Channel](https://www.youtube.com/channel/UC19FgzMBMqBro361HbE46Fw)
<!-- vale Crossplane.Spelling = NO -->
- Drop us a note on Twitter: [@crossplane_io](https://twitter.com/crossplane_io)
- Email us: [crossplane-info@lists.cncf.io](mailto:crossplane-info@lists.cncf.io)
- Email us: [info@crossplane.io](mailto:info@crossplane.io)
<!-- vale Crossplane.Spelling = YES -->
<!-- Named links -->

4
content/master/learn/release-cycle.md
View File

@ -68,7 +68,7 @@ During feature freeze, no new functionality should be merged into the main
development branch. Bug fixes, documentation changes, and non critical changes
may be made. In the case that a new feature is deemed absolutely necessary for a
release, the Crossplane maintainers will weigh the impact of the change and make
a decision on whether it should be included.
a decision on whether it should be included.
### Code freeze
@ -97,4 +97,4 @@ reviews, testing, and bug fixing to ensure a quality release.
[Feature Freeze]: #feature-freeze
[Code Freeze]: #code-freeze
[CONTRIBUTING.md]: https://github.com/crossplane/crossplane/blob/main/CONTRIBUTING.md
[community calendar]: https://zoom-lfx.platform.linuxfoundation.org/meetings/crossplane
[community calendar]: https://calendar.google.com/calendar/embed?src=c_2cdn0hs9e2m05rrv1233cjoj1k%40group.calendar.google.com

48
content/master/software/install.md
View File

@ -125,24 +125,19 @@ Apply customizations with the command line or with a Helm _values_ file.
| `customAnnotations` | Add custom `annotations` to the Crossplane pod deployment. | `{}` |
| `customLabels` | Add custom `labels` to the Crossplane pod deployment. | `{}` |
| `deploymentStrategy` | The deployment strategy for the Crossplane and RBAC Manager pods. | `"RollingUpdate"` |
| `dnsPolicy` | Specify the `dnsPolicy` to be used by the Crossplane pod. | `""` |
| `extraEnvVarsCrossplane` | Add custom environmental variables to the Crossplane pod deployment. Replaces any `.` in a variable name with `_`. For example, `SAMPLE.KEY=value1` becomes `SAMPLE_KEY=value1`. | `{}` |
| `extraEnvVarsRBACManager` | Add custom environmental variables to the RBAC Manager pod deployment. Replaces any `.` in a variable name with `_`. For example, `SAMPLE.KEY=value1` becomes `SAMPLE_KEY=value1`. | `{}` |
| `extraObjects` | To add arbitrary Kubernetes Objects during a Helm Install | `[]` |
| `extraVolumeMountsCrossplane` | Add custom `volumeMounts` to the Crossplane pod. | `{}` |
| `extraVolumesCrossplane` | Add custom `volumes` to the Crossplane pod. | `{}` |
| `function.packages` | A list of Function packages to install | `[]` |
| `functionCache.medium` | Set to `Memory` to hold the function cache in a RAM backed file system. Useful for Crossplane development. | `""` |
| `functionCache.pvc` | The name of a PersistentVolumeClaim to use as the function cache. Disables the default function cache `emptyDir` Volume. | `""` |
| `functionCache.sizeLimit` | The size limit for the function cache. If medium is `Memory` the `sizeLimit` can't exceed Node memory. | `"512Mi"` |
| `hostNetwork` | Enable `hostNetwork` for the Crossplane deployment. Caution: enabling `hostNetwork` grants the Crossplane Pod access to the host network namespace. Consider setting `dnsPolicy` to `ClusterFirstWithHostNet`. | `false` |
| `function.packages` | A list of Function packages to install. | `[]` |
| `hostNetwork` | Enable `hostNetwork` for the Crossplane deployment. Caution: enabling `hostNetwork` grants the Crossplane Pod access to the host network namespace. | `false` |
| `image.pullPolicy` | The image pull policy used for Crossplane and RBAC Manager pods. | `"IfNotPresent"` |
| `image.repository` | Repository for the Crossplane pod image. | `"xpkg.crossplane.io/crossplane/crossplane"` |
| `image.repository` | Repository for the Crossplane pod image. | `"xpkg.upbound.io/crossplane/crossplane"` |
| `image.tag` | The Crossplane image tag. Defaults to the value of `appVersion` in `Chart.yaml`. | `""` |
| `imagePullSecrets` | The imagePullSecret names to add to the Crossplane ServiceAccount. | `[]` |
| `imagePullSecrets` | The imagePullSecret names to add to the Crossplane ServiceAccount. | `{}` |
| `leaderElection` | Enable [leader election](https://docs.crossplane.io/latest/concepts/pods/#leader-election) for the Crossplane pod. | `true` |
| `metrics.enabled` | Enable Prometheus path, port and scrape annotations and expose port 8080 for both the Crossplane and RBAC Manager pods. | `false` |
| `metrics.port` | The port the metrics server listens on. | `""` |
| `nodeSelector` | Add `nodeSelectors` to the Crossplane pod deployment. | `{}` |
| `packageCache.configMap` | The name of a ConfigMap to use as the package cache. Disables the default package cache `emptyDir` Volume. | `""` |
| `packageCache.medium` | Set to `Memory` to hold the package cache in a RAM backed file system. Useful for Crossplane development. | `""` |
@ -158,24 +153,20 @@ Apply customizations with the command line or with a Helm _values_ file.
| `rbacManager.leaderElection` | Enable [leader election](https://docs.crossplane.io/latest/concepts/pods/#leader-election) for the RBAC Manager pod. | `true` |
| `rbacManager.nodeSelector` | Add `nodeSelectors` to the RBAC Manager pod deployment. | `{}` |
| `rbacManager.replicas` | The number of RBAC Manager pod `replicas` to deploy. | `1` |
| `rbacManager.revisionHistoryLimit` | The number of RBAC Manager ReplicaSets to retain. | `nil` |
| `rbacManager.skipAggregatedClusterRoles` | Don't install aggregated Crossplane ClusterRoles. | `false` |
| `rbacManager.tolerations` | Add `tolerations` to the RBAC Manager pod deployment. | `[]` |
| `rbacManager.topologySpreadConstraints` | Add `topologySpreadConstraints` to the RBAC Manager pod deployment. | `[]` |
| `readiness.port` | The port the readyz server listens on. | `""` |
| `registryCaBundleConfig.key` | The ConfigMap key containing a custom CA bundle to enable fetching packages from registries with unknown or untrusted certificates. | `""` |
| `registryCaBundleConfig.name` | The ConfigMap name containing a custom CA bundle to enable fetching packages from registries with unknown or untrusted certificates. | `""` |
| `replicas` | The number of Crossplane pod `replicas` to deploy. | `1` |
| `resourcesCrossplane.limits.cpu` | CPU resource limits for the Crossplane pod. | `"500m"` |
| `resourcesCrossplane.limits.memory` | Memory resource limits for the Crossplane pod. | `"1024Mi"` |
| `resourcesCrossplane.limits.cpu` | CPU resource limits for the Crossplane pod. | `"100m"` |
| `resourcesCrossplane.limits.memory` | Memory resource limits for the Crossplane pod. | `"512Mi"` |
| `resourcesCrossplane.requests.cpu` | CPU resource requests for the Crossplane pod. | `"100m"` |
| `resourcesCrossplane.requests.memory` | Memory resource requests for the Crossplane pod. | `"256Mi"` |
| `resourcesRBACManager.limits.cpu` | CPU resource limits for the RBAC Manager pod. | `"100m"` |
| `resourcesRBACManager.limits.memory` | Memory resource limits for the RBAC Manager pod. | `"512Mi"` |
| `resourcesRBACManager.requests.cpu` | CPU resource requests for the RBAC Manager pod. | `"100m"` |
| `resourcesRBACManager.requests.memory` | Memory resource requests for the RBAC Manager pod. | `"256Mi"` |
| `revisionHistoryLimit` | The number of Crossplane ReplicaSets to retain. | `nil` |
| `runtimeClassName` | The runtimeClassName name to apply to the Crossplane and RBAC Manager pods. | `""` |
| `securityContextCrossplane.allowPrivilegeEscalation` | Enable `allowPrivilegeEscalation` for the Crossplane pod. | `false` |
| `securityContextCrossplane.readOnlyRootFilesystem` | Set the Crossplane pod root file system as read-only. | `true` |
| `securityContextCrossplane.runAsGroup` | The group ID used by the Crossplane pod. | `65532` |
@ -184,14 +175,10 @@ Apply customizations with the command line or with a Helm _values_ file.
| `securityContextRBACManager.readOnlyRootFilesystem` | Set the RBAC Manager pod root file system as read-only. | `true` |
| `securityContextRBACManager.runAsGroup` | The group ID used by the RBAC Manager pod. | `65532` |
| `securityContextRBACManager.runAsUser` | The user ID used by the RBAC Manager pod. | `65532` |
| `service.customAnnotations` | Configure annotations on the service object. Only enabled when webhooks.enabled = true | `{}` |
| `serviceAccount.create` | Specifies whether Crossplane ServiceAccount should be created | `true` |
| `serviceAccount.customAnnotations` | Add custom `annotations` to the Crossplane ServiceAccount. | `{}` |
| `serviceAccount.name` | Provide the name of an already created Crossplane ServiceAccount. Required when `serviceAccount.create` is `false` | `""` |
| `tolerations` | Add `tolerations` to the Crossplane pod deployment. | `[]` |
| `topologySpreadConstraints` | Add `topologySpreadConstraints` to the Crossplane pod deployment. | `[]` |
| `webhooks.enabled` | Enable webhooks for Crossplane and installed Provider packages. | `true` |
| `webhooks.port` | The port the webhook server listens on. | `""` |
{{< /table >}}
{{< /expand >}}
<!-- vale gitlab.Substitutions = YES -->
@ -267,12 +254,10 @@ at the table below.
| Beta | `--enable-deployment-runtime-configs` | Enable support for DeploymentRuntimeConfigs. |
| Beta | `--enable-usages` | Enable support for Usages. |
| Beta | `--enable-ssa-claims` | Enable support for using server-side apply to sync claims with XRs. |
| Beta | `--enable-realtime-compositions` | Enable support for real time compositions. |
| Alpha | `--enable-external-secret-stores` | Enable support for External Secret Stores. |
| Alpha | `--enable-dependency-version-upgrades` | Enable automatic version upgrades of dependencies when updating packages. |
| Alpha | `--enable-dependency-version-downgrades` | Enable automatic version downgrades of dependencies when updating packages. |
| Alpha | `--enable-realtime-compositions` | Enable support for real time compositions. |
| Alpha | `--enable-dependency-version-upgrades ` | Enable automatic version upgrades of dependencies when updating packages. |
| Alpha | `--enable-signature-verification` | Enable support for package signature verification via ImageConfig API. |
| Alpha | `--enable-function-response-cache` | Enable support for caching composition function responses. |
{{< /table >}}
{{< /expand >}}
@ -282,8 +267,9 @@ args='{"--enable-composition-functions","--enable-composition-webhook-schema-val
#### Change the default package registry
Beginning with Crossplane version 1.20.0 Crossplane uses the [crossplane-contrib](https://github.com/orgs/crossplane-contrib/packages) GitHub Container Registry at `xpkg.crossplane.io` by default for downloading and
installing packages.
Beginning with Crossplane version 1.15.0 Crossplane downloads packages from the
[Upbound Marketplace](https://marketplace.upbound.io) at `xpkg.upbound.io`
instead of DockerHub.
Change the default registry location during the Crossplane install with
`--set args='{"--registry=index.docker.io"}'`.
@ -340,3 +326,15 @@ Community Crossplane distribution.
The CNCF certified third-party distributions as
"[conformant](https://github.com/cncf/crossplane-conformance)" with the
Community Crossplane distribution.
### Vendors
Below are vendors providing conformant Crossplane distributions.
#### Upbound
Upbound, the founders of Crossplane, maintains a free and open source
distribution of Crossplane called
[Universal Crossplane](https://www.upbound.io/product/universal-crossplane)
(`UXP`).
Find information on UXP in the
[Upbound UXP documentation](https://docs.upbound.io/uxp/install/).

4
content/master/software/uninstall.md
View File

@ -135,13 +135,13 @@ List the installed _providers_ with `kubectl get providers`.
```shell {copy-lines="1"}
kubectl get providers
NAME INSTALLED HEALTHY PACKAGE AGE
crossplane-contrib-provider-aws True True xpkg.crossplane.io/crossplane-contrib/provider-aws:v1.21.1 8h
upbound-provider-aws True True xpkg.upbound.io/upbound/provider-aws:v1.0.0 8h
```
Remove the installed _providers_ with `kubectl delete provider`.
```shell
kubectl delete provider crossplane-contrib-provider-aws
kubectl delete provider upbound-provider-aws
```
## Uninstall the Crossplane deployment

8
content/master/software/upgrade.md
View File

@ -46,9 +46,9 @@ Crossplane.
Crossplane uses any new default behaviors unless they're changed in the `helm
upgrade` command.
For example, in v1.20.0 Crossplane changed the default image registry from
`index.docker.io` to `xpkg.crossplane.io`. Upgrading Crossplane from a version
before v1.20.0 updates the default package registry.
For example, in v1.15.0 Crossplane changed the default image registry from
`index.docker.io` to `xpkg.upbound.io`. Upgrading Crossplane from a version
before v1.15.0 updates the default package registry.
Override new defaults by
[customizing the Helm chart]({{<ref "install#customize-the-crossplane-helm-chart" >}})
@ -56,5 +56,5 @@ with the upgrade command.
For example, to maintain the original image registry use
```shell
helm upgrade crossplane --namespace crossplane-system crossplane-stable/crossplane --set 'args={"--registry=index.docker.io"}'
helm upgrade crossplane --namespace crossplane-system crossplane-stable/crossplane `--set 'args={"--registry=index.docker.io"}'
```

2
content/v1.20/_index.md → content/v1.16/_index.md
View File

@ -2,7 +2,7 @@
title: "Overview"
weight: -1
cascade:
version: "1.20"
version: "1.16"
---
{{< img src="/media/banner.png" alt="Crossplane Popsicle Truck" size="large" >}}

0
content/v1.19/api/_index.md → content/v1.16/api/_index.md
View File

27
content/v1.20/api/crds/apiextensions.crossplane.io_compositeresourcedefinitions.yaml → content/v1.16/api/crds/apiextensions.crossplane.io_compositeresourcedefinitions.yaml
View File

@ -1,9 +1,8 @@
---
apiVersion: apiextensions.k8s.io/v1
kind: CustomResourceDefinition
metadata:
annotations:
controller-gen.kubebuilder.io/version: v0.16.5
controller-gen.kubebuilder.io/version: v0.14.0
name: compositeresourcedefinitions.apiextensions.crossplane.io
spec:
group: apiextensions.crossplane.io
@ -36,6 +35,7 @@ spec:
A CompositeResourceDefinition defines the schema for a new custom Kubernetes
API.
Read the Crossplane documentation for
[more information about CustomResourceDefinitions](https://docs.crossplane.io/latest/concepts/composite-resource-definitions).
properties:
@ -79,7 +79,6 @@ spec:
items:
type: string
type: array
x-kubernetes-list-type: atomic
kind:
description: |-
kind is the serialized kind of the resource. It is normally CamelCase and singular.
@ -104,7 +103,6 @@ spec:
items:
type: string
type: array
x-kubernetes-list-type: atomic
singular:
description: singular is the singular name of the resource. It
must be all lowercase. Defaults to lowercased `kind`.
@ -113,9 +111,6 @@ spec:
- kind
- plural
type: object
x-kubernetes-validations:
- message: Value is immutable
rule: self == oldSelf
connectionSecretKeys:
description: |-
ConnectionSecretKeys is the list of keys that will be exposed to the end
@ -154,6 +149,7 @@ spec:
service is a reference to the service for this webhook. Either
service or url must be specified.
If the webhook is running within the cluster, then you should use `service`.
properties:
name:
@ -187,24 +183,29 @@ spec:
(`scheme://host:port/path`). Exactly one of `url` or `service`
must be specified.
The `host` should not refer to a service running in the cluster; use
the `service` field instead. The host might be resolved via external
DNS in some apiservers (e.g., `kube-apiserver` cannot resolve
in-cluster DNS as that would be a layering violation). `host` may
also be an IP address.
Please note that using `localhost` or `127.0.0.1` as a `host` is
risky unless you take great care to run this webhook on all hosts
which run an apiserver which might need to make calls to this
webhook. Such installs are likely to be non-portable, i.e., not easy
to turn up in a new cluster.
The scheme must be "https"; the URL must begin with "https://".
A path is optional, and if present may be any string permissible in
a URL. You may use the path to pass an arbitrary string to the
webhook, for example, a cluster identifier.
Attempting to use a user or basic auth e.g. "user:password@" is not
allowed. Fragments ("#...") and query parameters ("?...") are not
allowed, either.
@ -221,7 +222,6 @@ spec:
items:
type: string
type: array
x-kubernetes-list-type: atomic
required:
- conversionReviewVersions
type: object
@ -268,18 +268,12 @@ spec:
required:
- name
type: object
x-kubernetes-validations:
- message: Value is immutable
rule: self == oldSelf
group:
description: |-
Group specifies the API group of the defined composite resource.
Composite resources are served under `/apis/<group>/...`. Must match the
name of the XRD (in the form `<names.plural>.<group>`).
type: string
x-kubernetes-validations:
- message: Value is immutable
rule: self == oldSelf
metadata:
description: Metadata specifies the desired metadata for the defined
composite resource and claim CRD's.
@ -318,7 +312,6 @@ spec:
items:
type: string
type: array
x-kubernetes-list-type: atomic
kind:
description: |-
kind is the serialized kind of the resource. It is normally CamelCase and singular.
@ -343,7 +336,6 @@ spec:
items:
type: string
type: array
x-kubernetes-list-type: atomic
singular:
description: singular is the singular name of the resource. It
must be all lowercase. Defaults to lowercased `kind`.
@ -352,9 +344,6 @@ spec:
- kind
- plural
type: object
x-kubernetes-validations:
- message: Value is immutable
rule: self == oldSelf
versions:
description: |-
Versions is the list of all API versions of the defined composite

1161
content/v1.20/api/crds/apiextensions.crossplane.io_compositionrevisions.yaml → content/v1.16/api/crds/apiextensions.crossplane.io_compositionrevisions.yaml
View File

File diff suppressed because it is too large Load Diff

571
content/v1.20/api/crds/apiextensions.crossplane.io_compositions.yaml → content/v1.16/api/crds/apiextensions.crossplane.io_compositions.yaml
View File

@ -1,9 +1,8 @@
---
apiVersion: apiextensions.k8s.io/v1
kind: CustomResourceDefinition
metadata:
annotations:
controller-gen.kubebuilder.io/version: v0.16.5
controller-gen.kubebuilder.io/version: v0.14.0
name: compositions.apiextensions.crossplane.io
spec:
group: apiextensions.crossplane.io
@ -35,6 +34,7 @@ spec:
A Composition defines a collection of managed resources or functions that
Crossplane uses to create and manage new composite resources.
Read the Crossplane documentation for
[more information about Compositions](https://docs.crossplane.io/latest/concepts/compositions).
properties:
@ -73,26 +73,523 @@ spec:
- apiVersion
- kind
type: object
x-kubernetes-validations:
- message: Value is immutable
rule: self == oldSelf
environment:
description: |-
Environment configures the environment in which resources are rendered.
THIS IS AN ALPHA FIELD. Do not use it in production. It is not honored
unless the relevant Crossplane feature flag is enabled, and may be
changed or removed without notice.
properties:
defaultData:
additionalProperties:
x-kubernetes-preserve-unknown-fields: true
description: |-
DefaultData statically defines the initial state of the environment.
It has the same schema-less structure as the data field in
environment configs.
It is overwritten by the selected environment configs.
type: object
environmentConfigs:
description: |-
EnvironmentConfigs selects a list of `EnvironmentConfig`s. The resolved
resources are stored in the composite resource at
`spec.environmentConfigRefs` and is only updated if it is null.
The list of references is used to compute an in-memory environment at
compose time. The data of all object is merged in the order they are
listed, meaning the values of EnvironmentConfigs with a larger index take
priority over ones with smaller indices.
The computed environment can be accessed in a composition using
`FromEnvironmentFieldPath` and `CombineFromEnvironment` patches.
items:
description: EnvironmentSource selects a EnvironmentConfig resource.
properties:
ref:
description: |-
Ref is a named reference to a single EnvironmentConfig.
Either Ref or Selector is required.
properties:
name:
description: The name of the object.
type: string
required:
- name
type: object
selector:
description: Selector selects EnvironmentConfig(s) via labels.
properties:
matchLabels:
description: MatchLabels ensures an object with matching
labels is selected.
items:
description: |-
An EnvironmentSourceSelectorLabelMatcher acts like a k8s label selector but
can draw the label value from a different path.
properties:
fromFieldPathPolicy:
default: Required
description: |-
FromFieldPathPolicy specifies the policy for the valueFromFieldPath.
The default is Required, meaning that an error will be returned if the
field is not found in the composite resource.
Optional means that if the field is not found in the composite resource,
that label pair will just be skipped. N.B. other specified label
matchers will still be used to retrieve the desired
environment config, if any.
enum:
- Optional
- Required
type: string
key:
description: Key of the label to match.
type: string
type:
default: FromCompositeFieldPath
description: Type specifies where the value for
a label comes from.
enum:
- FromCompositeFieldPath
- Value
type: string
value:
description: Value specifies a literal label value.
type: string
valueFromFieldPath:
description: ValueFromFieldPath specifies the
field path to look for the label value.
type: string
required:
- key
type: object
type: array
maxMatch:
description: MaxMatch specifies the number of extracted
EnvironmentConfigs in Multiple mode, extracts all
if nil.
format: int64
type: integer
minMatch:
description: MinMatch specifies the required minimum
of extracted EnvironmentConfigs in Multiple mode.
format: int64
type: integer
mode:
default: Single
description: 'Mode specifies retrieval strategy: "Single"
or "Multiple".'
enum:
- Single
- Multiple
type: string
sortByFieldPath:
default: metadata.name
description: SortByFieldPath is the path to the field
based on which list of EnvironmentConfigs is alphabetically
sorted.
type: string
type: object
type:
default: Reference
description: |-
Type specifies the way the EnvironmentConfig is selected.
Default is `Reference`
enum:
- Reference
- Selector
type: string
type: object
type: array
patches:
description: |-
Patches is a list of environment patches that are executed before a
composition's resources are composed.
items:
description: EnvironmentPatch is a patch for a Composition environment.
properties:
combine:
description: |-
Combine is the patch configuration for a CombineFromComposite or
CombineToComposite patch.
properties:
strategy:
description: |-
Strategy defines the strategy to use to combine the input variable values.
Currently only string is supported.
enum:
- string
type: string
string:
description: |-
String declares that input variables should be combined into a single
string, using the relevant settings for formatting purposes.
properties:
fmt:
description: |-
Format the input using a Go format string. See
https://golang.org/pkg/fmt/ for details.
type: string
required:
- fmt
type: object
variables:
description: |-
Variables are the list of variables whose values will be retrieved and
combined.
items:
description: |-
A CombineVariable defines the source of a value that is combined with
others to form and patch an output value. Currently, this only supports
retrieving values from a field path.
properties:
fromFieldPath:
description: |-
FromFieldPath is the path of the field on the source whose value is
to be used as input.
type: string
required:
- fromFieldPath
type: object
minItems: 1
type: array
required:
- strategy
- variables
type: object
fromFieldPath:
description: |-
FromFieldPath is the path of the field on the resource whose value is
to be used as input. Required when type is FromCompositeFieldPath or
ToCompositeFieldPath.
type: string
policy:
description: Policy configures the specifics of patching
behaviour.
properties:
fromFieldPath:
description: |-
FromFieldPath specifies how to patch from a field path. The default is
'Optional', which means the patch will be a no-op if the specified
fromFieldPath does not exist. Use 'Required' if the patch should fail if
the specified path does not exist.
enum:
- Optional
- Required
type: string
mergeOptions:
description: MergeOptions Specifies merge options on
a field path.
properties:
appendSlice:
description: Specifies that already existing elements
in a merged slice should be preserved
type: boolean
keepMapValues:
description: Specifies that already existing values
in a merged map should be preserved
type: boolean
type: object
type: object
toFieldPath:
description: |-
ToFieldPath is the path of the field on the resource whose value will
be changed with the result of transforms. Leave empty if you'd like to
propagate to the same path as fromFieldPath.
type: string
transforms:
description: |-
Transforms are the list of functions that are used as a FIFO pipe for the
input to be transformed.
items:
description: |-
Transform is a unit of process whose input is transformed into an output with
the supplied configuration.
properties:
convert:
description: Convert is used to cast the input into
the given output type.
properties:
format:
description: |-
The expected input format.
* `quantity` - parses the input as a K8s [`resource.Quantity`](https://pkg.go.dev/k8s.io/apimachinery/pkg/api/resource#Quantity).
Only used during `string -> float64` conversions.
* `json` - parses the input as a JSON string.
Only used during `string -> object` or `string -> list` conversions.
If this property is null, the default conversion is applied.
enum:
- none
- quantity
- json
type: string
toType:
description: ToType is the type of the output
of this transform.
enum:
- string
- int
- int64
- bool
- float64
- object
- array
type: string
required:
- toType
type: object
map:
additionalProperties:
x-kubernetes-preserve-unknown-fields: true
description: Map uses the input as a key in the given
map and returns the value.
type: object
match:
description: Match is a more complex version of Map
that matches a list of patterns.
properties:
fallbackTo:
default: Value
description: Determines to what value the transform
should fallback if no pattern matches.
enum:
- Value
- Input
type: string
fallbackValue:
description: |-
The fallback value that should be returned by the transform if now pattern
matches.
x-kubernetes-preserve-unknown-fields: true
patterns:
description: |-
The patterns that should be tested against the input string.
Patterns are tested in order. The value of the first match is used as
result of this transform.
items:
description: |-
MatchTransformPattern is a transform that returns the value that matches a
pattern.
properties:
literal:
description: |-
Literal exactly matches the input string (case sensitive).
Is required if `type` is `literal`.
type: string
regexp:
description: |-
Regexp to match against the input string.
Is required if `type` is `regexp`.
type: string
result:
description: The value that is used as result
of the transform if the pattern matches.
x-kubernetes-preserve-unknown-fields: true
type:
default: literal
description: |-
Type specifies how the pattern matches the input.
* `literal` - the pattern value has to exactly match (case sensitive) the
input string. This is the default.
* `regexp` - the pattern treated as a regular expression against
which the input string is tested. Crossplane will throw an error if the
key is not a valid regexp.
enum:
- literal
- regexp
type: string
required:
- result
- type
type: object
type: array
type: object
math:
description: |-
Math is used to transform the input via mathematical operations such as
multiplication.
properties:
clampMax:
description: ClampMax makes sure that the value
is not bigger than the given value.
format: int64
type: integer
clampMin:
description: ClampMin makes sure that the value
is not smaller than the given value.
format: int64
type: integer
multiply:
description: Multiply the value.
format: int64
type: integer
type:
default: Multiply
description: Type of the math transform to be
run.
enum:
- Multiply
- ClampMin
- ClampMax
type: string
type: object
string:
description: |-
String is used to transform the input into a string or a different kind
of string. Note that the input does not necessarily need to be a string.
properties:
convert:
description: |-
Optional conversion method to be specified.
`ToUpper` and `ToLower` change the letter case of the input string.
`ToBase64` and `FromBase64` perform a base64 conversion based on the input string.
`ToJson` converts any input value into its raw JSON representation.
`ToSha1`, `ToSha256` and `ToSha512` generate a hash value based on the input
converted to JSON.
`ToAdler32` generate a addler32 hash based on the input string.
enum:
- ToUpper
- ToLower
- ToBase64
- FromBase64
- ToJson
- ToSha1
- ToSha256
- ToSha512
- ToAdler32
type: string
fmt:
description: |-
Format the input using a Go format string. See
https://golang.org/pkg/fmt/ for details.
type: string
join:
description: Join defines parameters to join a
slice of values to a string.
properties:
separator:
description: |-
Separator defines the character that should separate the values from each
other in the joined string.
type: string
required:
- separator
type: object
regexp:
description: Extract a match from the input using
a regular expression.
properties:
group:
description: Group number to match. 0 (the
default) matches the entire expression.
type: integer
match:
description: |-
Match string. May optionally include submatches, aka capture groups.
See https://pkg.go.dev/regexp/ for details.
type: string
required:
- match
type: object
trim:
description: Trim the prefix or suffix from the
input
type: string
type:
default: Format
description: Type of the string transform to be
run.
enum:
- Format
- Convert
- TrimPrefix
- TrimSuffix
- Regexp
- Join
type: string
type: object
type:
description: Type of the transform to be run.
enum:
- map
- match
- math
- string
- convert
type: string
required:
- type
type: object
type: array
type:
default: FromCompositeFieldPath
description: |-
Type sets the patching behaviour to be used. Each patch type may require
its own fields to be set on the Patch object.
enum:
- FromCompositeFieldPath
- ToCompositeFieldPath
- CombineFromComposite
- CombineToComposite
type: string
type: object
type: array
policy:
description: |-
Policy represents the Resolve and Resolution policies which apply to
all EnvironmentSourceReferences in EnvironmentConfigs list.
properties:
resolution:
default: Required
description: |-
Resolution specifies whether resolution of this reference is required.
The default is 'Required', which means the reconcile will fail if the
reference cannot be resolved. 'Optional' means this reference will be
a no-op if it cannot be resolved.
enum:
- Required
- Optional
type: string
resolve:
description: |-
Resolve specifies when this reference should be resolved. The default
is 'IfNotPresent', which will attempt to resolve the reference only when
the corresponding field is not present. Use 'Always' to resolve the
reference on every reconcile.
enum:
- Always
- IfNotPresent
type: string
type: object
type: object
mode:
default: Resources
description: |-
Mode controls what type or "mode" of Composition will be used.
"Pipeline" indicates that a Composition specifies a pipeline of
Composition Functions, each of which is responsible for producing
composed resources that Crossplane should create or update.
"Resources" indicates that a Composition uses what is commonly referred
to as "Patch & Transform" or P&T composition. This mode of Composition
uses an array of resources, each a template for a composed resource.
"Resources" (the default) indicates that a Composition uses what is
commonly referred to as "Patch & Transform" or P&T composition. This mode
of Composition uses an array of resources, each a template for a composed
resource.
All Compositions should use Pipeline mode. Resources mode is deprecated.
Resources mode won't be removed in Crossplane 1.x, and will remain the
default to avoid breaking legacy Compositions. However, it's no longer
accepting new features, and only accepting security related bug fixes.
"Pipeline" indicates that a Composition specifies a pipeline
of Composition Functions, each of which is responsible for producing
composed resources that Crossplane should create or update. THE PIPELINE
MODE IS A BETA FEATURE. It is not honored if the relevant Crossplane
feature flag is disabled.
enum:
- Resources
- Pipeline
@ -103,10 +600,9 @@ spec:
resource in this Composition. PatchSets cannot themselves refer to other
PatchSets.
PatchSets are only used by the "Resources" mode of Composition. They
are ignored by other modes.
Deprecated: Use Composition Functions instead.
items:
description: |-
A PatchSet is a set of patches that can be reused from all resources within
@ -127,8 +623,8 @@ spec:
properties:
combine:
description: |-
Combine is the patch configuration for a CombineFromComposite or
CombineToComposite patch.
Combine is the patch configuration for a CombineFromComposite,
CombineFromEnvironment, CombineToComposite or CombineToEnvironment patch.
properties:
strategy:
description: |-
@ -177,8 +673,8 @@ spec:
fromFieldPath:
description: |-
FromFieldPath is the path of the field on the resource whose value is
to be used as input. Required when type is FromCompositeFieldPath or
ToCompositeFieldPath.
to be used as input. Required when type is FromCompositeFieldPath,
FromEnvironmentFieldPath, ToCompositeFieldPath, ToEnvironmentFieldPath.
type: string
patchSetName:
description: PatchSetName to include patches from. Required
@ -235,11 +731,13 @@ spec:
description: |-
The expected input format.
* `quantity` - parses the input as a K8s [`resource.Quantity`](https://pkg.go.dev/k8s.io/apimachinery/pkg/api/resource#Quantity).
Only used during `string -> float64` conversions.
* `json` - parses the input as a JSON string.
Only used during `string -> object` or `string -> list` conversions.
If this property is null, the default conversion is applied.
enum:
- none
@ -314,9 +812,11 @@ spec:
description: |-
Type specifies how the pattern matches the input.
* `literal` - the pattern value has to exactly match (case sensitive) the
input string. This is the default.
* `regexp` - the pattern treated as a regular expression against
which the input string is tested. Crossplane will throw an error if the
key is not a valid regexp.
@ -454,10 +954,14 @@ spec:
its own fields to be set on the Patch object.
enum:
- FromCompositeFieldPath
- FromEnvironmentFieldPath
- PatchSet
- ToCompositeFieldPath
- ToEnvironmentFieldPath
- CombineFromEnvironment
- CombineFromComposite
- CombineToComposite
- CombineToEnvironment
type: string
type: object
type: array
@ -472,8 +976,13 @@ spec:
composite resource referring to this composition is created. One of
resources and pipeline must be specified - you cannot specify both.
The Pipeline is only used by the "Pipeline" mode of Composition. It is
ignored by other modes.
THIS IS A BETA FIELD. It is not honored if the relevant Crossplane
feature flag is disabled.
items:
description: A PipelineStep in a Composition Function pipeline.
properties:
@ -555,6 +1064,7 @@ spec:
with which the connection details of composite resources dynamically
provisioned using this composition will be published.
THIS IS AN ALPHA FIELD. Do not use it in production. It is not honored
unless the relevant Crossplane feature flag is enabled, and may be
changed or removed without notice.
@ -570,10 +1080,9 @@ spec:
Resources is a list of resource templates that will be used when a
composite resource referring to this composition is created.
Resources are only used by the "Resources" mode of Composition. They are
ignored by other modes.
Deprecated: Use Composition Functions instead.
items:
description: |-
ComposedTemplate is used to provide information about how the composed resource
@ -655,8 +1164,8 @@ spec:
properties:
combine:
description: |-
Combine is the patch configuration for a CombineFromComposite or
CombineToComposite patch.
Combine is the patch configuration for a CombineFromComposite,
CombineFromEnvironment, CombineToComposite or CombineToEnvironment patch.
properties:
strategy:
description: |-
@ -705,8 +1214,8 @@ spec:
fromFieldPath:
description: |-
FromFieldPath is the path of the field on the resource whose value is
to be used as input. Required when type is FromCompositeFieldPath or
ToCompositeFieldPath.
to be used as input. Required when type is FromCompositeFieldPath,
FromEnvironmentFieldPath, ToCompositeFieldPath, ToEnvironmentFieldPath.
type: string
patchSetName:
description: PatchSetName to include patches from. Required
@ -763,11 +1272,13 @@ spec:
description: |-
The expected input format.
* `quantity` - parses the input as a K8s [`resource.Quantity`](https://pkg.go.dev/k8s.io/apimachinery/pkg/api/resource#Quantity).
Only used during `string -> float64` conversions.
* `json` - parses the input as a JSON string.
Only used during `string -> object` or `string -> list` conversions.
If this property is null, the default conversion is applied.
enum:
- none
@ -842,9 +1353,11 @@ spec:
description: |-
Type specifies how the pattern matches the input.
* `literal` - the pattern value has to exactly match (case sensitive) the
input string. This is the default.
* `regexp` - the pattern treated as a regular expression against
which the input string is tested. Crossplane will throw an error if the
key is not a valid regexp.
@ -982,10 +1495,14 @@ spec:
its own fields to be set on the Patch object.
enum:
- FromCompositeFieldPath
- FromEnvironmentFieldPath
- PatchSet
- ToCompositeFieldPath
- ToEnvironmentFieldPath
- CombineFromEnvironment
- CombineFromComposite
- CombineToComposite
- CombineToEnvironment
type: string
type: object
type: array

44
content/v1.20/api/crds/apiextensions.crossplane.io_environmentconfigs.yaml → content/v1.16/api/crds/apiextensions.crossplane.io_environmentconfigs.yaml
View File

@ -1,9 +1,8 @@
---
apiVersion: apiextensions.k8s.io/v1
kind: CustomResourceDefinition
metadata:
annotations:
controller-gen.kubebuilder.io/version: v0.16.5
controller-gen.kubebuilder.io/version: v0.14.0
name: environmentconfigs.apiextensions.crossplane.io
spec:
group: apiextensions.crossplane.io
@ -29,47 +28,6 @@ spec:
An EnvironmentConfig contains user-defined unstructured values for
use in a Composition.
Read the Crossplane documentation for
[more information about EnvironmentConfigs](https://docs.crossplane.io/latest/concepts/environment-configs).
properties:
apiVersion:
description: |-
APIVersion defines the versioned schema of this representation of an object.
Servers should convert recognized schemas to the latest internal value, and
may reject unrecognized values.
More info: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#resources
type: string
data:
additionalProperties:
x-kubernetes-preserve-unknown-fields: true
description: |-
The data of this EnvironmentConfig.
This may contain any kind of structure that can be serialized into JSON.
type: object
kind:
description: |-
Kind is a string value representing the REST resource this object represents.
Servers may infer this from the endpoint the client submits requests to.
Cannot be updated.
In CamelCase.
More info: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#types-kinds
type: string
metadata:
type: object
type: object
served: true
storage: false
subresources: {}
- additionalPrinterColumns:
- jsonPath: .metadata.creationTimestamp
name: AGE
type: date
name: v1beta1
schema:
openAPIV3Schema:
description: |-
An EnvironmentConfig contains user-defined unstructured values for
use in a Composition.
Read the Crossplane documentation for
[more information about EnvironmentConfigs](https://docs.crossplane.io/latest/concepts/environment-configs).

21
content/v2.0-preview/api/crds/protection.crossplane.io_usages.yaml → content/v1.16/api/crds/apiextensions.crossplane.io_usages.yaml
View File

@ -1,12 +1,11 @@
---
apiVersion: apiextensions.k8s.io/v1
kind: CustomResourceDefinition
metadata:
annotations:
controller-gen.kubebuilder.io/version: v0.16.5
name: usages.protection.crossplane.io
controller-gen.kubebuilder.io/version: v0.14.0
name: usages.apiextensions.crossplane.io
spec:
group: protection.crossplane.io
group: apiextensions.crossplane.io
names:
categories:
- crossplane
@ -14,7 +13,7 @@ spec:
listKind: UsageList
plural: usages
singular: usage
scope: Namespaced
scope: Cluster
versions:
- additionalPrinterColumns:
- jsonPath: .metadata.annotations.crossplane\.io/usage-details
@ -26,15 +25,17 @@ spec:
- jsonPath: .metadata.creationTimestamp
name: AGE
type: date
name: v1beta1
name: v1alpha1
schema:
openAPIV3Schema:
description: |-
A Usage defines a deletion blocking relationship between two resources.
Usages prevent accidental deletion of a single resource or deletion of
resources with dependent resources.
Read the Crossplane documentation for
[more information about Compositions](https://docs.crossplane.io/latest/concepts/usages).
properties:
@ -117,9 +118,6 @@ spec:
name:
description: Name of the referent.
type: string
namespace:
description: Namespace of the referent.
type: string
required:
- name
type: object
@ -139,11 +137,6 @@ spec:
description: MatchLabels ensures an object with matching labels
is selected.
type: object
namespace:
description: |-
Namespace ensures an object in the supplied namespace is selected.
Omit namespace to only match resources in the Usage's namespace.
type: string
type: object
type: object
x-kubernetes-validations:

14
content/v1.19/api/crds/pkg.crossplane.io_configurationrevisions.yaml → content/v1.16/api/crds/pkg.crossplane.io_configurationrevisions.yaml
View File

@ -1,9 +1,8 @@
---
apiVersion: apiextensions.k8s.io/v1
kind: CustomResourceDefinition
metadata:
annotations:
controller-gen.kubebuilder.io/version: v0.16.5
controller-gen.kubebuilder.io/version: v0.14.0
name: configurationrevisions.pkg.crossplane.io
spec:
group: pkg.crossplane.io
@ -46,6 +45,7 @@ spec:
A ConfigurationRevision represents a revision of a Configuration. Crossplane
creates new revisions when there are changes to a Configuration.
Crossplane creates and manages ConfigurationRevision. Don't directly edit
ConfigurationRevisions.
properties:
@ -112,13 +112,10 @@ spec:
referenced object inside the same namespace.
properties:
name:
default: ""
description: |-
Name of the referent.
This field is effectively required, but due to backwards compatibility is
allowed to be empty. Instances of this type with an empty value here are
almost certainly wrong.
More info: https://kubernetes.io/docs/concepts/overview/working-with-objects/names/#names
TODO: Add other useful fields. apiVersion, kind, uid?
type: string
type: object
x-kubernetes-map-type: atomic
@ -245,7 +242,6 @@ spec:
items:
type: string
type: array
x-kubernetes-list-type: atomic
nonResourceURLs:
description: |-
NonResourceURLs is a set of partial urls that a user should have access to. *s are allowed, but only as the full, final step in the path
@ -254,7 +250,6 @@ spec:
items:
type: string
type: array
x-kubernetes-list-type: atomic
resourceNames:
description: ResourceNames is an optional white list of names
that the rule applies to. An empty set means that everything
@ -262,21 +257,18 @@ spec:
items:
type: string
type: array
x-kubernetes-list-type: atomic
resources:
description: Resources is a list of resources this rule applies
to. '*' represents all resources.
items:
type: string
type: array
x-kubernetes-list-type: atomic
verbs:
description: Verbs is a list of Verbs that apply to ALL the
ResourceKinds contained in this rule. '*' represents all verbs.
items:
type: string
type: array
x-kubernetes-list-type: atomic
required:
- verbs
type: object

9
content/v1.19/api/crds/pkg.crossplane.io_configurations.yaml → content/v1.16/api/crds/pkg.crossplane.io_configurations.yaml
View File

@ -1,9 +1,8 @@
---
apiVersion: apiextensions.k8s.io/v1
kind: CustomResourceDefinition
metadata:
annotations:
controller-gen.kubebuilder.io/version: v0.16.5
controller-gen.kubebuilder.io/version: v0.14.0
name: configurations.pkg.crossplane.io
spec:
group: pkg.crossplane.io
@ -38,6 +37,7 @@ spec:
Crossplane with support for new kinds of CompositeResourceDefinitions and
Compositions.
Read the Crossplane documentation for
[more information about Configuration packages](https://docs.crossplane.io/latest/concepts/packages).
properties:
@ -98,13 +98,10 @@ spec:
referenced object inside the same namespace.
properties:
name:
default: ""
description: |-
Name of the referent.
This field is effectively required, but due to backwards compatibility is
allowed to be empty. Instances of this type with an empty value here are
almost certainly wrong.
More info: https://kubernetes.io/docs/concepts/overview/working-with-objects/names/#names
TODO: Add other useful fields. apiVersion, kind, uid?
type: string
type: object
x-kubernetes-map-type: atomic

387
content/v1.20/api/crds/pkg.crossplane.io_controllerconfigs.yaml → content/v1.16/api/crds/pkg.crossplane.io_controllerconfigs.yaml
View File

File diff suppressed because it is too large Load Diff

745
content/v1.20/api/crds/pkg.crossplane.io_deploymentruntimeconfigs.yaml → content/v1.16/api/crds/pkg.crossplane.io_deploymentruntimeconfigs.yaml
View File

File diff suppressed because it is too large Load Diff

72
content/v1.20/api/crds/pkg.crossplane.io_providerrevisions.yaml → content/v1.16/api/crds/pkg.crossplane.io_functionrevisions.yaml
View File

@ -1,20 +1,19 @@
---
apiVersion: apiextensions.k8s.io/v1
kind: CustomResourceDefinition
metadata:
annotations:
controller-gen.kubebuilder.io/version: v0.16.5
name: providerrevisions.pkg.crossplane.io
controller-gen.kubebuilder.io/version: v0.14.0
name: functionrevisions.pkg.crossplane.io
spec:
group: pkg.crossplane.io
names:
categories:
- crossplane
- pkgrev
kind: ProviderRevision
listKind: ProviderRevisionList
plural: providerrevisions
singular: providerrevision
kind: FunctionRevision
listKind: FunctionRevisionList
plural: functionrevisions
singular: functionrevision
scope: Cluster
versions:
- additionalPrinterColumns:
@ -39,15 +38,16 @@ spec:
- jsonPath: .metadata.creationTimestamp
name: AGE
type: date
name: v1
name: v1beta1
schema:
openAPIV3Schema:
description: |-
A ProviderRevision represents a revision of a Provider. Crossplane
creates new revisions when there are changes to a Provider.
A FunctionRevision represents a revision of a Function. Crossplane
creates new revisions when there are changes to the Function.
Crossplane creates and manages ProviderRevisions. Don't directly edit
ProviderRevisions.
Crossplane creates and manages FunctionRevisions. Don't directly edit
FunctionRevisions.
properties:
apiVersion:
description: |-
@ -67,7 +67,7 @@ spec:
metadata:
type: object
spec:
description: ProviderRevisionSpec specifies configuration for a ProviderRevision.
description: FunctionRevisionSpec specifies configuration for a FunctionRevision.
properties:
commonLabels:
additionalProperties:
@ -124,13 +124,10 @@ spec:
referenced object inside the same namespace.
properties:
name:
default: ""
description: |-
Name of the referent.
This field is effectively required, but due to backwards compatibility is
allowed to be empty. Instances of this type with an empty value here are
almost certainly wrong.
More info: https://kubernetes.io/docs/concepts/overview/working-with-objects/names/#names
TODO: Add other useful fields. apiVersion, kind, uid?
type: string
type: object
x-kubernetes-map-type: atomic
@ -186,30 +183,9 @@ spec:
- revision
type: object
status:
description: PackageRevisionStatus represents the observed state of a
PackageRevision.
description: FunctionRevisionStatus represents the observed state of a
FunctionRevision.
properties:
appliedImageConfigRefs:
description: |-
AppliedImageConfigRefs records any image configs that were applied in
reconciling this revision, and what they were used for.
items:
description: |-
ImageConfigRef is a reference to an image config that indicates how the
referenced image config was used by the package manager.
properties:
name:
description: Name is the name of the image config.
type: string
reason:
description: Reason indicates what the image config was used
for.
type: string
required:
- name
- reason
type: object
type: array
conditions:
description: Conditions of the resource.
items:
@ -256,6 +232,11 @@ spec:
x-kubernetes-list-map-keys:
- type
x-kubernetes-list-type: map
endpoint:
description: |-
Endpoint is the gRPC endpoint where Crossplane will send
RunFunctionRequests.
type: string
foundDependencies:
description: Dependency information.
format: int64
@ -309,7 +290,6 @@ spec:
items:
type: string
type: array
x-kubernetes-list-type: atomic
nonResourceURLs:
description: |-
NonResourceURLs is a set of partial urls that a user should have access to. *s are allowed, but only as the full, final step in the path
@ -318,7 +298,6 @@ spec:
items:
type: string
type: array
x-kubernetes-list-type: atomic
resourceNames:
description: ResourceNames is an optional white list of names
that the rule applies to. An empty set means that everything
@ -326,31 +305,22 @@ spec:
items:
type: string
type: array
x-kubernetes-list-type: atomic
resources:
description: Resources is a list of resources this rule applies
to. '*' represents all resources.
items:
type: string
type: array
x-kubernetes-list-type: atomic
verbs:
description: Verbs is a list of Verbs that apply to ALL the
ResourceKinds contained in this rule. '*' represents all verbs.
items:
type: string
type: array
x-kubernetes-list-type: atomic
required:
- verbs
type: object
type: array
resolvedImage:
description: |-
ResolvedPackage is the name of the package that was installed. It may be
different from spec.image if the package path was rewritten using an
image config.
type: string
type: object
type: object
served: true

60
content/v1.20/api/crds/pkg.crossplane.io_providers.yaml → content/v1.16/api/crds/pkg.crossplane.io_functions.yaml
View File

@ -1,20 +1,19 @@
---
apiVersion: apiextensions.k8s.io/v1
kind: CustomResourceDefinition
metadata:
annotations:
controller-gen.kubebuilder.io/version: v0.16.5
name: providers.pkg.crossplane.io
controller-gen.kubebuilder.io/version: v0.14.0
name: functions.pkg.crossplane.io
spec:
group: pkg.crossplane.io
names:
categories:
- crossplane
- pkg
kind: Provider
listKind: ProviderList
plural: providers
singular: provider
kind: Function
listKind: FunctionList
plural: functions
singular: function
scope: Cluster
versions:
- additionalPrinterColumns:
@ -30,15 +29,16 @@ spec:
- jsonPath: .metadata.creationTimestamp
name: AGE
type: date
name: v1
name: v1beta1
schema:
openAPIV3Schema:
description: |-
A Provider installs an OCI compatible Crossplane package, extending
Crossplane with support for new kinds of managed resources.
A Function installs an OCI compatible Crossplane package, extending
Crossplane with support for a new kind of composition function.
Read the Crossplane documentation for
[more information about Providers](https://docs.crossplane.io/latest/concepts/providers).
[more information about Functions](https://docs.crossplane.io/latest/concepts/composition-functions).
properties:
apiVersion:
description: |-
@ -58,9 +58,7 @@ spec:
metadata:
type: object
spec:
description: |-
ProviderSpec specifies details about a request to install a provider to
Crossplane.
description: FunctionSpec specifies the configuration of a Function.
properties:
commonLabels:
additionalProperties:
@ -109,13 +107,10 @@ spec:
referenced object inside the same namespace.
properties:
name:
default: ""
description: |-
Name of the referent.
This field is effectively required, but due to backwards compatibility is
allowed to be empty. Instances of this type with an empty value here are
almost certainly wrong.
More info: https://kubernetes.io/docs/concepts/overview/working-with-objects/names/#names
TODO: Add other useful fields. apiVersion, kind, uid?
type: string
type: object
x-kubernetes-map-type: atomic
@ -168,29 +163,8 @@ spec:
- package
type: object
status:
description: ProviderStatus represents the observed state of a Provider.
description: FunctionStatus represents the observed state of a Function.
properties:
appliedImageConfigRefs:
description: |-
AppliedImageConfigRefs records any image configs that were applied in
reconciling this package, and what they were used for.
items:
description: |-
ImageConfigRef is a reference to an image config that indicates how the
referenced image config was used by the package manager.
properties:
name:
description: Name is the name of the image config.
type: string
reason:
description: Reason indicates what the image config was used
for.
type: string
required:
- name
- reason
type: object
type: array
conditions:
description: Conditions of the resource.
items:
@ -252,12 +226,6 @@ spec:
reflect the most up to date revision, whether it has been activated or
not.
type: string
resolvedPackage:
description: |-
ResolvedPackage is the name of the package that was used for version
resolution. It may be different from spec.package if the package path was
rewritten using an image config.
type: string
type: object
type: object
served: true

99
content/v1.16/api/crds/pkg.crossplane.io_locks.yaml Normal file
View File

@ -0,0 +1,99 @@
apiVersion: apiextensions.k8s.io/v1
kind: CustomResourceDefinition
metadata:
annotations:
controller-gen.kubebuilder.io/version: v0.14.0
name: locks.pkg.crossplane.io
spec:
group: pkg.crossplane.io
names:
kind: Lock
listKind: LockList
plural: locks
singular: lock
scope: Cluster
versions:
- additionalPrinterColumns:
- jsonPath: .metadata.creationTimestamp
name: AGE
type: date
name: v1beta1
schema:
openAPIV3Schema:
description: Lock is the CRD type that tracks package dependencies.
properties:
apiVersion:
description: |-
APIVersion defines the versioned schema of this representation of an object.
Servers should convert recognized schemas to the latest internal value, and
may reject unrecognized values.
More info: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#resources
type: string
kind:
description: |-
Kind is a string value representing the REST resource this object represents.
Servers may infer this from the endpoint the client submits requests to.
Cannot be updated.
In CamelCase.
More info: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#types-kinds
type: string
metadata:
type: object
packages:
items:
description: LockPackage is a package that is in the lock.
properties:
dependencies:
description: |-
Dependencies are the list of dependencies of this package. The order of
the dependencies will dictate the order in which they are resolved.
items:
description: A Dependency is a dependency of a package in the
lock.
properties:
constraints:
description: |-
Constraints is a valid semver range, which will be used to select a valid
dependency version.
type: string
package:
description: Package is the OCI image name without a tag or
digest.
type: string
type:
description: Type is the type of package. Can be either Configuration
or Provider.
type: string
required:
- constraints
- package
- type
type: object
type: array
name:
description: Name corresponds to the name of the package revision
for this package.
type: string
source:
description: Source is the OCI image name without a tag or digest.
type: string
type:
description: Type is the type of package. Can be either Configuration
or Provider.
type: string
version:
description: Version is the tag or digest of the OCI image.
type: string
required:
- dependencies
- name
- source
- type
- version
type: object
type: array
type: object
served: true
storage: true
subresources:
status: {}

14
content/v1.19/api/crds/pkg.crossplane.io_providerrevisions.yaml → content/v1.16/api/crds/pkg.crossplane.io_providerrevisions.yaml
View File

@ -1,9 +1,8 @@
---
apiVersion: apiextensions.k8s.io/v1
kind: CustomResourceDefinition
metadata:
annotations:
controller-gen.kubebuilder.io/version: v0.16.5
controller-gen.kubebuilder.io/version: v0.14.0
name: providerrevisions.pkg.crossplane.io
spec:
group: pkg.crossplane.io
@ -46,6 +45,7 @@ spec:
A ProviderRevision represents a revision of a Provider. Crossplane
creates new revisions when there are changes to a Provider.
Crossplane creates and manages ProviderRevisions. Don't directly edit
ProviderRevisions.
properties:
@ -124,13 +124,10 @@ spec:
referenced object inside the same namespace.
properties:
name:
default: ""
description: |-
Name of the referent.
This field is effectively required, but due to backwards compatibility is
allowed to be empty. Instances of this type with an empty value here are
almost certainly wrong.
More info: https://kubernetes.io/docs/concepts/overview/working-with-objects/names/#names
TODO: Add other useful fields. apiVersion, kind, uid?
type: string
type: object
x-kubernetes-map-type: atomic
@ -288,7 +285,6 @@ spec:
items:
type: string
type: array
x-kubernetes-list-type: atomic
nonResourceURLs:
description: |-
NonResourceURLs is a set of partial urls that a user should have access to. *s are allowed, but only as the full, final step in the path
@ -297,7 +293,6 @@ spec:
items:
type: string
type: array
x-kubernetes-list-type: atomic
resourceNames:
description: ResourceNames is an optional white list of names
that the rule applies to. An empty set means that everything
@ -305,21 +300,18 @@ spec:
items:
type: string
type: array
x-kubernetes-list-type: atomic
resources:
description: Resources is a list of resources this rule applies
to. '*' represents all resources.
items:
type: string
type: array
x-kubernetes-list-type: atomic
verbs:
description: Verbs is a list of Verbs that apply to ALL the
ResourceKinds contained in this rule. '*' represents all verbs.
items:
type: string
type: array
x-kubernetes-list-type: atomic
required:
- verbs
type: object

9
content/v2.0-preview/api/crds/pkg.crossplane.io_providers.yaml → content/v1.16/api/crds/pkg.crossplane.io_providers.yaml
View File

@ -1,9 +1,8 @@
---
apiVersion: apiextensions.k8s.io/v1
kind: CustomResourceDefinition
metadata:
annotations:
controller-gen.kubebuilder.io/version: v0.16.5
controller-gen.kubebuilder.io/version: v0.14.0
name: providers.pkg.crossplane.io
spec:
group: pkg.crossplane.io
@ -37,6 +36,7 @@ spec:
A Provider installs an OCI compatible Crossplane package, extending
Crossplane with support for new kinds of managed resources.
Read the Crossplane documentation for
[more information about Providers](https://docs.crossplane.io/latest/concepts/providers).
properties:
@ -109,13 +109,10 @@ spec:
referenced object inside the same namespace.
properties:
name:
default: ""
description: |-
Name of the referent.
This field is effectively required, but due to backwards compatibility is
allowed to be empty. Instances of this type with an empty value here are
almost certainly wrong.
More info: https://kubernetes.io/docs/concepts/overview/working-with-objects/names/#names
TODO: Add other useful fields. apiVersion, kind, uid?
type: string
type: object
x-kubernetes-map-type: atomic

3
content/v1.20/api/crds/secrets.crossplane.io_storeconfigs.yaml → content/v1.16/api/crds/secrets.crossplane.io_storeconfigs.yaml
View File

@ -1,9 +1,8 @@
---
apiVersion: apiextensions.k8s.io/v1
kind: CustomResourceDefinition
metadata:
annotations:
controller-gen.kubebuilder.io/version: v0.16.5
controller-gen.kubebuilder.io/version: v0.14.0
name: storeconfigs.secrets.crossplane.io
spec:
group: secrets.crossplane.io

0
content/v1.19/cli/_index.md → content/v1.16/cli/_index.md
View File

480
content/v1.20/cli/command-reference.md → content/v1.16/cli/command-reference.md
View File

@ -6,22 +6,19 @@ description: "Command reference for the Crossplane CLI"
<!-- vale Google.Headings = NO -->
The `crossplane` CLI provides utilities to make using Crossplane easier.
The `crossplane` CLI provides utilities to make using Crossplane easier.
Read the [Crossplane CLI overview]({{<ref "../cli">}}) page for information on
Read the [Crossplane CLI overview]({{<ref "../cli">}}) page for information on
installing `crossplane`.
## Global flags
The following flags are available for all commands.
{{< table "table table-sm table-striped">}}
| Short flag | Long flag | Description |
|------------|-------------|------------------------------|
| `-h` | `--help` | Show context sensitive help. |
| | `--verbose` | Print verbose output. |
{{< /table >}}
## version
@ -31,176 +28,35 @@ and the control plane.
```shell
crossplane version
Client Version: v1.17.0
Server Version: v1.17.0
Client Version: v1.16.0
Server Version: v1.16.0
```
## render
The `crossplane render` command previews the output of a
[composite resource]({{<ref "../concepts/composite-resources">}}) after applying
any [composition functions]({{<ref "../concepts/compositions">}}).
{{< hint "important" >}}
The `crossplane render` command requires you to use composition functions.
{{< /hint >}}
The `crossplane render` command connects to the locally running Docker
Engine to pull and run composition functions.
{{<hint "important">}}
Running `crossplane render` requires [Docker](https://www.docker.com/).
{{< /hint >}}
Provide a composite resource, composition and composition function YAML
definition with the command to render the output locally.
For example,
`crossplane render xr.yaml composition.yaml function.yaml`
The output includes the original composite resource followed by the generated
managed resources.
{{<expand "An example render output" >}}
```yaml
---
apiVersion: nopexample.org/v1
kind: XBucket
metadata:
name: test-xrender
status:
bucketRegion: us-east-2
---
apiVersion: s3.aws.upbound.io/v1beta1
kind: Bucket
metadata:
annotations:
crossplane.io/composition-resource-name: my-bucket
generateName: test-xrender-
labels:
crossplane.io/composite: test-xrender
ownerReferences:
- apiVersion: nopexample.org/v1
blockOwnerDeletion: true
controller: true
kind: XBucket
name: test-xrender
uid: ""
spec:
forProvider:
region: us-east-2
```
{{< /expand >}}
### Flags
{{< table "table table-sm table-striped">}}
| Short flag | Long flag | Description |
| ------------ | ------------- | ------------------------------ |
| | `--context-files=<key>=<file>,<key>=<file>` | A comma separated list of files to load for function "contexts." |
| | `--context-values=<key>=<value>,<key>=<value>` | A comma separated list of key-value pairs to load for function "contexts." |
| `-r` | `--include-function-results` | Include the "results" or events from the function. |
| `-o` | `--observed-resources=<directory or file>` | Provide artificial managed resource data to the function. |
| `-e` | `--extra-resources=PATH` | A YAML file or directory of YAML files specifying extra resources to pass to the Function pipeline. |
| `-c` | `--include-context` | Include the context in the rendered output as a resource of kind: Context. |
| `-x` | `--include-full-xr` | Include a copy of the input Composite Resource spec and metadata fields in the rendered output. |
| | `--timeout=` | Amount of time to wait for a function to finish. (Default 1 minute) |
{{< /table >}}
The `crossplane render` command relies on standard
[Docker environmental variables](https://docs.docker.com/engine/reference/commandline/cli/#environment-variables)
to connect to the local Docker Engine and run composition functions.
### Provide function context
The `--context-files` and `--context-values` flags can provide data
to a function's `context`.
The context is JSON formatted data.
### Include function results
If a function produces Kubernetes events with statuses use the
`--include-function-results` to print them along with the managed resource
outputs.
### Include the composite resource
Composition functions can only change the `status` field of a composite
resource. By default, the `crossplane render` command only prints the
`status` field with `metadata.name`.
Use `--include-full-xr` to print the full composite resource,
including the `spec` and `metadata` fields.
### Mock managed resources
Provide mocked, or artificial data representing a managed resource with
`--observed-resources`. The `crossplane render` command treats the
provided inputs as if they were resources in a Crossplane cluster.
A function can reference and manipulate the included resource as part of
running the function.
The `observed-resources` may be a single YAML file with multiple resources or a
directory of YAML files representing multiple resources.
Inside the YAML file include an
{{<hover label="apiVersion" line="1">}}apiVersion{{</hover>}},
{{<hover label="apiVersion" line="2">}}kind{{</hover>}},
{{<hover label="apiVersion" line="3">}}metadata{{</hover>}} and
{{<hover label="apiVersion" line="7">}}spec{{</hover>}}.
```yaml {label="apiVersion"}
apiVersion: example.org/v1alpha1
kind: ComposedResource
metadata:
name: test-render-b
annotations:
crossplane.io/composition-resource-name: resource-b
spec:
coolerField: "I'm cooler!"
```
The schema of the resource isn't validated and may contain any data.
### Mock Extra Resources
Extra Resources allow a Composition to request Crossplane Objects on the cluster that aren't
part of the Composition. The `--extra-resources` option points at a directory containing
YAML manifests of resources to mock. Use Extra Resources in combination with a function like
[function-extra-resources](https://github.com/crossplane-contrib/function-extra-resources) or the
built-in support in [function-go-templating](https://github.com/crossplane-contrib/function-go-templating?tab=readme-ov-file#extraresources).
## xpkg
The `crossplane xpkg` commands create, install and update Crossplane
[packages]({{<ref "../concepts/packages">}}) as well as enable authentication
and publishing of Crossplane packages to a Crossplane package registry.
and publishing of Crossplane packages to a Crossplane package registry.
### xpkg build
Using `crossplane xpkg build` provides automation and simplification to build
Using `crossplane xpkg build` provides automation and simplification to build
Crossplane packages.
The Crossplane CLI combines a directory of YAML files and packages them as
The Crossplane CLI combines a directory of YAML files and packages them as
an [OCI container image](https://opencontainers.org/).
The CLI applies the required annotations and values to meet the
The CLI applies the required annotations and values to meet the
[Crossplane XPKG specification](https://github.com/crossplane/crossplane/blob/main/contributing/specifications/xpkg.md).
The `crossplane` CLI supports building
[configuration]({{< ref "../concepts/packages" >}}),
[function]({{<ref "../concepts/compositions">}}) and
[provider]({{<ref "../concepts/providers" >}}) package types.
[function]({{<ref "../concepts/composition-functions">}}) and
[provider]({{<ref "../concepts/providers" >}}) package types.
#### Flags
{{< table "table table-sm table-striped">}}
| Short flag | Long flag | Description |
| ------------ | ------------- | ------------------------------ |
| | `--embed-runtime-image-name=NAME` | The image name and tag of an image to include in the package. Only for provider and function packages. |
@ -211,12 +67,12 @@ The `crossplane` CLI supports building
| `-f` | `--package-root="."` | Directory to search for YAML files. |
{{< /table >}}
The `crossplane xpkg build` command recursively looks in the directory set by
`--package-root` and attempts to combine any files ending in `.yml` or `.yaml`
The `crossplane xpkg build` command recursively looks in the directory set by
`--package-root` and attempts to combine any files ending in `.yml` or `.yaml`
into a package.
All YAML files must be valid Kubernetes manifests with `apiVersion`, `kind`,
`metadata` and `spec` fields.
All YAML files must be valid Kubernetes manifests with `apiVersion`, `kind`,
`metadata` and `spec` fields.
#### Ignore files
@ -240,6 +96,9 @@ For example,
Include YAML files demonstrating how to use the package with `--examples-root`.
[Upbound Marketplace](https://marketplace.upbound.io/) uses files included with
`--examples-root` as documentation for published packages.
#### Include a runtime image
Functions and Providers require YAML files describing their dependencies and
@ -258,52 +117,6 @@ Use `docker pull` to download a missing image.
The `--embed-runtime-image-tarball` flag includes a local OCI image tarball
inside the function or provider package.
### xpkg init
The `crossplane xpkg init` command populates the current directory with
files to build a package.
Provide a name to use for the package and the package template to start from
with the command
`crossplane xpkg init <name> <template>`
The `<name>` input isn't used. Crossplane reserves the `<name>` for future releases.
The `<template>` value may be one of four well known templates:
* `configuration-template` - A template to build a Crossplane [Configuration]({{<ref "../concepts/packages">}}) from the [crossplane/configuration-template](https://github.com/crossplane/configuration-template) repository.
* `function-template-go` - A template to build Crossplane Go [composition functions]({{<ref "../concepts/compositions">}}) from the [crossplane/function-template-go](https://github.com/crossplane/function-template-go) repository.
* `function-template-python` - A template to build Crossplane Python [composition functions]({{<ref "../concepts/compositions">}}) from the [crossplane/function-template-python](https://github.com/crossplane/function-template-go) repository.
* `provider-template` - A template to build a basic Crossplane provider from the [Crossplane/provider-template](https://github.com/crossplane/provider-template) repository.
* `provider-template-upjet` - A template for building [Upjet](https://github.com/crossplane/upjet) based Crossplane providers from existing Terraform providers. Copies from the [upbound/upjet-provider-template](https://github.com/upbound/upjet-provider-template) repository.
Instead of a well known template the `<template>` value can be a git repository
URL.
#### NOTES.txt
If the template repository contains a `NOTES.txt` file in its root directory,
the `crossplane xpkg init` command prints the contents of the file to the
terminal after populating the directory with the template files. This can be
useful for providing information about the template.
#### init.sh
If the template repository contains an `init.sh` file in its root directory, the
`crossplane xpkg init` command starts a dialog after populating the
directory with the template files. The dialog prompts the user if they want
to view or run the script. Use the initialization script to automatically
personalize the template.
#### Flags
{{< table "table table-sm table-striped">}}
| Short flag | Long flag | Description |
| ------------ | ----------------------- | ------------------------------ |
| `-b` | `--ref-name` | The branch or tag to clone from the template repository. |
| `-d` | `--directory` | The directory to create and load the template files into. Uses the current directory by default. |
| `-r` | `--run-init-script` | Run the init.sh script without prompting, if it exists. |
<!-- vale Crossplane.Spelling = YES -->
{{< /table >}}
### xpkg install
@ -322,10 +135,10 @@ inside Crossplane.
The `<package-kind>` is either a `configuration`, `function` or `provider`.
For example, to install the latest version of the
[AWS S3 provider](https://github.com/crossplane-contrib/provider-upjet-aws):
For example, to install to the latest version of the
[AWS S3 provider](https://marketplace.upbound.io/providers/upbound/provider-aws-s3/):
`crossplane xpkg install provider xpkg.crossplane.io/crossplane-contrib/provider-aws-s3:v1.21.1`
`crossplane xpkg install provider xpkg.upbound.io/upbound/provider-aws-s3:v1`
#### Flags
{{< table "table table-sm table-striped">}}
@ -377,7 +190,11 @@ in the package documentation.
### xpkg login
Use `xpkg login` to authenticate to registries that host Crossplane packages.
Use `xpkg login` to authenticate to `xpkg.upbound.io`, the
[Upbound Marketplace](https://marketplace.upbound.io/) container registry.
[Register with the Upbound Marketplace](https://accounts.upbound.io/register)
to push packages and create private repositories.
#### Flags
@ -444,6 +261,10 @@ Using `crossplane xpkg logout` removes the `session` from the
Push a Crossplane package file to a package registry.
The Crossplane CLI pushes images to the
[Upbound Marketplace](https://marketplace.upbound.io/) at `xpkg.upbound.io` by
default.
{{< hint "note" >}}
Pushing a package may require authentication with
[`crossplane xpkg login`](#xpkg-login)
@ -493,11 +314,13 @@ already installed in Crossplane.
`crossplane xpkg update <package-kind> <registry package name and tag> [<optional-name>]`
The package file must be an organization, image and tag on the `xpkg.upbound.io`
registry on [Upbound Marketplace](https://marketplace.upbound.io/).
For example, to update to the latest version of the
[AWS S3 provider](https://github.com/crossplane-contrib/provider-upjet-aws):
`crossplane xpkg update provider xpkg.crossplane.io/crossplane-contrib/provider-aws-s3:v1.21.1`
[AWS S3 provider](https://marketplace.upbound.io/providers/upbound/provider-aws-s3/):
`crossplane xpkg update provider xpkg.upbound.io/upbound/provider-aws-s3:v1`
## beta
@ -517,8 +340,9 @@ converts a Crossplane resource to a new version or kind.
Use the `crossplane beta convert` command to convert an existing
[ControllerConfig]({{<ref "../concepts/providers#controller-configuration">}})
to a [DeploymentRuntimeConfig]({{<ref "../concepts/providers#runtime-configuration">}})
or a legacy Composition using `mode: Resources` to a
[Composition pipeline function]({{< ref "../concepts/compositions" >}}).
or a Composition using [patch and transforms]({{<ref "../concepts/patch-and-transform">}})
to a
[Composition pipeline function]({{< ref "../concepts/compositions#use-composition-functions" >}}).
Provide the `crossplane beta convert` command the conversion type, the input
file and optionally, an output file. By default the command writes the output to
@ -548,6 +372,138 @@ By default the function name is "function-patch-and-transform."
{{< /table >}}
### beta render
The `crossplane beta render` command previews the output of a
[composite resource]({{<ref "../concepts/composite-resources">}}) after applying
any [composition functions]({{<ref "../concepts/composition-functions">}}).
{{< hint "important" >}}
The `crossplane beta render` command doesn't apply
[patch and transform composition patches]({{<ref "../concepts/patch-and-transform">}}).
The command only supports function "patch and transforms."
{{< /hint >}}
The `crossplane beta render` command connects to the locally running Docker
Engine to pull and run composition functions.
{{<hint "important">}}
Running `crossplane beta render` requires [Docker](https://www.docker.com/).
{{< /hint >}}
Provide a composite resource, composition and composition function YAML
definition with the command to render the output locally.
For example,
`crossplane beta render xr.yaml composition.yaml function.yaml`
The output includes the original composite resource followed by the generated
managed resources.
{{<expand "An example render output" >}}
```yaml
---
apiVersion: nopexample.org/v1
kind: XBucket
metadata:
name: test-xrender
status:
bucketRegion: us-east-2
---
apiVersion: s3.aws.upbound.io/v1beta1
kind: Bucket
metadata:
annotations:
crossplane.io/composition-resource-name: my-bucket
generateName: test-xrender-
labels:
crossplane.io/composite: test-xrender
ownerReferences:
- apiVersion: nopexample.org/v1
blockOwnerDeletion: true
controller: true
kind: XBucket
name: test-xrender
uid: ""
spec:
forProvider:
region: us-east-2
```
{{< /expand >}}
#### Flags
{{< table "table table-sm table-striped">}}
| Short flag | Long flag | Description |
| ------------ | ------------- | ------------------------------ |
| | `--context-files=<key>=<file>,<key>=<file>` | A comma separated list of files to load for function "contexts." |
| | `--context-values=<key>=<value>,<key>=<value>` | A comma separated list of key-value pairs to load for function "contexts." |
| `-r` | `--include-function-results` | Include the "results" or events from the function. |
| `-o` | `--observed-resources=<directory or file>` |
Provide artificial managed resource data to the function.
|
| `-x` | `--include-full-xr` | Include a copy of the input Composite Resource spec and metadata fields in the rendered output. |
| | `--timeout=` | Amount of time to wait for a function to finish. |
{{< /table >}}
The `crossplane beta render` command relies on standard
[Docker environmental variables](https://docs.docker.com/engine/reference/commandline/cli/#environment-variables)
to connect to the local Docker engine and run composition functions.
#### Provide function context
The `--context-files` and `--context-values` flags can provide data
to a function's `context`.
The context is JSON formatted data.
#### Include function results
If a function produces Kubernetes events with statuses use the
`--include-function-results` to print them along with the managed resource
outputs.
#### Include the composite resource
Composition functions can only change the `status` field of a composite
resource. By default, the `crossplane beta render` command only prints the
`status` field with `metadata.name`.
Use `--include-full-xr` to print the full composite resource,
including the `spec` and `metadata` fields.
#### Mock managed resources
Provide mocked, or artificial data representing a managed resource with
`--observed-resources`. The `crossplane beta render` command treats the
provided inputs as if they were resources in a Crossplane cluster.
A function can reference and manipulate the included resource as part of
running the function.
The `observed-resources` may be a single YAML file with multiple resources or a
directory of YAML files representing multiple resources.
Inside the YAML file include an
{{<hover label="apiVersion" line="1">}}apiVersion{{</hover>}},
{{<hover label="apiVersion" line="2">}}kind{{</hover>}},
{{<hover label="apiVersion" line="3">}}metadata{{</hover>}} and
{{<hover label="apiVersion" line="7">}}spec{{</hover>}}.
```yaml {label="apiVersion"}
apiVersion: example.org/v1alpha1
kind: ComposedResource
metadata:
name: test-render-b
annotations:
crossplane.io/composition-resource-name: resource-b
spec:
coolerField: "I'm cooler!"
```
The schema of the resource isn't validated and may contain any data.
### beta top
The command `crossplane beta top` shows CPU and memory usage of Crossplane
@ -555,11 +511,11 @@ related pods.
```shell
crossplane beta top
TYPE NAMESPACE NAME CPU(cores) MEMORY
crossplane default crossplane-f98f9ddfd-tnm46 4m 32Mi
crossplane default crossplane-rbac-manager-74ff459b88-94p8p 4m 14Mi
provider default provider-aws-s3-1f1a3fb08cbc-5c49d84447-sggrq 3m 108Mi
provider default crossplane-contrib-provider-family-aws-48b3b5ccf964-76c9686b6-bgg65 2m 89Mi
TYPE NAMESPACE NAME CPU(cores) MEMORY
crossplane default crossplane-f98f9ddfd-tnm46 4m 32Mi
crossplane default crossplane-rbac-manager-74ff459b88-94p8p 4m 14Mi
provider default provider-aws-s3-1f1a3fb08cbc-5c49d84447-sggrq 3m 108Mi
provider default upbound-provider-family-aws-48b3b5ccf964-76c9686b6-bgg65 2m 89Mi
```
{{<hint "important" >}}
@ -871,16 +827,14 @@ Configuration/platform-ref-aws v0.9.0 True
The `crossplane beta validate` command validates
[compositions]({{<ref "../concepts/compositions">}}) against provider or XRD
schemas using the Kubernetes API server's validation library
with extra validation such as checking for unknown fields,
a common source of difficult to debug issues in Crossplane.
schemas using the Kubernetes API server's validation library.
The `crossplane beta validate` command supports validating the following
scenarios:
- Validate a managed resource or composite resource
[against a Provider or XRD schema](#validate-resources-against-a-schema).
- Use the output of `crossplane render` as [validation input](#validate-render-command-output).
- Use the output of `crossplane beta render` as [validation input](#validate-render-command-output).
- Validate an [XRD against Kubernetes Common Expression Language](#validate-common-expression-language-rules)
(CEL) rules.
- Validate resources against a [directory of schemas](#validate-against-a-directory-of-schemas).
@ -902,7 +856,6 @@ A Kubernetes cluster running Crossplane isn't required.
| | `--cache-dir=".crossplane/cache"` | Specify the absolute path to the cache directory to store downloaded schemas. |
| | `--clean-cache` | Clean the cache directory before downloading package schemas. |
| | `--skip-success-results` | Skip printing success results. |
| | `--error-on-missing-schemas` | Return a non zero exit code if any schemas are missing. |
| | `--verbose` | Print verbose logging statements. |
{{< /table >}}
@ -929,7 +882,7 @@ To clear the cache and download the CRD files again use the `--clean-cache` flag
To validate a managed resource against a provider,
first, create a provider manifest file. For example, to validate an IAM role
from Provider AWS, use the
[Provider AWS IAM](https://github.com/crossplane-contrib/provider-upjet-aws)
[Provider AWS IAM](https://marketplace.upbound.io/providers/upbound/provider-aws-iam/v1.0.0)
manifest.
{{<hint "tip" >}}
@ -944,7 +897,7 @@ kind: Provider
metadata:
name: provider-aws-iam
spec:
package: xpkg.crossplane.io/crossplane-contrib/provider-aws-iam:v1.21.1
package: xpkg.upbound.io/upbound/provider-aws-iam:v1
```
Now include the XR or managed resource to validate.
@ -974,18 +927,19 @@ crossplane beta validate provider.yaml managedResource.yaml
Total 1 resources: 0 missing schemas, 1 success case, 0 failure cases
```
#### Validate render command output
You can pipe the output of `crossplane render` into
You can pipe the output of `crossplane beta render` into
`crossplane beta validate` to validate complete Crossplane resource pipelines,
including XRs, compositions and composition functions.
including XRs, compositions and composition functions.
Use the `--include-full-xr` command with `crossplane render` and the `-`
option with `crossplane beta validate` to pipe the output from
`crossplane render` to the input of `crossplane beta validate`.
Use the `--include-full-xr` command with `crossplane beta render` and the `-`
option with `crossplane beta validate` to pipe the output from
`crossplane beta render` to the input of `crossplane beta validate`.
```shell {copy-lines="1"}
crossplane render xr.yaml composition.yaml function.yaml --include-full-xr | crossplane beta validate schemas.yaml -
crossplane beta render xr.yaml composition.yaml function.yaml --include-full-xr | crossplane beta validate schemas.yaml -
[x] schema validation error example.crossplane.io/v1beta1, Kind=XR, example : status.conditions[0].lastTransitionTime: Invalid value: "null": status.conditions[0].lastTransitionTime in body must be of type string: "null"
[x] schema validation error example.crossplane.io/v1beta1, Kind=XR, example : spec: Required value
[✓] iam.aws.upbound.io/v1beta1, Kind=AccessKey, sample-access-key-0 validated successfully
@ -995,8 +949,8 @@ crossplane render xr.yaml composition.yaml function.yaml --include-full-xr | cro
Total 5 resources: 0 missing schemas, 4 success cases, 1 failure cases
```
#### Validate Common Expression Language rules
#### Validate Common Expression Language rules
XRDs can define [validation rules](https://kubernetes.io/docs/tasks/extend-kubernetes/custom-resources/custom-resource-definitions/#validation-rules) expressed in the Common Expression Language
([CEL](https://kubernetes.io/docs/reference/using-api/cel/)).
@ -1032,7 +986,7 @@ spec:
The rule in this example checks that the vale of the
{{<hover label="celXR" line="6">}}replicas{{</hover>}} field of an XR is between
the {{<hover label="celXR" line="7">}}minReplicas{{</hover>}} and
the {{<hover label="celXR" line="7">}}minReplicas{{</hover>}} and
{{<hover label="celXR" line="8">}}maxReplicas{{</hover>}} values.
```yaml {label="celXR"}
@ -1055,16 +1009,17 @@ error.
Total 1 resources: 0 missing schemas, 0 success cases, 1 failure cases
```
#### Validate against a directory of schemas
The `crossplane render` command can validate a directory of YAML files.
The `crossplane beta render` command can validate a directory of YAML files.
The command only processes `.yaml` and `.yml` files, while ignoring all other
file types.
With a directory of files, provide the directory and resource to validate.
With a directory of files, provide the directory and resource to validate.
For example, using a directory named
For example, using a directory named
{{<hover label="validateDir" line="2">}}schemas{{</hover>}} containing the XRD
and Provider schemas.
@ -1079,8 +1034,8 @@ schemas
`-- xrd.yaml
```
Provide the directory name and a resource YAML file to the
`crossplane beta validate` command.
Provide the directory name and a resource YAML file to the
`crossplane beta validate` command.
```shell
crossplane beta validate schema resources.yaml
@ -1093,4 +1048,51 @@ crossplane beta validate schema resources.yaml
Total 5 resources: 0 missing schemas, 4 success cases, 1 failure cases
```
### beta xpkg init
The `crossplane beta xpkg init` command populates the current directory with
files to build a package.
Provide a name to use for the package and the package template to start from
with the command
`crossplane beta xpkg init <name> <template>`
The `<name>` input isn't used. Crossplane reserves the `<name>` for future releases.
The `<template>` value may be one of four well known templates:
* `configuration-template` - A template to build a Crossplane [Configuration]({{<ref "../concepts/packages">}}) from the [crossplane/configuration-template](https://github.com/crossplane/configuration-template) repository.
* `function-template-go` - A template to build Crossplane Go [composition functions]({{<ref "../concepts/composition-functions">}}) from the [crossplane/function-template-go](https://github.com/crossplane/function-template-go) repository.
* `function-template-python` - A template to build Crossplane Python [composition functions]({{<ref "../concepts/composition-functions">}}) from the [crossplane/function-template-python](https://github.com/crossplane/function-template-go) repository.
* `provider-template` - A template to build a basic Crossplane provider from the [Crossplane/provider-template](https://github.com/crossplane/provider-template) repository.
* `provider-template-upjet` - A template for building [Upjet](https://github.com/crossplane/upjet) based Crossplane providers from existing Terraform providers. Copies from the [upbound/upjet-provider-template](https://github.com/upbound/upjet-provider-template) repository.
Instead of a well known template the `<template>` value can be a git repository
URL.
#### NOTES.txt
If the template repository contains a `NOTES.txt` file in its root directory,
the `crossplane beta xpkg init` command prints the contents of the file to the
terminal after populating the directory with the template files. This can be
useful for providing information about the template.
#### init.sh
If the template repository contains an `init.sh` file in its root directory, the
`crossplane beta xpkg init` command starts a dialog after populating the
directory with the template files. The dialog prompts the user if they want
to view or run the script. Use the initialization script to automatically
personalize the template.
#### Flags
{{< table "table table-sm table-striped">}}
| Short flag | Long flag | Description |
| ------------ | ----------------------- | ------------------------------ |
| `-b` | `--ref-name` | The branch or tag to clone from the template repository. |
| `-d` | `--directory` | The directory to create and load the template files into. Uses the current directory by default. |
| `-r` | `--run-init-script` | Run the init.sh script without prompting, if it exists. |
<!-- vale Crossplane.Spelling = YES -->
{{< /table >}}

10
content/v1.20/concepts/_index.md → content/v1.16/concepts/_index.md
View File

@ -55,6 +55,16 @@ building and managing external resources through Kubernetes.
Composite Resource. Platform users create Claims in their unique namespace,
isolating their resources from other teams in other namespaces.
* [**Composition Functions**]({{<ref "./composition-functions">}}) are custom
programs, written your programming language of choice, to apply logic and
loops before or after Crossplane creates resources.
* [**Patches and Transforms**]({{<ref "./patch-and-transform">}}) allow platform
engineers to use user inputs to their custom API and change how Crossplane
creates resources. Patches and transforms allow for flexible and
abstract inputs like `big` or `encrypted` to have specific meanings when
creating the actual managed resources.
* [**EnvironmentConfigs**]({{<ref "./environment-configs">}}) are an in-memory
data store, like a Kubernetes ConfigMap. EnvironmentConfigs are useful for
custom resource mapping or storing and retrieving data across Claims and

0
content/v1.19/concepts/claims.md → content/v1.16/concepts/claims.md
View File

4
content/v1.20/concepts/composite-resource-definitions.md → content/v1.16/concepts/composite-resource-definitions.md
View File

@ -413,7 +413,7 @@ field indicates which version of the schema Compositions use. Only one
version can be `referenceable`.
{{< hint "note" >}}
Changing which version is `referenceable:true` requires [updating the `compositeTypeRef.apiVersion`]({{<ref "./compositions#enable-composite-resources" >}})
Changing which version is `referenceable:true` requires [updating the `compositeTypeRef.apiVersion`]({{<ref "./compositions#enabling-composite-resources" >}})
of any Compositions referencing that XRD.
{{< /hint >}}
@ -582,7 +582,7 @@ key names listed in the Composition's `connectionDetails`.
An XRD ignores any keys listed that aren't created by a managed resource.
For more information read the
[Composition documentation]({{<ref "./compositions#store-connection-details">}}).
[Composition documentation]({{<ref "./compositions#storing-connection-details">}}).
{{< /hint >}}

29
content/v1.20/concepts/composite-resources.md → content/v1.16/concepts/composite-resources.md
View File

@ -133,27 +133,16 @@ kind: Composition
metadata:
name: my-composition
spec:
mode: Pipeline
pipeline:
- step: patch-and-transform
functionRef:
name: function-patch-and-transform
input:
apiVersion: pt.fn.crossplane.io/v1beta1
kind: Resources
resources:
- name: database
base:
# Removed for brevity
patches:
- fromFieldPath: metadata.annotations
toFieldPath: metadata.annotations
resources:
- name: database
base:
# Removed for brevity
patches:
- fromFieldPath: metadata.annotations
toFieldPath: metadata.annotations
```
For more information on using `function-patch-and-transform` to patch
resources refer to the
[Function Patch and Transform]({{<ref "../guides/function-patch-and-transform">}})
documentation.
For more information on patching resources refer to the [Patch and Transform]({{<ref "./patch-and-transform">}}) documentation.
### Composition selection
@ -163,7 +152,7 @@ Select a specific Composition for a composite resource to use with
{{<hint "important">}}
The selected Composition must allow the composite resource to use it with a
`compositeTypeRef`. Read more about the `compositeTypeRef` field in the
[Enable Composite Resources]({{<ref "./compositions#enable-composite-resources">}})
[Enabling Composite Resources]({{<ref "./compositions#enabling-composite-resources">}})
section of the Composition documentation.
{{< /hint >}}

508
content/v2.0-preview/composition/compositions.md → content/v1.16/concepts/composition-functions.md
View File

@ -1,96 +1,29 @@
---
title: Compositions
weight: 30
aliases:
- composition
- composition-functions
title: Composition Functions
state: beta
alphaVersion: "1.11"
betaVersion: "1.14"
weight: 80
description: "Composition Functions allow you to template resources using general-purpose programming languages"
aliases:
- /knowledge-base/guides/composition-functions
description: "Compositions are a template for creating composite resources"
---
Compositions are a template for creating multiple Kubernetes resources as a
single _composite_ resource.
Composition functions (or just functions, for short) are custom programs that
template Crossplane resources. Crossplane calls composition functions to
determine what resources it should create when you create a composite resource
(XR). You can write a function to template resources using a general purpose
programming language like Go or Python. Using a general purpose programming
language allows a Function to use more advanced logic to template resources,
like loops and conditionals.
A Composition _composes_ individual resources together into a larger, reusable,
solution.
You can build a function using general purpose programming languages such as Go
or Python. The Crossplane community has also built functions that let you
template Crossplane resources using [CUE](https://cuelang.org), Helm-like
[Go templates](https://pkg.go.dev/text/template) or
[Patch and Transforms]({{<ref "./patch-and-transform">}}).
An example Composition may combine a virtual machine, storage resources and
networking policies. A Composition template links all these individual
resources together.
Here's an example Composition. When you create an
{{<hover label="intro" line="8">}}AcmeBucket{{</hover >}} composite resource
(XR) that uses this Composition, Crossplane uses the template to create the
Amazon S3 {{<hover label="intro" line="18">}}Bucket{{</hover >}} managed
resource.
```yaml {label="intro"}
apiVersion: apiextensions.crossplane.io/v1
kind: Composition
metadata:
name: example
spec:
compositeTypeRef:
apiVersion: custom-api.example.org/v1alpha1
kind: AcmeBucket
mode: Pipeline
pipeline:
- step: patch-and-transform
functionRef:
name: function-patch-and-transform
input:
apiVersion: pt.fn.crossplane.io/v1beta1
kind: Resources
resources:
- name: storage-bucket
base:
apiVersion: s3.aws.m.upbound.io/v1beta1
kind: Bucket
spec:
forProvider:
region: "us-east-2"
```
{{<expand "What are XRs, XRDs and Compositions?" >}}
A [composite resource]({{<ref "./composite-resources">}}) or XR is a custom API.
You use two Crossplane types to create a new custom API:
* A [Composite Resource Definition]({{<ref "./composite-resource-definitions">}})
(XRD) - Defines the XR's schema.
* A Composition - This page. Configures how the XR creates other resources.
{{</expand >}}
## Create a Composition
Creating a Composition consists of:
* [Using composition functions](#use-a-function-in-a-composition) to define the
resources to create.
* [Enabling composite resources](#match-composite-resources) to use the
Composition template.
A Composition is a pipeline of composition functions.
Composition functions (or just functions, for short) are Crossplane extensions
that template Crossplane resources. Crossplane calls the composition functions
to determine what resources it should create when you create a composite
resource (XR).
{{<hint "tip" >}}
Crossplane has functions that let you template composed resources using YAML
[patch and transforms]({{<ref "../guides/function-patch-and-transform">}}).
Helm-like
[YAML templates](https://github.com/crossplane-contrib/function-go-templating),
[CUE](https://github.com/crossplane-contrib/function-cue),
[KCL](https://github.com/crossplane-contrib/function-kcl), or
[Python](https://github.com/crossplane-contrib/function-python).
You can also [write your own function](#write-a-composition-function) using Go
or Python.
{{< /hint >}}
### Install a composition function
## Install a composition function
Installing a Function creates a function pod. Crossplane sends requests to this
pod to ask it what resources to create when you create a composite resource.
@ -101,26 +34,26 @@ Install a Function with a Crossplane
location of the function package.
For example, to install [Function Patch and Transform]({{<ref "../guides/function-patch-and-transform">}}),
For example, to install [Function Patch and Transform](https://github.com/crossplane-contrib/function-patch-and-transform),
```yaml {label="install"}
apiVersion: pkg.crossplane.io/v1
apiVersion: pkg.crossplane.io/v1beta1
kind: Function
metadata:
name: function-patch-and-transform
spec:
package: xpkg.crossplane.io/crossplane-contrib/function-patch-and-transform:v0.8.2
package: xpkg.upbound.io/crossplane-contrib/function-patch-and-transform:v0.1.4
```
{{< hint "tip" >}}
Functions are Crossplane Packages. Read more about Packages in the
[Packages documentation]({{<ref "../packages/functions" >}}).
[Packages documentation]({{<ref "packages" >}}).
{{< /hint >}}
By default, the Function pod installs in the same namespace as Crossplane
(`crossplane-system`).
### Verify a composition function
## Verify a composition function
View the status of a Function with `kubectl get functions`
@ -130,48 +63,71 @@ During the install a Function reports `INSTALLED` as `True` and `HEALTHY` as
```shell {copy-lines="1"}
kubectl get functions
NAME INSTALLED HEALTHY PACKAGE AGE
function-patch-and-transform True Unknown xpkg.crossplane.io/crossplane-contrib/function-patch-and-transform:v0.8.2 10s
function-patch-and-transform True Unknown xpkg.upbound.io/crossplane-contrib/function-patch-and-transform:v0.1.4 10s
```
After the Function install completes and it's ready for use the `HEALTHY` status
reports `True`.
### Use a function in a composition
## Use a function in a composition
Crossplane calls a Function to determine what resources it should create when
you create a composite resource. The Function also tells Crossplane what to do
with these resources when you update or delete a composite resource.
When Crossplane calls a Function it sends it the current state of the composite
resource. It also sends it the current state of any resources the composite
resource owns.
resource. It also sends it the current state of any managed resources the
composite resource owns.
Crossplane knows what Function to call when a composite resource changes by
looking at the Composition the composite resource uses.
To use composition functions set the Composition
{{<expand "Confused about Composite Resources and Compositions?" >}}
Crossplane has four core components that users commonly mix up:
* [Composition]({{<ref "./compositions">}}) - A template to define how to create
resources.
* [CompositeResourceDefinition]({{<ref "./composite-resource-definitions">}})
(`XRD`) - A custom API specification.
* [Composite Resource]({{<ref "./composite-resources">}}) (`XR`) - Created by
using the custom API defined in a CompositeResourceDefinition. XRs use the
Composition template to create new managed resources.
* [Claim]({{<ref "./claims" >}}) (`XRC`) - Like a Composite Resource, but with
namespace scoping.
{{</expand >}}
To use composition functions set the Composition
{{<hover label="single" line="6">}}mode{{</hover>}} to
{{<hover label="single" line="6">}}Pipeline{{</hover>}}.
Define a {{<hover label="single" line="7">}}pipeline{{</hover>}} of
{{<hover label="single" line="8">}}steps{{</hover>}}. Each
{{<hover label="single" line="8">}}step{{</hover>}} calls a Function.
Define a {{<hover label="single" line="7">}}pipeline{{</hover>}} of
{{<hover label="single" line="8">}}steps{{</hover>}}. Each
{{<hover label="single" line="8">}}step{{</hover>}} calls a Function.
Each {{<hover label="single" line="8">}}step{{</hover>}} uses a
Each {{<hover label="single" line="8">}}step{{</hover>}} uses a
{{<hover label="single" line="9">}}functionRef{{</hover>}} to reference the
{{<hover label="single" line="10">}}name{{</hover>}} of the Function to call.
{{<hover label="single" line="10">}}name{{</hover>}} of the Function to call.
Some Functions also allow you to specify an
{{<hover label="single" line="11">}}input{{</hover>}}.
{{<hint "important" >}}
Compositions using {{<hover label="single" line="6">}}mode: Pipeline{{</hover>}}
can't specify resource templates with a `resources` field.
Use function "Patch and Transform" to create resource templates.
{{< /hint >}}
Some Functions also allow you to specify an
{{<hover label="single" line="11">}}input{{</hover>}}.
The function defines the
{{<hover label="single" line="13">}}kind{{</hover>}} of input.
This example uses
[Function Patch and Transform]({{<ref "../guides/function-patch-and-transform">}}).
[Function Patch and Transform](https://github.com/crossplane-contrib/function-patch-and-transform).
Function Patch and Transform implements Crossplane resource
templates.
The input kind is {{<hover label="single" line="13">}}Resources{{</hover>}},
and it accepts {{<hover label="single" line="14">}}resources{{</hover>}} as input.
templates.
The input kind is {{<hover label="single" line="13">}}Resources{{</hover>}},
and it accepts [Patch and Transform]({{<ref "./patch-and-transform">}})
{{<hover label="single" line="14">}}resources{{</hover>}} as input.
```yaml {label="single",copy-lines="none"}
apiVersion: apiextensions.crossplane.io/v1
@ -190,14 +146,15 @@ spec:
resources:
- name: storage-bucket
base:
apiVersion: s3.aws.m.upbound.io/v1beta1
apiVersion: s3.aws.upbound.io/v1beta1
kind: Bucket
spec:
forProvider:
region: "us-east-2"
```
### Use a pipeline of functions in a composition
## Use a pipeline of functions in a composition
Crossplane can ask more than one Function what to do when a composite resource
changes. When a Composition has a pipeline of two or more steps, Crossplane
@ -206,7 +163,7 @@ calls them all. It calls them in the order they appear in the pipeline.
Crossplane passes each Function in the pipeline the result of the previous
Function. This enables powerful combinations of Functions. In this example,
Crossplane calls {{<hover label="double" line="10">}}function-cue{{</hover>}} to
create an S3 bucket. Crossplane then passes the bucket to
create an S3 bucket. Crossplane then passes the bucket to
{{<hover label="double" line="23">}}function-auto-ready{{</hover>}}, which marks the
composite resource as ready when the bucket becomes ready.
@ -228,110 +185,22 @@ spec:
export:
target: Resources
value: |
apiVersion: "s3.aws.m.upbound.io/v1beta1"
apiVersion: "s3.aws.upbound.io/v1beta1"
kind: "Bucket"
spec: forProvider: region: "us-east-2"
spec:
forProvider:
region: "us-east-2"
- step: automatically-detect-readiness
functionRef:
name: function-auto-ready
```
## Test a composition that uses functions
### Match composite resources
You can preview the output of any composition that uses composition functions
using the Crossplane CLI. You don't need a Crossplane control plane to do
this. The Crossplane CLI uses Docker Engine to run functions.
A Composition is only a template defining how to create composed resources. A
Composition limits which kind of composite resource (XR) can use this template.
A Composition's {{<hover label="typeref" line="6">}}compositeTypeRef{{</hover>}}
defines which Composite Resource type can use this Composition.
{{<hint "note" >}}
Read more about Composite Resources in the
[Composite Resources page]({{<ref "./composite-resources" >}}).
{{< /hint >}}
Inside a Composition's
{{<hover label="typeref" line="5">}}spec{{</hover>}}
define the Composite Resource
{{<hover label="typeref" line="7">}}apiVersion{{</hover>}} and
{{<hover label="typeref" line="8">}}kind{{</hover>}}
that the Composition allows to use this template.
```yaml {label="typeref",copy-lines="none"}
apiVersion: apiextensions.crossplane.io/v1
kind: Composition
metadata:
name: dynamodb-with-bucket
spec:
compositeTypeRef:
apiVersion: custom-api.example.org/v1alpha1
kind: database
# Removed for brevity
```
### Grant access to composed resources
Crossplane uses its [service account](https://kubernetes.io/docs/concepts/security/service-accounts/)
to create the composed resources that a function pipeline returns.
Crossplane's service account has access to create, update, and delete any
resource installed by a [provider]({{<ref "../packages/providers">}}), or
defined by an XRD. This includes all
[MRs]({{<ref "../managed-resources/managed-resources">}}) and
[XRs]({{<ref "composite-resources">}}). It also has access to some types of
Kubernetes resources that it needs to function - for example it can create
deployments.
You must grant Crossplane access to compose any other kind of resource. You do
this by creating an [RBAC ClusterRole](https://kubernetes.io/docs/reference/access-authn-authz/rbac/).
<!-- vale write-good.TooWordy = NO -->
<!-- TooWordy thinks "aggregate" is too wordy, but it's the name of the concept. -->
The ClusterRole must aggregate to Crossplane's primary ClusterRole using
[ClusterRole aggregation](https://kubernetes.io/docs/reference/access-authn-authz/rbac/#aggregated-clusterroles).
<!-- vale write-good.TooWordy = YES -->
Here's a ClusterRole that grants Crossplane access to manage
[CloudNativePG](https://cloudnative-pg.io) PostgreSQL clusters.
``` yaml
apiVersion: rbac.authorization.k8s.io/v1
kind: ClusterRole
metadata:
name: cnpg:aggregate-to-crossplane
labels:
rbac.crossplane.io/aggregate-to-crossplane: "true"
rules:
- apiGroups:
- postgresql.cnpg.io
resources:
- clusters
verbs:
- "*"
```
<!-- vale write-good.TooWordy = NO -->
<!-- TooWordy thinks "aggregate" is too wordy, but it's the name of the concept. -->
The `rbac.crossplane.io/aggregate-to-crossplane: "true"` label is critical. It
configures the role to aggregate to Crossplane's primary cluster role.
<!-- vale write-good.TooWordy = YES -->
{{<hint "note" >}}
The [RBAC manager]({{<ref "../guides/pods#rbac-manager-pod">}}) automatically
grants Crossplane access to MRs and XRs. The RBAC manager uses
[escalate access](https://kubernetes.io/docs/concepts/security/rbac-good-practices/#escalate-verb)
to grant Crossplane access that the RBAC manager doesn't have.
The RBAC manager is an optional Crossplane component that's enabled by default.
**If you disable the RBAC manager, you must manually grant Crossplane access to
_any_ kind of resource you wish to compose - including XRs and MRs.**
{{< /hint >}}
## Test a composition
You can preview the output of any composition using the Crossplane CLI. You
don't need a Crossplane control plane to do this. The Crossplane CLI uses Docker
Engine to run functions.
{{<hint "tip">}}
See the [Crossplane CLI docs]({{<ref "../cli">}}) to
@ -339,28 +208,28 @@ learn how to install and use the Crossplane CLI.
{{< /hint >}}
{{<hint "important">}}
Running `crossplane render` requires [Docker](https://www.docker.com).
Running `crossplane beta render` requires [Docker](https://www.docker.com).
{{< /hint >}}
Provide a composite resource, composition and composition functions to render
the output locally.
the output locally.
```shell
crossplane render xr.yaml composition.yaml functions.yaml
crossplane beta render xr.yaml composition.yaml functions.yaml
```
`crossplane render` prints resources as YAML to stdout. It prints the
`crossplane beta render` prints resources as YAML to stdout. It prints the
composite resource first, followed by the resources the composition functions
created.
```yaml
---
apiVersion: example.crossplane.io/v1
kind: Bucket
kind: XBucket
metadata:
name: example-render
---
apiVersion: s3.aws.m.upbound.io/v1beta1
apiVersion: s3.aws.upbound.io/v1beta1
kind: Bucket
metadata:
annotations:
@ -372,7 +241,7 @@ metadata:
- apiVersion: example.crossplane.io/v1
blockOwnerDeletion: true
controller: true
kind: Bucket
kind: XBucket
name: example-render
uid: ""
spec:
@ -382,14 +251,14 @@ spec:
{{<expand "The xr.yaml, composition.yaml and function.yaml files used in the example">}}
You can recreate the output below by running `crossplane render` with
You can recreate the output below using by running `crossplane beta render` with
these files.
The `xr.yaml` file contains the composite resource to render:
```yaml
apiVersion: example.crossplane.io/v1
kind: Bucket
kind: XBucket
metadata:
name: example-render
spec:
@ -407,7 +276,7 @@ metadata:
spec:
compositeTypeRef:
apiVersion: example.crossplane.io/v1
kind: Bucket
kind: XBucket
mode: Pipeline
pipeline:
- step: patch-and-transform
@ -419,7 +288,7 @@ spec:
resources:
- name: storage-bucket
base:
apiVersion: s3.aws.m.upbound.io/v1beta1
apiVersion: s3.aws.upbound.io/v1beta1
kind: Bucket
patches:
- type: FromCompositeFieldPath
@ -432,21 +301,21 @@ its pipeline steps:
```yaml
---
apiVersion: pkg.crossplane.io/v1
apiVersion: pkg.crossplane.io/v1beta1
kind: Function
metadata:
name: function-patch-and-transform
spec:
package: xpkg.crossplane.io/crossplane-contrib/function-patch-and-transform:v0.8.2
package: xpkg.upbound.io/crossplane-contrib/function-patch-and-transform:v0.1.4
```
{{</expand>}}
The Crossplane CLI uses Docker Engine to run functions. You can change how the
Crossplane CLI runs a function by adding an annotation in `functions.yaml`. Add
Crossplane CLI run a function by adding an annotation in `functions.yaml`. Add
the `render.crossplane.io/runtime` annotation to a Function to change how it's
run.
`crossplane render` supports two `render.crossplane.io/runtime` values:
`crossplane beta render` supports two `render.crossplane.io/runtime` values:
* `Docker` (the default) connects to Docker Engine. It uses Docker to pull and
run a function runtime.
@ -461,14 +330,14 @@ transport security. Most function SDKs let you run a function with the
function locally using `go run . --insecure`.
```yaml {label="development"}
apiVersion: pkg.crossplane.io/v1
apiVersion: pkg.crossplane.io/v1beta1
kind: Function
metadata:
name: function-patch-and-transform
annotations:
render.crossplane.io/runtime: Development
spec:
package: xpkg.crossplane.io/crossplane-contrib/function-patch-and-transform:v0.8.2
package: xpkg.upbound.io/crossplane-contrib/function-patch-and-transform:v0.1.4
```
{{<hint "tip">}}
@ -477,7 +346,7 @@ Use the `Development` runtime when you
function end-to-end.
{{</hint>}}
`crossplane render` also supports the following Function annotations. These
`crossplane beta render` also supports the following Function annotations. These
annotations affect how it runs Functions:
* `render.crossplane.io/runtime-docker-cleanup` - When using the `Docker`
@ -492,36 +361,6 @@ the container, and `Orphan`, to leave it running.
running at the specified target. It uses
[gRPC target syntax](https://github.com/grpc/grpc/blob/v1.59.1/doc/naming.md).
## Verify a Composition
View all available Compositions with `kubectl get composition`.
```shell {copy-lines="1"}
kubectl get composition
NAME XR-KIND XR-APIVERSION AGE
xapps.aws.platformref.upbound.io XApp aws.platformref.upbound.io/v1alpha1 123m
xclusters.aws.platformref.upbound.io XCluster aws.platformref.upbound.io/v1alpha1 123m
xeks.aws.platformref.upbound.io XEKS aws.platformref.upbound.io/v1alpha1 123m
xnetworks.aws.platformref.upbound.io XNetwork aws.platformref.upbound.io/v1alpha1 123m
xservices.aws.platformref.upbound.io XServices aws.platformref.upbound.io/v1alpha1 123m
xsqlinstances.aws.platformref.upbound.io XSQLInstance aws.platformref.upbound.io/v1alpha1 123m
```
The `XR-KIND` lists the Composite Resource `kind` that's allowed to use the
Composition template.
The `XR-APIVERSION` lists the Composite Resource API versions allowed to use the
Composition template.
{{<hint "note" >}}
The output of `kubectl get composition` is different than `kubectl get
composite`.
`kubectl get composition` lists all available Compositions.
`kubectl get composite` lists all created Composite Resources and their related
Composition.
{{< /hint >}}
## Write a composition function
Composition functions let you replace complicated Compositions with code written
@ -535,16 +374,91 @@ Here's an example of a tiny, hello world function. This example is written in
<!-- vale write-good.Passive = YES -->
```go
func (f *Function) RunFunction(_ context.Context, req *fnv1.RunFunctionRequest) (*fnv1.RunFunctionResponse, error) {
func (f *Function) RunFunction(_ context.Context, req *fnv1beta1.RunFunctionRequest) (*fnv1beta1.RunFunctionResponse, error) {
rsp := response.To(req, response.DefaultTTL)
response.Normal(rsp, "Hello world!")
return rsp, nil
}
```
Crossplane has [language specific guides]({{<ref "../guides">}}) to writing a
composition function. Refer to the guide for your preferred language to learn
how to write a composition function.
Some people design composition functions for you to use them with any kind of
composite resource.
[Function Patch and Transform](https://github.com/crossplane-contrib/function-patch-and-transform)
and
[Function Auto Ready](https://github.com/crossplane-contrib/function-auto-ready)
work with any kind of composite resource.
Another common pattern is to write a composition function specific to one kind
of composite resource. The function contains all the logic needed to tell
Crossplane what resources to create when you create a composite resource. When
you write a composition function like this, your Composition can be small. It
just tells Crossplane what function to run when you create, update, or delete a
composite resource.
This Composition tells Crossplane to call {{<hover label="dedicated"
line="13">}}function-xr-xbucket{{</hover>}} whenever you create, update, or
delete an {{<hover label="dedicated" line="8">}}XBucket{{</hover>}} composite
resource. `function-xr-xbucket` is hard coded to handle `XBucket` composite
resources.
```yaml {label="dedicated"}
apiVersion: apiextensions.crossplane.io/v1
kind: Composition
metadata:
name: example-bucket-function
spec:
compositeTypeRef:
apiVersion: example.crossplane.io/v1
kind: XBucket
mode: Pipeline
pipeline:
- step: handle-xbucket-xr
functionRef:
name: function-xr-xbucket
```
To write a composition function, you:
1. Create the function from a template.
1. Edit the template to add the function's logic.
1. [Test the function](#test-a-composition-that-uses-functions).
1. Build the function, and push it to a package registry.
You use the [Crossplane CLI]({{<ref "../cli">}}) to
create, test, build, and push a function. For example,
```shell {copy-lines=none}
# Create the function from a template.
crossplane beta xpkg init function-example function-template-go
Initialized package "function-example" in directory "/home/negz/control/negz/function-example" from https://github.com/crossplane/function-template-go/tree/91a1a5eed21964ff98966d72cc6db6f089ad63f4 (main)
$ ls
Dockerfile fn.go fn_test.go go.mod go.sum input LICENSE main.go package README.md renovate.json
# Edit the template to add your function's logic
$ vim fn.go
# Build the function.
$ docker build . --quiet --tag runtime
sha256:2c31b0f7a34b34ba5b0b2dacc94c360d18aca1b99f56ca4f40a1f26535a7c1c4
# Package the function.
$ crossplane xpkg build -f package --embed-runtime-image=runtime
# Test the function.
$ go run . --insecure
$ crossplane beta render xr.yaml composition.yaml functions.yaml
# Push the function package to xpkg.upbound.io.
$ crossplane xpkg push -f package/*.xpkg crossplane-contrib/function-example:v0.1.0
```
{{<hint "tip">}}
Crossplane has
[language specific guides]({{<ref "../guides">}}) to writing
a composition function. Refer to the guide for your preferred language for a
more detailed guide to writing a function.
{{</hint>}}
When you're writing a composition function it's useful to know how composition
functions work. Read the next section to learn
@ -603,8 +517,8 @@ which composed resources it should create or update.
If the function needs __extra resources__ to determine the desired state it can
request any cluster-scoped resource Crossplane already has access to, either by
name or labels through the returned RunFunctionResponse. Crossplane then calls
the function again including the requested __extra resources__ and the
by name or labels through the returned RunFunctionResponse. Crossplane then
calls the function again including the requested __extra resources__ and the
__context__ returned by the Function itself alongside the same __input__,
__observed__ and __desired state__ of the previous RunFunctionRequest. Functions
can iteratively request __extra resources__ if needed, but to avoid endlessly
@ -614,8 +528,13 @@ stable, so the Function returns the same exact request two times in a row.
Crossplane errors if stability isn't reached after 5 iterations.
{{<hint "tip">}}
<!-- vale write-good.Weasel = NO -->
<!-- Disable Weasel to say "usually", which is correct in this context. -->
A _composed_ resource is a resource created by a composite resource. Composed
resources can be any kind of Kubernetes resource.
resources are usually Crossplane managed resources (MRs), but they can be any
kind of Crossplane resource. For example a composite resource could also create
a ProviderConfig, or another kind of composite resource.
<!-- vale write-good.Weasel = YES -->
{{</hint>}}
### Observed state
@ -625,7 +544,7 @@ sends it to the composition function as part of the observed state.
```yaml
apiVersion: example.crossplane.io/v1
kind: Bucket
kind: XBucket
metadata:
name: example-render
spec:
@ -633,7 +552,7 @@ spec:
```
If any composed resources already exist, Crossplane observes them and sends them
to your function as part of the observed state.
to your function to as part of the observed state.
Crossplane also observes the connection details of your composite resource and
any composed resources. It sends them to your function as part of the observed
@ -705,7 +624,7 @@ For example, if all a function wants is to make sure an S3 bucket in region
resources.
```yaml
apiVersion: s3.aws.m.upbound.io/v1beta1
apiVersion: s3.aws.upbound.io/v1beta1
kind: Bucket
spec:
forProvider:
@ -737,7 +656,7 @@ metadata:
spec:
compositeTypeRef:
apiVersion: example.crossplane.io/v1
kind: Bucket
kind: XBucket
mode: Pipeline
pipeline:
- step: patch-and-transform
@ -749,7 +668,7 @@ spec:
resources:
- name: storage-bucket
base:
apiVersion: s3.aws.m.upbound.io/v1beta1
apiVersion: s3.aws.upbound.io/v1beta1
kind: Bucket
patches:
- type: FromCompositeFieldPath
@ -769,3 +688,58 @@ that isn't desired state. Functions can use context for this. Any function can
write to the pipeline context. Crossplane passes the context to all following
functions. When Crossplane has called all functions it discards the pipeline
context.
Crossplane can write context too. If you enable the alpha
[composition environment]({{<ref "environment-configs">}}) feature Crossplane
writes the environment to the top-level context field
`apiextensions.crossplane.io/environment`.
## Disable composition functions
Crossplane enables composition functions by default. Disable support for
composition functions by disabling the beta feature flag in Crossplane with
`helm install --args`.
```shell
helm install crossplane --namespace crossplane-system crossplane-stable/crossplane \
--create-namespace \
--set "args='{--enable-composition-functions=false}'"
```
The preceding Helm command installs Crossplane with the composition functions
feature flag disabled. Confirm you have disabled composition functions by
looking for a log line:
```shell {copy-lines="1"}
kubectl -n crossplane-system logs -l app=crossplane
{"level":"info","ts":1674535093.36186,"logger":"crossplane","msg":"Beta feature enabled","flag":"EnableBetaCompositionFunctions"}
```
If you don't see the log line emitted when Crossplane starts, you have disabled
composition functions.
## Disable extra resources
Crossplane enables __extra resources__ by default, allowing Functions to get access
to any cluster-scoped resource Crossplane already has access to. Disable support
for __extra resources__, while keeping composition functions enabled, by disabling
the beta feature flag in Crossplane with `helm install --args`.
```shell
helm install crossplane --namespace crossplane-system crossplane-stable/crossplane \
--create-namespace \
--set "args='{--enable-composition-functions-extra-resources=false}'"
```
The preceding Helm command installs Crossplane with the extra resources
feature flag disabled. Confirm you have disabled composition functions by
looking for a log line:
```shell {copy-lines="1"}
kubectl -n crossplane-system logs -l app=crossplane
{"level":"info","ts":1674535093.36186,"logger":"crossplane","msg":"Beta feature enabled","flag":"EnableBetaCompositionFunctionsExtraResources"}
```
If you don't see the log line emitted when Crossplane starts, you have disabled
__extra resources__ for composition functions, which means requests by functions for __extra
resources__ are just ignored.

74
content/v1.19/concepts/composition-revisions.md → content/v1.16/concepts/composition-revisions.md
View File

@ -16,10 +16,10 @@ database configuration of an Azure MySQL Server and a few firewall rules. The
`Composition` contains the 'base' configuration for the MySQL server and the
firewall rules that are extended by the configuration for the `PlatformDB`.
A `Composition` is associated with multiple XRs that make use of it. You might
define a `Composition` named `big-platform-db` that's used by ten different
`PlatformDB` XRs. Usually, in the interest of self-service, the `Composition`
is managed by a different team from the actual `PlatformDB` XRs. For example
A `Composition` is associated with multiple XRs that make use of it. You might
define a `Composition` named `big-platform-db` that's used by ten different
`PlatformDB` XRs. Usually, in the interest of self-service, the `Composition`
is managed by a different team from the actual `PlatformDB` XRs. For example
the `Composition` may be written and maintained by a platform team member,
while individual application teams create `PlatformDB` XRs that use said
`Composition`.
@ -130,9 +130,9 @@ spec:
This tutorial discusses how CompositionRevisions work and how they manage Composite Resource
(XR) updates. This starts with a `Composition` and `CompositeResourceDefinition` (XRD) that defines a `MyVPC`
resource and continues with creating multiple XRs to observe different upgrade paths. Crossplane will
assign different CompositionRevisions to the created composite resources each time the composition is updated.
assign different CompositionRevisions to the created composite resources each time the composition is updated.
### Preparation
### Preparation
##### Install Crossplane
Install Crossplane v1.11.0 or later and wait until the Crossplane pods are running.
```shell
@ -164,25 +164,17 @@ spec:
compositeTypeRef:
apiVersion: aws.example.upbound.io/v1alpha1
kind: MyVPC
mode: Pipeline
pipeline:
- step: patch-and-transform
functionRef:
name: function-patch-and-transform
input:
apiVersion: pt.fn.crossplane.io/v1beta1
kind: Resources
resources:
- name: my-vpc
base:
apiVersion: ec2.aws.upbound.io/v1beta1
kind: VPC
spec:
forProvider:
region: us-west-1
cidrBlock: 192.168.0.0/16
enableDnsSupport: true
enableDnsHostnames: true
resources:
- base:
apiVersion: ec2.aws.upbound.io/v1beta1
kind: VPC
spec:
forProvider:
region: us-west-1
cidrBlock: 192.168.0.0/16
enableDnsSupport: true
enableDnsHostnames: true
name: my-vcp
```
Apply the example XRD.
@ -325,7 +317,7 @@ The `vpc-staging` XR label doesn't match any existing Composition Revisions.
### Create new Composition revisions
Crossplane creates a new CompositionRevision when a Composition is created or updated. Label and annotation changes will
also trigger a new CompositionRevision.
also trigger a new CompositionRevision.
#### Update the Composition label
Update the `Composition` label to `channel: staging`:
@ -384,25 +376,17 @@ spec:
compositeTypeRef:
apiVersion: aws.example.upbound.io/v1alpha1
kind: MyVPC
mode: Pipeline
pipeline:
- step: patch-and-transform
functionRef:
name: function-patch-and-transform
input:
apiVersion: pt.fn.crossplane.io/v1beta1
kind: Resources
resources:
- name: my-vpc
base:
apiVersion: ec2.aws.upbound.io/v1beta1
kind: VPC
spec:
forProvider:
region: us-west-1
cidrBlock: 192.168.0.0/16
enableDnsSupport: false
enableDnsHostnames: true
resources:
- base:
apiVersion: ec2.aws.upbound.io/v1beta1
kind: VPC
spec:
forProvider:
region: us-west-1
cidrBlock: 192.168.0.0/16
enableDnsSupport: false
enableDnsHostnames: true
name: my-vcp
```
Expected Output:

1421
content/v1.16/concepts/compositions.md Normal file
View File

File diff suppressed because it is too large Load Diff

375
content/v1.20/concepts/connection-details.md → content/v1.16/concepts/connection-details.md
View File

@ -9,8 +9,8 @@ Using connection details in Crossplane requires the following components:
* Defining the `writeConnectionSecretsToNamespace` value in the [Composition]({{<ref "/master/concepts/compositions#composite-resource-combined-secret">}}).
* Define the `writeConnectionSecretToRef` name and namespace for each resource in the
[Composition]({{<ref "/master/concepts/compositions#composed-resource-secrets">}}).
* Define the list of secret keys produced by each composed resource with in the
[Composition]({{<ref "/master/concepts/compositions">}}).
* Define the list of secret keys produced by each composed resource with `connectionDetails` in the
[Composition]({{<ref "./compositions#define-secret-keys">}}).
* Optionally, define the `connectionSecretKeys` in a
[CompositeResourceDefinition]({{<ref "/master/concepts/composite-resource-definitions#manage-connection-secrets">}}).
@ -49,7 +49,7 @@ All the following examples use the same set of Compositions,
CompositeResourceDefinitions and Claims.
All examples rely on
[provider-aws-iam](https://github.com/crossplane-contrib/provider-upjet-aws)
[Upbound provider-aws-iam](https://marketplace.upbound.io/providers/upbound/provider-aws-iam/)
to create resources.
{{<expand "Reference Composition" >}}
@ -63,95 +63,73 @@ spec:
compositeTypeRef:
apiVersion: example.org/v1alpha1
kind: XSecretTest
mode: Pipeline
pipeline:
- step: patch-and-transform
functionRef:
name: function-patch-and-transform
input:
apiVersion: pt.fn.crossplane.io/v1beta1
kind: Resources
resources:
- name: key
base:
apiVersion: iam.aws.upbound.io/v1beta1
kind: AccessKey
spec:
forProvider:
userSelector:
matchControllerRef: true
writeConnectionSecretToRef:
namespace: docs
name: key1
connectionDetails:
- name: user
type: FromConnectionSecretKey
resources:
- name: key
base:
apiVersion: iam.aws.upbound.io/v1beta1
kind: AccessKey
spec:
forProvider:
userSelector:
matchControllerRef: true
writeConnectionSecretToRef:
namespace: docs
name: key1
connectionDetails:
- fromConnectionSecretKey: username
- fromConnectionSecretKey: password
- fromConnectionSecretKey: attribute.secret
- fromConnectionSecretKey: attribute.ses_smtp_password_v4
patches:
- fromFieldPath: "metadata.uid"
toFieldPath: "spec.writeConnectionSecretToRef.name"
transforms:
- type: string
string:
fmt: "%s-secret1"
- name: user
base:
apiVersion: iam.aws.upbound.io/v1beta1
kind: User
spec:
forProvider: {}
- name: user2
base:
apiVersion: iam.aws.upbound.io/v1beta1
kind: User
metadata:
labels:
docs.crossplane.io: user
spec:
forProvider: {}
- name: key2
base:
apiVersion: iam.aws.upbound.io/v1beta1
kind: AccessKey
spec:
forProvider:
userSelector:
matchLabels:
docs.crossplane.io: user
writeConnectionSecretToRef:
namespace: docs
name: key2
connectionDetails:
- name: key2-user
fromConnectionSecretKey: username
- name: password
type: FromConnectionSecretKey
- name: key2-password
fromConnectionSecretKey: password
- name: key
type: FromConnectionSecretKey
- name: key2-secret
fromConnectionSecretKey: attribute.secret
- name: smtp
type: FromConnectionSecretKey
- name: key2-smtp
fromConnectionSecretKey: attribute.ses_smtp_password_v4
patches:
- fromFieldPath: "metadata.uid"
toFieldPath: "spec.writeConnectionSecretToRef.name"
transforms:
- type: string
string:
type: Format
fmt: "%s-secret1"
- name: user
base:
apiVersion: iam.aws.upbound.io/v1beta1
kind: User
spec:
forProvider: {}
- name: user2
base:
apiVersion: iam.aws.upbound.io/v1beta1
kind: User
metadata:
labels:
docs.crossplane.io: user
spec:
forProvider: {}
- name: key2
base:
apiVersion: iam.aws.upbound.io/v1beta1
kind: AccessKey
spec:
forProvider:
userSelector:
matchLabels:
docs.crossplane.io: user
writeConnectionSecretToRef:
namespace: docs
name: key2
connectionDetails:
- name: key2-user
type: FromConnectionSecretKey
fromConnectionSecretKey: username
- name: key2-password
type: FromConnectionSecretKey
fromConnectionSecretKey: password
- name: key2-secret
type: FromConnectionSecretKey
fromConnectionSecretKey: attribute.secret
- name: key2-smtp
type: FromConnectionSecretKey
fromConnectionSecretKey: attribute.ses_smtp_password_v4
patches:
- fromFieldPath: "metadata.uid"
toFieldPath: "spec.writeConnectionSecretToRef.name"
transforms:
- type: string
string:
type: Format
fmt: "%s-secret2"
patches:
- fromFieldPath: "metadata.uid"
toFieldPath: "spec.writeConnectionSecretToRef.name"
transforms:
- type: string
string:
fmt: "%s-secret2"
```
{{</expand >}}
@ -306,36 +284,28 @@ apiVersion: apiextensions.crossplane.io/v1
kind: Composition
spec:
writeConnectionSecretsToNamespace: other-namespace
mode: Pipeline
pipeline:
- step: patch-and-transform
functionRef:
name: function-patch-and-transform
input:
apiVersion: pt.fn.crossplane.io/v1beta1
kind: Resources
resources:
- name: key1
base:
apiVersion: iam.aws.upbound.io/v1beta1
kind: AccessKey
spec:
forProvider:
# Removed for brevity
writeConnectionSecretToRef:
namespace: docs
name: key1-secret
- name: key2
base:
apiVersion: iam.aws.upbound.io/v1beta1
kind: AccessKey
spec:
forProvider:
# Removed for brevity
writeConnectionSecretToRef:
namespace: docs
name: key2-secret
# Removed for brevity
resources:
- name: key1
base:
apiVersion: iam.aws.upbound.io/v1beta1
kind: AccessKey
spec:
forProvider:
# Removed for brevity
writeConnectionSecretToRef:
namespace: docs
name: key1-secret
- name: key2
base:
apiVersion: iam.aws.upbound.io/v1beta1
kind: AccessKey
spec:
forProvider:
# Removed for brevity
writeConnectionSecretToRef:
namespace: docs
name: key2-secret
# Removed for brevity
```
After applying a Claim, view the Kubernetes secrets to see three secret objects
@ -394,39 +364,23 @@ apiVersion: apiextensions.crossplane.io/v1
kind: Composition
spec:
writeConnectionSecretsToNamespace: other-namespace
mode: Pipeline
pipeline:
- step: patch-and-transform
functionRef:
name: function-patch-and-transform
input:
apiVersion: pt.fn.crossplane.io/v1beta1
kind: Resources
resources:
- name: key
base:
apiVersion: iam.aws.upbound.io/v1beta1
kind: AccessKey
spec:
forProvider:
# Removed for brevity
writeConnectionSecretToRef:
namespace: docs
name: key1
connectionDetails:
- name: user
type: FromConnectionSecretKey
fromConnectionSecretKey: username
- name: password
type: FromConnectionSecretKey
fromConnectionSecretKey: password
- name: key
type: FromConnectionSecretKey
fromConnectionSecretKey: attribute.secret
- name: smtp
type: FromConnectionSecretKey
fromConnectionSecretKey: attribute.ses_smtp_password_v4
# Removed for brevity
resources:
- name: key
base:
apiVersion: iam.aws.upbound.io/v1beta1
kind: AccessKey
spec:
forProvider:
# Removed for brevity
writeConnectionSecretToRef:
namespace: docs
name: key1
connectionDetails:
- fromConnectionSecretKey: username
- fromConnectionSecretKey: password
- fromConnectionSecretKey: attribute.secret
- fromConnectionSecretKey: attribute.ses_smtp_password_v4
# Removed for brevity
```
After applying a Claim the composite resource secret object contains the list of
@ -464,39 +418,28 @@ apiVersion: apiextensions.crossplane.io/v1
kind: Composition
spec:
writeConnectionSecretsToNamespace: other-namespace
mode: Pipeline
pipeline:
- step: patch-and-transform
functionRef:
name: function-patch-and-transform
input:
apiVersion: pt.fn.crossplane.io/v1beta1
kind: Resources
resources:
- name: key
base:
kind: AccessKey
spec:
# Removed for brevity
writeConnectionSecretToRef:
namespace: docs
name: key1
connectionDetails:
- name: user
type: FromConnectionSecretKey
fromConnectionSecretKey: username
- name: key2
base:
kind: AccessKey
spec:
# Removed for brevity
writeConnectionSecretToRef:
namespace: docs
name: key2
connectionDetails:
- name: key2-user
type: FromConnectionSecretKey
fromConnectionSecretKey: username
resources:
- name: key
base:
kind: AccessKey
spec:
# Removed for brevity
writeConnectionSecretToRef:
namespace: docs
name: key1
connectionDetails:
- fromConnectionSecretKey: username
- name: key2
base:
kind: AccessKey
spec:
# Removed for brevity
writeConnectionSecretToRef:
namespace: docs
name: key2
connectionDetails:
- name: key2-user
fromConnectionSecretKey: username
```
The secret object contains both keys,
@ -534,10 +477,11 @@ the secret key names to create. Crossplane only adds the keys listed to the
combined secret.
{{<hint "warning">}}
When changing the {{<hover label="xrd" line="4">}}connectionSecretKeys{{</hover>}} of an XRD the change isn't immediately reflected.
You have two options to change the keys in the combined secret object.
- Delete and recreate the XRD. This only makes sense if the XRD isn't used as it leads to the deletion of XRs.
- Restart the XR reconciler, which can be done by restarting the Crossplane pod.
You can't change the
{{<hover label="xrd" line="4">}}connectionSecretKeys{{</hover>}} of an XRD.
You must delete and
recreate the XRD to change the
{{<hover label="xrd" line="4">}}connectionSecretKeys{{</hover>}}.
{{</hint >}}
For example, an XRD may restrict the secrets to only the
@ -604,39 +548,28 @@ apiVersion: apiextensions.crossplane.io/v1
kind: Composition
spec:
writeConnectionSecretsToNamespace: other-namespace
mode: Pipeline
pipeline:
- step: patch-and-transform
functionRef:
name: function-patch-and-transform
input:
apiVersion: pt.fn.crossplane.io/v1beta1
kind: Resources
resources:
- name: key
base:
kind: AccessKey
spec:
# Removed for brevity
writeConnectionSecretToRef:
namespace: docs
name: key1
connectionDetails:
- name: user
type: FromConnectionSecretKey
fromConnectionSecretKey: username
- name: key2
base:
kind: AccessKey
spec:
# Removed for brevity
writeConnectionSecretToRef:
namespace: docs
name: key2
connectionDetails:
- name: key2-user
type: FromConnectionSecretKey
fromConnectionSecretKey: username
resources:
- name: key
base:
kind: AccessKey
spec:
# Removed for brevity
writeConnectionSecretToRef:
namespace: docs
name: key1
connectionDetails:
- fromConnectionSecretKey: username
- name: key2
base:
kind: AccessKey
spec:
# Removed for brevity
writeConnectionSecretToRef:
namespace: docs
name: key2
connectionDetails:
- name: key2-user
fromConnectionSecretKey: username
```
If a Claim uses a secret, it's stored in the same namespace as the Claim with

483
content/v1.16/concepts/environment-configs.md Normal file
View File

@ -0,0 +1,483 @@
---
title: Environment Configurations
weight: 75
state: alpha
alphaVersion: "1.11"
description: "Environment Configurations or EnvironmentConfigs are an in-memory datastore used in patching Compositions"
---
<!--
TODO: Add Policies
-->
A Crossplane EnvironmentConfig is a cluster scoped
[ConfigMap](https://kubernetes.io/docs/concepts/configuration/configmap/)-like
resource used
by Compositions. Compositions can use the environment to store information from
individual resources or to apply [patches]({{<ref "patch-and-transform">}}).
Crossplane supports multiple EnvironmentConfigs, each acting as a unique
data store.
When Crossplane creates a composite resource, Crossplane merges all the
EnvironmentConfigs referenced in the associated Composition and creates a unique
in-memory environment for that composite resource.
The composite resource can read and write data to their unique
in-memory environment.
{{<hint "important" >}}
The in-memory environment is unique to each composite resource.
A composite resource can't read data in another composite resource's
environment.
{{< /hint >}}
## Enable EnvironmentConfigs
EnvironmentConfigs are an alpha feature. Alpha features aren't enabled by
default.
Enable EnvironmentConfig support by
[changing the Crossplane pod setting]({{<ref "./pods#change-pod-settings">}})
and enabling
{{<hover label="deployment" line="12">}}--enable-environment-configs{{</hover>}}
argument.
```yaml {label="deployment",copy-lines="12"}
$ kubectl edit deployment crossplane --namespace crossplane-system
apiVersion: apps/v1
kind: Deployment
spec:
# Removed for brevity
template:
spec:
containers:
- args:
- core
- start
- --enable-environment-configs
```
{{<hint "tip" >}}
The [Crossplane install guide]({{<ref "../software/install#feature-flags">}})
describes enabling feature flags like
{{<hover label="deployment" line="12">}}--enable-environment-configs{{</hover>}}
with Helm.
{{< /hint >}}
<!-- vale Google.Headings = NO -->
## Create an EnvironmentConfig
<!-- vale Google.Headings = YES -->
An {{<hover label="env1" line="2">}}EnvironmentConfig{{</hover>}} has a single
object field,
{{<hover label="env1" line="5">}}data{{</hover>}}.
An EnvironmentConfig supports any data inside the
{{<hover label="env1" line="5">}}data{{</hover>}} field.
Here an example
{{<hover label="env1" line="2">}}EnvironmentConfig{{</hover>}}.
```yaml {label="env1"}
apiVersion: apiextensions.crossplane.io/v1alpha1
kind: EnvironmentConfig
metadata:
name: example-environment
data:
locations:
us: us-east-2
eu: eu-north-1
key1: value1
key2: value2
key3:
- item1
- item2
```
<!-- vale Google.Headings = NO -->
## Select an EnvironmentConfig
<!-- vale Google.Headings = YES -->
Select the EnvironmentConfigs to use
inside a Composition's
{{<hover label="comp" line="6">}}environment{{</hover>}} field.
The {{<hover label="comp" line="7">}}environmentConfigs{{</hover>}} field is a
list of environments this Composition can use.
Select an environment by
{{<hover label="comp" line="8">}}Reference{{</hover>}} or
by
{{<hover label="comp" line="11">}}Selector{{</hover>}}.
A
{{<hover label="comp" line="8">}}Reference{{</hover>}}
selects an environment by
{{<hover label="comp" line="10">}}name{{</hover>}}.
The
{{<hover label="comp" line="11">}}Selector{{</hover>}} selects an environment
based on the
{{<hover label="comp" line="13">}}Labels{{</hover>}} applied to the environment.
```yaml {label="comp",copy-lines="none"}
apiVersion: apiextensions.crossplane.io/v1
kind: Composition
metadata:
name: example-composition
spec:
environment:
environmentConfigs:
- type: Reference
ref:
name: example-environment
- type: Selector
selector:
matchLabels:
# Removed for brevity
```
If a Composition uses multiple
{{<hover label="comp" line="7">}}environmentConfigs{{</hover>}}
Crossplane merges them together in the order they're listed.
{{<hint "note" >}}
If multiple
{{<hover label="comp" line="7">}}environmentConfigs{{</hover>}}
use the same key, the Composition uses the value of the last environment listed.
{{</hint >}}
### Select by name
Select an environment by name with
{{<hover label="byName" line="8">}}type: Reference{{</hover>}}.
Define the
{{<hover label="byName" line="9">}}ref{{</hover>}} object and the
{{<hover label="byName" line="10">}}name{{</hover>}} matching the exact name of
the environment.
For example, select the
{{<hover label="byName" line="7">}}environmentConfig{{</hover>}}
named
{{<hover label="byName" line="10">}}example-environment{{</hover>}}
```yaml {label="byName",copy-lines="all"}
apiVersion: apiextensions.crossplane.io/v1
kind: Composition
metadata:
name: example-composition
spec:
environment:
environmentConfigs:
- type: Reference
ref:
name: example-environment
```
### Select by label
Select an environment by labels with a
{{<hover label="byLabel" line="8">}}type: Selector{{</hover>}}.
Define the {{<hover label="byLabel" line="9">}}selector{{</hover>}} object.
The
{{<hover label="byLabel" line="10">}}matchLabels{{</hover>}} object contains a
list of labels to match on.
Selecting a label requires matching both the label
{{<hover label="byLabel" line="11">}}key{{</hover>}}
and the value of key.
When matching the label's value, provide an exact value with a
{{<hover label="byLabel" line="12">}}type: Value{{</hover>}} and provide the value
to match in the
{{<hover label="byLabel" line="13">}}value{{</hover>}} field.
Crossplane can also match a label's value based on an input in the composite
resource. Use
{{<hover label="byLabel" line="15">}}type: FromCompositeFieldPath{{</hover>}}
and provide the field to match in the
{{<hover label="byLabel" line="16">}}valueFromFieldPath{{</hover>}} field.
```yaml {label="byLabel",copy-lines="all"}
apiVersion: apiextensions.crossplane.io/v1
kind: Composition
metadata:
name: example-composition
spec:
environment:
environmentConfigs:
- type: Selector
selector:
matchLabels:
- key: my-label-key
type: Value
value: my-label-value
- key: my-label-key
type: FromCompositeFieldPath
valueFromFieldPath: spec.parameters.deploy
resources:
# Removed for brevity
```
#### Manage selector results
Selecting environments by labels may return more than one environment.
The Composition sorts all the results by the name of the environments and
only uses the first environment in the sorted list.
Set the {{<hover label="selectResults" line="10">}}mode{{</hover>}} as
{{<hover label="selectResults" line="10">}}mode: Multiple{{</hover>}} to return
all matched environments. Use
{{<hover label="selectResults" line="19">}}mode: Single{{</hover>}} to
return a single environment.
{{<hint "note" >}}
Sorting and the selection
{{<hover label="selectResults" line="10">}}mode{{</hover>}}
only applies to a single
{{<hover label="selectResults" line="8">}}type: Selector{{</hover>}}.
This doesn't change how Compositions merge multiple
{{<hover label="selectResults" line="7">}}environmentConfigs{{</hover>}}.
{{< /hint >}}
```yaml {label="selectResults"}
apiVersion: apiextensions.crossplane.io/v1
kind: Composition
metadata:
name: example-composition
spec:
environment:
environmentConfigs:
- type: Selector
selector:
mode: Multiple
matchLabels:
- key: my-label-key
type: Value
value: my-label-value
- key: my-label-key
type: FromCompositeFieldPath
valueFromFieldPath: spec.parameters.deploy
- type: Selector
selector:
mode: Single
matchLabels:
- key: my-other-label-key
type: Value
value: my-other-label-value
- key: my-other-label-key
type: FromCompositeFieldPath
valueFromFieldPath: spec.parameters.deploy
```
When using
{{<hover label="maxMatch" line="10">}}mode: Multiple{{</hover>}} limit the
number of returned environments with
{{<hover label="maxMatch" line="11">}}maxMatch{{</hover>}} and define the
maximum number of environments returned.
Use `minMatch` and define the minimum
number of environments returned.
The Composition sorts the returned environments alphabetically by name. Sort the
environments on a different field with
{{<hover label="maxMatch" line="12">}}sortByFieldPath{{</hover>}} and define
the field to sort by.
```yaml {label="maxMatch"}
apiVersion: apiextensions.crossplane.io/v1
kind: Composition
metadata:
name: example-composition
spec:
environment:
environmentConfigs:
- type: Selector
selector:
mode: Multiple
maxMatch: 4
sortByFieldPath: metadata.annotations[sort.by/weight]
matchLabels:
- key: my-label-key
type: Value
value: my-label-value
- key: my-label-key
type: FromCompositeFieldPath
valueFromFieldPath: spec.parameters.deploy
```
The environments selected by
{{<hover label="maxMatch" line="18">}}matchLabels{{</hover>}} are then merged
into any other environments listed in the
{{<hover label="maxMatch" line="7">}}environmentConfigs{{</hover>}}.
#### Optional selector labels
By default, Crossplane issues an error if a
{{<hover label="byLabelOptional" line="16">}}valueFromFieldPath{{</hover>}}
field doesn't exist in the composite resource.
Add
{{<hover label="byLabelOptional" line="17">}}fromFieldPathPolicy{{</hover>}}
as {{<hover label="byLabelOptional" line="17">}}Optional{{</hover>}}
to ignore a field if it doesn't exist.
```yaml {label="byLabelOptional",copy-lines="all"}
apiVersion: apiextensions.crossplane.io/v1
kind: Composition
metadata:
name: example-composition
spec:
environment:
environmentConfigs:
- type: Selector
selector:
matchLabels:
- key: my-first-label-key
type: Value
value: my-first-label-value
- key: my-second-label-key
type: FromCompositeFieldPath
valueFromFieldPath: spec.parameters.deploy
fromFieldPathPolicy: Optional
resources:
# Removed for brevity
```
Set a default value for an optional label by setting the default
{{<hover label="byLabelOptionalDefault" line="15">}}value{{</hover>}} for the
{{<hover label="byLabelOptionalDefault" line="14">}}key{{</hover>}} first, then
define the
{{<hover label="byLabelOptionalDefault" line="20">}}Optional{{</hover>}} label.
For example, this Composition defines
{{<hover label="byLabelOptionalDefault" line="16">}}value: my-default-value{{</hover>}}
for the key {{<hover label="byLabelOptionalDefault" line="14">}}my-second-label-key{{</hover>}}.
If the label
{{<hover label="byLabelOptionalDefault" line="17">}}my-second-label-key{{</hover>}}
exists, Crossplane uses the value from the label instead.
```yaml {label="byLabelOptionalDefault",copy-lines="all"}
apiVersion: apiextensions.crossplane.io/v1
kind: Composition
metadata:
name: example-composition
spec:
environment:
environmentConfigs:
- type: Selector
selector:
matchLabels:
- key: my-first-label-key
type: Value
value: my-label-value
- key: my-second-label-key
type: Value
value: my-default-value
- key: my-second-label-key
type: FromCompositeFieldPath
valueFromFieldPath: spec.parameters.deploy
fromFieldPathPolicy: Optional
resources:
# Removed for brevity
```
{{<hint "warning" >}}
Crossplane applies values in order. The value of the last key defined always takes precedence.
Defining the default value _after_ the label always overwrites the label
value.
{{< /hint >}}
## Patching with EnvironmentConfigs
When Crossplane creates or updates a composite resource, Crossplane
merges all the specified EnvironmentConfigs into an in-memory environment.
The composite resource can read or write data between the EnvironmentConfig and
composite resource or between the EnvironmentConfig and individual resources
defined inside the composite resource.
{{<hint "tip" >}}
Read about EnvironmentConfig patch types in the
[Patch and Transform]({{<ref "./patch-and-transform">}}) documentation.
{{< /hint >}}
<!-- these two sections are duplicated in the compositions doc with different header depths -->
### Patch a composite resource
To patch the composite resource use
{{< hover label="xrpatch" line="7">}}patches{{</hover>}} inside of the
{{< hover label="xrpatch" line="5">}}environment{{</hover>}}.
Use the
{{< hover label="xrpatch" line="5">}}ToCompositeFieldPath{{</hover>}} to copy
data from the in-memory environment to the composite resource.
Use the
{{< hover label="xrpatch" line="5">}}FromCompositeFieldPath{{</hover>}} to copy
data from the composite resource to the in-memory environment.
```yaml {label="xrpatch",copy-lines="none"}
apiVersion: apiextensions.crossplane.io/v1
kind: Composition
# Removed for Brevity
spec:
environment:
# Removed for Brevity
patches:
- type: ToCompositeFieldPath
fromFieldPath: tags
toFieldPath: metadata.labels[envTag]
- type: FromCompositeFieldPath
fromFieldPath: metadata.name
toFieldPath: newEnvironmentKey
```
Individual resources can use any data written to the in-memory environment.
### Patch an individual resource
To patch an individual resource, inside the
{{<hover label="envpatch" line="16">}}patches{{</hover>}} of the
resource, use
{{<hover label="envpatch" line="17">}}ToEnvironmentFieldPath{{</hover>}} to copy
data from the resource to the in-memory environment.
Use {{<hover label="envpatch" line="20">}}FromEnvironmentFieldPath{{</hover>}}
to copy data to the resource from the in-memory environment.
```yaml {label="envpatch",copy-lines="none"}
apiVersion: apiextensions.crossplane.io/v1
kind: Composition
# Removed for Brevity
spec:
environment:
# Removed for Brevity
resources:
# Removed for Brevity
- name: vpc
base:
apiVersion: ec2.aws.upbound.io/v1beta1
kind: VPC
spec:
forProvider:
cidrBlock: 172.16.0.0/16
patches:
- type: ToEnvironmentFieldPath
fromFieldPath: status.atProvider.id
toFieldPath: vpcId
- type: FromEnvironmentFieldPath
fromFieldPath: tags
toFieldPath: spec.forProvider.tags
```
The [Patch and Transform]({{<ref "./patch-and-transform">}}) documentation has
more information on patching individual resources.
<!-- End duplicated content -->

86
content/v1.16/concepts/image-configs.md Normal file
View File

@ -0,0 +1,86 @@
---
title: Image Configs
weight: 400
description: "Image Configs is an API for centralized control of the configuration of Crossplane package images."
---
<!-- vale write-good.Passive = NO -->
`ImageConfig` is an API for centralized control over the configuration of
Crossplane package images. It allows you to configure package manager behavior
for images globally, without needing to be referenced by other objects.
## Configuring a pull secret
You can use `ImageConfig` to inject a pull secret into the Crossplane package
manager registry client whenever it interacts with the registry, such as for
dependency resolution or image pulls.
In the following example, the `ImageConfig` resource named `acme-packages` is
configured to inject the pull secret named `acme-registry-credentials` whenever
it needs to interact with the registry for images with the prefix
`registry1.com/acme-co/`.
```yaml
apiVersion: pkg.crossplane.io/v1beta1
kind: ImageConfig
metadata:
name: acme-packages
spec:
matchImages:
- type: Prefix
prefix: registry1.com/acme-co/
registry:
authentication:
pullSecretRef:
name: acme-registry-credentials
```
`spec.registry.authentication.pullSecretRef` is a reference to the pull secret
that should be injected into the registry client. The secret must be of type
`kubernetes.io/dockerconfigjson` and must be in the Crossplane installation
namespace, typically `crossplane-system`. One can create the secret using the
following command:
```shell
kubectl -n crossplane-system create secret docker-registry acme-registry-credentials --docker-server=registry1.com --docker-username=<user> --docker-password=<password>
```
### Matching image references
`spec.matchImages` is a list of image references that the `ImageConfig` applies
to. Each item in the list specifies the type and configuration of the image
reference to match. The only supported type is `Prefix`, which matches the
prefix of the image reference. No wildcards are supported. The `type` defaults
to `Prefix` and can be omitted.
When there are multiple `ImageConfigs` matching an image reference, the one
with the longest matching prefix is selected. If there are multiple
`ImageConfigs` with the same longest matching prefix, one of them is selected
arbitrarily. Please note that this situation occurs only if there are
overlapping prefixes in the `matchImages` lists of different `ImageConfig`
resources, which should be avoided.
### Debugging
When the package manager selects an `ImageConfig` for a package, it throws an
event with the reason `ImageConfigSelection` and the name of the selected
`ImageConfig` and injected pull secret. You can find these events both on the
package and package revision resources.
For example, the following event indicates that the `ImageConfig` named
`acme-packages` was selected for the configuration named `acme-configuration-foo`:
```shell
$ kubectl describe configuration acme-configuration-foo
...
Events:
Type Reason Age From Message
---- ------ ---- ---- -------
Normal ImageConfigSelection 45s packages/configuration.pkg.crossplane.io Selected pullSecret "acme-registry-credentials" from ImageConfig "acme-packages" for registry authentication
```
If you can't find the expected event, ensure the prefix of the image reference
matches the `matchImages` list of any `ImageConfig` resources in the cluster.
<!-- vale write-good.Passive = YES -->

110
content/v1.19/concepts/managed-resources.md → content/v1.16/concepts/managed-resources.md
View File

@ -15,9 +15,9 @@ external object inside the Provider an _external resource_.
{{< /hint >}}
Examples of managed resources include:
* Amazon AWS EC2 `Instance` defined in [provider-upjet-aws](https://github.com/crossplane-contrib/provider-upjet-aws).
* Google Cloud GKE `Cluster` defined in [provider-upjet-gcp](https://github.com/crossplane-contrib/provider-upjet-gcp).
* Microsoft Azure PostgreSQL `Database` defined in [provider-upjet-azure](https://github.com/crossplane-contrib/provider-upjet-azure).
* Amazon AWS EC2 [`Instance`](https://marketplace.upbound.io/providers/upbound/provider-aws/latest/resources/ec2.aws.upbound.io/Instance/v1beta1)
* Google Cloud GKE [`Cluster`](https://marketplace.upbound.io/providers/upbound/provider-gcp/latest/resources/container.gcp.upbound.io/Cluster/v1beta1)
* Microsoft Azure PostgreSQL [`Database`](https://marketplace.upbound.io/providers/upbound/provider-azure/latest/resources/dbforpostgresql.azure.upbound.io/Database/v1beta1)
{{< hint "tip" >}}
@ -35,7 +35,7 @@ Provider also define the available settings of a managed resource.
Each managed resource is a unique API endpoint with their own
group, kind and version.
For example [provider-upjet-aws](https://github.com/crossplane-contrib/provider-upjet-aws)
For example the [Upbound AWS Provider](https://marketplace.upbound.io/providers/upbound/provider-aws/latest/)
defines the {{<hover label="gkv" line="2">}}Instance{{</hover>}} kind from the
group {{<hover label="gkv" line="1">}}ec2.aws.upbound.io{{</hover>}}
@ -183,6 +183,12 @@ spec:
Matching by selector is the most flexible matching method.
{{<hint "note" >}}
The [Compositions]({{<ref "./compositions">}}) section covers the
`matchControllerRef` selector.
{{</hint >}}
Use `matchLabels` to match the labels applied to a resource. For example, this
Subnet resource only matches VPC resources with the label
`my-label: label-value`.
@ -198,100 +204,6 @@ spec:
my-label: label-value
```
##### Matching by controller reference
Matching a controller reference ensures that the matching resource is part of
the same composite resource.
{{<hint "note" >}}
Learn more about composite resources in the
[Composite Resources]({{<ref "./composite-resources">}}) section.
{{</hint >}}
Matching only a controller reference simplifies the matching process without
requiring labels or more information.
For example, creating an AWS `InternetGateway` requires a `VPC`.
The `InternetGateway` could match a label, but every VPC created by this
Composition shares the same label.
Using `matchControllerRef` matches only the VPC created in the same composite
resource that created the `InternetGateway`.
```yaml {label="controller1",copy-lines="none"}
apiVersion: pt.fn.crossplane.io/v1beta1
kind: Resources
resources:
- base:
apiVersion: ec2.aws.upbound.io/v1beta1
kind: VPC
name: my-vpc
spec:
forProvider:
# Removed for brevity
- base:
apiVersion: ec2.aws.upbound.io/v1beta1
kind: InternetGateway
name: my-gateway
spec:
forProvider:
vpcIdSelector:
matchControllerRef: true
```
Resources can match both labels and a controller reference to match a specific
resource in the larger composite resource.
For example, this Composition creates two `VPC` resources, but the
`InternetGateway` must match only one.
Applying a `label` to the second `VPC` allows the `InternetGateway` to match the
label `type: internet` and only match objects in the same composite resource
with `matchControllerRef`.
```yaml {label="controller2",copy-lines="none"}
apiVersion: pt.fn.crossplane.io/v1beta1
kind: Resources
resources:
- name: my-first-vpc
base:
apiVersion: ec2.aws.upbound.io/v1beta1
kind: VPC
metadata:
labels:
type: backend
spec:
forProvider:
# Removed for brevity
- name: my-second-vpc
base:
apiVersion: ec2.aws.upbound.io/v1beta1
kind: VPC
metadata:
labels:
type: internet
spec:
forProvider:
# Removed for brevity
- name: my-gateway
base:
apiVersion: ec2.aws.upbound.io/v1beta1
kind: InternetGateway
spec:
forProvider:
vpcIdSelector:
matchControllerRef: true
matchLabels:
type: internet
```
{{<hint "note" >}}
These examples use Function Patch and Transform. Learn more about functions and
Compositions in the [Compositions]({{<ref "./compositions">}}) section.
{{</hint >}}
#### Immutable fields
@ -529,7 +441,7 @@ Crossplane stores these details in a Kubernetes Secret object specified by the
`writeConnectionSecretToRef` values.
For example, when creating an AWS RDS database instance with the Crossplane
[community AWS provider](https://github.com/crossplane-contrib/provider-aws)
[community AWS provider](https://marketplace.upbound.io/providers/crossplane-contrib/provider-aws/v0.40.0)
generates an endpoint, password, port and username data. The Provider saves
these variables in the Kubernetes secret
{{<hover label="secretname" line="9" >}}rds-secret{{</hover>}}, referenced by

111
content/v2.0-preview/packages/configurations.md → content/v1.16/concepts/packages.md
View File

@ -1,27 +1,28 @@
---
title: Configurations
title: Configuration Packages
description: "Packages combine multiple Crossplane resources into a single, portable, OCI image."
altTitle: "Crossplane Packages"
weight: 200
---
A _Configuration_ package is an
[OCI container image](https://opencontainers.org/) containing a collection of
[Compositions]({{<ref "../composition/compositions" >}}),
[Composite Resource Definitions]({{<ref "../composition/composite-resource-definitions" >}})
[OCI container images](https://opencontainers.org/) containing a collection of
[Compositions]({{<ref "./compositions" >}}),
[Composite Resource Definitions]({{<ref "./composite-resource-definitions" >}})
and any required [Providers]({{<ref "./providers">}}) or
[Functions]({{<ref "./functions" >}}).
[Functions]({{<ref "./composition-functions" >}}).
Configuration packages make your Crossplane configuration fully portable.
{{<hint "important" >}}
Crossplane Providers and Functions are also Crossplane packages.
Crossplane [Providers]({{<ref "./providers">}}) and
[Functions]({{<ref "./composition-functions">}}) are also Crossplane packages.
This document describes how to install and manage configuration packages.
Refer to the
[Provider]({{<ref "./providers">}}) and
[Functions]({{<ref "./functions">}}) chapters for
[Composition Functions]({{<ref "./composition-functions">}}) chapters for
details on their usage of packages.
{{< /hint >}}
@ -33,39 +34,26 @@ the {{<hover line="6" label="install">}}spec.package{{</hover>}} value to the
location of the configuration package.
{{< hint "important" >}}
Beginning with Crossplane version 1.20.0 Crossplane uses the [crossplane-contrib](https://github.com/orgs/crossplane-contrib/packages) GitHub Container Registry at `xpkg.crossplane.io` by default for downloading and
Beginning with Crossplane version 1.15.0 Crossplane uses the Upbound Marketplace
Crossplane package registry at `xpkg.upbound.io` by default for downloading and
installing packages.
Specify the full domain name with the `package` or change the default Crossplane
registry with the `--registry` flag on the [Crossplane pod]({{<ref "../guides/pods">}})
registry with the `--registry` flag on the [Crossplane pod]({{<ref "./pods">}})
{{< /hint >}}
For example to install the
[Getting Started Configuration](https://github.com/crossplane-contrib/configuration-quickstart),
[Upbound AWS reference platform](https://marketplace.upbound.io/configurations/upbound/platform-ref-aws/v0.6.0),
```yaml {label="install"}
apiVersion: pkg.crossplane.io/v1
kind: Configuration
metadata:
name: configuration-quickstart
name: platform-ref-aws
spec:
package: xpkg.crossplane.io/crossplane-contrib/configuration-quickstart:v0.1.0
package: xpkg.upbound.io/upbound/platform-ref-aws:v0.6.0
```
{{<hint "tip" >}}
Crossplane supports installations with image digests instead of tags to get deterministic
and repeatable installations.
```yaml {label="digest"}
apiVersion: pkg.crossplane.io/v1
kind: Configuration
metadata:
name: configuration-quickstart
spec:
package: xpkg.crossplane.io/crossplane-contrib/configuration-quickstart@sha256:ef9795d146190637351a5c5848e0bab5e0c190fec7780f6c426fbffa0cb68358
```
{{< /hint >}}
Crossplane installs the Compositions, Composite Resource Definitions and
Providers listed in the Configuration.
@ -78,19 +66,19 @@ Use the
{{<hover label="helm" line="5" >}}--set configuration.packages{{</hover >}}
argument with `helm install`.
For example, to install the Getting Started configuration,
For example, to install the Upbound AWS reference platform,
```shell {label="helm"}
helm install crossplane \
crossplane-stable/crossplane \
--namespace crossplane-system \
--create-namespace \
--set configuration.packages='{xpkg.crossplane.io/crossplane-contrib/configuration-quickstart:v0.1.0}'
--set configuration.packages='{xpkg.upbound.io/upbound/platform-ref-aws:v0.6.0}'
```
### Install offline
Installing Crossplane packages offline requires a local container registry, such as
Installing Crossplane packages offline requires a local container registry like
[Harbor](https://goharbor.io/) to host the packages. Crossplane only
supports installing packages from a container registry.
@ -114,8 +102,8 @@ View the configuration revisions with
```shell {label="rev",copy-lines="1"}
kubectl get configurationrevisions
NAME HEALTHY REVISION IMAGE STATE DEP-FOUND DEP-INSTALLED AGE
platform-ref-aws-1735d56cd88d True 2 xpkg.crossplane.io/crossplane-contrib/platform-ref-aws:v0.5.0 Active 2 2 46s
platform-ref-aws-3ac761211893 True 1 xpkg.crossplane.io/crossplane-contrib/platform-ref-aws:v0.4.1 Inactive 5m13s
platform-ref-aws-1735d56cd88d True 2 xpkg.upbound.io/upbound/platform-ref-aws:v0.5.0 Active 2 2 46s
platform-ref-aws-3ac761211893 True 1 xpkg.upbound.io/upbound/platform-ref-aws:v0.4.1 Inactive 5m13s
```
Only a single revision is active at a time. The active revision determines the
@ -273,47 +261,6 @@ spec:
# Removed for brevity
```
#### Automatically update dependency versions
Crossplane can automatically upgrade a package's dependency version to the minimum
valid version that satisfies all the constraints. It's an alpha feature that
requires enabling with the `--enable-dependency-version-upgrades` flag.
In some cases, dependency version downgrade is required for proceeding with
installations. Suppose configuration A, which depends on package X with the
constraint`>=v0.0.0`, is installed on the control plane. In this case, the package
manager installs the latest version of package X, such as `v3.0.0`. Later, you decide
to install configuration B, which depends on package X with the constraint `<=v2.0.0`.
Since version `v2.0.0`satisfies both conditions, package X must be downgraded to
allow the installation of configuration B which is disabled by default.
For enabling automatic dependency version downgrades, there is a configuration
option as a helm value `packageManager.enableAutomaticDependencyDowngrade=true`.
Downgrading a package can cause unexpected behavior, therefore, this
option is disabled by default. After enabling this option, the package manager will
automatically downgrade a package's dependency version to the maximum valid version
that satisfies the constraints.
{{<hint "note" >}}
This configuration requires the `--enable-dependency-version-upgrades` flag.
Please check the
[configuration options]({{<ref "../get-started/install#customize-the-crossplane-helm-chart">}})
and
[feature flags]({{<ref "../get-started/install#feature-flags">}})
are available in the
[Crossplane Install]({{<ref "../get-started/install">}})
section for more details.
{{</hint >}}
{{<hint "important" >}}
Enabling automatic dependency downgrades may have unintended consequences, such as:
1) CRDs missing in the downgraded version, possibly leaving orphaned MRs without
controllers to reconcile them.
2) Loss of data if downgraded CRD versions omit fields that were set before.
3) Changes in the CRD storage version, which may prevent package version update.
{{</hint >}}
#### Ignore Crossplane version requirements
A Configuration package may require a specific or minimum Crossplane version
@ -348,7 +295,7 @@ A working configuration reports `Installed` and `Healthy` as `True`.
```shell {label="verify",copy-lines="1"}
kubectl get configuration
NAME INSTALLED HEALTHY PACKAGE AGE
platform-ref-aws True True xpkg.crossplane.io/crossplane-contrib/configuration-quickstart:v0.1.0 54s
platform-ref-aws True True xpkg.upbound.io/upbound/platform-ref-aws:v0.6.0 54s
```
### Manage dependencies
@ -359,13 +306,13 @@ Functions, Providers or other Configurations.
If Crossplane can't meet the dependencies of a Configuration the Configuration
reports `HEALTHY` as `False`.
For example, this installation of the Getting Started Configuration is
For example, this installation of the Upbound AWS reference platform is
`HEALTHY: False`.
```shell {copy-lines="1"}
kubectl get configuration
NAME INSTALLED HEALTHY PACKAGE AGE
platform-ref-aws True False xpkg.crossplane.io/crossplane-contrib/configuration-quickstart:v0.1.0 71s
platform-ref-aws True False xpkg.upbound.io/upbound/platform-ref-aws:v0.6.0 71s
```
To see more information on why the Configuration isn't `HEALTHY` use
@ -379,7 +326,7 @@ Kind: ConfigurationRevision
# Removed for brevity
Spec:
Desired State: Active
Image: xpkg.crossplane.io/crossplane-contrib/configuration-quickstart:v0.1.0
Image: xpkg.upbound.io/upbound/platform-ref-aws:v0.6.0
Revision: 1
Status:
Conditions:
@ -392,7 +339,7 @@ Status:
Events:
Type Reason Age From Message
---- ------ ---- ---- -------
Warning LintPackage 29s (x2 over 29s) packages/configurationrevision.pkg.crossplane.io incompatible Crossplane version: package isn't compatible with Crossplane version (v1.12.0)
Warning LintPackage 29s (x2 over 29s) packages/configurationrevision.pkg.crossplane.io incompatible Crossplane version: package is not compatible with Crossplane version (v1.12.0)
```
The {{<hover label="depend" line="18">}}Events{{</hover>}} show a
@ -463,9 +410,7 @@ metadata:
name: test-configuration
spec:
dependsOn:
- apiVersion: pkg.crossplane.io/v1
kind: Provider
package: xpkg.crossplane.io/crossplane-contrib/provider-aws
- provider: xpkg.upbound.io/crossplane-contrib/provider-aws
version: ">=v0.36.0"
crossplane:
version: ">=v1.12.1-0"
@ -488,11 +433,11 @@ You must ignore any other YAML files with `--ignore=<file_list>`.
For
example, `crossplane xpkg build --package-root=test-directory --ignore=".tmp/*"`.
Including YAML files that aren't Compositions or CompositeResourceDefinitions
isn't supported.
Including YAML files that aren't Compositions or CompositeResourceDefinitions,
including Claims isn't supported.
{{</hint >}}
By default, Crossplane creates a `.xpkg` file of the Configuration name and
By default, Crossplane creates an `.xpkg` file of the Configuration name and
a SHA-256 hash of the package contents.
For example, a {{<hover label="xpkgName" line="2">}}Configuration{{</hover>}}

1726
content/v1.16/concepts/patch-and-transform.md Normal file
View File

File diff suppressed because it is too large Load Diff

2
content/v1.19/concepts/pods.md → content/v1.16/concepts/pods.md
View File

@ -350,7 +350,7 @@ the Helm `values.yml` file or after installation by editing the `Deployment`.
The full list of
[configuration options]({{<ref "../software/install#customize-the-crossplane-helm-chart">}})
and
[feature flags]({{<ref "../software/install#feature-flags">}})
[feature flags]({{<ref "../software/install#customize-the-crossplane-helm-chart">}})
are available in the
[Crossplane Install]({{<ref "../software/install">}})
section.

143
content/v2.0-preview/packages/providers.md → content/v1.16/concepts/providers.md
View File

@ -21,12 +21,16 @@ Examples of providers include:
* [Provider GCP](https://github.com/upbound/provider-gcp)
* [Provider Kubernetes](https://github.com/crossplane-contrib/provider-kubernetes)
{{< hint "tip" >}}
Find more providers in the [Upbound Marketplace](https://marketplace.upbound.io).
{{< /hint >}}
<!-- vale write-good.Passive = NO -->
<!-- "are Managed" isn't passive in this context -->
Providers define every external resource they can create in Kubernetes as a
Kubernetes API endpoint.
These endpoints are
[_Managed Resources_]({{<ref "../managed-resources/managed-resources" >}}).
[_Managed Resources_]({{<ref "managed-resources" >}}).
<!-- vale write-good.Passive = YES -->
@ -44,11 +48,12 @@ Install a Provider with a Crossplane
location of the provider package.
{{< hint "important" >}}
Beginning with Crossplane version 1.20.0 Crossplane uses the [crossplane-contrib](https://github.com/orgs/crossplane-contrib/packages) GitHub Container Registry at `xpkg.crossplane.io` by default for downloading and
Beginning with Crossplane version 1.15.0 Crossplane uses the Upbound Marketplace
Crossplane package registry at `xpkg.upbound.io` by default for downloading and
installing packages.
Specify the full domain name with the `package` or change the default Crossplane
registry with the `--registry` flag on the [Crossplane pod]({{<ref "../guides/pods">}})
registry with the `--registry` flag on the [Crossplane pod]({{<ref "./pods">}})
{{< /hint >}}
For example, to install the
@ -60,7 +65,7 @@ kind: Provider
metadata:
name: provider-aws
spec:
package: xpkg.crossplane.io/crossplane-contrib/provider-aws:v0.39.0
package: xpkg.upbound.io/crossplane-contrib/provider-aws:v0.39.0
```
By default, the Provider pod installs in the same namespace as Crossplane
@ -108,7 +113,7 @@ helm install crossplane \
crossplane-stable/crossplane \
--namespace crossplane-system \
--create-namespace \
--set provider.packages='{xpkg.crossplane.io/crossplane-contrib/provider-aws:v0.39.0}'
--set provider.packages='{xpkg.upbound.io/crossplane-contrib/provider-aws:v0.39.0}'
```
### Install offline
@ -125,20 +130,6 @@ volumes.
Providers support multiple configuration options to change installation related
settings.
{{<hint "tip" >}}
Crossplane supports installations with image digests instead of tags to get deterministic
and repeatable installations.
```yaml {label="digest"}
apiVersion: pkg.crossplane.io/v1
kind: Provider
metadata:
name: provider-aws
spec:
package: xpkg.crossplane.io/crossplane-contrib/provider-aws@sha256:ee6bece46dbb54cc3f0233961f5baac317fa4e4a81b41198bdc72fc472d113d0
```
{{< /hint >}}
#### Provider pull policy
Use a {{<hover label="pullpolicy" line="6">}}packagePullPolicy{{</hover>}} to
@ -297,47 +288,6 @@ spec:
# Removed for brevity
```
#### Automatically update dependency versions
Crossplane can automatically upgrade a package's dependency version to the minimum
valid version that satisfies all the constraints. It's an alpha feature that
requires enabling with the `--enable-dependency-version-upgrades` flag.
In some cases, dependency version downgrade is required for proceeding with
installations. Suppose configuration A, which depends on package X with the
constraint`>=v0.0.0`, is installed on the control plane. In this case, the package
manager installs the latest version of package X, such as `v3.0.0`. Later, you decide
to install configuration B, which depends on package X with the constraint `<=v2.0.0`.
Since version `v2.0.0`satisfies both conditions, package X must be downgraded to
allow the installation of configuration B which is disabled by default.
For enabling automatic dependency version downgrades, there is a configuration
option as a helm value `packageManager.enableAutomaticDependencyDowngrade=true`.
Downgrading a package can cause unexpected behavior, therefore, this
option is disabled by default. After enabling this option, the package manager will
automatically downgrade a package's dependency version to the maximum valid version
that satisfies the constraints.
{{<hint "note" >}}
This configuration requires the `--enable-dependency-version-upgrades` flag.
Please check the
[configuration options]({{<ref "../get-started/install#customize-the-crossplane-helm-chart">}})
and
[feature flags]({{<ref "../get-started/install#feature-flags">}})
are available in the
[Crossplane Install]({{<ref "../get-started/install">}})
section for more details.
{{</hint >}}
{{<hint "important" >}}
Enabling automatic dependency downgrades may have unintended consequences, such as:
1) CRDs missing in the downgraded version, possibly leaving orphaned MRs without
controllers to reconcile them.
2) Loss of data if downgraded CRD versions omit fields that were set before.
3) Changes in the CRD storage version, which may prevent package version update.
{{</hint >}}
#### Ignore Crossplane version requirements
A Provider package may require a specific or minimum Crossplane version before
@ -369,16 +319,16 @@ Configurations or other Providers.
If Crossplane can't meet the dependencies of a Provider package the Provider
reports `HEALTHY` as `False`.
For example, this installation of the Getting Started Configuration is
For example, this installation of the Upbound AWS reference platform is
`HEALTHY: False`.
```shell {copy-lines="1"}
kubectl get providers
NAME INSTALLED HEALTHY PACKAGE AGE
provider-aws-s3 True False xpkg.crossplane.io/crossplane-contrib/provider-aws-s3:v1.21.1 12s
provider-aws-s3 True False xpkg.upbound.io/upbound/provider-aws-s3:v1.0.0 12s
```
To see more information on why the Provider isn't `HEALTHY` use
To see more information on why the Provider isn't `HEALTHY` use
{{<hover label="depend" line="1">}}kubectl describe providerrevisions{{</hover>}}.
```yaml {copy-lines="1",label="depend"}
@ -388,7 +338,7 @@ API Version: pkg.crossplane.io/v1
Kind: ProviderRevision
Spec:
Desired State: Active
Image: xpkg.crossplane.io/crossplane-contrib/provider-aws-s3:v1.21.1
Image: xpkg.upbound.io/upbound/provider-aws-s3:v1.0.0
Revision: 1
Status:
Conditions:
@ -401,7 +351,7 @@ Status:
Events:
Type Reason Age From Message
---- ------ ---- ---- -------
Warning LintPackage 41s (x3 over 47s) packages/providerrevision.pkg.crossplane.io incompatible Crossplane version: package isn't compatible with Crossplane version (v1.10.0)
Warning LintPackage 41s (x3 over 47s) packages/providerrevision.pkg.crossplane.io incompatible Crossplane version: package is not compatible with Crossplane version (v1.10.0)
```
The {{<hover label="depend" line="17">}}Events{{</hover>}} show a
@ -426,13 +376,13 @@ View the `ProviderRevisions` with
```shell {label="getPR",copy-lines="1"}
kubectl get providerrevisions
NAME HEALTHY REVISION IMAGE STATE DEP-FOUND DEP-INSTALLED AGE
provider-aws-s3-dbc7f981d81f True 1 xpkg.crossplane.io/crossplane-contrib/provider-aws-s3:v1.21.1 Active 1 1 10d
provider-nop-552a394a8acc True 2 xpkg.crossplane.io/crossplane-contrib/provider-nop:v0.3.0 Active 11d
provider-nop-7e62d2a1a709 True 1 xpkg.crossplane.io/crossplane-contrib/provider-nop:v0.2.0 Inactive 13d
crossplane-contrib-provider-family-aws-710d8cfe9f53 True 1 xpkg.crossplane.io/crossplane-contrib/provider-family-aws:v1.21.1 Active 10d
provider-aws-s3-dbc7f981d81f True 1 xpkg.upbound.io/upbound/provider-aws-s3:v1.0.0 Active 1 1 10d
provider-nop-552a394a8acc True 2 xpkg.upbound.io/crossplane-contrib/provider-nop:v0.3.0 Active 11d
provider-nop-7e62d2a1a709 True 1 xpkg.upbound.io/crossplane-contrib/provider-nop:v0.2.0 Inactive 13d
upbound-provider-family-aws-710d8cfe9f53 True 1 xpkg.upbound.io/upbound/provider-family-aws:v1.0.0 Active 10d
```
By default Crossplane keeps a single
By default Crossplane keeps a single
{{<hover label="getPR" line="5">}}Inactive{{</hover>}} Provider.
Read the [revision history limit](#package-revision-history-limit) section to
@ -472,7 +422,7 @@ During the install a Provider report `INSTALLED` as `True` and `HEALTHY` as
```shell {copy-lines="1"}
kubectl get providers
NAME INSTALLED HEALTHY PACKAGE AGE
crossplane-contrib-provider-aws True Unknown xpkg.crossplane.io/crossplane-contrib/provider-aws:v0.39.0 63s
crossplane-contrib-provider-aws True Unknown xpkg.upbound.io/crossplane-contrib/provider-aws:v0.39.0 63s
```
After the Provider install completes and it's ready for use the `HEALTHY` status
@ -481,7 +431,7 @@ reports `True`.
```shell {copy-lines="1"}
kubectl get providers
NAME INSTALLED HEALTHY PACKAGE AGE
crossplane-contrib-provider-aws True True xpkg.crossplane.io/crossplane-contrib/provider-aws:v0.39.0 88s
crossplane-contrib-provider-aws True True xpkg.upbound.io/crossplane-contrib/provider-aws:v0.39.0 88s
```
{{<hint "important" >}}
@ -614,24 +564,57 @@ Reason: UnknownPackageRevisionHealth
Providers have two different types of configurations:
* _Runtime configurations_ that change the settings of the Provider pod
* _Controller configurations_ that change the settings of the Provider pod
running inside the Kubernetes cluster. For example, setting a `toleration` on
the Provider pod.
* _Provider configurations_ that change settings used when communicating with
an external provider. For example, cloud provider authentication.
{{<hint "important" >}}
Apply `ControllerConfig` objects to Providers.
Apply `ProviderConfig` objects to managed resources.
{{< /hint >}}
### Controller configuration
{{< hint "important" >}}
<!-- vale write-good.Passive = NO -->
<!-- vale gitlab.FutureTense = NO -->
The `ControllerConfig` type was deprecated in v1.11 and will be removed in
a future release.
<!-- vale write-good.Passive = YES -->
<!-- vale gitlab.FutureTense = YES -->
[`DeploymentRuntimeConfig`]({{<ref "#runtime-configuration" >}}) is the
replacement for Controller configuration and is available in v1.14+.
{{< /hint >}}
Applying a Crossplane `ControllerConfig` to a Provider changes the settings of
the Provider's pod. The
[Crossplane ControllerConfig schema]({{< ref "../api#ControllerConfig-spec" >}})
defines the supported set of ControllerConfig settings.
The most common use case for ControllerConfigs are providing `args` to a
Provider's pod enabling optional services. For example, enabling
[external secret stores]({{< ref "../guides/vault-as-secret-store#enable-external-secret-stores-in-the-provider" >}})
for a Provider.
Each Provider determines their supported set of `args`.
### Runtime configuration
{{<hint "important" >}}
`DeploymentRuntimeConfigs` is a beta feature.
`DeploymentRuntimeConfigs` is a beta feature.
It's on by default, and you can disable it by passing
`--enable-deployment-runtime-configs=false` to the Crossplane deployment.
{{< /hint >}}
Runtime configuration is a generalized mechanism for configuring the runtime for
Crossplane packages with a runtime, namely `Providers` and `Functions`.
Crossplane packages with a runtime, namely `Providers` and `Functions`. It
replaces the deprecated `ControllerConfig` type and is available in v1.14+.
With its default configuration, Crossplane uses Kubernetes Deployments to
deploy runtime for packages, more specifically, a controller for a `Provider`
@ -639,6 +622,14 @@ or a gRPC server for a `Function`. It's possible to configure the runtime
manifest by applying a `DeploymentRuntimeConfig` and referencing it in the
`Provider` or `Function` object.
{{<hint "note" >}}
Different from `ControllerConfig`, `DeploymentRuntimeConfig` embed the whole
Kubernetes Deployment spec, which allows for more flexibility in configuring
the runtime. Refer to the [design document](https://github.com/crossplane/crossplane/blob/2c5e7f07ba9e3d83d1c85169bbde685de8514ab8/design/one-pager-package-runtime-config.md)
for more details.
{{< /hint >}}
As an example, to enable the external secret stores alpha feature for a `Provider`
by adding the `--enable-external-secret-stores` argument to the controller,
one can apply the following:
@ -649,7 +640,7 @@ kind: Provider
metadata:
name: provider-gcp-iam
spec:
package: xpkg.crossplane.io/crossplane-contrib/provider-gcp-iam:v1.12.1
package: xpkg.upbound.io/upbound/provider-gcp-iam:v1
runtimeConfigRef:
name: enable-ess
---

35
content/v1.19/concepts/server-side-apply.md → content/v1.16/concepts/server-side-apply.md
View File

@ -1,8 +1,7 @@
---
title: Server-Side Apply
state: beta
state: alpha
alphaVersion: "1.15"
betaVersion: "1.19"
weight: 300
---
@ -18,20 +17,6 @@ Server-side apply is a Kubernetes feature. Read more about server-side apply in
the [Kubernetes documentation](https://kubernetes.io/docs/reference/using-api/server-side-apply/).
{{</hint>}}
## Disable server-side apply
<!-- vale write-good.Passive = NO -->
Server-Side Apply is a beta feature. Beta features are enabled by default.
<!-- vale write-good.Passive = YES -->
Disable server-side apply by disabling the `--enable-ssa-claims` feature flag.
Read the [Install Crossplane documentation]({{<ref "../software/install#feature-flags">}})
to learn about feature flags.
When server-side apply is disabled, you might see fields reappearing after you delete
them from a claim's `spec`. Also, Crossplane doesn't delete labels and annotations from
the composite resource when you delete them from the claim.
## Use server-side apply to sync claims with composite resources
When you create a claim, Crossplane creates a corresponding composite resource.
@ -44,26 +29,36 @@ and how they relate to composite resources.
Crossplane can use server-side apply to keep the claim in sync with the
composite resource.
Use the `--enable-ssa-claims` feature flag to enable using server-side apply.
Read the [Install Crossplane documentation]({{<ref "../software/install#feature-flags">}})
to learn about feature flags.
If you see fields reappearing after you delete them from a claim's `spec`,
enable server-side apply to fix the problem. Enabling server-side apply also
fixes the problem where Crossplane doesn't delete labels and annotations from
the composite resource when you delete them from the claim.
{{<hint "important">}}
With server-side apply, Crossplane is stricter about how it syncs
When you enable server-side apply, Crossplane is stricter about how it syncs
a claim with its counterpart composite resource:
- The claim's `metadata` syncs to the composite resource's `metadata`.
- The claim's `spec` syncs to the composite resource's `spec`.
- The composite resource's `status` syncs to the claim's `status`.
With server-side apply Crossplane doesn't sync the composite resource's `metadata`
When you enable server-side apply Crossplane doesn't sync the composite resource's `metadata`
and `spec` back to the claim's `metadata` and `spec`. It also doesn't sync the
claim's `status` to the composite resource's `status`.
{{</hint>}}
## Use server-side apply to sync claims end-to-end
To get the full benefit of server-side apply, use it together with composition functions.
To get the full benefit of server-side apply, use the `--enable-ssa-claims`
feature flag together with composition functions.
When you use composition functions, Crossplane uses server side apply to sync
composite resources with composed resources. Read more about this in the
[composition functions documentation]({{<ref "./compositions#how-composition-functions-work">}}).
[composition functions documentation]({{<ref "./composition-functions#how-composition-functions-work">}}).
```mermaid
graph LR

83
content/v1.20/concepts/usages.md → content/v1.16/concepts/usages.md
View File

@ -1,9 +1,8 @@
---
title: Usages
weight: 95
state: beta
state: alpha
alphaVersion: "1.14"
betaVersion: "1.19"
description: "Usage defines a usage relationship for Managed Resources or Composites"
---
@ -20,14 +19,12 @@ first use case and the section [Usage for Deletion Ordering](#usage-for-deletion
for the second one.
## Enable usages
<!-- vale write-good.Passive = NO -->
Usages are a beta feature. Beta features are enabled by default.
<!-- vale write-good.Passive = YES -->
Usages are an alpha feature. Alpha features aren't enabled by default.
Disable `Usage` support by
Enable `Usage` support by
[changing the Crossplane pod setting]({{<ref "./pods#change-pod-settings">}})
and setting
{{<hover label="deployment" line="12">}}--enable-usages=false{{</hover>}}
and enabling
{{<hover label="deployment" line="12">}}--enable-usages{{</hover>}}
argument.
```yaml {label="deployment",copy-lines="12"}
@ -42,7 +39,7 @@ spec:
- args:
- core
- start
- --enable-usages=false
- --enable-usages
```
{{<hint "tip" >}}
@ -88,7 +85,7 @@ any deletion request with the
{{<hover label="protect" line="11">}}reason{{</hover>}} defined.
```yaml {label="protect"}
apiVersion: apiextensions.crossplane.io/v1beta1
apiVersion: apiextensions.crossplane.io/v1alpha1
kind: Usage
metadata:
name: protect-production-database
@ -109,7 +106,7 @@ any deletion request before the deletion of
{{<hover label="order" line="15">}}my-prometheus-chart{{</hover>}} resource.
```yaml {label="order"}
apiVersion: apiextensions.crossplane.io/v1beta1
apiVersion: apiextensions.crossplane.io/v1alpha1
kind: Usage
metadata:
name: release-uses-cluster
@ -135,7 +132,7 @@ This enables using {{<hover label="selectors" line="12">}}labels{{</hover>}} or
to define resource instead of providing the resource name.
```yaml {label="selectors"}
apiVersion: apiextensions.crossplane.io/v1beta1
apiVersion: apiextensions.crossplane.io/v1alpha1
kind: Usage
metadata:
name: release-uses-cluster
@ -169,7 +166,7 @@ random resource is selected from the list of matched resources.
{{< /hint >}}
```yaml {label="selectors-resolved"}
apiVersion: apiextensions.crossplane.io/v1beta1
apiVersion: apiextensions.crossplane.io/v1alpha1
kind: Usage
metadata:
name: release-uses-cluster
@ -200,7 +197,7 @@ Replaying the blocked deletion is possible by setting the
{{<hover label="replay" line="6">}}replayDeletion{{</hover>}} field to `true`.
```yaml {label="replay"}
apiVersion: apiextensions.crossplane.io/v1beta1
apiVersion: apiextensions.crossplane.io/v1alpha1
kind: Usage
metadata:
name: release-uses-cluster
@ -231,9 +228,9 @@ for the long exponential backoff durations of the Kubernetes garbage collector.
A typical use case for Usages is to define a deletion ordering between the
resources in a Composition. The Usages support
[matching controller reference]({{<ref "./managed-resources#matching-by-controller-reference" >}})
[matching controller reference]({{<ref "./compositions#match-a-controller-reference" >}})
in selectors to ensures that the matching resource is in the same composite
resource in the same way as [cross-resource referencing]({{<ref "./managed-resources#referencing-other-resources" >}}).
resource in the same way as [cross-resource referencing]({{<ref "./compositions#cross-resource-references" >}}).
The following example shows a Composition that defines a deletion ordering
between a `Cluster` and a `Release` resource. The `Usage` blocks deletion of
@ -243,41 +240,33 @@ the `Cluster` resource until the `Release` resource is successfully deleted.
apiVersion: apiextensions.crossplane.io/v1
kind: Composition
spec:
mode: Pipeline
pipeline:
- step: patch-and-transform
functionRef:
name: function-patch-and-transform
input:
apiVersion: pt.fn.crossplane.io/v1beta1
kind: Resources
resources:
- name: cluster
base:
resources:
- name: cluster
base:
apiVersion: container.gcp.upbound.io/v1beta1
kind: Cluster
# Removed for brevity
- name: release
base:
apiVersion: helm.crossplane.io/v1beta1
kind: Release
# Removed for brevity
- name: release-uses-cluster
base:
apiVersion: apiextensions.crossplane.io/v1alpha1
kind: Usage
spec:
replayDeletion: true
of:
apiVersion: container.gcp.upbound.io/v1beta1
kind: Cluster
# Removed for brevity
- name: release
base:
resourceSelector:
matchControllerRef: true
by:
apiVersion: helm.crossplane.io/v1beta1
kind: Release
# Removed for brevity
- name: release-uses-cluster
base:
apiVersion: apiextensions.crossplane.io/v1beta1
kind: Usage
spec:
replayDeletion: true
of:
apiVersion: container.gcp.upbound.io/v1beta1
kind: Cluster
resourceSelector:
matchControllerRef: true
by:
apiVersion: helm.crossplane.io/v1beta1
kind: Release
resourceSelector:
matchControllerRef: true
resourceSelector:
matchControllerRef: true
```
{{<hint "tip" >}}

0
content/v1.19/getting-started/_index.md → content/v1.16/getting-started/_index.md
View File

18
content/v1.20/getting-started/install-crossplane-include.md → content/v1.16/getting-started/install-crossplane-include.md
View File

@ -5,7 +5,7 @@ searchExclude: true
## Install Crossplane
Crossplane installs into an existing Kubernetes cluster.
Crossplane installs into an existing Kubernetes cluster.
{{< hint type="tip" >}}
If you don't have a Kubernetes cluster create one locally with [Kind](https://kind.sigs.k8s.io/).
@ -71,7 +71,7 @@ function:
hostNetwork: false
image:
pullPolicy: IfNotPresent
repository: xpkg.crossplane.io/crossplane/crossplane
repository: xpkg.upbound.io/crossplane/crossplane
tag: ""
imagePullSecrets: {}
leaderElection: true
@ -840,7 +840,7 @@ spec:
serviceAccountName: crossplane
hostNetwork: false
initContainers:
- image: "xpkg.crossplane.io/crossplane/crossplane:v1.15.0"
- image: "xpkg.upbound.io/crossplane/crossplane:v1.15.0"
args:
- core
- init
@ -894,7 +894,7 @@ spec:
- name: "TLS_CLIENT_SECRET_NAME"
value: crossplane-tls-client
containers:
- image: "xpkg.crossplane.io/crossplane/crossplane:v1.15.0"
- image: "xpkg.upbound.io/crossplane/crossplane:v1.15.0"
args:
- core
- start
@ -1011,7 +1011,7 @@ spec:
spec:
serviceAccountName: rbac-manager
initContainers:
- image: "xpkg.crossplane.io/crossplane/crossplane:v1.15.0"
- image: "xpkg.upbound.io/crossplane/crossplane:v1.15.0"
args:
- rbac
- init
@ -1041,7 +1041,7 @@ spec:
containerName: crossplane-init
resource: limits.memory
containers:
- image: "xpkg.crossplane.io/crossplane/crossplane:v1.15.0"
- image: "xpkg.upbound.io/crossplane/crossplane:v1.15.0"
args:
- rbac
- start
@ -1104,7 +1104,7 @@ crossplane-d4cd8d784-ldcgb 1/1 Running 0 54s
crossplane-rbac-manager-84769b574-6mw6f 1/1 Running 0 54s
```
Installing Crossplane creates new Kubernetes API end-points.
Installing Crossplane creates new Kubernetes API end-points.
Look at the new API end-points with `kubectl api-resources | grep crossplane`.
```shell {label="grep",copy-lines="1"}
@ -1112,7 +1112,7 @@ kubectl api-resources | grep crossplane
compositeresourcedefinitions xrd,xrds apiextensions.crossplane.io/v1 false CompositeResourceDefinition
compositionrevisions comprev apiextensions.crossplane.io/v1 false CompositionRevision
compositions comp apiextensions.crossplane.io/v1 false Composition
environmentconfigs envcfg apiextensions.crossplane.io/v1beta1 false EnvironmentConfig
environmentconfigs envcfg apiextensions.crossplane.io/v1alpha1 false EnvironmentConfig
usages apiextensions.crossplane.io/v1alpha1 false Usage
configurationrevisions pkg.crossplane.io/v1 false ConfigurationRevision
configurations pkg.crossplane.io/v1 false Configuration
@ -1124,4 +1124,4 @@ locks pkg.crossplane.io/v1beta1
providerrevisions pkg.crossplane.io/v1 false ProviderRevision
providers pkg.crossplane.io/v1 false Provider
storeconfigs secrets.crossplane.io/v1alpha1 false StoreConfig
```
```

39
content/v1.19/getting-started/introduction.md → content/v1.16/getting-started/introduction.md
View File

@ -86,9 +86,9 @@ The following sections describe the functions of some of these CRDs.
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)
[AWS](https://marketplace.upbound.io/providers/upbound/provider-aws),
[Azure](https://marketplace.upbound.io/providers/upbound/provider-azure)
and [GCP](https://marketplace.upbound.io/providers/upbound/provider-gcp)
are different providers for each cloud service.
{{< hint "tip" >}}
@ -100,16 +100,19 @@ 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)
For example, the
[Upbound Provider AWS](https://marketplace.upbound.io/providers/upbound/provider-aws/)
defines a
[`bucket`](https://github.com/crossplane-contrib/provider-upjet-aws/blob/release-1.20/package/crds/s3.aws.upbound.io_buckets.yaml)
[`bucket`](https://marketplace.upbound.io/providers/upbound/provider-aws/v0.25.0/resources/s3.aws.upbound.io/Bucket/v1beta1)
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)
[`spec.forProvider.region`](https://marketplace.upbound.io/providers/upbound/provider-aws/v0.25.0/resources/s3.aws.upbound.io/Bucket/v1beta1#doc:spec-forProvider-region)
value that defines which AWS region to deploy the bucket in.
The Upbound Marketplace contains a large
[collection of Crossplane Providers](https://marketplace.upbound.io/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.
@ -222,7 +225,7 @@ metadata:
spec:
compositeTypeRef:
apiVersion: test.example.org/v1alpha1
kind: MyComputeResource
kind: myComputeResource
# Removed for brevity
```
@ -232,9 +235,9 @@ label="comp" line="8">}}kind{{< /hover >}}.
```yaml {label="xr"}
apiVersion: test.example.org/v1alpha1
kind: MyComputeResource
kind: myComputeResource
metadata:
name: my-resource
name: myResource
spec:
storage: "large"
```
@ -307,7 +310,7 @@ to define the _Composite Resource_ {{<hover label="xr2" line="6" >}}spec{{</hove
spec:
group: test.example.org
names:
kind: MyComputeResource
kind: myComputeResource
versions:
- name: v1alpha1
schema:
@ -319,9 +322,9 @@ A _Composite Resource_ based on this _Composite Resource Definition_ looks like
```yaml {label="xr2"}
# Composite Resource (XR)
apiVersion: test.example.org/v1alpha1
kind: MyComputeResource
kind: myComputeResource
metadata:
name: my-resource
name: myResource
spec:
storage: "large"
```
@ -352,7 +355,7 @@ or {{<hover label="specVersions" line="21" >}}large{{< /hover >}}.
spec:
group: test.example.org
names:
kind: MyComputeResource
kind: myComputeResource
versions:
- name: v1alpha1
served: true
@ -389,7 +392,7 @@ allows the creation of _Claims_ of `kind: computeClaim`.
spec:
group: test.example.org
names:
kind: MyComputeResource
kind: myComputeResource
claimNames:
kind: computeClaim
# Removed for brevity
@ -428,7 +431,7 @@ _Composite Resources_.
spec:
group: test.example.org
names:
kind: MyComputeResource
kind: myComputeResource
claimNames:
kind: computeClaim
# Removed for brevity
@ -474,9 +477,9 @@ The _Composite Resource Definition_ defines the
```yaml {label="xr-claim"}
# Composite Resource (XR)
apiVersion: test.example.org/v1alpha1
kind: MyComputeResource
kind: myComputeResource
metadata:
name: my-resource
name: myResource
spec:
storage: "large"
```

282
content/v1.20/getting-started/provider-aws-part-2.md → content/v1.16/getting-started/provider-aws-part-2.md
View File

@ -7,7 +7,7 @@ aliases:
---
{{< hint "important" >}}
This guide is part 2 of a series.
This guide is part 2 of a series.
[**Part 1**]({{<ref "provider-aws" >}}) covers
to installing Crossplane and connect your Kubernetes cluster to AWS.
@ -36,7 +36,7 @@ crossplane-stable/crossplane \
```
2. When the Crossplane pods finish installing and are ready, apply the AWS Provider
```yaml {label="provider",copy-lines="all"}
cat <<EOF | kubectl apply -f -
apiVersion: pkg.crossplane.io/v1
@ -44,7 +44,7 @@ kind: Provider
metadata:
name: provider-aws-s3
spec:
package: xpkg.crossplane.io/crossplane-contrib/provider-aws-s3:v1.21.1
package: xpkg.upbound.io/upbound/provider-aws-s3:v1.0.0
EOF
```
@ -83,11 +83,11 @@ EOF
## Install the DynamoDB Provider
Part 1 only installed the AWS S3 Provider. This section deploys an S3 bucket
along with a DynamoDB Table.
Deploying a DynamoDB Table requires the DynamoDB Provider as well.
Part 1 only installed the AWS S3 Provider. This section deploys an S3 bucket
along with a DynamoDB Table.
Deploying a DynamoDB Table requires the DynamoDB Provider as well.
Add the new Provider to the cluster.
Add the new Provider to the cluster.
```yaml
cat <<EOF | kubectl apply -f -
@ -96,7 +96,7 @@ kind: Provider
metadata:
name: provider-aws-dynamodb
spec:
package: xpkg.crossplane.io/crossplane-contrib/provider-aws-dynamodb:v1.21.1
package: xpkg.upbound.io/upbound/provider-aws-dynamodb:v1
EOF
```
@ -105,10 +105,10 @@ View the new DynamoDB provider with `kubectl get providers`.
```shell {copy-lines="1"}
kubectl get providers
NAME INSTALLED HEALTHY PACKAGE AGE
crossplane-contrib-provider-family-aws True True xpkg.crossplane.io/crossplane-contrib/provider-family-aws:v1.21.1 15m
provider-aws-dynamodb True True xpkg.crossplane.io/crossplane-contrib/provider-aws-dynamodb:v1.21.1 22s
provider-aws-s3 True True xpkg.crossplane.io/crossplane-contrib/provider-aws-s3:v1.21.1 15m
NAME INSTALLED HEALTHY PACKAGE AGE
provider-aws-dynamodb True True xpkg.upbound.io/upbound/provider-aws-dynamodb:v1.0.0 3m55s
provider-aws-s3 True True xpkg.upbound.io/upbound/provider-aws-s3:v1.0.0 13m
upbound-provider-family-aws True True xpkg.upbound.io/upbound/provider-family-aws:v1.0.0 13m
```
## Create a custom API
@ -116,10 +116,10 @@ provider-aws-s3 True True xpkg.crossplane.i
<!-- vale alex.Condescending = NO -->
Crossplane allows you to build your own custom APIs for your users, abstracting
away details about the cloud provider and their resources. You can make your API
as complex or simple as you wish.
as complex or simple as you wish.
<!-- vale alex.Condescending = YES -->
The custom API is a Kubernetes object.
The custom API is a Kubernetes object.
Here is an example custom API.
```yaml {label="exAPI"}
@ -127,39 +127,39 @@ apiVersion: database.example.com/v1alpha1
kind: NoSQL
metadata:
name: my-nosql-database
spec:
spec:
location: "US"
```
Like any Kubernetes object the API has a
{{<hover label="exAPI" line="1">}}version{{</hover>}},
{{<hover label="exAPI" line="2">}}kind{{</hover>}} and
Like any Kubernetes object the API has a
{{<hover label="exAPI" line="1">}}version{{</hover>}},
{{<hover label="exAPI" line="2">}}kind{{</hover>}} and
{{<hover label="exAPI" line="5">}}spec{{</hover>}}.
### Define a group and version
To create your own API start by defining an
[API group](https://kubernetes.io/docs/reference/using-api/#api-groups) and
[version](https://kubernetes.io/docs/reference/using-api/#api-versioning).
To create your own API start by defining an
[API group](https://kubernetes.io/docs/reference/using-api/#api-groups) and
[version](https://kubernetes.io/docs/reference/using-api/#api-versioning).
The _group_ can be any value, but common convention is to map to a fully
qualified domain name.
qualified domain name.
<!-- vale gitlab.SentenceLength = NO -->
The version shows how mature or stable the API is and increments when changing,
adding or removing fields in the API.
<!-- vale gitlab.SentenceLength = YES -->
Crossplane doesn't require specific versions or a specific version naming
convention, but following
Crossplane doesn't require specific versions or a specific version naming
convention, but following
[Kubernetes API versioning guidelines](https://kubernetes.io/docs/reference/using-api/#api-versioning)
is strongly recommended.
is strongly recommended.
* `v1alpha1` - A new API that may change at any time.
* `v1beta1` - An existing API that's considered stable. Breaking changes are
strongly discouraged.
* `v1` - A stable API that doesn't have breaking changes.
* `v1` - A stable API that doesn't have breaking changes.
This guide uses the group
This guide uses the group
{{<hover label="version" line="1">}}database.example.com{{</hover>}}.
Because this is the first version of the API, this guide uses the version
@ -176,10 +176,10 @@ individual kinds representing different resources.
For example a `database` group may have a `Relational` and `NoSQL` kinds.
The `kind` can be anything, but it must be
The `kind` can be anything, but it must be
[UpperCamelCased](https://kubernetes.io/docs/contribute/style/style-guide/#use-upper-camel-case-for-api-objects).
This API's kind is
This API's kind is
{{<hover label="kind" line="2">}}NoSQL{{</hover>}}
```yaml {label="kind",copy-lines="none"}
@ -190,51 +190,51 @@ kind: NoSQL
### Define a spec
The most important part of an API is the schema. The schema defines the inputs
accepted from users.
accepted from users.
This API allows users to provide a
{{<hover label="spec" line="4">}}location{{</hover>}} of where to run their
This API allows users to provide a
{{<hover label="spec" line="4">}}location{{</hover>}} of where to run their
cloud resources.
All other resource settings can't be configurable by the users. This allows
Crossplane to enforce any policies and standards without worrying about
user errors.
user errors.
```yaml {label="spec",copy-lines="none"}
apiVersion: database.example.com/v1alpha1
kind: NoSQL
spec:
spec:
location: "US"
```
### Apply the API
Crossplane uses
{{<hover label="xrd" line="3">}}Composite Resource Definitions{{</hover>}}
Crossplane uses
{{<hover label="xrd" line="3">}}Composite Resource Definitions{{</hover>}}
(also called an `XRD`) to install your custom API in
Kubernetes.
Kubernetes.
The XRD {{<hover label="xrd" line="6">}}spec{{</hover>}} contains all the
information about the API including the
information about the API including the
{{<hover label="xrd" line="7">}}group{{</hover>}},
{{<hover label="xrd" line="12">}}version{{</hover>}},
{{<hover label="xrd" line="9">}}kind{{</hover>}} and
{{<hover label="xrd" line="9">}}kind{{</hover>}} and
{{<hover label="xrd" line="13">}}schema{{</hover>}}.
The XRD's {{<hover label="xrd" line="5">}}name{{</hover>}} must be the
combination of the {{<hover label="xrd" line="9">}}plural{{</hover>}} and
combination of the {{<hover label="xrd" line="9">}}plural{{</hover>}} and
{{<hover label="xrd" line="7">}}group{{</hover>}}.
The {{<hover label="xrd" line="13">}}schema{{</hover>}} uses the
{{<hover label="xrd" line="14">}}OpenAPIv3{{</hover>}} specification to define
the API {{<hover label="xrd" line="17">}}spec{{</hover>}}.
the API {{<hover label="xrd" line="17">}}spec{{</hover>}}.
The API defines a {{<hover label="xrd" line="20">}}location{{</hover>}} that
must be {{<hover label="xrd" line="22">}}oneOf{{</hover>}} either
{{<hover label="xrd" line="23">}}EU{{</hover>}} or
must be {{<hover label="xrd" line="22">}}oneOf{{</hover>}} either
{{<hover label="xrd" line="23">}}EU{{</hover>}} or
{{<hover label="xrd" line="24">}}US{{</hover>}}.
Apply this XRD to create the custom API in your Kubernetes cluster.
Apply this XRD to create the custom API in your Kubernetes cluster.
```yaml {label="xrd",copy-lines="all"}
cat <<EOF | kubectl apply -f -
@ -272,20 +272,20 @@ EOF
```
Adding the {{<hover label="xrd" line="29">}}claimNames{{</hover>}} allows users
to access this API either at the cluster level with the
to access this API either at the cluster level with the
{{<hover label="xrd" line="9">}}nosql{{</hover>}} endpoint or in a namespace
with the
{{<hover label="xrd" line="29">}}nosqlclaim{{</hover>}} endpoint.
with the
{{<hover label="xrd" line="29">}}nosqlclaim{{</hover>}} endpoint.
The namespace scoped API is a Crossplane _Claim_.
{{<hint "tip" >}}
For more details on the fields and options of Composite Resource Definitions
read the
[XRD documentation]({{<ref "../concepts/composite-resource-definitions">}}).
read the
[XRD documentation]({{<ref "../concepts/composite-resource-definitions">}}).
{{< /hint >}}
View the installed XRD with `kubectl get xrd`.
View the installed XRD with `kubectl get xrd`.
```shell {copy-lines="1"}
kubectl get xrd
@ -307,36 +307,26 @@ When users access the custom API Crossplane takes their inputs and combines them
with a template describing what infrastructure to deploy. Crossplane calls this
template a _Composition_.
The {{<hover label="comp" line="3">}}Composition{{</hover>}} defines all the
cloud resources to deploy. Each entry in the template is a full resource
definition, defining all the resource settings and metadata like labels and
annotations.
The {{<hover label="comp" line="3">}}Composition{{</hover>}} defines all the
cloud resources to deploy.
Each entry in the template
is a full resource definitions, defining all the resource settings and metadata
like labels and annotations.
This template creates an AWS
This template creates an AWS
{{<hover label="comp" line="13">}}S3{{</hover>}}
{{<hover label="comp" line="14">}}Bucket{{</hover>}} and a
{{<hover label="comp" line="14">}}Bucket{{</hover>}} and a
{{<hover label="comp" line="33">}}DynamoDB{{</hover>}}
{{<hover label="comp" line="34">}}Table{{</hover>}}.
This Composition takes the user's
{{<hover label="comp" line="21">}}location{{</hover>}} input and uses it as the
{{<hover label="comp" line="16">}}region{{</hover>}} used in the individual
Crossplane uses {{<hover label="comp" line="19">}}patches{{</hover>}} to apply
the user's input to the resource template.
This Composition takes the user's
{{<hover label="comp" line="21">}}location{{</hover>}} input and uses it as the
{{<hover label="comp" line="16">}}region{{</hover>}} used in the individual
resource.
{{<hint "important" >}}
This Composition uses an array of resource templates. You can patch each
template with data copied from the custom API. Crossplane calls this a _Patch
and Transform_ Composition.
You don't have to use Patch and Transform. Crossplane supports a variety of
alternatives, including Go Templating and CUE. You can also write a function in
Go or Python to template your resources.
Read the [Composition documentation]({{<ref "../concepts/compositions">}}) for
more information on configuring Compositions and all the available options.
{{< /hint >}}
Apply this Composition to your cluster.
Apply this Composition to your cluster.
```yaml {label="comp",copy-lines="all"}
cat <<EOF | kubectl apply -f -
@ -345,55 +335,51 @@ kind: Composition
metadata:
name: dynamo-with-bucket
spec:
mode: Pipeline
pipeline:
- step: patch-and-transform
functionRef:
name: function-patch-and-transform
input:
apiVersion: pt.fn.crossplane.io/v1beta1
kind: Resources
resources:
- name: s3Bucket
base:
apiVersion: s3.aws.upbound.io/v1beta1
kind: Bucket
spec:
forProvider:
region: us-east-2
providerConfigRef:
name: default
patches:
- type: FromCompositeFieldPath
fromFieldPath: "spec.location"
toFieldPath: "spec.forProvider.region"
transforms:
- type: map
map:
EU: "eu-north-1"
US: "us-east-2"
- name: dynamoDB
base:
apiVersion: dynamodb.aws.upbound.io/v1beta1
kind: Table
spec:
forProvider:
region: "us-east-2"
writeCapacity: 1
readCapacity: 1
attribute:
- name: S3ID
type: S
hashKey: S3ID
patches:
- type: FromCompositeFieldPath
fromFieldPath: "spec.location"
toFieldPath: "spec.forProvider.region"
transforms:
- type: map
map:
EU: "eu-north-1"
US: "us-east-2"
resources:
- name: s3Bucket
base:
apiVersion: s3.aws.upbound.io/v1beta1
kind: Bucket
metadata:
name: crossplane-quickstart-bucket
spec:
forProvider:
region: us-east-2
providerConfigRef:
name: default
patches:
- type: FromCompositeFieldPath
fromFieldPath: "spec.location"
toFieldPath: "spec.forProvider.region"
transforms:
- type: map
map:
EU: "eu-north-1"
US: "us-east-2"
- name: dynamoDB
base:
apiVersion: dynamodb.aws.upbound.io/v1beta1
kind: Table
metadata:
name: crossplane-quickstart-database
spec:
forProvider:
region: "us-east-2"
writeCapacity: 1
readCapacity: 1
attribute:
- name: S3ID
type: S
hashKey: S3ID
patches:
- type: FromCompositeFieldPath
fromFieldPath: "spec.location"
toFieldPath: "spec.forProvider.region"
transforms:
- type: map
map:
EU: "eu-north-1"
US: "us-east-2"
compositeTypeRef:
apiVersion: database.example.com/v1alpha1
kind: NoSQL
@ -403,32 +389,14 @@ EOF
The {{<hover label="comp" line="52">}}compositeTypeRef{{</hover >}} defines
which custom APIs can use this template to create resources.
A Composition uses a pipeline of _composition functions_ to define the cloud
resources to deploy. This template uses
{{<hover label="comp" line="10">}}function-patch-and-transform{{</hover>}}.
You must install the function before you can use it in a Composition.
Apply this Function to install `function-patch-and-transform`:
```yaml {label="install"}
cat <<EOF | kubectl apply -f -
apiVersion: pkg.crossplane.io/v1
kind: Function
metadata:
name: function-patch-and-transform
spec:
package: xpkg.crossplane.io/crossplane-contrib/function-patch-and-transform:v0.8.2
EOF
```
{{<hint "tip" >}}
Read the [Composition documentation]({{<ref "../concepts/compositions">}}) for
more information on configuring Compositions and all the available options.
Read the
[Patch and Transform function documentation]({{<ref "../guides/function-patch-and-transform">}})
for more information on how it uses patches to map user inputs to Composition
resource templates.
Read the
[Patch and Transform documentation]({{<ref "../concepts/patch-and-transform">}})
for more information on how Crossplane uses patches to map user inputs to
Composition resource templates.
{{< /hint >}}
View the Composition with `kubectl get composition`
@ -455,7 +423,7 @@ apiVersion: database.example.com/v1alpha1
kind: NoSQL
metadata:
name: my-nosql-database
spec:
spec:
location: "US"
EOF
```
@ -468,10 +436,10 @@ NAME SYNCED READY COMPOSITION AGE
my-nosql-database True True dynamo-with-bucket 14s
```
This object is a Crossplane _composite resource_ (also called an `XR`).
This object is a Crossplane _composite resource_ (also called an `XR`).
It's a
single object representing the collection of resources created from the
Composition template.
Composition template.
View the individual resources with `kubectl get managed`
@ -504,17 +472,17 @@ No resources found
## Using the API with namespaces
Accessing the API `nosql` happens at the cluster scope.
Accessing the API `nosql` happens at the cluster scope.
Most organizations
isolate their users into namespaces.
isolate their users into namespaces.
A Crossplane _Claim_ is the custom API in a namespace.
Creating a _Claim_ is just like accessing the custom API endpoint, but with the
{{<hover label="claim" line="3">}}kind{{</hover>}}
{{<hover label="claim" line="3">}}kind{{</hover>}}
from the custom API's `claimNames`.
Create a new namespace to test create a Claim in.
Create a new namespace to test create a Claim in.
```shell
kubectl create namespace crossplane-test
@ -529,7 +497,7 @@ kind: NoSQLClaim
metadata:
name: my-nosql-database
namespace: crossplane-test
spec:
spec:
location: "US"
EOF
```
@ -542,7 +510,7 @@ my-nosql-database True True 17s
```
The Claim automatically creates a composite resource, which creates the managed
resources.
resources.
View the Crossplane created composite resource with `kubectl get composite`.
@ -591,9 +559,9 @@ No resources found
```
## Next steps
* Explore AWS resources that Crossplane can configure in the
[provider CRD reference](https://github.com/crossplane-contrib/provider-upjet-aws/blob/main/package/crds).
* Join the [Crossplane Slack](https://slack.crossplane.io/) and connect with
* Explore AWS resources that Crossplane can configure in the
[Provider CRD reference](https://marketplace.upbound.io/providers/upbound/provider-family-aws/).
* Join the [Crossplane Slack](https://slack.crossplane.io/) and connect with
Crossplane users and contributors.
* Read more about the [Crossplane concepts]({{<ref "../concepts">}}) to find out what else you can do
with Crossplane.
with Crossplane.

28
content/v1.20/getting-started/provider-aws.md → content/v1.16/getting-started/provider-aws.md
View File

@ -4,8 +4,8 @@ weight: 100
---
Connect Crossplane to AWS to create and manage cloud resources from Kubernetes
with
[provider-upjet-aws](https://github.com/crossplane-contrib/provider-upjet-aws).
with the
[Upbound AWS Provider](https://marketplace.upbound.io/providers/upbound/provider-family-aws).
This guide is in two parts:
* Part 1 walks through installing Crossplane, configuring the provider to
@ -37,7 +37,7 @@ kind: Provider
metadata:
name: provider-aws-s3
spec:
package: xpkg.crossplane.io/crossplane-contrib/provider-aws-s3:v1.21.1
package: xpkg.upbound.io/upbound/provider-aws-s3:v1
EOF
```
@ -51,13 +51,13 @@ Verify the provider installed with `kubectl get providers`.
```shell {copy-lines="1",label="getProvider"}
kubectl get providers
NAME INSTALLED HEALTHY PACKAGE AGE
crossplane-contrib-provider-family-aws True True xpkg.crossplane.io/crossplane-contrib/provider-family-aws:v1.21.1 30s
provider-aws-s3 True True xpkg.crossplane.io/crossplane-contrib/provider-aws-s3:v1.21.1 34s
NAME INSTALLED HEALTHY PACKAGE AGE
provider-aws-s3 True True xpkg.upbound.io/upbound/provider-aws-s3:1.0.0 97s
upbound-provider-family-aws True True xpkg.upbound.io/upbound/provider-family-aws:1.0.0 88s
```
The S3 Provider installs a second Provider, the
{{<hover label="getProvider" line="4">}}crossplane-contrib-provider-family-aws{{</hover >}}.
{{<hover label="getProvider" line="4">}}upbound-provider-family-aws{{</hover >}}.
The family provider manages authentication to AWS across all AWS family
Providers.
@ -67,7 +67,7 @@ Every CRD maps to a unique AWS service Crossplane can provision and manage.
{{< hint type="tip" >}}
See details about all the supported CRDs in the
[provider examples](https://github.com/crossplane-contrib/provider-upjet-aws/tree/main/examples).
[Upbound Marketplace](https://marketplace.upbound.io/providers/upbound/provider-aws-s3/v1.1.0).
{{< /hint >}}
## Create a Kubernetes secret for AWS
@ -197,16 +197,16 @@ spec:
EOF
```
The {{< hover label="xr" line="2">}}apiVersion{{< /hover >}} and
{{< hover label="xr" line="3">}}kind{{</hover >}} are from the provider's CRDs.
The {{< hover label="xr" line="3">}}apiVersion{{< /hover >}} and
{{< hover label="xr" line="4">}}kind{{</hover >}} are from the provider's CRDs.
The {{< hover label="xr" line="5">}}metadata.generateName{{< /hover >}} value is the
The {{< hover label="xr" line="6">}}metadata.name{{< /hover >}} value is the
name of the created S3 bucket in AWS.
This example uses the generated name `crossplane-bucket-<hash>` in the
{{< hover label="xr" line="5">}}$bucket{{</hover >}} variable.
{{< hover label="xr" line="6">}}$bucket{{</hover >}} variable.
The {{< hover label="xr" line="8">}}spec.forProvider.region{{< /hover >}} tells
The {{< hover label="xr" line="9">}}spec.forProvider.region{{< /hover >}} tells
AWS which AWS region to use when deploying resources.
The region can be any
@ -239,6 +239,6 @@ bucket.s3.aws.upbound.io "crossplane-bucket-hhdzh" deleted
* [**Continue to part 2**]({{< ref "provider-aws-part-2">}}) to create and use a
custom API with Crossplane.
* Explore AWS resources that Crossplane can configure in the
[provider CRD reference](https://github.com/crossplane-contrib/provider-upjet-aws/blob/main/package/crds).
[Provider CRD reference](https://marketplace.upbound.io/providers/upbound/provider-family-aws/).
* Join the [Crossplane Slack](https://slack.crossplane.io/) and connect with
Crossplane users and contributors.

414
content/v1.19/getting-started/provider-azure-part-2.md → content/v1.16/getting-started/provider-azure-part-2.md
View File

@ -7,7 +7,7 @@ aliases:
---
{{< hint "important" >}}
This guide is part 2 of a series.
This guide is part 2 of a series.
[**Part 1**]({{<ref "provider-azure" >}}) covers
to installing Crossplane and connect your Kubernetes cluster to Azure.
@ -35,9 +35,9 @@ crossplane-stable/crossplane \
--create-namespace
```
2. When the Crossplane pods finish installing and are ready, apply the Azure
2. When the Crossplane pods finish installing and are ready, apply the Azure
Provider
```yaml {label="provider",copy-lines="all"}
cat <<EOF | kubectl apply -f -
apiVersion: pkg.crossplane.io/v1
@ -45,11 +45,11 @@ kind: Provider
metadata:
name: provider-azure-network
spec:
package: xpkg.crossplane.io/crossplane-contrib/provider-azure-network:v1.11.2
package: xpkg.upbound.io/upbound/provider-azure-network:v1
EOF
```
3. Use the Azure CLI to create a service principal and save the JSON output as
3. Use the Azure CLI to create a service principal and save the JSON output as
`azure-crednetials.json`
{{< editCode >}}
```console
@ -91,10 +91,10 @@ EOF
<!-- vale alex.Condescending = NO -->
Crossplane allows you to build your own custom APIs for your users, abstracting
away details about the cloud provider and their resources. You can make your API
as complex or simple as you wish.
as complex or simple as you wish.
<!-- vale alex.Condescending = YES -->
The custom API is a Kubernetes object.
The custom API is a Kubernetes object.
Here is an example custom API.
```yaml {label="exAPI"}
@ -102,39 +102,39 @@ apiVersion: compute.example.com/v1alpha1
kind: VirtualMachine
metadata:
name: my-vm
spec:
spec:
location: "US"
```
Like any Kubernetes object the API has a
{{<hover label="exAPI" line="1">}}version{{</hover>}},
{{<hover label="exAPI" line="2">}}kind{{</hover>}} and
Like any Kubernetes object the API has a
{{<hover label="exAPI" line="1">}}version{{</hover>}},
{{<hover label="exAPI" line="2">}}kind{{</hover>}} and
{{<hover label="exAPI" line="5">}}spec{{</hover>}}.
### Define a group and version
To create your own API start by defining an
[API group](https://kubernetes.io/docs/reference/using-api/#api-groups) and
[version](https://kubernetes.io/docs/reference/using-api/#api-versioning).
To create your own API start by defining an
[API group](https://kubernetes.io/docs/reference/using-api/#api-groups) and
[version](https://kubernetes.io/docs/reference/using-api/#api-versioning).
The _group_ can be any value, but common convention is to map to a fully
qualified domain name.
qualified domain name.
<!-- vale gitlab.SentenceLength = NO -->
The version shows how mature or stable the API is and increments when changing,
adding or removing fields in the API.
<!-- vale gitlab.SentenceLength = YES -->
Crossplane doesn't require specific versions or a specific version naming
convention, but following
Crossplane doesn't require specific versions or a specific version naming
convention, but following
[Kubernetes API versioning guidelines](https://kubernetes.io/docs/reference/using-api/#api-versioning)
is strongly recommended.
is strongly recommended.
* `v1alpha1` - A new API that may change at any time.
* `v1beta1` - An existing API that's considered stable. Breaking changes are
strongly discouraged.
* `v1` - A stable API that doesn't have breaking changes.
* `v1` - A stable API that doesn't have breaking changes.
This guide uses the group
This guide uses the group
{{<hover label="version" line="1">}}compute.example.com{{</hover>}}.
Because this is the first version of the API, this guide uses the version
@ -151,10 +151,10 @@ individual kinds representing different resources.
For example a `compute` group may have a `VirtualMachine` and `BareMetal` kinds.
The `kind` can be anything, but it must be
The `kind` can be anything, but it must be
[UpperCamelCased](https://kubernetes.io/docs/contribute/style/style-guide/#use-upper-camel-case-for-api-objects).
This API's kind is
This API's kind is
{{<hover label="kind" line="2">}}VirtualMachine{{</hover>}}
```yaml {label="kind",copy-lines="none"}
@ -165,51 +165,51 @@ kind: VirtualMachine
### Define a spec
The most important part of an API is the schema. The schema defines the inputs
accepted from users.
accepted from users.
This API allows users to provide a
{{<hover label="spec" line="4">}}location{{</hover>}} of where to run their
This API allows users to provide a
{{<hover label="spec" line="4">}}location{{</hover>}} of where to run their
cloud resources.
All other resource settings can't be configurable by the users. This allows
Crossplane to enforce any policies and standards without worrying about
user errors.
user errors.
```yaml {label="spec",copy-lines="none"}
apiVersion: compute.example.com/v1alpha1
kind: VirtualMachine
spec:
spec:
location: "US"
```
### Apply the API
Crossplane uses
{{<hover label="xrd" line="3">}}Composite Resource Definitions{{</hover>}}
Crossplane uses
{{<hover label="xrd" line="3">}}Composite Resource Definitions{{</hover>}}
(also called an `XRD`) to install your custom API in
Kubernetes.
Kubernetes.
The XRD {{<hover label="xrd" line="6">}}spec{{</hover>}} contains all the
information about the API including the
information about the API including the
{{<hover label="xrd" line="7">}}group{{</hover>}},
{{<hover label="xrd" line="12">}}version{{</hover>}},
{{<hover label="xrd" line="9">}}kind{{</hover>}} and
{{<hover label="xrd" line="9">}}kind{{</hover>}} and
{{<hover label="xrd" line="13">}}schema{{</hover>}}.
The XRD's {{<hover label="xrd" line="5">}}name{{</hover>}} must be the
combination of the {{<hover label="xrd" line="10">}}plural{{</hover>}} and
combination of the {{<hover label="xrd" line="10">}}plural{{</hover>}} and
{{<hover label="xrd" line="7">}}group{{</hover>}}.
The {{<hover label="xrd" line="13">}}schema{{</hover>}} uses the
{{<hover label="xrd" line="14">}}OpenAPIv3{{</hover>}} specification to define
the API {{<hover label="xrd" line="17">}}spec{{</hover>}}.
the API {{<hover label="xrd" line="17">}}spec{{</hover>}}.
The API defines a {{<hover label="xrd" line="20">}}location{{</hover>}} that
must be {{<hover label="xrd" line="22">}}oneOf{{</hover>}} either
{{<hover label="xrd" line="23">}}EU{{</hover>}} or
must be {{<hover label="xrd" line="22">}}oneOf{{</hover>}} either
{{<hover label="xrd" line="23">}}EU{{</hover>}} or
{{<hover label="xrd" line="24">}}US{{</hover>}}.
Apply this XRD to create the custom API in your Kubernetes cluster.
Apply this XRD to create the custom API in your Kubernetes cluster.
```yaml {label="xrd",copy-lines="all"}
cat <<EOF | kubectl apply -f -
@ -247,20 +247,20 @@ EOF
```
Adding the {{<hover label="xrd" line="29">}}claimNames{{</hover>}} allows users
to access this API either at the cluster level with the
to access this API either at the cluster level with the
{{<hover label="xrd" line="9">}}VirtualMachine{{</hover>}} endpoint or in a namespace
with the
{{<hover label="xrd" line="30">}}VirtualMachineClaim{{</hover>}} endpoint.
with the
{{<hover label="xrd" line="30">}}VirtualMachineClaim{{</hover>}} endpoint.
The namespace scoped API is a Crossplane _Claim_.
{{<hint "tip" >}}
For more details on the fields and options of Composite Resource Definitions
read the
[XRD documentation]({{<ref "../concepts/composite-resource-definitions">}}).
read the
[XRD documentation]({{<ref "../concepts/composite-resource-definitions">}}).
{{< /hint >}}
View the installed XRD with `kubectl get xrd`.
View the installed XRD with `kubectl get xrd`.
```shell {copy-lines="1"}
kubectl get xrd
@ -282,38 +282,27 @@ When users access the custom API Crossplane takes their inputs and combines them
with a template describing what infrastructure to deploy. Crossplane calls this
template a _Composition_.
The {{<hover label="comp" line="3">}}Composition{{</hover>}} defines all the
The {{<hover label="comp" line="3">}}Composition{{</hover>}} defines all the
cloud resources to deploy.
Each entry in the template
is a full resource definitions, defining all the resource settings and metadata
like labels and annotations.
like labels and annotations.
This template creates an Azure
{{<hover label="comp" line="11">}}LinuxVirtualMachine{{</hover>}}
{{<hover label="comp" line="46">}}NetworkInterface{{</hover>}},
{{<hover label="comp" line="46">}}NetworkInterface{{</hover>}},
{{<hover label="comp" line="69">}}Subnet{{</hover>}}
{{<hover label="comp" line="90">}}VirtualNetwork{{</hover>}} and
{{<hover label="comp" line="110">}}ResourceGroup{{</hover>}}.
This Composition takes the user's
{{<hover label="comp" line="36">}}location{{</hover>}} input and uses it as the
{{<hover label="comp" line="37">}}location{{</hover>}} used in the individual
Crossplane uses {{<hover label="comp" line="34">}}patches{{</hover>}} to apply
the user's input to the resource template.
This Composition takes the user's
{{<hover label="comp" line="36">}}location{{</hover>}} input and uses it as the
{{<hover label="comp" line="37">}}location{{</hover>}} used in the individual
resource.
{{<hint "important" >}}
This Composition uses an array of resource templates. You can patch each
template with data copied from the custom API. Crossplane calls this a _Patch
and Transform_ Composition.
You don't have to use Patch and Transform. Crossplane supports a variety of
alternatives, including Go Templating and CUE. You can also write a function in
Go or Python to template your resources.
Read the [Composition documentation]({{<ref "../concepts/compositions">}}) for
more information on configuring Compositions and all the available options.
{{< /hint >}}
Apply this Composition to your cluster.
Apply this Composition to your cluster.
```yaml {label="comp",copy-lines="all"}
cat <<EOF | kubectl apply -f -
@ -322,121 +311,122 @@ kind: Composition
metadata:
name: crossplane-quickstart-vm-with-network
spec:
mode: Pipeline
pipeline:
- step: patch-and-transform
functionRef:
name: function-patch-and-transform
input:
apiVersion: pt.fn.crossplane.io/v1beta1
kind: Resources
resources:
- name: quickstart-vm
base:
apiVersion: compute.azure.upbound.io/v1beta1
kind: LinuxVirtualMachine
spec:
forProvider:
adminUsername: adminuser
adminSshKey:
- publicKey: ssh-rsa
AAAAB3NzaC1yc2EAAAADAQABAAABAQC+wWK73dCr+jgQOAxNsHAnNNNMEMWOHYEccp6wJm2gotpr9katuF/ZAdou5AaW1C61slRkHRkpRRX9FA9CYBiitZgvCCz+3nWNN7l/Up54Zps/pHWGZLHNJZRYyAB6j5yVLMVHIHriY49d/GZTZVNB8GoJv9Gakwc/fuEZYYl4YDFiGMBP///TzlI4jhiJzjKnEvqPFki5p2ZRJqcbCiF4pJrxUQR/RXqVFQdbRLZgYfJ8xGB878RENq3yQ39d8dVOkq4edbkzwcUmwwwkYVPIoDGsYLaRHnG+To7FvMeyO7xDVQkMKzopTQV8AuKpyvpqu0a9pWOMaiCyDytO7GGN
example@docs.crossplane.io
username: adminuser
location: "Central US"
osDisk:
- caching: ReadWrite
storageAccountType: Standard_LRS
resourceGroupNameSelector:
resources:
- name: quickstart-vm
base:
apiVersion: compute.azure.upbound.io/v1beta1
kind: LinuxVirtualMachine
spec:
forProvider:
adminUsername: adminuser
adminSshKey:
- publicKey: ssh-rsa
AAAAB3NzaC1yc2EAAAADAQABAAABAQC+wWK73dCr+jgQOAxNsHAnNNNMEMWOHYEccp6wJm2gotpr9katuF/ZAdou5AaW1C61slRkHRkpRRX9FA9CYBiitZgvCCz+3nWNN7l/Up54Zps/pHWGZLHNJZRYyAB6j5yVLMVHIHriY49d/GZTZVNB8GoJv9Gakwc/fuEZYYl4YDFiGMBP///TzlI4jhiJzjKnEvqPFki5p2ZRJqcbCiF4pJrxUQR/RXqVFQdbRLZgYfJ8xGB878RENq3yQ39d8dVOkq4edbkzwcUmwwwkYVPIoDGsYLaRHnG+To7FvMeyO7xDVQkMKzopTQV8AuKpyvpqu0a9pWOMaiCyDytO7GGN
example@docs.crossplane.io
username: adminuser
location: "Central US"
osDisk:
- caching: ReadWrite
storageAccountType: Standard_LRS
resourceGroupNameSelector:
matchControllerRef: true
size: Standard_B1ms
sourceImageReference:
- offer: debian-11
publisher: Debian
sku: 11-backports-gen2
version: latest
networkInterfaceIdsSelector:
matchControllerRef: true
patches:
- type: FromCompositeFieldPath
fromFieldPath: "spec.location"
toFieldPath: "spec.forProvider.location"
transforms:
- type: map
map:
EU: "Sweden Central"
US: "Central US"
- name: quickstart-nic
base:
apiVersion: network.azure.upbound.io/v1beta1
kind: NetworkInterface
spec:
forProvider:
ipConfiguration:
- name: crossplane-quickstart-configuration
privateIpAddressAllocation: Dynamic
subnetIdSelector:
matchControllerRef: true
size: Standard_B1ms
sourceImageReference:
- offer: debian-11
publisher: Debian
sku: 11-backports-gen2
version: latest
networkInterfaceIdsSelector:
matchControllerRef: true
patches:
- type: FromCompositeFieldPath
fromFieldPath: "spec.location"
toFieldPath: "spec.forProvider.location"
transforms:
- type: map
map:
EU: "Sweden Central"
US: "Central US"
- name: quickstart-nic
base:
apiVersion: network.azure.upbound.io/v1beta1
kind: NetworkInterface
spec:
forProvider:
ipConfiguration:
- name: crossplane-quickstart-configuration
privateIpAddressAllocation: Dynamic
subnetIdSelector:
matchControllerRef: true
location: "Central US"
resourceGroupNameSelector:
matchControllerRef: true
patches:
- type: FromCompositeFieldPath
fromFieldPath: "spec.location"
toFieldPath: "spec.forProvider.location"
transforms:
- type: map
map:
EU: "Sweden Central"
US: "Central US"
- name: quickstart-subnet
base:
apiVersion: network.azure.upbound.io/v1beta1
kind: Subnet
spec:
forProvider:
addressPrefixes:
- 10.0.1.0/24
virtualNetworkNameSelector:
matchControllerRef: true
resourceGroupNameSelector:
matchControllerRef: true
- name: quickstart-network
base:
apiVersion: network.azure.upbound.io/v1beta1
kind: VirtualNetwork
spec:
forProvider:
addressSpace:
- 10.0.0.0/16
location: "Central US"
resourceGroupNameSelector:
matchControllerRef: true
patches:
- type: FromCompositeFieldPath
fromFieldPath: "spec.location"
toFieldPath: "spec.forProvider.location"
transforms:
- type: map
map:
EU: "Sweden Central"
US: "Central US"
- name: crossplane-resourcegroup
base:
apiVersion: azure.upbound.io/v1beta1
kind: ResourceGroup
spec:
forProvider:
location: Central US
patches:
- type: FromCompositeFieldPath
fromFieldPath: "spec.location"
toFieldPath: "spec.forProvider.location"
transforms:
- type: map
map:
EU: "Sweden Central"
US: "Central US"
location: "Central US"
resourceGroupNameSelector:
matchControllerRef: true
patches:
- type: FromCompositeFieldPath
fromFieldPath: "spec.location"
toFieldPath: "spec.forProvider.location"
transforms:
- type: map
map:
EU: "Sweden Central"
US: "Central US"
- name: quickstart-subnet
base:
apiVersion: network.azure.upbound.io/v1beta1
kind: Subnet
spec:
forProvider:
addressPrefixes:
- 10.0.1.0/24
virtualNetworkNameSelector:
matchControllerRef: true
resourceGroupNameSelector:
matchControllerRef: true
patches:
- type: FromCompositeFieldPath
fromFieldPath: "spec.location"
toFieldPath: "spec.forProvider.location"
transforms:
- type: map
map:
EU: "Sweden Central"
US: "Central US"
- name: quickstart-network
base:
apiVersion: network.azure.upbound.io/v1beta1
kind: VirtualNetwork
spec:
forProvider:
addressSpace:
- 10.0.0.0/16
location: "Central US"
resourceGroupNameSelector:
matchControllerRef: true
patches:
- type: FromCompositeFieldPath
fromFieldPath: "spec.location"
toFieldPath: "spec.forProvider.location"
transforms:
- type: map
map:
EU: "Sweden Central"
US: "Central US"
- name: crossplane-resourcegroup
base:
apiVersion: azure.upbound.io/v1beta1
kind: ResourceGroup
spec:
forProvider:
location: Central US
patches:
- type: FromCompositeFieldPath
fromFieldPath: "spec.location"
toFieldPath: "spec.forProvider.location"
transforms:
- type: map
map:
EU: "Sweden Central"
US: "Central US"
compositeTypeRef:
apiVersion: compute.example.com/v1alpha1
kind: VirtualMachine
@ -446,32 +436,14 @@ EOF
The {{<hover label="comp" line="52">}}compositeTypeRef{{</hover >}} defines
which custom APIs can use this template to create resources.
A Composition uses a pipeline of _composition functions_ to define the cloud
resources to deploy. This template uses
{{<hover label="comp" line="10">}}function-patch-and-transform{{</hover>}}.
You must install the function before you can use it in a Composition.
Apply this Function to install `function-patch-and-transform`:
```yaml {label="install"}
cat <<EOF | kubectl apply -f -
apiVersion: pkg.crossplane.io/v1
kind: Function
metadata:
name: function-patch-and-transform
spec:
package: xpkg.crossplane.io/crossplane-contrib/function-patch-and-transform:v0.8.2
EOF
```
{{<hint "tip" >}}
Read the [Composition documentation]({{<ref "../concepts/compositions">}}) for
more information on configuring Compositions and all the available options.
Read the
[Patch and Transform function documentation]({{<ref "../guides/function-patch-and-transform">}})
for more information on how it uses patches to map user inputs to Composition
resource templates.
Read the
[Patch and Transform documentation]({{<ref "../concepts/patch-and-transform">}})
for more information on how Crossplane uses patches to map user inputs to
Composition resource templates.
{{< /hint >}}
View the Composition with `kubectl get composition`
@ -485,9 +457,9 @@ crossplane-quickstart-vm-with-network XVirtualMachine custom-api.example.org
## Install the Azure virtual machine provider
Part 1 only installed the Azure Virtual Network Provider. To deploying virtual
machines requires the Azure Compute provider as well.
machines requires the Azure Compute provider as well.
Add the new Provider to the cluster.
Add the new Provider to the cluster.
```yaml
cat <<EOF | kubectl apply -f -
@ -496,7 +468,7 @@ kind: Provider
metadata:
name: provider-azure-compute
spec:
package: xpkg.crossplane.io/crossplane-contrib/provider-azure-compute:v1.11.2
package: xpkg.upbound.io/upbound/provider-azure-compute:v1
EOF
```
@ -505,10 +477,10 @@ View the new Compute provider with `kubectl get providers`.
```shell {copy-lines="1"}
kubectl get providers
NAME INSTALLED HEALTHY PACKAGE AGE
crossplane-contrib-provider-family-azure True True xpkg.crossplane.io/crossplane-contrib/provider-family-azure:v1.11.2 23m
provider-azure-compute True True xpkg.crossplane.io/crossplane-contrib/provider-azure-compute:v1.11.2 2m54s
provider-azure-network True True xpkg.crossplane.io/crossplane-contrib/provider-azure-network:v1.11.2 23m
NAME INSTALLED HEALTHY PACKAGE AGE
provider-azure-compute True True xpkg.upbound.io/upbound/provider-azure-compute:v1.0.0 25s
provider-azure-network True True xpkg.upbound.io/upbound/provider-azure-network:v1.0.0 3h
upbound-provider-family-azure True True xpkg.upbound.io/upbound/provider-family-azure:v1.0.0 3h
```
## Access the custom API
@ -516,7 +488,7 @@ provider-azure-network True True xpkg.crossplane
With the custom API (XRD) installed and associated to a resource template
(Composition) users can access the API to create resources.
Create a {{<hover label="xr" line="3">}}VirtualMachine{{</hover>}} object to
Create a {{<hover label="xr" line="3">}}VirtualMachine{{</hover>}} object to
create the cloud resources.
```yaml {copy-lines="all",label="xr"}
@ -525,7 +497,7 @@ apiVersion: compute.example.com/v1alpha1
kind: VirtualMachine
metadata:
name: my-vm
spec:
spec:
location: "EU"
EOF
```
@ -542,10 +514,10 @@ NAME SYNCED READY COMPOSITION AGE
my-vm True True crossplane-quickstart-vm-with-network 3m3s
```
This object is a Crossplane _composite resource_ (also called an `XR`).
This object is a Crossplane _composite resource_ (also called an `XR`).
It's a
single object representing the collection of resources created from the
Composition template.
Composition template.
View the individual resources with `kubectl get managed`
@ -568,7 +540,7 @@ virtualnetwork.network.azure.upbound.io/my-vm-pd2sw True True my-vm-pd2
```
Accessing the API created all five resources defined in the template and linked
them together.
them together.
Look at a specific resource to see it's created in the location used in the API.
@ -598,17 +570,17 @@ No resources found
## Using the API with namespaces
Accessing the API `VirtualMachine` happens at the cluster scope.
Accessing the API `VirtualMachine` happens at the cluster scope.
Most organizations
isolate their users into namespaces.
isolate their users into namespaces.
A Crossplane _Claim_ is the custom API in a namespace.
Creating a _Claim_ is just like accessing the custom API endpoint, but with the
{{<hover label="claim" line="3">}}kind{{</hover>}}
{{<hover label="claim" line="3">}}kind{{</hover>}}
from the custom API's `claimNames`.
Create a new namespace to test create a Claim in.
Create a new namespace to test create a Claim in.
```shell
kubectl create namespace crossplane-test
@ -623,7 +595,7 @@ kind: VirtualMachineClaim
metadata:
name: my-namespaced-vm
namespace: crossplane-test
spec:
spec:
location: "EU"
EOF
```
@ -636,7 +608,7 @@ my-namespaced-vm True True 5m11s
```
The Claim automatically creates a composite resource, which creates the managed
resources.
resources.
View the Crossplane created composite resource with `kubectl get composite`.
@ -693,9 +665,9 @@ No resources found
```
## Next steps
* Explore Azure resources that Crossplane can configure in the
[Provider CRD reference](https://github.com/crossplane-contrib/provider-upjet-azure/tree/main/package/crds).
* Join the [Crossplane Slack](https://slack.crossplane.io/) and connect with
* Explore Azure resources that Crossplane can configure in the
[Provider CRD reference](https://marketplace.upbound.io/providers/upbound/provider-family-azure/).
* Join the [Crossplane Slack](https://slack.crossplane.io/) and connect with
Crossplane users and contributors.
* Read more about the [Crossplane concepts]({{<ref "../concepts">}}) to find out
what else you can do with Crossplane.
what else you can do with Crossplane.

18
content/v1.20/getting-started/provider-azure.md → content/v1.16/getting-started/provider-azure.md
View File

@ -4,8 +4,8 @@ weight: 110
---
Connect Crossplane to Azure to create and manage cloud resources from Kubernetes
with
[provider-upjet-azure](https://github.com/crossplane-contrib/provider-upjet-azure).
with the
[Upbound Azure Provider](https://marketplace.upbound.io/providers/upbound/provider-family-azure/).
This guide is in two parts:
* Part 1 walks through installing Crossplane, configuring the provider to
@ -39,7 +39,7 @@ kind: Provider
metadata:
name: provider-azure-network
spec:
package: xpkg.crossplane.io/crossplane-contrib/provider-azure-network:v1.11.2
package: xpkg.upbound.io/upbound/provider-azure-network:v1.0.0
EOF
```
@ -53,13 +53,13 @@ Verify the provider installed with `kubectl get providers`.
```shell {copy-lines="1",label="getProvider"}
kubectl get providers
NAME INSTALLED HEALTHY PACKAGE AGE
crossplane-contrib-provider-family-azure True True xpkg.crossplane.io/crossplane-contrib/provider-family-azure:v1.11.2 2m18s
provider-azure-network True True xpkg.crossplane.io/crossplane-contrib/provider-azure-network:v1.11.2 2m23s
NAME INSTALLED HEALTHY PACKAGE AGE
provider-azure-network True True xpkg.upbound.io/upbound/provider-azure-network:v1.0.0 38s
upbound-provider-family-azure True True xpkg.upbound.io/upbound/provider-family-azure:v1.0.0 26s
```
The Network Provider installs a second Provider, the
{{<hover label="getProvider" line="4">}}crossplane-contrib-provider-family-azure{{</hover>}}
{{<hover label="getProvider" line="4">}}upbound-provider-family-azure{{</hover>}}
provider.
The family provider manages authentication to Azure across all Azure family
Providers.
@ -69,7 +69,7 @@ Every CRD maps to a unique Azure service Crossplane can provision and manage.
{{< hint type="tip" >}}
See details about all the supported CRDs in the
[provider examples](https://github.com/crossplane-contrib/provider-upjet-azure/tree/main/examples).
[Upbound Marketplace](https://marketplace.upbound.io/providers/upbound/provider-family-azure/v0.42.1).
{{< /hint >}}
@ -234,6 +234,6 @@ virtualnetwork.network.azure.upbound.io "crossplane-quickstart-network" deleted
* [**Continue to part 2**]({{< ref "provider-azure-part-2">}}) to create and use
a custom API with Crossplane.
* Explore Azure resources that Crossplane can configure in the
[Provider CRD reference](https://github.com/crossplane-contrib/provider-upjet-azure/tree/main/package/crds).
[Provider CRD reference](https://marketplace.upbound.io/providers/upbound/provider-family-azure/).
* Join the [Crossplane Slack](https://slack.crossplane.io/) and connect with
Crossplane users and contributors.

271
content/v1.19/getting-started/provider-gcp-part-2.md → content/v1.16/getting-started/provider-gcp-part-2.md
View File

@ -7,20 +7,20 @@ aliases:
---
{{< hint "important" >}}
This guide is part 2 of a series.
This guide is part 2 of a series.
[**Part 1**]({{<ref "provider-gcp" >}}) covers
to installing Crossplane and connect your Kubernetes cluster to GCP.
{{< /hint >}}
This guide walks you through building and accessing a custom API with
This guide walks you through building and accessing a custom API with
Crossplane.
## Prerequisites
* Complete [quickstart part 1]({{<ref "provider-gcp" >}}) connecting Kubernetes
to GCP.
* a GCP account with permissions to create a GCP
* a GCP account with permissions to create a GCP
[storage bucket](https://cloud.google.com/storage) and a
[Pub/Sub topic](https://cloud.google.com/pubsub).
@ -37,9 +37,9 @@ crossplane-stable/crossplane \
--create-namespace
```
2. When the Crossplane pods finish installing and are ready, apply the GCP
2. When the Crossplane pods finish installing and are ready, apply the GCP
Provider.
```yaml {label="provider",copy-lines="all"}
cat <<EOF | kubectl apply -f -
apiVersion: pkg.crossplane.io/v1
@ -47,16 +47,16 @@ kind: Provider
metadata:
name: provider-gcp-storage
spec:
package: xpkg.crossplane.io/crossplane-contrib/provider-gcp-storage:v1.12.1
package: xpkg.upbound.io/upbound/provider-gcp-storage:v1
EOF
```
3. Create a file called `gcp-credentials.json` with your GCP service account
3. Create a file called `gcp-credentials.json` with your GCP service account
JSON file.
{{< hint "tip" >}}
The
[GCP documentation](https://cloud.google.com/iam/docs/creating-managing-service-account-keys)
The
[GCP documentation](https://cloud.google.com/iam/docs/creating-managing-service-account-keys)
provides information on how to generate a service account JSON file.
{{< /hint >}}
@ -69,12 +69,12 @@ generic gcp-secret \
```
5. Create a _ProviderConfig_
Include your
Include your
{{< hover label="providerconfig" line="7" >}}GCP project ID{{< /hover >}} in the
_ProviderConfig_ settings.
{{< hint type="tip" >}}
Find your GCP project ID from the `project_id` field of the
Find your GCP project ID from the `project_id` field of the
`gcp-credentials.json` file.
{{< /hint >}}
@ -101,11 +101,11 @@ EOF
## Install the PubSub Provider
Part 1 only installed the GCP Storage Provider. This section deploys a
PubSub Topic along with a GCP storage bucket.
Part 1 only installed the GCP Storage Provider. This section deploys a
PubSub Topic along with a GCP storage bucket.
First install the GCP PubSub Provider.
Add the new Provider to the cluster.
Add the new Provider to the cluster.
```yaml
cat <<EOF | kubectl apply -f -
@ -114,7 +114,7 @@ kind: Provider
metadata:
name: provider-gcp-pubsub
spec:
package: xpkg.crossplane.io/crossplane-contrib/provider-gcp-pubsub:v1.12.1
package: xpkg.upbound.io/upbound/provider-gcp-pubsub:v1
EOF
```
@ -122,10 +122,10 @@ View the new PubSub provider with `kubectl get providers`.
```shell {copy-lines="1"}
kubectl get providers
NAME INSTALLED HEALTHY PACKAGE AGE
crossplane-contrib-provider-family-gcp True True xpkg.crossplane.io/crossplane-contrib/provider-family-gcp:v1.12.1 48m
provider-gcp-pubsub True True xpkg.crossplane.io/crossplane-contrib/provider-gcp-pubsub:v1.12.1 14s
provider-gcp-storage True True xpkg.crossplane.io/crossplane-contrib/provider-gcp-storage:v1.12.1 48m
NAME INSTALLED HEALTHY PACKAGE AGE
provider-gcp-pubsub True True xpkg.upbound.io/upbound/provider-gcp-pubsub:v1.0.0 39s
provider-gcp-storage True True xpkg.upbound.io/upbound/provider-gcp-storage:v1.0.0 13m
upbound-provider-family-gcp True True xpkg.upbound.io/upbound/provider-family-gcp:v1.0.0 12m
```
@ -134,10 +134,10 @@ provider-gcp-storage True True xpkg.crossplane.i
<!-- vale alex.Condescending = NO -->
Crossplane allows you to build your own custom APIs for your users, abstracting
away details about the cloud provider and their resources. You can make your API
as complex or simple as you wish.
as complex or simple as you wish.
<!-- vale alex.Condescending = YES -->
The custom API is a Kubernetes object.
The custom API is a Kubernetes object.
Here is an example custom API.
```yaml {label="exAPI"}
@ -145,39 +145,39 @@ apiVersion: database.example.com/v1alpha1
kind: NoSQL
metadata:
name: my-nosql-database
spec:
spec:
location: "US"
```
Like any Kubernetes object the API has a
{{<hover label="exAPI" line="1">}}version{{</hover>}},
{{<hover label="exAPI" line="2">}}kind{{</hover>}} and
Like any Kubernetes object the API has a
{{<hover label="exAPI" line="1">}}version{{</hover>}},
{{<hover label="exAPI" line="2">}}kind{{</hover>}} and
{{<hover label="exAPI" line="5">}}spec{{</hover>}}.
### Define a group and version
To create your own API start by defining an
[API group](https://kubernetes.io/docs/reference/using-api/#api-groups) and
[version](https://kubernetes.io/docs/reference/using-api/#api-versioning).
To create your own API start by defining an
[API group](https://kubernetes.io/docs/reference/using-api/#api-groups) and
[version](https://kubernetes.io/docs/reference/using-api/#api-versioning).
The _group_ can be any value, but common convention is to map to a fully
qualified domain name.
qualified domain name.
<!-- vale gitlab.SentenceLength = NO -->
The version shows how mature or stable the API is and increments when changing,
adding or removing fields in the API.
<!-- vale gitlab.SentenceLength = YES -->
Crossplane doesn't require specific versions or a specific version naming
convention, but following
Crossplane doesn't require specific versions or a specific version naming
convention, but following
[Kubernetes API versioning guidelines](https://kubernetes.io/docs/reference/using-api/#api-versioning)
is strongly recommended.
is strongly recommended.
* `v1alpha1` - A new API that may change at any time.
* `v1beta1` - An existing API that's considered stable. Breaking changes are
strongly discouraged.
* `v1` - A stable API that doesn't have breaking changes.
* `v1` - A stable API that doesn't have breaking changes.
This guide uses the group
This guide uses the group
{{<hover label="version" line="1">}}database.example.com{{</hover>}}.
Because this is the first version of the API, this guide uses the version
@ -194,10 +194,10 @@ individual kinds representing different resources.
For example a `queue` group may have a `PubSub` and `CloudTask` kinds.
The `kind` can be anything, but it must be
The `kind` can be anything, but it must be
[UpperCamelCased](https://kubernetes.io/docs/contribute/style/style-guide/#use-upper-camel-case-for-api-objects).
This API's kind is
This API's kind is
{{<hover label="kind" line="2">}}PubSub{{</hover>}}
```yaml {label="kind",copy-lines="none"}
@ -208,51 +208,51 @@ kind: PubSub
### Define a spec
The most important part of an API is the schema. The schema defines the inputs
accepted from users.
accepted from users.
This API allows users to provide a
{{<hover label="spec" line="4">}}location{{</hover>}} of where to run their
This API allows users to provide a
{{<hover label="spec" line="4">}}location{{</hover>}} of where to run their
cloud resources.
All other resource settings can't be configurable by the users. This allows
Crossplane to enforce any policies and standards without worrying about
user errors.
user errors.
```yaml {label="spec",copy-lines="none"}
apiVersion: queue.example.com/v1alpha1
kind: PubSub
spec:
spec:
location: "US"
```
### Apply the API
Crossplane uses
{{<hover label="xrd" line="3">}}Composite Resource Definitions{{</hover>}}
Crossplane uses
{{<hover label="xrd" line="3">}}Composite Resource Definitions{{</hover>}}
(also called an `XRD`) to install your custom API in
Kubernetes.
Kubernetes.
The XRD {{<hover label="xrd" line="6">}}spec{{</hover>}} contains all the
information about the API including the
information about the API including the
{{<hover label="xrd" line="7">}}group{{</hover>}},
{{<hover label="xrd" line="12">}}version{{</hover>}},
{{<hover label="xrd" line="9">}}kind{{</hover>}} and
{{<hover label="xrd" line="9">}}kind{{</hover>}} and
{{<hover label="xrd" line="13">}}schema{{</hover>}}.
The XRD's {{<hover label="xrd" line="5">}}name{{</hover>}} must be the
combination of the {{<hover label="xrd" line="9">}}plural{{</hover>}} and
combination of the {{<hover label="xrd" line="9">}}plural{{</hover>}} and
{{<hover label="xrd" line="7">}}group{{</hover>}}.
The {{<hover label="xrd" line="13">}}schema{{</hover>}} uses the
{{<hover label="xrd" line="14">}}OpenAPIv3{{</hover>}} specification to define
the API {{<hover label="xrd" line="17">}}spec{{</hover>}}.
the API {{<hover label="xrd" line="17">}}spec{{</hover>}}.
The API defines a {{<hover label="xrd" line="20">}}location{{</hover>}} that
must be {{<hover label="xrd" line="22">}}oneOf{{</hover>}} either
{{<hover label="xrd" line="23">}}EU{{</hover>}} or
must be {{<hover label="xrd" line="22">}}oneOf{{</hover>}} either
{{<hover label="xrd" line="23">}}EU{{</hover>}} or
{{<hover label="xrd" line="24">}}US{{</hover>}}.
Apply this XRD to create the custom API in your Kubernetes cluster.
Apply this XRD to create the custom API in your Kubernetes cluster.
```yaml {label="xrd",copy-lines="all"}
cat <<EOF | kubectl apply -f -
@ -290,20 +290,20 @@ EOF
```
Adding the {{<hover label="xrd" line="29">}}claimNames{{</hover>}} allows users
to access this API either at the cluster level with the
to access this API either at the cluster level with the
{{<hover label="xrd" line="9">}}pubsub{{</hover>}} endpoint or in a namespace
with the
{{<hover label="xrd" line="29">}}pubsubclaim{{</hover>}} endpoint.
with the
{{<hover label="xrd" line="29">}}pubsubclaim{{</hover>}} endpoint.
The namespace scoped API is a Crossplane _Claim_.
{{<hint "tip" >}}
For more details on the fields and options of Composite Resource Definitions
read the
[XRD documentation]({{<ref "../concepts/composite-resource-definitions">}}).
read the
[XRD documentation]({{<ref "../concepts/composite-resource-definitions">}}).
{{< /hint >}}
View the installed XRD with `kubectl get xrd`.
View the installed XRD with `kubectl get xrd`.
```shell {copy-lines="1"}
kubectl get xrd
@ -325,37 +325,26 @@ When users access the custom API Crossplane takes their inputs and combines them
with a template describing what infrastructure to deploy. Crossplane calls this
template a _Composition_.
The {{<hover label="comp" line="3">}}Composition{{</hover>}} defines all the
The {{<hover label="comp" line="3">}}Composition{{</hover>}} defines all the
cloud resources to deploy.
Each entry in the template
is a full resource definitions, defining all the resource settings and metadata
like labels and annotations.
like labels and annotations.
This template creates a GCP
{{<hover label="comp" line="10">}}Storage{{</hover>}}
{{<hover label="comp" line="11">}}Bucket{{</hover>}} and a
{{<hover label="comp" line="11">}}Bucket{{</hover>}} and a
{{<hover label="comp" line="25">}}PubSub{{</hover>}}
{{<hover label="comp" line="26">}}Topic{{</hover>}}.
This Composition takes the user's
{{<hover label="comp" line="16">}}location{{</hover>}} input and uses it as the
{{<hover label="comp" line="14">}}location{{</hover>}} used in the individual
Crossplane uses {{<hover label="comp" line="15">}}patches{{</hover>}} to apply
the user's input to the resource template.
This Composition takes the user's
{{<hover label="comp" line="16">}}location{{</hover>}} input and uses it as the
{{<hover label="comp" line="14">}}location{{</hover>}} used in the individual
resource.
{{<hint "important" >}}
This Composition uses an array of resource templates. You can patch each
template with data copied from the custom API. Crossplane calls this a _Patch
and Transform_ Composition.
You don't have to use Patch and Transform. Crossplane supports a variety of
alternatives, including Go Templating and CUE. You can also write a function in
Go or Python to template your resources.
Read the [Composition documentation]({{<ref "../concepts/compositions">}}) for
more information on configuring Compositions and all the available options.
{{< /hint >}}
Apply this Composition to your cluster.
Apply this Composition to your cluster.
```yaml {label="comp",copy-lines="all"}
cat <<EOF | kubectl apply -f -
@ -364,47 +353,39 @@ kind: Composition
metadata:
name: topic-with-bucket
spec:
mode: Pipeline
pipeline:
- step: patch-and-transform
functionRef:
name: function-patch-and-transform
input:
apiVersion: pt.fn.crossplane.io/v1beta1
kind: Resources
resources:
- name: crossplane-quickstart-bucket
base:
apiVersion: storage.gcp.upbound.io/v1beta1
kind: Bucket
spec:
forProvider:
location: "US"
patches:
- fromFieldPath: "spec.location"
toFieldPath: "spec.forProvider.location"
transforms:
- type: map
map:
EU: "EU"
US: "US"
- name: crossplane-quickstart-topic
base:
apiVersion: pubsub.gcp.upbound.io/v1beta1
kind: Topic
spec:
forProvider:
messageStoragePolicy:
- allowedPersistenceRegions:
- "us-central1"
patches:
- fromFieldPath: "spec.location"
toFieldPath: "spec.forProvider.messageStoragePolicy[0].allowedPersistenceRegions[0]"
transforms:
- type: map
map:
EU: "europe-central2"
US: "us-central1"
resources:
- name: crossplane-quickstart-bucket
base:
apiVersion: storage.gcp.upbound.io/v1beta1
kind: Bucket
spec:
forProvider:
location: "US"
patches:
- fromFieldPath: "spec.location"
toFieldPath: "spec.forProvider.location"
transforms:
- type: map
map:
EU: "EU"
US: "US"
- name: crossplane-quickstart-topic
base:
apiVersion: pubsub.gcp.upbound.io/v1beta1
kind: Topic
spec:
forProvider:
messageStoragePolicy:
- allowedPersistenceRegions:
- "us-central1"
patches:
- fromFieldPath: "spec.location"
toFieldPath: "spec.forProvider.messageStoragePolicy[0].allowedPersistenceRegions[0]"
transforms:
- type: map
map:
EU: "europe-central2"
US: "us-central1"
compositeTypeRef:
apiVersion: queue.example.com/v1alpha1
kind: PubSub
@ -414,32 +395,14 @@ EOF
The {{<hover label="comp" line="40">}}compositeTypeRef{{</hover >}} defines
which custom APIs can use this template to create resources.
A Composition uses a pipeline of _composition functions_ to define the cloud
resources to deploy. This template uses
{{<hover label="comp" line="10">}}function-patch-and-transform{{</hover>}}.
You must install the function before you can use it in a Composition.
Apply this Function to install `function-patch-and-transform`:
```yaml {label="install"}
cat <<EOF | kubectl apply -f -
apiVersion: pkg.crossplane.io/v1
kind: Function
metadata:
name: function-patch-and-transform
spec:
package: xpkg.crossplane.io/crossplane-contrib/function-patch-and-transform:v0.8.2
EOF
```
{{<hint "tip" >}}
Read the [Composition documentation]({{<ref "../concepts/compositions">}}) for
more information on configuring Compositions and all the available options.
Read the
[Patch and Transform function documentation]({{<ref "../guides/function-patch-and-transform">}})
for more information on how it uses patches to map user inputs to Composition
resource templates.
Read the
[Patch and Transform documentation]({{<ref "../concepts/patch-and-transform">}})
for more information on how Crossplane uses patches to map user inputs to
Composition resource templates.
{{< /hint >}}
View the Composition with `kubectl get composition`
@ -464,7 +427,7 @@ apiVersion: queue.example.com/v1alpha1
kind: PubSub
metadata:
name: my-pubsub-queue
spec:
spec:
location: "US"
EOF
```
@ -477,10 +440,10 @@ NAME SYNCED READY COMPOSITION AGE
my-pubsub-queue True True topic-with-bucket 2m12s
```
This object is a Crossplane _composite resource_ (also called an `XR`).
This object is a Crossplane _composite resource_ (also called an `XR`).
It's a
single object representing the collection of resources created from the
Composition template.
Composition template.
View the individual resources with `kubectl get managed`
@ -513,17 +476,17 @@ No resources found
## Using the API with namespaces
Accessing the API `pubsub` happens at the cluster scope.
Accessing the API `pubsub` happens at the cluster scope.
Most organizations
isolate their users into namespaces.
isolate their users into namespaces.
A Crossplane _Claim_ is the custom API in a namespace.
Creating a _Claim_ is just like accessing the custom API endpoint, but with the
{{<hover label="claim" line="3">}}kind{{</hover>}}
{{<hover label="claim" line="3">}}kind{{</hover>}}
from the custom API's `claimNames`.
Create a new namespace to test create a Claim in.
Create a new namespace to test create a Claim in.
```shell
kubectl create namespace crossplane-test
@ -535,10 +498,10 @@ Then create a Claim in the `crossplane-test` namespace.
cat <<EOF | kubectl apply -f -
apiVersion: queue.example.com/v1alpha1
kind: PubSubClaim
metadata:
metadata:
name: my-pubsub-queue
namespace: crossplane-test
spec:
spec:
location: "US"
EOF
```
@ -551,7 +514,7 @@ my-pubsub-queue True True 2m10s
```
The Claim automatically creates a composite resource, which creates the managed
resources.
resources.
View the Crossplane created composite resource with `kubectl get composite`.
@ -600,9 +563,9 @@ No resources found
```
## Next steps
* Explore AWS resources that Crossplane can configure in the
[provider CRD reference](https://github.com/crossplane-contrib/provider-upjet-aws/blob/main/package/crds).
* Join the [Crossplane Slack](https://slack.crossplane.io/) and connect with
* Explore AWS resources that Crossplane can configure in the
[Provider CRD reference](https://marketplace.upbound.io/providers/upbound/provider-family-aws/).
* Join the [Crossplane Slack](https://slack.crossplane.io/) and connect with
Crossplane users and contributors.
* Read more about the [Crossplane concepts]({{<ref "../concepts">}}) to find out what else you can do
with Crossplane.
with Crossplane.

18
content/v1.20/getting-started/provider-gcp.md → content/v1.16/getting-started/provider-gcp.md
View File

@ -4,8 +4,8 @@ weight: 140
---
Connect Crossplane to GCP to create and manage cloud resources from Kubernetes
with
[provider-upjet-gcp](https://github.com/crossplane-contrib/provider-upjet-gcp).
with the
[Upbound GCP Provider](https://marketplace.upbound.io/providers/upbound/provider-family-gcp/).
This guide is in two parts:
* Part 1 walks through installing Crossplane, configuring the provider to
@ -36,7 +36,7 @@ kind: Provider
metadata:
name: provider-gcp-storage
spec:
package: xpkg.crossplane.io/crossplane-contrib/provider-gcp-storage:v1.12.1
package: xpkg.upbound.io/upbound/provider-gcp-storage:v1.0.0
EOF
```
@ -50,13 +50,13 @@ Verify the provider installed with `kubectl get providers`.
```shell {copy-lines="1",label="getProvider"}
kubectl get providers
NAME INSTALLED HEALTHY PACKAGE AGE
crossplane-contrib-provider-family-gcp True True xpkg.crossplane.io/crossplane-contrib/provider-family-gcp:v1.12.1 33s
provider-gcp-storage True True xpkg.crossplane.io/crossplane-contrib/provider-gcp-storage:v1.12.1 37s
NAME INSTALLED HEALTHY PACKAGE AGE
provider-gcp-storage True True xpkg.upbound.io/upbound/provider-gcp-storage:v1.0.0 36s
upbound-provider-family-gcp True True xpkg.upbound.io/upbound/provider-family-gcp:v1.0.0 29s
```
The Storage Provider installs a second Provider, the
{{<hover label="getProvider" line="4">}}crossplane-contrib-provider-family-gcp{{</hover>}}
{{<hover label="getProvider" line="4">}}upbound-provider-family-gcp{{</hover>}}
provider.
The family provider manages authentication to GCP across all GCP family
Providers.
@ -66,7 +66,7 @@ Every CRD maps to a unique GCP service Crossplane can provision and manage.
{{< hint "tip" >}}
See details about all the supported CRDs in the
[provider examples](https://github.com/crossplane-contrib/provider-upjet-gcp/tree/main/examples).
[Upbound Marketplace](https://marketplace.upbound.io/providers/upbound/provider-family-gcp/).
{{< /hint >}}
@ -246,6 +246,6 @@ bucket.storage.gcp.upbound.io "crossplane-bucket-8b7gw" deleted
* [**Continue to part 2**]({{< ref "provider-gcp-part-2">}}) to create a
Crossplane _Composite Resource_ and _Claim_.
* Explore GCP resources that can Crossplane can configure in the
[Provider CRD reference](https://github.com/crossplane-contrib/provider-upjet-gcp/tree/main/package/crds).
[Provider CRD reference](https://marketplace.upbound.io/providers/upbound/provider-family-gcp/).
* Join the [Crossplane Slack](https://slack.crossplane.io/) and connect with
Crossplane users and contributors.

0
content/v1.19/guides/_index.md → content/v1.16/guides/_index.md
View File

2
content/v1.19/guides/crossplane-with-argo-cd.md → content/v1.16/guides/crossplane-with-argo-cd.md
View File

@ -5,7 +5,7 @@ weight: 270
[Argo CD](https://argoproj.github.io/cd/) and [Crossplane](https://crossplane.io)
are a great combination. Argo CD provides GitOps while Crossplane turns any Kubernetes
cluster into a Universal Control Plane for all of your resources. Configuration details are
cluster into a Universal Control Plane for all of your resources. Configuration details are
required in order for the two to work together properly.
This doc will help you understand these requirements. It is recommended to use
Argo CD version 2.4.8 or later with Crossplane.

0
content/v1.19/guides/disaster-recovery.md → content/v1.16/guides/disaster-recovery.md
View File

6
content/v1.19/guides/import-existing-resources.md → content/v1.16/guides/import-existing-resources.md
View File

@ -5,7 +5,7 @@ weight: 200
If you have resources that are already provisioned in a Provider,
you can import them as managed resources and let Crossplane manage them.
A managed resource's [`managementPolicies`]({{<ref "../concepts/managed-resources#managementpolicies">}})
A managed resource's [`managementPolicies`]({{<ref "/v1.16/concepts/managed-resources#managementpolicies">}})
field enables importing external resources into Crossplane.
Crossplane can import resources either [manually]({{<ref "#import-resources-manually">}})
@ -84,7 +84,7 @@ managed resource `spec` changes the external resource.
## Import resources automatically
Automatically import external resources with an `Observe` [management policy]({{<ref "../concepts/managed-resources#managementpolicies">}}).
Automatically import external resources with an `Observe` [management policy]({{<ref "/v1.16/concepts/managed-resources#managementpolicies">}}).
Crossplane imports observe only resources but never changes or deletes the
resources.
@ -282,4 +282,4 @@ status:
```
Crossplane now fully manages the imported resource. Crossplane applies any
changes to the managed resource in the Provider's external resource.
changes to the managed resource in the Provider's external resource.

6
content/v1.20/guides/multi-tenant.md → content/v1.16/guides/multi-tenant.md
View File

@ -315,9 +315,9 @@ dedicated control planes to many tenants within a single organization.
[Multiple Source Field patching]: https://github.com/crossplane/crossplane/pull/2093
[Configuration packages]: {{<ref "../../master/concepts/packages" >}}
[OCI images]: https://github.com/opencontainers/image-spec
[EKS Cluster]: https://github.com/crossplane-contrib/provider-upjet-aws/blob/main/examples/eks/v1beta2/cluster.yaml
[provider-aws]: https://github.com/crossplane-contrib/provider-upjet-aws
[provider-helm]: https://github.com/crossplane-contrib/provider-helm
[EKS Cluster]: https://marketplace.upbound.io/providers/crossplane-contrib/provider-aws/latest/resources/eks.aws.crossplane.io/Cluster/v1beta1
[provider-aws]: https://marketplace.upbound.io/providers/crossplane-contrib/provider-aws
[provider-helm]: https://marketplace.upbound.io/providers/crossplane-contrib/provider-helm/
[Open Service Broker API]: https://github.com/openservicebrokerapi/servicebroker
[Crossplane Service Broker]: https://github.com/vshn/crossplane-service-broker
[Cloudfoundry]: https://www.cloudfoundry.org/

0
content/v1.19/guides/self-signed-ca-certs.md → content/v1.16/guides/self-signed-ca-certs.md
View File

52
content/v1.19/guides/troubleshoot-crossplane.md → content/v1.16/guides/troubleshoot-crossplane.md
View File

@ -5,15 +5,14 @@ weight: 306
## Requested Resource Not Found
If you use the Crossplane CLI to install a `Provider` or
`Configuration` (for example, `crossplane xpkg install provider
xpkg.crossplane.io/crossplane-contrib/provider-aws-s3:v1.21.1`) and get `the server
`Configuration` (for example, `crossplane install provider
xpkg.upbound.io/crossplane-contrib/provider-aws:v0.33.0`) and get `the server
could not find the requested resource` error, more often than not, that's an
indicator that the Crossplane CLI you're using is outdated. In other words
some Crossplane API has been graduated from alpha to beta or stable and the old
plugin isn't aware of this change.
## Resource Status and Conditions
Most Crossplane resources have a `status` section that can represent the current
@ -81,37 +80,28 @@ kubectl -n crossplane-system logs <name-of-provider-pod>
All providers maintained by the Crossplane community mirror Crossplane's support
of the `--debug` flag. The easiest way to set flags on a provider is to create a
`DeploymentRuntimeConfig` and reference it from the `Provider`:
`ControllerConfig` and reference it from the `Provider`:
```yaml
apiVersion: pkg.crossplane.io/v1beta1
kind: DeploymentRuntimeConfig
apiVersion: pkg.crossplane.io/v1alpha1
kind: ControllerConfig
metadata:
name: debug-config
spec:
deploymentTemplate:
spec:
selector: {}
template:
spec:
containers:
- name: package-runtime
args:
- --debug
args:
- --debug
---
apiVersion: pkg.crossplane.io/v1
kind: Provider
metadata:
name: provider-aws
spec:
package: xpkg.crossplane.io/crossplane-contrib/provider-aws:v0.33.0
runtimeConfigRef:
apiVersion: pkg.crossplane.io/v1beta1
kind: DeploymentRuntimeConfig
package: xpkg.upbound.io/crossplane-contrib/provider-aws:v0.33.0
controllerConfigRef:
name: debug-config
```
> Note that a reference to a `DeploymentRuntimeConfig` can be added to an already
> Note that a reference to a `ControllerConfig` can be added to an already
> installed `Provider` and it will update its `Deployment` accordingly.
## Compositions and composite resource definition
@ -345,35 +335,29 @@ kubectl -n crossplane-system scale --replicas=1 deployment/crossplane
## Pausing Providers
Providers can also be paused when troubleshooting an issue or orchestrating a
complex migration of resources. Creating and referencing a `DeploymentRuntimeConfig` is
the easiest way to scale down a provider, and the `DeploymentRuntimeConfig` can be
complex migration of resources. Creating and referencing a `ControllerConfig` is
the easiest way to scale down a provider, and the `ControllerConfig` can be
modified or the reference can be removed to scale it back up:
```yaml
apiVersion: pkg.crossplane.io/v1beta1
kind: DeploymentRuntimeConfig
apiVersion: pkg.crossplane.io/v1alpha1
kind: ControllerConfig
metadata:
name: scale-config
spec:
deploymentTemplate:
spec:
selector: {}
replicas: 0
template: {}
replicas: 0
---
apiVersion: pkg.crossplane.io/v1
kind: Provider
metadata:
name: provider-aws
spec:
package: xpkg.crossplane.io/crossplane-contrib/provider-aws:v0.33.0
runtimeConfigRef:
apiVersion: pkg.crossplane.io/v1beta1
kind: DeploymentRuntimeConfig
package: xpkg.upbound.io/crossplane-contrib/provider-aws:v0.33.0
controllerConfigRef:
name: scale-config
```
> Note that a reference to a `DeploymentRuntimeConfig` can be added to an already
> Note that a reference to a `ControllerConfig` can be added to an already
> installed `Provider` and it will update its `Deployment` accordingly.
## Deleting When a Resource Hangs

74
content/v1.19/guides/vault-as-secret-store.md → content/v1.16/guides/vault-as-secret-store.md
View File

@ -217,7 +217,7 @@ Next, install the Crossplane ESS Plugin pod to the `crossplane-system` namespace
and apply the Vault annotations.
```shell
helm upgrade --install ess-plugin-vault oci://xpkg.crossplane.io/crossplane-contrib/ess-plugin-vault --namespace crossplane-system -f values.yaml
helm upgrade --install ess-plugin-vault oci://xpkg.upbound.io/crossplane-contrib/ess-plugin-vault --namespace crossplane-system -f values.yaml
```
## Configure Crossplane
@ -255,7 +255,7 @@ kind: Provider
metadata:
name: provider-gcp
spec:
package: xpkg.crossplane.io/crossplane-contrib/provider-gcp:v0.23.0-rc.0.19.ge9b75ee5
package: xpkg.upbound.io/crossplane-contrib/provider-gcp:v0.23.0-rc.0.19.ge9b75ee5
controllerConfigRef:
name: vault-config" | kubectl apply -f -
```
@ -341,7 +341,7 @@ Check that Crossplane installed the Provider and the Provider is healthy.
```shell {copy-lines="1"}
kubectl get providers
NAME INSTALLED HEALTHY PACKAGE AGE
provider-gcp True True xpkg.crossplane.io/crossplane-contrib/provider-gcp:v0.23.0-rc.0.19.ge9b75ee5 10m
provider-gcp True True xpkg.upbound.io/crossplane-contrib/provider-gcp:v0.23.0-rc.0.19.ge9b75ee5 10m
```
### Create a CompositeResourceDefinition
@ -410,47 +410,35 @@ spec:
compositeTypeRef:
apiVersion: ess.example.org/v1alpha1
kind: CompositeESSInstance
mode: Pipeline
pipeline:
- step: patch-and-transform
functionRef:
name: function-patch-and-transform
input:
apiVersion: pt.fn.crossplane.io/v1beta1
kind: Resources
resources:
- name: serviceaccount
base:
apiVersion: iam.gcp.crossplane.io/v1alpha1
kind: ServiceAccount
resources:
- name: serviceaccount
base:
apiVersion: iam.gcp.crossplane.io/v1alpha1
kind: ServiceAccount
metadata:
name: ess-test-sa
spec:
forProvider:
displayName: a service account to test ess
- name: serviceaccountkey
base:
apiVersion: iam.gcp.crossplane.io/v1alpha1
kind: ServiceAccountKey
spec:
forProvider:
serviceAccountSelector:
matchControllerRef: true
publishConnectionDetailsTo:
name: ess-mr-conn
metadata:
name: ess-test-sa
spec:
forProvider:
displayName: a service account to test ess
- name: serviceaccountkey
base:
apiVersion: iam.gcp.crossplane.io/v1alpha1
kind: ServiceAccountKey
spec:
forProvider:
serviceAccountSelector:
matchControllerRef: true
publishConnectionDetailsTo:
name: ess-mr-conn
metadata:
labels:
environment: development
team: backend
configRef:
name: vault
connectionDetails:
- name: publicKey
type: FromConnectionSecretKey
fromConnectionSecretKey: publicKey
- name: publicKey
type: FromConnectionSecretKey
fromConnectionSecretKey: publicKeyType" | kubectl apply -f -
labels:
environment: development
team: backend
configRef:
name: vault
connectionDetails:
- fromConnectionSecretKey: publicKey
- fromConnectionSecretKey: publicKeyType" | kubectl apply -f -
```
### Create a Claim

Some files were not shown because too many files have changed in this diff Show More