mirror of https://github.com/crossplane/docs.git
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
parent
f78a611aaf
commit
3462331316
|
|
@ -6,6 +6,10 @@ 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).
|
||||
|
||||
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:
|
||||
|
|
@ -15,50 +19,25 @@ This quickstart requires:
|
|||
* 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)
|
||||
|
||||
## 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 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.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
|
||||
services. These CRDs allow you to create AWS resources directly inside
|
||||
Kubernetes.
|
||||
|
|
@ -81,7 +60,7 @@ Providers.
|
|||
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" >}}
|
||||
{{< 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 >}}
|
||||
|
|
@ -96,7 +75,7 @@ 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.
|
||||
|
||||
{{< hint type="tip" >}}
|
||||
{{< 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 >}}
|
||||
|
|
@ -113,7 +92,7 @@ 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 >}}
|
||||
|
||||
|
|
@ -135,14 +114,10 @@ generic aws-secret \
|
|||
```
|
||||
|
||||
## 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:
|
||||
|
|
@ -154,73 +129,79 @@ spec:
|
|||
namespace: crossplane-system
|
||||
name: aws-secret
|
||||
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
|
||||
{{< hover label="providerconfig" line="9">}}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
|
||||
```
|
||||
{{< hover label="providerconfig" line="8">}}secretRef{{</ hover>}}.
|
||||
|
||||
## 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.
|
||||
Any unique name is acceptable.
|
||||
{{< /hint >}}
|
||||
|
||||
```yaml {label="xr"}
|
||||
cat <<EOF | kubectl create -f -
|
||||
```yaml {label="bucket"}
|
||||
apiVersion: s3.aws.m.upbound.io/v1beta1
|
||||
kind: Bucket
|
||||
metadata:
|
||||
namespace: crossplane-aws-app
|
||||
namespace: default
|
||||
generateName: crossplane-bucket-
|
||||
spec:
|
||||
forProvider:
|
||||
region: us-east-2
|
||||
providerConfigRef:
|
||||
name: default
|
||||
EOF
|
||||
```
|
||||
|
||||
The {{< hover label="xr" line="6">}}metadata.generateName{{< /hover >}} gives a
|
||||
pattern that the provider will use to create a unique name for the bucket in S3.
|
||||
Save this to a file called `bucket.yaml`, then apply it with:
|
||||
|
||||
```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>`.
|
||||
|
||||
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`.
|
||||
This may take up to 5 minutes.
|
||||
{{< /hint >}}
|
||||
|
||||
```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
|
||||
crossplane-bucket-7tfcj True True crossplane-bucket-7tfcj 3m4s
|
||||
```
|
||||
|
||||
## Delete the managed resource
|
||||
Before shutting down your Kubernetes cluster, delete the S3 bucket that was just created.
|
||||
|
||||
Use `kubectl -n crossplane-aws-app delete buckets.s3.aws.m.upbound.io <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 -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
|
||||
```
|
||||
|
||||
{{< 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 v2 allows you to compose **any type of resource** into custom APIs
|
||||
for your users, which includes managed resources. Enjoy the freedom that
|
||||
Crossplane v2 gives you to compose the diverse set of resources your
|
||||
applications need for their unique environments, scenarios, and requirements.
|
||||
Crossplane allows you to compose **any type of resource** into custom APIs for
|
||||
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.
|
||||
|
|
|
|||
Loading…
Reference in New Issue