Get started with Upbound Spaces. This guide deploys a self-hosted Upbound cluster in GCP.
Disconnected Spaces allows you to host managed control planes in your preferred environment.
Prerequisites
To get started deploying your own Disconnected Space, you need:
- An Upbound organization account string, provided by your Upbound account representative
- A
token.json
license, provided by your Upbound account representative - An GCP account and the GCP CLI
Provision the hosting environment
Create a cluster
Configure the name and target region you want the GKE cluster deployed to.
export SPACES_PROJECT_NAME=upbound-spaces-project
export SPACES_CLUSTER_NAME=upbound-spaces-quickstart
export SPACES_LOCATION=us-west1-a
Create a new project and set it as the current project.
gcloud projects create ${SPACES_PROJECT_NAME}
gcloud config set project ${SPACES_PROJECT_NAME}
Provision a 3-node cluster.
gcloud container clusters create ${SPACES_CLUSTER_NAME} \
--enable-network-policy \
--num-nodes=3 \
--zone=${SPACES_LOCATION} \
--machine-type=e2-standard-4
Get the kubeconfig of your GKE cluster.
gcloud container clusters get-credentials ${SPACES_CLUSTER_NAME} --zone=${SPACES_LOCATION}
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 Spaces software you want to install.
export SPACES_VERSION=1.7.0
Set the router host and cluster type. The SPACES_ROUTER_HOST
is the domain name that’s used to access the control plane instances. It’s used by the ingress controller to route requests.
export SPACES_ROUTER_HOST=""
SPACES_ROUTER_HOST
and provide a real domain that you own.The SPACES_CLUSTER_TYPE
is the Kubernetes cluster provider you configured in the previous step.
export SPACES_CLUSTER_TYPE=gke
Install the Spaces software
Install cert-manager
Install cert-manager.
kubectl apply -f https://github.com/cert-manager/cert-manager/releases/download/v1.11.0/cert-manager.yaml
kubectl wait deployment -n cert-manager cert-manager-webhook --for condition=Available=True --timeout=360s
Install ingress-nginx
Install ingress-nginx.
helm upgrade --install ingress-nginx ingress-nginx \
--create-namespace --namespace ingress-nginx \
--repo https://kubernetes.github.io/ingress-nginx \
--version 4.7.1 \
--set 'controller.service.type=LoadBalancer' \
--wait
Install Upbound Spaces software
Create an image pull secret so that the cluster can pull Upbound Spaces images.
kubectl create ns upbound-system
kubectl -n upbound-system create secret docker-registry upbound-pull-secret \
--docker-server=https://xpkg.upbound.io \
--docker-username="$(jq -r .accessId $SPACES_TOKEN_PATH)" \
--docker-password="$(jq -r .token $SPACES_TOKEN_PATH)"
Log in with Helm to be able to pull chart images for the installation commands.
jq -r .token $SPACES_TOKEN_PATH | helm registry login xpkg.upbound.io -u $(jq -r .accessId $SPACES_TOKEN_PATH) --password-stdin
Install the Spaces software.
helm -n upbound-system upgrade --install spaces \
oci://xpkg.upbound.io/spaces-artifacts/spaces \
--version "${SPACES_VERSION}" \
--set "ingress.host=${SPACES_ROUTER_HOST}" \
--set "clusterType=${SPACES_CLUSTER_TYPE}" \
--set "account=${UPBOUND_ACCOUNT}" \
--set "authentication.hubIdentities=true" \
--set "authorization.hubRBAC=true" \
--wait
Create a DNS record
Create a DNS record for the load balancer of the public facing ingress. To get the address for the Ingress, run the following:
kubectl get ingress \
-n upbound-system mxe-router-ingress \
-o jsonpath='{.status.loadBalancer.ingress[0].ip}'
If the preceding command doesn’t return a load balancer address then your provider may not have allocated it yet. Once it’s available, add a DNS record for the ROUTER_HOST
to point to the given load balancer address. If it’s an IPv4 address, add an A record. If it’s a domain name, add a CNAME record.
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 software, create a managed control plane:
cat <<EOF | kubectl apply -f -
apiVersion: spaces.upbound.io/v1beta1
kind: ControlPlane
metadata:
name: ctp1
namespace: default
spec:
writeConnectionSecretToRef:
name: kubeconfig-ctp1
namespace: default
EOF
The first managed control plane you create in a Space takes around 5 minutes to get into a condition=READY
state. Wait until it’s ready using the following command:
kubectl wait controlplane ctp1 --for condition=Ready=True --timeout=360s
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/ctp1
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 -