Deploy your first control plane with Azure

This quickstart guides you through how to create your first managed control plane in Upbound. Connect Upbound to Azure, and use your control plane to create and manage AKS clusters.


You need the following:

  • An Upbound account.
  • An Azure account with permissions to manage IAM policies.
  • A GitHub account with permission to install GitHub Apps.
If you don’t have an Upbound account, sign up for a free trial.

Get started

The first time you sign in to Upbound, you walk through a Getting Started experience designed to bootstrap your environment in the matter of minutes.

Go to Upbound to get started.

Create an organization

Your first time in Upbound you must create an organization. Give your organization an ID and a friendly name.

Select Create Organization.

Upbound Create organization screen

On the next screen, start your free trial. This trial allows you to create up to three managed control planes, three configurations, and invite a total of 10 team members in an organization.

Upbound Free trial entry

Choose a configuration

Upbound offers a curated gallery of Crossplane configurations for you to choose from. These configurations provide ready-built APIs that Upbound installs in your control plane. You can select the source link to view the configuration files that define this API in GitHub.

Select the Configuration called AKS as a service.

Upbound Azure configuration

Connect to GitHub

After you’ve selected a Configuration, you need to connect Upbound to your GitHub account. Upbound uses GitHub’s authorization flow and installs a GitHub app into your account.

Select Connect to GitHub.

Upbound connect to GitHub
Git connectivity is at the core of Upbound’s workflows. To learn more about git integration, read the GitOps with MCP section.

After you’ve connected to GitHub, select an account owner and repository name. Upbound creates a new repository under your account and clones the contents of the Configuration into that repository.

Give your repository a name, like my-control-plane-apis.

Select Clone configuration to GitHub.

Upbound Create Repository screen

Create a managed control plane

After Upbound clones the Configuration into your own repository, create a managed control plane.

Give your control plane a name, like my-control-plane.

Select Create Control Plane.

Upbound Create Control Plane screen

Connect to Azure with OIDC

While Upbound creates your control plane, connect Upbound to Azure.

Upbound recommends using OpenID Connect (OIDC) to authenticate to Azure without exchanging any private information.

Create an identity pool

  1. Open the Azure portal.
  2. Select Azure Active Directory.
  3. If this is your first time registering Upbound as an identity provider in Azure Active Directory, select App registrations
  4. At the top of the page, select New registration.
  5. Name the pool, like upbound-oidc-provider.
  6. In the Supported account types section select Accounts in this organizational directory only.
  7. In the Redirect URI section select Web and leave the URL field blank.
  8. Select Register.
    Upbound Get Started Configure OIDC screen for Azure

Create a federated credential

To allow the upbound-oidc-provider registration created in the previous step to trust the Upbound Control Plane, do the following in the resource view.

  1. Select Certificates and secrets in the left navigation.
  2. Select Federated credentials tab.
  3. Select Add credential.
  4. In Federated credential scenario select Other Issuer.
  5. In Issuer enter
  6. In Subject identifier enter:
  1. In Credential details name enter:
  1. In Credential details description enter:
upbound MCP  Provider provider-azure
  1. Leave Audience unmodified with api://AzureADTokenExchange.
  2. Select Add.
Azure configure app registration

Grant permissions to the service principal

For your control plane to be able to perform actions required by this configuration, you need to grant permissions to the Application Service Principal. Assign a role to the Application Service Principal by following instructions at Assign a role to the application.

  1. Open the Azure portal
  2. Select Subscriptions.
  3. Select your subscription.
  4. Select Access control (IAM) in the left navigation.
  5. Select Add and select Add role assignment.
  6. Find and select the Contributor role on the Privileged administrator roles tab.
  7. Select Next.
  8. In Assign access to select User, group, or service principal.
  9. Select Select members.
  10. Find your application by entering upbound-oidc-provider in the search field.
  11. Select Select.
  12. Select Review + assign.
  13. Make sure everything is correct and press Review + assign again.
Azure grant permissions to service principal

Finish configuring the Upbound identity provider

Back in Upbound, finish configuring the identity provider.

In the Application (client) ID field enter your Application (client) ID.

For the Directory (tenant) ID field, enter your Directory (tenant) ID. You can find this by selecting your Application under Azure Active Directory -> Application Registrations.

In the Azure Subscription ID field, enter your Subscription ID. You can find this by selecting your Subscription in the Azure portal.

Upbound configuration to connect to Azure with OIDC

Select Authenticate.
Select Launch Control Plane.

Welcome to the Upbound Console

After completing the Get Started experience, you are in the Upbound Console and greeted by the Control Planes screen.

Upbound Azure control plane instance screen

The control plane details view gives users a view into what’s happening on their control planes.

Read about the Upbound Console for a full tour of what the Console has to offer.

Create your first resource

From the control planes view, select the Portal tab, and select Open Control Plane Portal.

Navigate to control plane portal

The Control Plane Portal lists the available resources that users can claim in the left-side menu.
These resources are your abstracted APIs presented to users.

Control plane portal with a Kubernetes Cluster resource

Select the KubernetesCluster resource and then select the Create New button at the top of the page.

The form are the parameters defined in your custom API. Fill-in the form with the following:

  • name: my-app-cluster
  • namespace: default
  • id: my-app-cluster
  • count: 1
  • size: small
Navigate to control plane portal

When you Create Instance the portal generates a Crossplane claim.


After creating an instance, the Events section are logs directly from Kubernetes.

Crossplane commonly generates a Kubernetes error cannot apply composite resource: cannot patch object: Operation cannot be fulfilled that may appear as an Event.

Events showing the error cannot apply composite resource: cannot patch object

You can ignore this error. For more information about what causes this, read Crossplane issue #2114.

Observe your resources

Navigate back to Upbound Console window and to your control plane in the Overview tab.

There’s now a claim card next to the KubernetesCluster type card.

Select the claim and Upbound renders the full resource tree that’s getting created and managed by your managed control plane.

Navigate to control plane portal

Congratulations, you created your first resources with your control plane.

Next steps

To learn more about the core concepts of Upbound, read the concepts documentation. To learn how to begin building your own platform on Upbound, read the Crossplane Architecture Framework.