Get Started With Managed Resources

On this page

This guide shows how to install and use a new kind of custom resource called Bucket. When a user calls the custom resource API to create a Bucket, Crossplane creates a bucket in AWS S3.

Crossplane calls this a managed resource. A managed resource is a ready-made custom resource that manages something outside of the control plane.

A Bucket managed resource looks like this:

1apiVersion: s3.aws.m.upbound.io/v1beta1
2kind: Bucket
3metadata:
4  namespace: default
5  name: crossplane-bucket-example
6spec:
7  forProvider:
8    region: us-east-2

Note

Kubernetes calls third party API resources custom resources.

Prerequisites

This guide requires:

A Kubernetes cluster with at least 2 GB of RAM
Crossplane v2 installed on the Kubernetes cluster
An AWS account with permissions to create an S3 storage bucket
AWS access keys

Install support for the managed resource

Follow these steps to install support for the Bucket managed resource:

Install the provider
Save the provider’s credentials as a secret
Configure the provider to use the secret

After you complete these steps you can use the Bucket managed resource.

Install the provider

A Crossplane provider installs support for a set of related managed resources. The AWS S3 provider installs support for all the AWS S3 managed resources.

Create this provider to install the AWS S3 provider:

1apiVersion: pkg.crossplane.io/v1
2kind: Provider
3metadata:
4  name: crossplane-contrib-provider-aws-s3
5spec:
6  package: xpkg.crossplane.io/crossplane-contrib/provider-aws-s3:v2.0.0

1kubectl apply -f https://docs.crossplane.io/latest/manifests/get-started/managed-resources/provider.yaml

Check that Crossplane installed the provider:

1kubectl get providers
2NAME                                     INSTALLED   HEALTHY   PACKAGE                                                                                     AGE
3crossplane-contrib-provider-family-aws   True        True      xpkg.crossplane.io/crossplane-contrib/provider-family-aws:v2.0.0   27s
4crossplane-contrib-provider-aws-s3       True        True      xpkg.crossplane.io/crossplane-contrib/provider-aws-s3:v2.0.0       31s

Note

The S3 provider installs a second provider, the crossplane-contrib-provider-family-aws. The family provider manages authentication to AWS across all AWS family providers.

Crossplane installed the AWS S3 provider. The provider needs credentials to connect to AWS. Before you can use managed resources, you have to save the provider’s credentials and configure the provider to use them.

Save the provider’s credentials

The provider needs credentials to create and manage AWS resources. Providers use a Kubernetes secret to connect the credentials to the provider.

Generate a secret from your AWS key-pair.

Tip

The AWS documentation provides information on how to generate AWS Access keys.

Create a file containing the AWS account aws_access_key_id and aws_secret_access_key:

1[default]
2aws_access_key_id = 
3aws_secret_access_key =

Save the text file as aws-credentials.ini.

Note

The Authentication section of the AWS Provider documentation describes other authentication methods.

Create a secret from the text file:

1kubectl create secret generic aws-secret \
2  --namespace=crossplane-system \
3  --from-file=creds=./aws-credentials.ini

Important

Crossplane providers don’t have to store their credentials in a secret. They can load their credentials from multiple sources.

Next, configure the provider to use the credentials.

Configure the provider

A provider configuration customizes the settings of the AWS Provider.

All providers need a configuration to tell them where to load credentials.

Create this cluster-wide provider configuration:

 1apiVersion: aws.m.upbound.io/v1beta1
 2kind: ClusterProviderConfig
 3metadata:
 4  name: default
 5spec:
 6  credentials:
 7    source: Secret
 8    secretRef:
 9      namespace: crossplane-system
10      name: aws-secret
11      key: creds

1kubectl apply -f https://docs.crossplane.io/latest/manifests/get-started/managed-resources/providerconfig.yaml

This tells the provider to load credentials from the secret.

Note

This example uses a ClusterProviderConfig that applies to managed resources across all namespaces.

You can also use a namespaced ProviderConfig that only applies to managed resources in a specific namespace. See the providerConfigRef section in the managed resources docs for more details.

Use the managed resource

Note

AWS S3 bucket names must be globally unique. This example uses generateName to generate a random name. Any unique name is acceptable.

1apiVersion: s3.aws.m.upbound.io/v1beta1
2kind: Bucket
3metadata:
4  namespace: default
5  generateName: crossplane-bucket-
6spec:
7  forProvider:
8    region: us-east-2

1kubectl create -f https://docs.crossplane.io/latest/manifests/get-started/managed-resources/bucket.yaml

Check that Crossplane created the bucket:

1kubectl get buckets.s3.aws.m.upbound.io
2NAME                      SYNCED   READY   EXTERNAL-NAME             AGE
3crossplane-bucket-7tfcj   True     True    crossplane-bucket-7tfcj   3m4s

Tip

Crossplane created the bucket when the values READY and SYNCED are True.

Delete the bucket:

1kubectl delete buckets.s3.aws.m.upbound.io crossplane-bucket-7tfcj
2bucket.s3.aws.m.upbound.io "crossplane-bucket-7tfcj" deleted

When you delete the bucket managed resource, Crossplane deletes the S3 bucket from AWS.

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.

Next steps

Crossplane allows you to compose any kind 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 to learn more about how composition works.