Skip to main content

Get Started With Managed Resources

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:

apiVersion: s3.aws.m.upbound.io/v1beta1
kind: Bucket
metadata:
  namespace: default
  name: crossplane-bucket-example
spec:
  forProvider:
    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:

  1. Install the provider
  2. Save the provider's credentials as a secret
  3. 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:

apiVersion: pkg.crossplane.io/v1
kind: Provider
metadata:
  name: crossplane-contrib-provider-aws-s3
spec:
  package: xpkg.crossplane.io/crossplane-contrib/provider-aws-s3:v1.22.0-crossplane-v2-preview.0

Save this as provider.yaml and apply it:

kubectl apply -f provider.yaml

Check that Crossplane installed the provider:

kubectl get providers
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
crossplane-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:

[default] aws_access_key_id = AWS_ACCESS_KEY aws_secret_access_key = AWS_SECRET_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:

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

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 configurationproviderconfig customizes the settings of the AWS Provider. All providers need a configuration to tell them where to load credentials. Create this provider configuration:

apiVersion: aws.upbound.io/v1beta1
kind: ProviderConfig
metadata:
  name: default
spec:
  credentials:
    source: Secret
    secretRef:
      namespace: crossplane-system
      name: aws-secret
      key: creds

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

kubectl 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.

apiVersion: s3.aws.m.upbound.io/v1beta1
kind: Bucket
metadata:
  namespace: default
  generateName: crossplane-bucket-
spec:
  forProvider:
    region: us-east-2

Save the bucket to bucket.yaml and apply it:

kubectl create -f bucket.yaml

Check that Crossplane created the bucket:

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

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

Delete the bucket:

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

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

warning

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.