Skip to content

full walkthrough for get started with managed resources guide #900

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
negz merged 3 commits into from
Mar 28, 2025
Merged

full walkthrough for get started with managed resources guide #900

Changes from all commits
Commits
Show all changes
3 commits
Select commit Hold shift + click to select a range
0fd8146
full walkthrough for get started with managed resources guide
jbw976 Mar 27, 2025
f78a611
Streamline getting started with managed resources guide by removing f…
jbw976 Mar 28, 2025
3462331
incorporate PR feedback for get started with managed resources page
jbw976 Mar 28, 2025
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
190 changes: 85 additions & 105 deletions content/v2.0-preview/get-started/get-started-with-managed-resources.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -3,10 +3,13 @@ title: Get Started With Managed Resources
weight: 200
---

Connect Crossplane to AWS to create and manage cloud resources from Kubernetes
with
[provider-upjet-aws](https://github.com/crossplane-contrib/provider-upjet-aws).
Connect Crossplane to AWS to create and manage cloud resources from Kubernetes
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
This quickstart requires:
Expand All @@ -17,66 +20,67 @@ This quickstart requires:
* AWS [access keys](https://docs.aws.amazon.com/cli/latest/userguide/cli-configure-quickstart.html#cli-configure-quickstart-creds)

## Install the AWS provider

Install the AWS S3 provider into the Kubernetes cluster with a Kubernetes
configuration file.
Install the AWS S3 provider into the Kubernetes cluster with a Kubernetes
configuration file.

```yaml {label="provider",copy-lines="all"}
cat <<EOF | kubectl apply -f -
apiVersion: pkg.crossplane.io/v1
kind: Provider
metadata:
name: provider-aws-s3
spec:
package: xpkg.crossplane.io/crossplane-contrib/provider-aws-s3:v1.21.1
EOF
package: xpkg.crossplane.io/crossplane-contrib/provider-aws-s3:v1.22.0-crossplane-v2-preview.0
```

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="3" >}}Provider{{</hover>}}
The Crossplane {{< hover label="provider" line="2" >}}Provider{{</hover>}}
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.
Comment on lines 35 to 43
Copy link
Copy Markdown
Member

@negz negz Mar 28, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I'd like to drop all mentions of CRDs here - too much detail for this context IMO.


Verify the provider installed with `kubectl get providers`.
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
crossplane-contrib-provider-family-aws True True xpkg.crossplane.io/crossplane-contrib/provider-family-aws:v1.22.0-crossplane-v2-preview.0 27s
provider-aws-s3 True True xpkg.crossplane.io/crossplane-contrib/provider-aws-s3:v1.22.0-crossplane-v2-preview.0 31s
```

The S3 Provider installs a second Provider, the
{{<hover label="getProvider" line="4">}}crossplane-contrib-provider-family-aws{{</hover >}}.
{{<hover label="getProvider" line="4">}}crossplane-contrib-provider-family-aws{{</hover >}}.
The family provider manages authentication to AWS across all AWS family
Providers.
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.

{{< hint type="tip" >}}
See details about all the supported CRDs in the
{{< hint "tip" >}}
See details about all the supported CRDs in the
[provider examples](https://github.com/crossplane-contrib/provider-upjet-aws/tree/main/examples).
{{< /hint >}}

## Create a Kubernetes secret for AWS
The provider requires credentials to create and manage AWS resources.
The provider requires credentials to create and manage AWS resources.
Providers use a Kubernetes _Secret_ to connect the credentials to the provider.

Generate a Kubernetes _Secret_ from your AWS key-pair and
Generate a Kubernetes _Secret_ from your AWS key-pair and
then configure the Provider to use it.

### 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" >}}
The [AWS documentation](https://docs.aws.amazon.com/cli/latest/userguide/cli-configure-quickstart.html#cli-configure-quickstart-creds)
{{< hint "tip" >}}
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.
{{< /hint >}}

Create a text file containing the AWS account `aws_access_key_id` and `aws_secret_access_key`.
Create a text file containing the AWS account `aws_access_key_id` and `aws_secret_access_key`.

{{< editCode >}}
```ini {copy-lines="all"}
Expand All @@ -88,17 +92,17 @@ aws_secret_access_key = $@<aws_secret_key>$@

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.
{{< /hint >}}

### Create a Kubernetes secret with the AWS credentials
A Kubernetes generic secret has a name and contents.
Use
{{< hover label="kube-create-secret" line="1">}}kubectl create secret{{</hover >}}
to generate the secret object named
{{< hover label="kube-create-secret" line="2">}}aws-secret{{< /hover >}}
in the {{< hover label="kube-create-secret" line="3">}}crossplane-system{{</ hover >}} namespace.
A Kubernetes generic secret has a name and contents.
Use
{{< hover label="kube-create-secret" line="1">}}kubectl create secret{{</hover >}}
to generate the secret object named
{{< hover label="kube-create-secret" line="2">}}aws-secret{{< /hover >}}
in the {{< hover label="kube-create-secret" line="3">}}crossplane-system{{</ hover >}} namespace.

