Deploy your first control plane with GCP

This quickstart guides you through how to create your first managed control plane in Upbound. Connect Upbound to GCP, and use your control plane to create and manage PostgreSQL databases.

Prerequisites

  • An Upbound account.
  • A GCP account with permissions to manage IAM policies.
  • A GitHub account with permission to install GitHub Apps.
Tip
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 CloudSQL as a service.

Upbound connect to GitHub screen

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
Tip
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 GCP with OIDC

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

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

Warning

GCP doesn’t authenticate a second OIDC pool in the same projected connecting to Upbound.

Add a new Service Account to the existing pool instead.

Create an identity pool

  1. Open the GCP IAM Admin console.
  2. Select Workload Identity Federation.
  3. If this is your first Workload Identity Federation configuration select Get Started
  4. At the top of the page, select Create Pool.
  5. Name the pool, like upbound-oidc-pool.
  6. Enter a description like An identity provider for Upbound.
  7. Enable the pool.
  8. Select Continue
    Upbound Get Started Configure OIDC screen for GCP

Add Upbound to the pool

Under the Add a provider to pool configuration under Select a provider use OpenID Connect (OIDC)

Provider Name: upbound-oidc-provider
Provider ID: upbound-oidc-provider-id
Issuer (URL): https://proidc.upbound.io

Select Allowed audiences
For Audience 1 enter sts.googleapis.com

Select Continue.

GCP add a provider to pool configuration

Configure provider attributes

The provider attributes restrict which remote entities you allow access to your resources. When Upbound authenticates to GCP it provides an OIDC subject (sub) in the form:

mcp:<account>/<mcp-name>:provider:<provider-name>

Configure the google.subject attribute as assertion.sub

Under Attribute Conditions select Add Condition.

To authenticate any managed control plane in your organization, in the Conditional CEL input box put

1google.subject.contains("mcp:")
Warning
Not providing a CEL condition allows any Upbound managed control plane to access your GCP account if they know the project ID and service account name.

Select Save.

GCP configure provider attributes configuration

Create a GCP Service Account

GCP requires Upbound to use a Service Account. The required GCP roles of the service account depend on the services managed by your control plane.

  1. Open the GCP IAM Admin console.
  2. Select Service Accounts.
  3. From the top of the page, select Create Service Account.
Service account details

Under Service account details enter Service account name: upbound-service-account
Service account ID: upbound-service-account-id
Description: Upbound managed control planes service account

Select Create and Continue.

GCP service account creation screen
Grant this service account access to project

For the CloudSQL as a service configuration the service account requires the roles:
Cloud SQL Admin
Workload Identity User

Select Done.

GCP service project access screen
Record the service account email address

At the list of service accounts copy the service account email.
Upbound requires this to authenticate your managed control plane.

list of GCP service accounts

Add the service account to the identity pool

Add the service account to the Workload Identity Federation pool to authenticate to Upbound with OIDC.

  1. Return to the Workload Identity Federation page and select the upbound-oidc-pool.
  2. Near the top of the page select Grant Access.
  3. Select the new service account, upbound-service-account.
  4. Under Select principals use All identities in the pool.
    Pool select service account screen
    Select Save.
    In the Configure your application window, select Dismiss.

Enable the Cloud SQL Admin GCP API

GCP requires explicitly enabling the Cloud SQL Admin API.

Go to the Cloud SQL Admin API page in the GCP console.

Select Enable.

Enable the Cloud SQL Admin API in the GCP console

Finish configuring the Upbound identity provider

Back in Upbound, finish configuring the identity provider.

In the Identifier of GCP project field enter your GCP project ID.

For the Name of federated identity provider, edit your GCP Project ID and enter:

1projects//locations/global/workloadIdentityPools/upbound-oidc-pool/providers/upbound-oidc-provider


Note
The identity provider format is: projects/<GCP_PROJECT_ID>/locations/global/workloadIdentityPools/<OIDC_POOL_NAME>/providers/<OIDC_POOL_PROVIDER_NAME>

In the Name of federated identity provider field.

In the Attached service account email address field enter the service account email.

Upbound configuration to connect to GCP 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 GCP instance screen

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

Tip
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

Select the PostgreSQLInstance resource.
Select the Create New button at the top-right of the page.

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

  • name: my-db
  • namespace: default
  • region: east
  • size: small
  • storage: 20
Create database form

When you Create Instance the portal generates a Crossplane claim.

Note

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 resource

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

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

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

Observe created resource

Congratulations, you created your first resources with your MCP.

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 reference architecture knowledge base article.