Get Started With Managed Resources

On this page

This document is for a preview version of Crossplane.

This document applies to Crossplane v2.0-preview and not to the latest release v1.19.

Don't use Crossplane v2.0-preview in production.

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
The Crossplane v2 preview installed on the Kubernetes cluster
An AWS account with permissions to create an S3 storage bucket
AWS access keys

Note

Only AWS managed resources support the Crossplane v2 preview.

Maintainers will update the managed resources for other systems including Azure, GCP, Terraform, Helm, GitHub, etc to support Crossplane v2 soon.

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:v1.22.0-crossplane-v2-preview.0

Save this as provider.yaml and apply it:

1kubectl apply -f 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:v1.22.0-crossplane-v2-preview.0   27s
4crossplane-contrib-provider-aws-s3       True        True      xpkg.crossplane.io/crossplane-contrib/provider-aws-s3:v1.22.0-crossplane-v2-preview.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 various 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 provider configuration:

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

Save the provider configuration as providerconfig.yaml and apply it:

1kubectl apply -f providerconfig.yaml

This tells the provider to load credentials from the secret.

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

Save the bucket to bucket.yaml and apply it:

1kubectl create -f 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.