---
title: AWS Quickstart
weight: 100
---

Connect Crossplane to AWS to create and manage cloud resources from Kubernetes 
with  
[provider-upjet-aws](https://github.com/crossplane-contrib/provider-upjet-aws).

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](https://helm.sh/) version v3.2.0 or later
* 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)

{{<include file="/master/getting-started/install-crossplane-include.md" type="page" >}}

## 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.21.1
EOF
```

The Crossplane {{< hover label="provider" line="3" >}}Provider{{</hover>}}
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`. 


```shell {copy-lines="1",label="getProvider"}
kubectl get providers
NAME                                     INSTALLED   HEALTHY   PACKAGE                                                             AGE
crossplane-contrib-provider-family-aws   True        True      xpkg.crossplane.io/crossplane-contrib/provider-family-aws:v1.21.1   30s
provider-aws-s3                          True        True      xpkg.crossplane.io/crossplane-contrib/provider-aws-s3:v1.21.1       34s
```

The S3 Provider installs a second Provider, the
{{<hover label="getProvider" line="4">}}crossplane-contrib-provider-family-aws{{</hover >}}.   
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 
[provider examples](https://github.com/crossplane-contrib/provider-upjet-aws/tree/main/examples).
{{< /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](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 >}}

Create a text file containing the AWS account `aws_access_key_id` and `aws_secret_access_key`.  

{{< editCode >}}
```ini {copy-lines="all"}
[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](https://docs.upbound.io/providers/provider-aws/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{{</hover >}}  
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={{</hover>}} argument to set the value to the contents of the  {{< hover label="kube-create-secret" line="4">}}aws-credentials.txt{{< /hover >}} file.

```shell {label="kube-create-secret",copy-lines="all"}
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 >}}

```shell {copy-lines="1"}
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:
```yaml {label="providerconfig",copy-lines="all"}
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 >}}

```yaml {label="xr"}
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="2">}}apiVersion{{< /hover >}} and 
{{< hover label="xr" line="3">}}kind{{</hover >}} are from the provider's CRDs.


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

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

The region can be any 
[AWS Regional endpoint](https://docs.aws.amazon.com/general/latest/gr/rande.html#regional-endpoints) 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 >}}

```shell {copy-lines="1"}
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.

```shell {copy-lines="1"}
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](https://github.com/crossplane-contrib/provider-upjet-aws/blob/main/package/crds).
* Join the [Crossplane Slack](https://slack.crossplane.io/) and connect with 
  Crossplane users and contributors.
