docs/content/v1.18/getting-started/provider-aws.md

title	weight
AWS Quickstart	100

Connect Crossplane to AWS to create and manage cloud resources from Kubernetes with the Upbound AWS Provider.

This guide is in two parts:

• Part 1 walks through installing Crossplane, configuring the provider to authenticate to AWS and creating a Managed Resource in AWS directly from your Kubernetes cluster. This shows Crossplane can communicate with AWS.
• [Part 2]({{< ref "provider-aws-part-2" >}}) shows how to build and access a custom API with Crossplane.

Prerequisites

This quickstart requires:

• a Kubernetes cluster with at least 2 GB of RAM
• permissions to create pods and secrets in the Kubernetes cluster
• Helm version v3.2.0 or later
• an AWS account with permissions to create an S3 storage bucket
• AWS access keys

{{}}

Install the AWS provider

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

cat <<EOF | kubectl apply -f -
apiVersion: pkg.crossplane.io/v1
kind: Provider
metadata:
  name: provider-aws-s3
spec:
  package: xpkg.upbound.io/upbound/provider-aws-s3:v1.17.0
EOF

The Crossplane {{< hover label="provider" line="3" >}}Provider{{}} installs the Kubernetes Custom Resource Definitions (CRDs) representing AWS S3 services. These CRDs allow you to create AWS resources directly inside Kubernetes.

Verify the provider installed with kubectl get providers.

kubectl get providers
NAME                          INSTALLED   HEALTHY   PACKAGE                                               AGE
provider-aws-s3               True        True      xpkg.upbound.io/upbound/provider-aws-s3:1.1.0         97s
upbound-provider-family-aws   True        True      xpkg.upbound.io/upbound/provider-family-aws:1.1.0     88s

The S3 Provider installs a second Provider, the {{}}upbound-provider-family-aws{{}}.
The family provider manages authentication to AWS across all AWS family 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" >}} See details about all the supported CRDs in the Upbound Marketplace. {{< /hint >}}

Create a Kubernetes secret for AWS

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 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" >}} The AWS documentation 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.

{{< editCode >}}

[default]
aws_access_key_id = $@<aws_access_key>$@
aws_secret_access_key = $@<aws_secret_key>$@

{{< /editCode >}}

Save this text file as aws-credentials.txt.

{{< hint type="note" >}} The 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{{}}
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={{}} argument to set the value to the contents of the {{< hover label="kube-create-secret" line="4">}}aws-credentials.txt{{< /hover >}} file.

kubectl create secret \
generic aws-secret \
-n crossplane-system \
--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 >}}

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.

Apply the {{< hover label="providerconfig" line="3">}}ProviderConfig{{</ hover >}} with the this Kubernetes configuration file:

cat <<EOF | kubectl apply -f -
apiVersion: aws.upbound.io/v1beta1
kind: ProviderConfig
metadata:
  name: default
spec:
  credentials:
    source: Secret
    secretRef:
      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>}}.

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

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. Any unique name is acceptable. {{< /hint >}}

cat <<EOF | kubectl create -f -
apiVersion: s3.aws.upbound.io/v1beta1
kind: Bucket
metadata:
  generateName: crossplane-bucket-
spec:
  forProvider:
    region: us-east-2
  providerConfigRef:
    name: default
EOF

The {{< hover label="xr" line="3">}}apiVersion{{< /hover >}} and {{< hover label="xr" line="4">}}kind{{}} are from the provider's CRDs.

The {{< hover label="xr" line="6">}}metadata.name{{< /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="6">}}$bucket{{}} variable.

The {{< hover label="xr" line="9">}}spec.forProvider.region{{< /hover >}} tells AWS which AWS region to use when deploying resources.

The region can be any AWS Regional endpoint code.

Use kubectl get buckets 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 >}}

kubectl get buckets
NAME                      READY   SYNCED   EXTERNAL-NAME             AGE
crossplane-bucket-hhdzh   True    True     crossplane-bucket-hhdzh   5s

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.

kubectl delete bucket crossplane-bucket-hhdzh
bucket.s3.aws.upbound.io "crossplane-bucket-hhdzh" deleted

Next steps

• [Continue to part 2]({{< ref "provider-aws-part-2">}}) to create and use a custom API with Crossplane.
• Explore AWS resources that Crossplane can configure in the Provider CRD reference.
• Join the Crossplane Slack and connect with Crossplane users and contributors.