Get started with Upbound Spaces. This guide deploys a self-hosted Upbound cluster with a local kind cluster.

Self-hosted Spaces allow you to host managed control planes in your preferred environment.

Prerequisites

To get started deploying your own self-hosted Space, you need:

• An Upbound Account string, provided by your Upbound account representative
• A token.json license, provided by your Upbound account representative
• kind installed locally

Provision the hosting environment

Upbound Spaces requires a cloud Kubernetes or kind cluster as a hosting environment. For your first time set up or a development environment, Upbound recommends starting with a kind cluster.

Create a cluster

Provision a new kind cluster.

cat <<EOF | kind create cluster --wait 5m --config=-
kind: Cluster
apiVersion: kind.x-k8s.io/v1alpha4
nodes:
- role: control-plane
  kubeadmConfigPatches:
  - |
    kind: InitConfiguration
    nodeRegistration:
      kubeletExtraArgs:
        node-labels: "ingress-ready=true"    
  extraPortMappings:
  - containerPort: 443
    hostPort: 443
    protocol: TCP
EOF

Configure the pre-install

Set your Upbound organization account details

Set your Upbound organization account string as an environment variable for use in future steps

export UPBOUND_ACCOUNT=

Set up pre-install configurations

Export the path of the license token JSON file provided by your Upbound account representative.

# Change the path to where you saved the token.
export SPACES_TOKEN_PATH=""

Set the version of the Spaces software you want to install.

export SPACES_VERSION=1.9.5

Install the Spaces software

The up CLI gives you a “batteries included” experience. It automatically detects which prerequisites aren’t met and prompts you to install them to move forward. This guide requires CLI version v0.33.0 or newer.

Install the Spaces software.

up space init --token-file="${SPACES_TOKEN_PATH}" "v${SPACES_VERSION}" \
  --set "account=${UPBOUND_ACCOUNT}"

You are ready to create your first managed control plane in your Space.

Create your first managed control plane

With your kubeconfig pointed at the Kubernetes cluster where you installed the Upbound Space, create a managed control plane:

up ctp create controlplane1

The first managed control plane you create in a Space takes around 5 minutes to get into a condition=READY state. To report the control plane status, use the following command:

up ctp list

Connect to your managed control plane

Connect to your managed control plane with the up ctx command. With your kubeconfig still pointed at the Kubernetes cluster where you installed the Upbound Space, run the following:

up ctx ./default/controlplane1

This command updates your current kubecontext. You’re now connected to your managed control plane directly. Confirm this is the case by trying to list the CRDs in your managed control plane:

kubectl get crds

To disconnect from your managed control plane and switch back to your previous context:

up ctx -

Connect your Space to Upbound

Upbound allows you to connect self-hosted Spaces and enables a streamlined operations and debugging experience in your Console.

Before you begin, make sure you have:

• An existing Upbound organization in Upbound SaaS.
• The up CLI installed and logged into your organization
• kubectl installed with the kubecontext of your self-hosted Space cluster.
• A token.json license, provided by your Upbound account representative.

Enable the Query API

Connecting a Space requires that you enable the Query API.

Upbound’s Query API allows users to inspect objects and resources within their control planes. The read-only up alpha query and up alpha get CLI commands allow you to gather information on your control planes in a fast and efficient package. These commands follow the kubectl conventions for filtering, sorting, and retrieving information from your Space.

To enable, set features.alpha.apollo.enabled=true and features.alpha.apollo.storage.postgres.create=true when installing Spaces:

up space init --token-file="${SPACES_TOKEN_PATH}" "v${SPACES_VERSION}" \
  ...
  --set "features.alpha.apollo.enabled=true" \
  --set "features.alpha.apollo.storage.postgres.create=true"

These flags create a PostgreSQL cluster handled by CloudNativePG.

Users can also provide their own instance if needed, by setting features.alpha.apollo.storage.postgres.create=false and providing all the required information at features.alpha.apollo.storage.postgres.connection.

Connect your Space

Create a new UPBOUND_SPACE_NAME. If you don’t create a name, up automatically generates one for you:

export UPBOUND_SPACE_NAME=

With up CLI

Log into Upbound SaaS with the up CLI. Update <org-account> with your organization account name:

up login -a <org-account>

Connect the Space to the Console:

up space connect "${UPBOUND_SPACE_NAME}"

This command installs a Connect agent, creates a service account, and configures permissions in your Upbound cloud organization in the upbound-system namespace of your Space.

With Helm

Export your Upbound org account name to an environment variable called UPBOUND_ORG_NAME. You can see this value by running up org list after logging on to Upbound.

export UPBOUND_ORG_NAME=

Create a new robot token and export it to an environment variable called UPBOUND_TOKEN:

up robot create "${UPBOUND_SPACE_NAME}" --description="Robot used for authenticating Space '${UPBOUND_SPACE_NAME}' with Upbound Connect"
export UPBOUND_TOKEN=$(up robot token create "${UPBOUND_SPACE_NAME}" "${UPBOUND_SPACE_NAME}" --output=-| awk -F': ' '/Token:/ {print $2}')

Create a secret containing the robot token:

kubectl create secret -n upbound-system generic connect-token --from-literal=token=${UPBOUND_TOKEN}

Specify your username and password for the helm OCI registry:

jq -r .token $SPACES_TOKEN_PATH | helm registry login xpkg.upbound.io -u $(jq -r .accessId $SPACES_TOKEN_PATH) --password-stdin

In the same cluster where you installed the Spaces software, install the Upbound connect agent with your token secret.

helm -n upbound-system upgrade --install agent \
  oci://xpkg.upbound.io/spaces-artifacts/agent \
  --version "0.0.0-441.g68777b9" \
  --set "image.repository=xpkg.upbound.io/spaces-artifacts/agent" \
  --set "registration.image.repository=xpkg.upbound.io/spaces-artifacts/register-init" \
  --set "imagePullSecrets[0].name=upbound-pull-secret" \
  --set "registration.enabled=true" \
  --set "space=${UPBOUND_SPACE_NAME}" \
  --set "organization=${UPBOUND_ORG_NAME}" \
  --set "tokenSecret=connect-token" \
  --wait

View your Space in the Console

Go to the Upbound Console, log in, and choose the newly connected Space from the Space selector dropdown.