AWS Quickstart Connect Crossplane to AWS to create and manage cloud resources from Kubernetes with the AWS Official Provider .
This guide walks you through the steps required to get started with the AWS Official Provider. This includes installing Upbound Universal Crossplane, configuring the provider to authenticate to AWS and creating a Managed Resource in AWS directly from your Kubernetes cluster.
This quickstart requires:
a Kubernetes cluster with at least 3 GB of RAM permissions to create pods and secrets in the Kubernetes cluster an AWS account with permissions to create an S3 storage bucket AWS access keys
If you don’t have a Kubernetes cluster create one locally with
minikube or
kind .
You can use this guide in one of two methods:
shell script guided tour Both methods create an identical environment. Choose the method that best fits your learning style.
Copy and paste quickstart
You can either run a single Bash script or run each command individually.
All commands use the current kubeconfig context and configuration.
You need your:
AWS Access Key ID AWS Secret Access Key Download the script with wget.
1
wget https://docs.upbound.io/quickstart/scripts/aws-quickstart-script.sh
Click to view the complete Bash script
↕
Paste this script into a text file and run it as a script. Some terminals don’t handle lots of commands at once.
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
#!/usr/bin/env bash
set -eE
read -p "AWS access_key_id: " aws_access_key; read -sp "AWS secret_access_key: " aws_secret_key; export AWS_KEY = $aws_access_key ; export AWS_SECRET = $aws_secret_key ;
if ! kubectl -n upbound-system get deployment crossplane > /dev/null 2>& 1
then
printf "\n\nInstalling up CLI...\n"
curl -sL "https://cli.upbound.io" | sh
sudo mv up /usr/local/bin/
printf "\n\nInstalling UXP...\n"
up uxp install
fi
printf "\n\nChecking the UXP installation (this only takes a minute)...\n"
kubectl -n upbound-system wait deployment crossplane --for= condition = Available --timeout= 180s
printf "\n\nInstalling the provider (this will take a few minutes)...\n"
cat <<EOF | kubectl apply -f -
apiVersion: pkg.crossplane.io/v1
kind: Provider
metadata:
name: provider-aws
spec:
package: xpkg.upbound.io/upbound/provider-aws:v0.17.0
EOF
kubectl wait "providers.pkg.crossplane.io/provider-aws" --for= condition = Installed --timeout= 180s
kubectl wait "providers.pkg.crossplane.io/provider-aws" --for= condition = Healthy --timeout= 180s
cat <<EOF | kubectl apply -f -
apiVersion: v1
kind: Secret
metadata:
name: aws-secret
namespace: upbound-system
stringData:
creds: |
$(printf "[default]\n aws_access_key_id = %s\n aws_secret_access_key = %s" "${AWS_KEY}" "${ASW_SECRET}")
EOF
cat <<EOF | kubectl apply -f -
apiVersion: aws.upbound.io/v1beta1
kind: ProviderConfig
metadata:
name: default
spec:
credentials:
source: Secret
secretRef:
namespace: upbound-system
name: aws-secret
key: creds
EOF
cat <<EOF | kubectl create -f -
apiVersion: s3.aws.upbound.io/v1beta1
kind: Bucket
metadata:
generateName: upbound-bucket-
spec:
forProvider:
region: us-east-1
EOF
printf "\n\nChecking AWS bucket creation (this takes a minute)...\n"
kubectl wait " $( kubectl get buckets -o name) " --for= condition = Ready --timeout= 180s
kubectl get buckets
Your Kubernetes cluster created this AWS S3 bucket.
Remove it with kubectl delete bucket <bucket name>
1
kubectl delete bucket upbound-bucket-$VAR
These steps are the same as the preceding script, but provides more information for each action.
All commands use the current kubeconfig context and configuration.
You need your:
AWS Access Key ID AWS Secret Access Key Install the Up command-line
The Up command-line helps manage Upbound Universal Crossplane, Upbound’s enterprise Crossplane distribution and manage Upbound user accounts.
Download and install the Upbound up command-line.
1
2
curl -sL "https://cli.upbound.io" | sh
sudo mv up /usr/local/bin/
Install Upbound Universal Crossplane
Upbound Universal Crossplane (UXP ) consists of upstream Crossplane and Upbound-specific enhancements and patches. It’s open source and maintained by Upbound.
Install UXP with the Up command-line up uxp install command.
1
2
up uxp install
UXP 1.9.1-up.2 installed
Verify all UXP pods are Running with kubectl get pods -n upbound-system. This may take up to five minutes depending on your Kubernetes cluster.
1
2
3
4
kubectl get pods -n upbound-system
NAME READY STATUS RESTARTS AGE
crossplane-7fdfbd897c-pmrml 1/1 Running 0 68m
crossplane-rbac-manager-7d6867bc4d-v7wpb 1/1 Running 0 68m
For more details about UXP pods, read the UXP section.
Installing UXP and Crossplane creates new Kubernetes API end-points. Take a look at the new API end-points with kubectl api-resources | grep crossplane. In a later step you use the Provider
1
2
3
4
5
6
7
8
9
10
11
kubectl api-resources | grep crossplane
compositeresourcedefinitions xrd,xrds apiextensions.crossplane.io/v1 false CompositeResourceDefinition
compositionrevisions apiextensions.crossplane.io/v1alpha1 false CompositionRevision
compositions apiextensions.crossplane.io/v1 false Composition
configurationrevisions pkg.crossplane.io/v1 false ConfigurationRevision
configurations pkg.crossplane.io/v1 false Configuration
controllerconfigs pkg.crossplane.io/v1alpha1 false ControllerConfig
locks pkg.crossplane.io/v1beta1 false Lock
providerrevisions pkg.crossplane.io/v1 false ProviderRevision
providers pkg.crossplane.io/v1 false Provider
storeconfigs secrets.crossplane.io/v1alpha1 false StoreConfig
Install the official AWS provider
Install the official provider into the Kubernetes cluster with the up command-line or a Kubernetes configuration file.
Verify the provider installed with kubectl get providers.
It may take up to five minutes for the provider to list HEALTHY as True.
1
2
3
kubectl get providers
NAME INSTALLED HEALTHY PACKAGE AGE
upbound-provider-aws True True xpkg.upbound.io/upbound/provider-aws:v0.21.0 73s
A provider installs their own Kubernetes Custom Resource Definitions (CRDs). These CRDs allow you to create AWS resources directly inside Kubernetes.
You can view the new CRDs with kubectl get crds. Every CRD maps to a unique AWS service Crossplane can provision and manage.
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.
First 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.
The
AWS documentation provides information on how to generate AWS Access keys.
Create a text file containing the AWS account aws_access_key_id and aws_secret_access_key.
1
2
3
[default]
aws_access_key_id = <aws_access_key>
aws_secret_access_key = <aws_secret_key>
Save this text file as aws-credentials.txt.
The
Configuration section of the Provider documentation describes other authentication methods.
Create a Kubernetes secret with the AWS credentials
A Kubernetes generic secret has a name and contents. Use kubectl create secret aws-secret upbound-system --from-file= aws-credentials.txt
1
2
3
4
kubectl create secret \
\
\
= creds = ./aws-credentials.txt
View the secret with kubectl describe secret
The size may be larger if there are extra blank spaces in your text file.
1
2
3
4
5
6
7
8
9
10
11
kubectl describe secret aws-secret -n upbound-system
Name: aws-secret
Namespace: upbound-system
Labels: <none>
Annotations: <none>
Type: Opaque
Data
====
creds: 114 bytes
A ProviderConfig customizes the settings of the AWS Provider.
Apply the ProviderConfig
1
2
3
4
5
6
7
8
9
10
11
12
13
cat <<EOF | kubectl apply -f -
apiVersion : aws.upbound.io/v1beta1
kind : ProviderConfig
metadata :
name : default
spec :
credentials :
source : Secret
secretRef :
namespace : upbound-system
name : aws-secret
key : creds
EOF
This attaches the AWS credentials, saved as a Kubernetes secret, as a secretRef
The spec.credentials.secretRef.name spec.credentials.secretRef.namespace
Create a managed resource
A managed resource is anything Crossplane creates and manages outside of the Kubernetes cluster. This creates an AWS S3 bucket with Crossplane. The S3 bucket is a managed resource .
AWS S3 bucket names must be globally unique. To generate a unique name the example uses a random hash.
Any unique name is acceptable.
1
2
3
4
5
6
7
8
9
10
11
12
bucket=$(echo "upbound-bucket-"$(head -n 4096 /dev/urandom | openssl sha1 | tail -c 10))
cat <<EOF | kubectl apply -f -
apiVersion : s3.aws.upbound.io/v1beta1
kind : Bucket
metadata :
name : $bucket
spec :
forProvider :
region : us-east-1
providerConfigRef :
name : default
EOF
Notice the apiVersion kind Provider's CRDs.
The metadata.name upbound-bucket-<hash> in the `$bucket`
The spec.forProvider.region AWS Regional endpoint code.
Use kubectl get buckets to verify Crossplane created the bucket.
Upbound created the bucket when the values READY and SYNCED are True.
1
2
3
kubectl get buckets
NAME READY SYNCED EXTERNAL-NAME AGE
upbound-bucket-45eed4ae0 True True upbound-bucket-45eed4ae0 61s
Optionally, log into the AWS Console and see the bucket inside AWS.
AWS console shows an S3 bucket with the name upbound-bucket-45eed4ae0 that matches the bucket created by Crossplane. Is the bucket not SYNCED? Click here for troubleshooting tips
↕ If the READY or SYNCED are blank or False use kubectl describe bucket to understand why.
A common issue is incorrect AWS credentials or not having permissions to create the S3 bucket.
The following output is an example of the kubectl describe bucket output when using the wrong AWS credentials.
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
kubectl describe bucket
Name: upbound-bucket-ff2ce7e86
Annotations: crossplane.io/external-name: upbound-bucket-ff2ce7e86
API Version: s3.aws.upbound.io/v1beta1
Kind: Bucket
# Output trimmed for brevity
Spec:
Deletion Policy: Delete
For Provider:
Region: us-east-1
Tags:
Crossplane - Kind: bucket.s3.aws.upbound.io
Crossplane - Name: upbound-bucket-ff2ce7e86
Crossplane - Providerconfig: default
Provider Config Ref:
Name: default
Status:
At Provider:
Conditions:
Last Transition Time: 2022-09-30T15:47:18Z
Message: connect failed: cannot get terraform setup: cannot get the caller identity: GetCallerIdentity query failed: GetCallerIdentity query failed: operation error STS: GetCallerIdentity, https response error StatusCode: 403, RequestID: bc190d08-20fc-40c2-82ba-875ecb98bef6, api error InvalidClientTokenId: The security token included in the request is invalid.
Reason: ReconcileError
Status: False
Type: Synced
Events:
Type Reason Age From Message
---- ------ ---- ---- -------
Warning CannotConnectToProvider 0s ( x12 over 2s) managed/s3.aws.upbound.io/v1beta1, kind = bucket ( combined from similar events) : cannot get terraform setup: cannot get the caller identity: GetCallerIdentity query failed: GetCallerIdentity query failed: operation error STS: GetCallerIdentity, https response error StatusCode: 403, RequestID: bc190d08-20fc-40c2-82ba-875ecb98bef6, api error InvalidClientTokenId: The security token included in the request is invalid.
The error message in the Events log indicates the problem.api error InvalidClientTokenId: The security token included in the request is invalid.
To fix the problem:
Update your AWS credentials in the aws-credentials.txt text file. Delete the original Kubernetes secret with kubectl delete secret aws-secret -n upbound-systemCreate a new secret withkubectl create secret generic aws-secret -n upbound-system --from-file=creds=aws.txt Delete the ProviderConfig withkubectl delete providerconfig.aws.upbound.io/default Recreate the ProviderConfig with the output in the ProviderConfig section . Create the bucket again .
Deleting the ProviderConfig isn’t required, but is faster than waiting for Kubernetes to synchronize and update.
Still need help? Join the Crossplane Slack and ask in the #Upbound room to get help directly from Upbound employees and community members.
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.
1
2
kubectl delete bucket $bucket
bucket.s3.aws.upbound.io "upbound-bucket-45eed4ae0" deleted
Look in the AWS Console to confirm Crossplane deleted the bucket from AWS.
AWS console showing no buckets exist, indicating Crossplane deleted the S3 bucket managed resource. 
