Azure Reference Platform

This repository contains a reference Azure Platform Configuration for Crossplane. It's a great starting point for building internal cloud platforms with Azure and offer a self-service API to your internal development teams.

This platform offers APIs for setting up fully configured AKS clusters with secure networking, stateful cloud services (Database) that can securely connect to the AKS clusters, an Observability Stack, and a GitOps System. All these components are built using cloud service tools from the Official Upbound Family Azure Provider. App deployments can securely connect to the infrastructure they need using secrets distributed directly to the app namespace.

Overview

This reference platform outlines a specialized API for generating an AKS cluster (XCluster) that incorporates XRs from the specified configurations:

• upbound-configuration-app
• upbound-configuration-azure-database
• upbound-configuration-azure-aks
• upbound-configuration-azure-network
• upbound-configuration-gitops-flux
• upbound-configuration-observability-oss

graph LR;
    MyApp(My App)---MyCluster(XRC: my-cluster);
    MyCluster---XRD1(XRD: XCluster);
    MyApp---MyDB(XRC: my-db);
    MyDB---XRD2(XRD: XPostgreSQLInstance);
		subgraph Configuration:upbound/platform-ref-azure;
	    XRD1---Composition(XAKS, XNetwork, XServices);
	    XRD2---Composition2(Composition);
		end
		subgraph Provider:upbound/provider-azure
	    Composition---Network.MRs(MRs: ResourceGroup, VirtualNetwork, Subnet);
	    Composition---AKS.MRs(MRs: KubernetesCluster);
	    Composition2---Postgres.MRs(MRs: VirtualNetworkRule, Server);
		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-azure fill:#f1d16d,opacity:0.3
style Provider:upbound/provider-azure 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 Network.MRs color:#000,fill:#81CABB,stroke:#000,stroke-width:2px
style AKS.MRs color:#000,fill:#81CABB,stroke:#000,stroke-width:2px
style Postgres.MRs color:#000,fill:#81CABB,stroke:#000,stroke-width:2px

Loading

Learn more about Composite Resources in the Crossplane Docs.

Quickstart

Pre-Requisites

Before we can install the reference platform we want to 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 | sh

See up docs for more install options.

To intstall crossplane CLI follow https://docs.crossplane.io/latest/cli/#installing-the-cli

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 cluster

Finally install UXP into the upbound-system namespace:

up uxp install --set='args[0]=--enable-usages'

We will need Usages alpha feature for the correct deployment and eventual de-provisioning of this reference platform.

You can validate the install by inspecting all installed components:

kubectl get all -n upbound-system

Install the Azure Reference Platform

Now 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-azure:v0.12.0

Validate the install by inspecting the provider and configuration packages:

kubectl get configurations,configurationrevisions
kubectl get configurations --watch

After all Configurations are ready, you can check the status of associated Providers that were pulled as dependencies

kubectl get providers,providerrevision

Check the marketplace for the latest version of this platform.

Configure the Azure provider

Before we can use the reference platform we need to configure it with Azure credentials:

# Create a azure.json file with the azure cli:
# Replace <Subscription ID> with your subscription ID.
az ad sp create-for-rbac --sdk-auth --role Owner --scopes /subscriptions/<Subscription ID> \
  > azure.json

# Create a K8s secret with the Azure creds:
kubectl create secret generic azure-creds -n upbound-system --from-file=credentials=./azure.json

# Configure the Azure Provider to use the secret:
kubectl apply -f examples/azure-default-provider.yaml

See provider-azure docs for more detailed configuration options

Using the Azure reference platform

🎉 Congratulations. You have just installed your first Crossplane powered platform!

Application developers can now use the platform to request resources which than will provisioned in Azure. This would usually 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 https://raw.githubusercontent.com/upbound/platform-ref-azure/main/examples/cluster-claim.yaml

Create a custom defined database:

kubectl apply -f https://raw.githubusercontent.com/upbound/platform-ref-azure/main/examples/mariadb-claim.yaml

NOTE: The database abstraction relies on the cluster claim to be ready - it uses the same network to have connectivity with the AKS cluster.

Now deploy the sample application:

kubectl apply -f https://raw.githubusercontent.com/upbound/platform-ref-azure/main/examples/app-claim.yaml

NOTE: application has a strong dependency on mariadb type of the database

You can verify status by inspecting the claims, composites and managed resources:

kubectl get claim,composite,managed

To get nice representation of the Claim deployment status you can use crossplane beta trace command

crossplane beta trace cluster.aws.platformref.upbound.io/platform-ref-aws

To delete the provisioned resources you would simply delete the claims again:

kubectl delete -f https://raw.githubusercontent.com/upbound/platform-ref-azure/main/examples/cluster-claim.yaml,https://raw.githubusercontent.com/upbound/platform-ref-azure/main/examples/mariadb-claim.yaml,https://raw.githubusercontent.com/upbound/platform-ref-azure/main/examples/app-claim.yaml

To uninstall the provider & platform configuration:

kubectl delete configurations.pkg.crossplane.io upbound-platform-ref-azure
kubectl delete configurations.pkg.crossplane.io upbound-configuration-app
kubectl delete configurations.pkg.crossplane.io upbound-configuration-azure-database
kubectl delete configurations.pkg.crossplane.io upbound-configuration-azure-aks
kubectl delete configurations.pkg.crossplane.io upbound-configuration-azure-network
kubectl delete configurations.pkg.crossplane.io upbound-configuration-gitops-flux
kubectl delete configurations.pkg.crossplane.io upbound-configuration-observability-oss

kubectl delete providers.pkg.crossplane.io crossplane-contrib-provider-helm
kubectl delete providers.pkg.crossplane.io crossplane-contrib-provider-kubernetes
kubectl delete providers.pkg.crossplane.io grafana-provider-grafana
kubectl delete providers.pkg.crossplane.io upbound-provider-azure-containerservice
kubectl delete providers.pkg.crossplane.io upbound-provider-azure-dbformariadb
kubectl delete providers.pkg.crossplane.io upbound-provider-azure-dbforpostgresql
kubectl delete providers.pkg.crossplane.io upbound-provider-azure-network
kubectl delete providers.pkg.crossplane.io upbound-provider-family-azure

Customize for your Organization

So far we have used the existing reference platform but haven't made any changes.

For the following examples we are using my-org and my-platform:

ORG=my-org
PLATFORM=my-platform

Pre-Requisites

First you need to create a free Upbound account to push your custom platform. Afterwards you can log in:

up login

Make the changes

To make your changes clone this repository:

git clone https://github.com/upbound/platform-ref-azure.git $PLATFORM && cd $PLATFORM

Build and push your platform

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=. --examples-root=examples --ignore=".github/workflows/*.yaml,.github/workflows/*.yml,examples/*.yaml,.work/uptest-datasource.yaml"

Afterwards you can push it to the marketplace. It will be not automatically listed but the OCI repository will be publicly accessible.

TAG=v0.1.0
up repo -a $ORG create ${PLATFORM}
up xpkg push ${ORG}/${PLATFORM}:${TAG} -f package.xpkg

Using your custom platform

Now to use your custom platform, you can pull the Configuration package from your repository

up ctp configuration install xpkg.upbound.io/${ORG}/${PLATFORM}:${TAG} --package-pull-secrets=personal-pull-secret

For alternative declarative installation approach see the example Configuration manifest. Please update to your org, platform and tag before applying.

🎉 Congratulations. You have just build and installed your first custom Crossplane powered platform!

Questions?

For any questions, thoughts and comments don't hesitate to reach out or drop by slack.crossplane.io, and say hi!