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

incorporate PR feedback for get started with managed resources page 

Signed-off-by: Jared Watts <jbw976@gmail.com>
This commit is contained in:
Jared Watts 2025-03-27 19:26:17 -07:00
parent f78a611aaf
commit 3462331316
No known key found for this signature in database
GPG Key ID: 0467EEAE3B6EC0D2
1 changed files with 49 additions and 68 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

117
content/v2.0-preview/get-started/get-started-with-managed-resources.md
View File

@ -6,6 +6,10 @@ weight: 200
Connect Crossplane to AWS to create and manage cloud resources from Kubernetes 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 [provider-upjet-aws](https://github.com/crossplane-contrib/provider-upjet-aws).
A _managed resource_ is anything Crossplane creates and manages outside of the
control plane.
This guide creates an AWS S3 bucket with Crossplane. The S3 bucket is a _managed resource_.
## Prerequisites ## Prerequisites
This quickstart requires: This quickstart requires:
@ -15,50 +19,25 @@ This quickstart requires:
* An AWS account with permissions to create an S3 storage bucket * An AWS account with permissions to create an S3 storage bucket
* AWS [access keys](https://docs.aws.amazon.com/cli/latest/userguide/cli-configure-quickstart.html#cli-configure-quickstart-creds) * AWS [access keys](https://docs.aws.amazon.com/cli/latest/userguide/cli-configure-quickstart.html#cli-configure-quickstart-creds)
## About Managed Resources in Crossplane v2
A _managed resource_ is anything Crossplane creates and manages outside of the
Kubernetes cluster.
This guide creates an AWS S3 bucket with Crossplane.
The S3 bucket is a _managed resource_.
Crossplane v2 allows you to compose namespaced resources. To better support this
new ability, managed resources (MRs) are now namespaced in Providers that have
been updated for Crossplane v2.
To support backwards compatibility while users are adopting Crossplane v2, each
provider will offer the legacy cluster scoped MRs in addition to the new
namespaced MRs.
For example, when the AWS provider that has been upated to support Crossplane v2
is installed during this guide, you will see two CRDs for each type of managed
resource:
1. A legacy cluster scoped MR in the `*.aws.upbound.io` API group
1. A namespaced MR in the `*.aws.m.upbound.io` API group
{{< hint type="tip" >}}
More about namespaced managed resources can be read in the [Crossplane v2 proposal](https://github.com/crossplane/crossplane/pull/6255).
{{< /hint >}}
## Install the AWS provider ## Install the AWS provider
Install the AWS S3 provider into the Kubernetes cluster with a Kubernetes Install the AWS S3 provider into the Kubernetes cluster with a Kubernetes
configuration file. configuration file.
```yaml {label="provider",copy-lines="all"} ```yaml {label="provider",copy-lines="all"}
cat <<EOF | kubectl apply -f -
apiVersion: pkg.crossplane.io/v1 apiVersion: pkg.crossplane.io/v1
kind: Provider kind: Provider
metadata: metadata:
name: provider-aws-s3 name: provider-aws-s3
spec: spec:
package: xpkg.crossplane.io/crossplane-contrib/provider-aws-s3:v1.22.0-crossplane-v2-preview.0 package: xpkg.crossplane.io/crossplane-contrib/provider-aws-s3:v1.22.0-crossplane-v2-preview.0
EOF
``` ```
The Crossplane {{< hover label="provider" line="3" >}}Provider{{</hover>}} Save this to a file called `provider.yaml`, then apply it with:
```shell {label="kube-apply-provider",copy-lines="all"}
kubectl apply -f provider.yaml
```
The Crossplane {{< hover label="provider" line="2" >}}Provider{{</hover>}}
installs the Kubernetes _Custom Resource Definitions_ (CRDs) representing AWS S3 installs the Kubernetes _Custom Resource Definitions_ (CRDs) representing AWS S3
services. These CRDs allow you to create AWS resources directly inside services. These CRDs allow you to create AWS resources directly inside
Kubernetes. Kubernetes.
@ -81,7 +60,7 @@ Providers.
You can view the new CRDs with `kubectl get crds`. You can view the new CRDs with `kubectl get crds`.
Every CRD maps to a unique AWS service Crossplane can provision and manage. Every CRD maps to a unique AWS service Crossplane can provision and manage.
{{< hint type="tip" >}} {{< hint "tip" >}}
See details about all the supported CRDs in the See details about all the supported CRDs in the
[provider examples](https://github.com/crossplane-contrib/provider-upjet-aws/tree/main/examples). [provider examples](https://github.com/crossplane-contrib/provider-upjet-aws/tree/main/examples).
{{< /hint >}} {{< /hint >}}
@ -96,7 +75,7 @@ then configure the Provider to use it.
### Generate an AWS key-pair file ### Generate an AWS key-pair file
For basic user authentication, use an AWS Access keys key-pair file. For basic user authentication, use an AWS Access keys key-pair file.
{{< hint type="tip" >}} {{< hint "tip" >}}
The [AWS documentation](https://docs.aws.amazon.com/cli/latest/userguide/cli-configure-quickstart.html#cli-configure-quickstart-creds) The [AWS documentation](https://docs.aws.amazon.com/cli/latest/userguide/cli-configure-quickstart.html#cli-configure-quickstart-creds)
provides information on how to generate AWS Access keys. provides information on how to generate AWS Access keys.
{{< /hint >}} {{< /hint >}}
@ -113,7 +92,7 @@ aws_secret_access_key = $@<aws_secret_key>$@
Save this text file as `aws-credentials.txt`. Save this text file as `aws-credentials.txt`.
{{< hint type="note" >}} {{< hint "note" >}}
The [Authentication](https://docs.upbound.io/providers/provider-aws/authentication/) section of the AWS Provider documentation describes other authentication methods. The [Authentication](https://docs.upbound.io/providers/provider-aws/authentication/) section of the AWS Provider documentation describes other authentication methods.
{{< /hint >}} {{< /hint >}}
@ -135,14 +114,10 @@ generic aws-secret \
``` ```
## Create a ProviderConfig ## Create a ProviderConfig
A {{< hover label="providerconfig" line="3">}}ProviderConfig{{</ hover >}} A {{< hover label="providerconfig" line="2">}}ProviderConfig{{</ hover >}}
customizes the settings of the AWS Provider. customizes the settings of the AWS Provider:
Apply the
{{< hover label="providerconfig" line="3">}}ProviderConfig{{</ hover >}}
with the this Kubernetes configuration file:
```yaml {label="providerconfig",copy-lines="all"} ```yaml {label="providerconfig",copy-lines="all"}
cat <<EOF | kubectl apply -f -
apiVersion: aws.upbound.io/v1beta1 apiVersion: aws.upbound.io/v1beta1
kind: ProviderConfig kind: ProviderConfig
metadata: metadata:
@ -154,73 +129,79 @@ spec:
namespace: crossplane-system namespace: crossplane-system
name: aws-secret name: aws-secret
key: creds key: creds
EOF ```
Save this to a file called `providerconfig.yaml`, then apply it with:
```shell {label="kube-apply-providerconfig",copy-lines="all"}
kubectl apply -f providerconfig.yaml
``` ```
This attaches the AWS credentials, saved as a Kubernetes secret, as a This attaches the AWS credentials, saved as a Kubernetes secret, as a
{{< hover label="providerconfig" line="9">}}secretRef{{</ hover>}}. {{< hover label="providerconfig" line="8">}}secretRef{{</ hover>}}.
## Create a namespace
Before we can create our namespaced S3 bucket managed resource, we must create a
namespace for it.
```shell {label="kube-create-namespace",copy-lines="all"}
kubectl create namespace crossplane-aws-app
```
## Create a managed resource ## Create a managed resource
{{< hint type="note" >}} {{< hint "note" >}}
AWS S3 bucket names must be globally unique. To generate a unique name the example uses a random hash. AWS S3 bucket names must be globally unique. To generate a unique name the example uses a random hash.
Any unique name is acceptable. Any unique name is acceptable.
{{< /hint >}} {{< /hint >}}
```yaml {label="xr"} ```yaml {label="bucket"}
cat <<EOF | kubectl create -f -
apiVersion: s3.aws.m.upbound.io/v1beta1 apiVersion: s3.aws.m.upbound.io/v1beta1
kind: Bucket kind: Bucket
metadata: metadata:
namespace: crossplane-aws-app namespace: default
generateName: crossplane-bucket- generateName: crossplane-bucket-
spec: spec:
forProvider: forProvider:
region: us-east-2 region: us-east-2
providerConfigRef: providerConfigRef:
name: default name: default
EOF
``` ```
The {{< hover label="xr" line="6">}}metadata.generateName{{< /hover >}} gives a Save this to a file called `bucket.yaml`, then apply it with:
pattern that the provider will use to create a unique name for the bucket in S3.
```shell {label="kube-create-bucket",copy-lines="all"}
kubectl create -f bucket.yaml
```
The {{< hover label="bucket" line="5">}}metadata.generateName{{< /hover >}} gives a
pattern that Kubernetes will use to create a unique name for the bucket in S3.
The generated name will look like `crossplane-bucket-<hash>`. The generated name will look like `crossplane-bucket-<hash>`.
Use `kubectl -n crossplane-aws-app get buckets.s3.aws.m.upbound.io` to verify Crossplane created the bucket. Use `kubectl -n default get buckets.s3.aws.m.upbound.io` to verify Crossplane created the bucket.
{{< hint type="tip" >}} {{< hint "tip" >}}
Crossplane created the bucket when the values `READY` and `SYNCED` are `True`. Crossplane created the bucket when the values `READY` and `SYNCED` are `True`.
This may take up to 5 minutes. This may take up to 5 minutes.
{{< /hint >}} {{< /hint >}}
```shell {copy-lines="1"} ```shell {copy-lines="1"}
kubectl -n crossplane-aws-app get buckets.s3.aws.m.upbound.io kubectl -n default get buckets.s3.aws.m.upbound.io
NAME SYNCED READY EXTERNAL-NAME AGE NAME SYNCED READY EXTERNAL-NAME AGE
crossplane-bucket-7tfcj True True crossplane-bucket-7tfcj 3m4s crossplane-bucket-7tfcj True True crossplane-bucket-7tfcj 3m4s
``` ```
## Delete the managed resource ## Delete the managed resource
Before shutting down your Kubernetes cluster, delete the S3 bucket that was just created. When you are finished with your S3 bucket, use `kubectl -n default
delete buckets.s3.aws.m.upbound.io <bucketname>` to remove the bucket.
Use `kubectl -n crossplane-aws-app delete buckets.s3.aws.m.upbound.io <bucketname>` to remove the bucket.
```shell {copy-lines="1"} ```shell {copy-lines="1"}
kubectl -n crossplane-aws-app delete buckets.s3.aws.m.upbound.io crossplane-bucket-7tfcj kubectl -n default delete buckets.s3.aws.m.upbound.io crossplane-bucket-7tfcj
bucket.s3.aws.m.upbound.io "crossplane-bucket-7tfcj" deleted bucket.s3.aws.m.upbound.io "crossplane-bucket-7tfcj" deleted
``` ```
{{< hint "important" >}}
Make sure to delete the S3 bucket before uninstalling the provider or shutting
down your control plane. If those are no longer running, they can't clean up any
managed resources and you would need to do so manually.
{{< /hint >}}
## Composing managed resources ## Composing managed resources
Crossplane v2 allows you to compose **any type of resource** into custom APIs Crossplane allows you to compose **any type of resource** into custom APIs for
for your users, which includes managed resources. Enjoy the freedom that your users, which includes managed resources. Enjoy the freedom that Crossplane
Crossplane v2 gives you to compose the diverse set of resources your gives you to compose the diverse set of resources your applications need for
applications need for their unique environments, scenarios, and requirements. their unique environments, scenarios, and requirements.
Follow [Get Started with Composition]({{<ref "../get-started/get-started-with-composition">}}) Follow [Get Started with Composition]({{<ref "../get-started/get-started-with-composition">}})
to learn more about how composition works. to learn more about how composition works.