This repository contains a reference AWS Platform Configuration for Crossplane. It's a great starting point for building internal cloud platforms with AWS and offering a self-service API to your internal development teams.
This platform provides APIs to provision fully configured EKS clusters, with secure networking, and stateful cloud services (RDS) designed to securely connect to the nodes in each EKS cluster — all composed using cloud service primitives from the Official Upbound AWS Provider. App deployments can securely connect to the infrastructure they need using secrets distributed directly to the app namespace.
This reference platform defines a custom API for creating an EKS cluster (XCluster) which includes the actual EKS cluster, a network fabric, Prometheus, and other cluster services (XServices). Additionally, it defines a custom API for provisioning RDS Databases (XSQLInstance).
graph LR;
MyApp(My App)---MyCluster(XRC: my-cluster);
MyCluster---XRD1(XRD: XCluster);
MyApp---MyDB(XRC: my-db);
MyDB---XRD2(XRD: XSQLInstance);
subgraph Configuration:upbound/platform-ref-aws;
XRD1---Composition(XEKS, XNetwork, XServices);
XRD2---Composition2(Composition);
end
subgraph Provider:upbound/provider-aws
Composition---IAM.MRs(MRs: IAM Role, RolePolicyAttachment,OpenIDConnectProvider);
Composition---EKS.MRs(MRs: EKS Cluster, ClusterAuth, NodeGroup);
Composition2---RDS.MRs(MRs: RDS SubnetGroup, Instance);
end
style MyApp color:#000,fill:#e6e6e6,stroke:#000,stroke-width:2px
style MyCluster color:#000,fill:#D68A82,stroke:#000,stroke-width:2px
style MyDB color:#000,fill:#D68A82,stroke:#000,stroke-width:2px
style Configuration:upbound/platform-ref-aws fill:#f1d16d,opacity:0.3
style Provider:upbound/provider-aws fill:#81CABB,opacity:0.3
style XRD1 color:#000,fill:#f1d16d,stroke:#000,stroke-width:2px,stroke-dasharray: 5 5
style XRD2 color:#000,fill:#f1d16d,stroke:#000,stroke-width:2px,stroke-dasharray: 5 5
style Composition color:#000,fill:#f1d16d,stroke:#000,stroke-width:2px
style Composition2 color:#000,fill:#f1d16d,stroke:#000,stroke-width:2px
style IAM.MRs color:#000,fill:#81CABB,stroke:#000,stroke-width:2px
style EKS.MRs color:#000,fill:#81CABB,stroke:#000,stroke-width:2px
style RDS.MRs color:#000,fill:#81CABB,stroke:#000,stroke-width:2px
Learn more about Composite Resources in the Crossplane Docs.
Before we can install the reference platform we should install the up CLI.
This is a utility that makes following this quickstart guide easier. Everything
described here can also be done in a declarative approach - which we highly
recommend for any production type use-case.
To install up run this install script:
curl -sL https://cli.upbound.io | shSee up docs for more install options.
We need a running Crossplane control plane to install our instance. We are using Universal Crossplane (UXP) . Ensure that your kubectl context points to the correct Kubernetes cluster or create a new kind cluster:
kind create clusterFinally install UXP into the upbound-system namespace:
up uxp installYou can validate the install by inspecting all installed components:
kubectl get all -n upbound-systemNow you can install this reference platform. It's packaged as a Crossplane configuration package so there is a single command to install it:
up ctp configuration install xpkg.upbound.io/upbound/platform-ref-aws:v0.6.0Validate the install by inspecting the provider and configuration packages:
kubectl get providers,providerrevision
kubectl get configurations,configurationrevisionsCheck the marketplace for the latest version of this platform.
Before we can use the reference platform we need to configure it with AWS credentials:
# Create a creds.conf file with the aws cli:
AWS_PROFILE=default && echo -e "[default]\naws_access_key_id = $(aws configure get aws_access_key_id --profile $AWS_PROFILE)\naws_secret_access_key = $(aws configure get aws_secret_access_key --profile $AWS_PROFILE)" > creds.conf
# Create a K8s secret with the AWS creds:
kubectl create secret generic aws-creds -n upbound-system --from-file=credentials=./creds.conf
# Configure the AWS Provider to use the secret:
kubectl apply -f examples/aws-default-provider.yamlSee provider-aws docs for more detailed configuration options.
🎉 Congratulations. You have just installed your first Crossplane-powered platform!
Application developers can now use the platform to request resources which then will be provisioned in AWS. This would usually be done by bundling a claim as part of the application code. In our example here we simply create the claims directly:
Create a custom defined cluster:
kubectl apply -f examples/cluster-claim.yamlCreate a custom defined database:
kubectl apply -f examples/postgres-claim.yamlNOTE: The database abstraction relies on the cluster claim to be ready - it uses the same network to have connectivity with the EKS cluster.
Alternatively, you can use a mariadb claim:
kubectl apply -f examples/mariadb-claim.yaml
Now deploy the sample application:
kubectl apply -f examples/ghost-claim.yaml
You can verify the status by inspecting the claims, composites and managed resources:
kubectl get claim,composite,managedTo delete the provisioned resources you would simply delete the claims:
kubectl delete -f examples/cluster-claim.yaml,examples/postgres-claim.yamlTo uninstall the provider & platform configuration:
kubectl delete configurations.pkg.crossplane.io upbound-platform-ref-aws
kubectl delete providers.pkg.crossplane.io upbound-provider-aws
kubectl delete providers.pkg.crossplane.io crossplane-contrib-provider-helmSo far we have used the existing reference platform but haven't made any changes. Let's change this and customize the platform by ensuring the EKS Cluster is deployed to Frankfurt (eu-central-1) and that clusters are limited to 10 nodes.
For the following examples we are using my-org and my-platform:
ORG=my-org
PLATFORM=my-platformFirst you need to create a free Upbound account to push your custom platform. Afterwards you can log in:
up login --username=$ORGTo make your changes clone this repository:
git clone https://github.com/upbound/platform-ref-aws.git $PLATFORM && cd $PLATFORMIn the EKS composition find the region
definitions and change them from us-west-2 to eu-central-1. Also find the
scalingConfig.maxSize and change it from 100 to 10.
To share your new platform you need to build and distribute this package.
To build the package use the up xpkg build command:
up xpkg build --name package.xpkg --package-root=package --examples-root=examplesAfterwards you can push it to the marketplace. Don't worry - it's private to you.
TAG=v0.1.0
up repo create ${PLATFORM}
up xpkg push ${ORG}/${PLATFORM}:${TAG} -f package/package.xpkgYou can now see your listing in the marketplace:
open https://marketplace.upbound.io/configurations/${ORG}/${PLATFORM}/${TAG}Now to use your custom platform, you can follow the steps above. The only difference is that you need to specify a package-pull-secret, as the package is currently private:
up ctp pull-secret create personal-pull-secretup ctp configuration install xpkg.upbound.io/${ORG}/${PLATFORM}:${TAG} --package-pull-secrets=personal-pull-secretFor the alternative declarative installation approach see the example Configuration manifest. Please update to your org, platform and tag before applying.
🎉 Congratulations. You have just built and installed your first custom Crossplane-powered platform!
For any questions, thoughts and comments don't hesitate to reach out or drop by slack.crossplane.io, and say hi!