Use the {{< hover label="kube-create-secret" line="4">}}--from-file={{</hover>}} argument to set the value to the contents of the {{< hover label="kube-create-secret" line="4">}}aws-credentials.txt{{< /hover >}} file.

Expand All @@ -109,35 +113,11 @@ generic aws-secret \
--from-file=creds=./aws-credentials.txt
```

View the secret with `kubectl describe secret`

{{< hint type="note" >}}
The size may be larger if there are extra blank spaces in your text file.
{{< /hint >}}

```shell {copy-lines="1"}
kubectl describe secret aws-secret -n crossplane-system
Name: aws-secret
Namespace: crossplane-system
Labels: <none>
Annotations: <none>

Type: Opaque

Data
====
creds: 114 bytes
```

## Create a ProviderConfig
A {{< hover label="providerconfig" line="3">}}ProviderConfig{{</ hover >}}
customizes the settings of the AWS Provider.
A {{< hover label="providerconfig" line="2">}}ProviderConfig{{</ hover >}}
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"}
cat <<EOF | kubectl apply -f -
apiVersion: aws.upbound.io/v1beta1
kind: ProviderConfig
metadata:
Expand All @@ -149,83 +129,83 @@ spec:
namespace: crossplane-system
name: aws-secret
key: creds
EOF
```

This attaches the AWS credentials, saved as a Kubernetes secret, as a
{{< hover label="providerconfig" line="9">}}secretRef{{</ hover>}}.
Save this to a file called `providerconfig.yaml`, then apply it with:

The
{{< hover label="providerconfig" line="11">}}spec.credentials.secretRef.name{{< /hover >}}
value is the name of the Kubernetes secret containing the AWS credentials in the
{{< hover label="providerconfig" line="10">}}spec.credentials.secretRef.namespace{{< /hover >}}.
```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
{{< hover label="providerconfig" line="8">}}secretRef{{</ hover>}}.

## Create a managed resource
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_.

{{< hint type="note" >}}
AWS S3 bucket names must be globally unique. To generate a unique name the example uses a random hash.
{{< hint "note" >}}
AWS S3 bucket names must be globally unique. To generate a unique name the example uses a random hash.
Any unique name is acceptable.
{{< /hint >}}

```yaml {label="xr"}
cat <<EOF | kubectl create -f -
apiVersion: s3.aws.upbound.io/v1beta1
```yaml {label="bucket"}
apiVersion: s3.aws.m.upbound.io/v1beta1
kind: Bucket
metadata:
namespace: default
generateName: crossplane-bucket-
spec:
forProvider:
region: us-east-2
providerConfigRef:
name: default
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="5">}}metadata.generateName{{< /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.
Save this to a file called `bucket.yaml`, then apply it with:

The {{< hover label="xr" line="8">}}spec.forProvider.region{{< /hover >}} tells
AWS which AWS region to use when deploying resources.
```shell {label="kube-create-bucket",copy-lines="all"}
kubectl create -f bucket.yaml
```

The region can be any
[AWS Regional endpoint](https://docs.aws.amazon.com/general/latest/gr/rande.html#regional-endpoints) code.
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>`.

Use `kubectl get buckets` 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" >}}
Crossplane created the bucket when the values `READY` and `SYNCED` are `True`.
This may take up to 5 minutes.
{{< hint "tip" >}}
Crossplane created the bucket when the values `READY` and `SYNCED` are `True`.
This may take up to 5 minutes.
{{< /hint >}}

```shell {copy-lines="1"}
kubectl get buckets
NAME READY SYNCED EXTERNAL-NAME AGE
crossplane-bucket-hhdzh True True crossplane-bucket-hhdzh 5s
kubectl -n default get buckets.s3.aws.m.upbound.io
NAME SYNCED READY EXTERNAL-NAME AGE
crossplane-bucket-7tfcj True True crossplane-bucket-7tfcj 3m4s
```

## Delete the managed resource
Before shutting down your Kubernetes cluster, delete the S3 bucket just created.

Use `kubectl delete bucket <bucketname>` to remove the bucket.
When you are finished with your S3 bucket, use `kubectl -n default
delete buckets.s3.aws.m.upbound.io <bucketname>` to remove the bucket.

```shell {copy-lines="1"}
kubectl delete bucket crossplane-bucket-hhdzh
bucket.s3.aws.upbound.io "crossplane-bucket-hhdzh" deleted
kubectl -n default delete buckets.s3.aws.m.upbound.io crossplane-bucket-7tfcj
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
Crossplane allows you to compose **any type of resource** into custom APIs for
Copy link
Copy Markdown
Member

@negz negz Mar 28, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Vale hack: it thinks "type of" is too wordy but "kind of" is fine. 🙃

your users, which includes managed resources. Enjoy the freedom that Crossplane
gives you to compose the diverse set of resources your applications need for
their unique environments, scenarios, and requirements.

Follow [Get Started with Composition]({{<ref "../get-started/get-started-with-composition">}})
to learn more about how composition works.

## Next steps
* Join the [Crossplane Slack](https://slack.crossplane.io/) and connect with
* Join the [Crossplane Slack](https://slack.crossplane.io/) and connect with
Crossplane users and contributors.
Loading