Skip to main content

Deployment Workflow

This guide deploys a self-hosted Upbound cluster in AWS.

Disconnected Spaces allows you to host 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 AWS account and the AWS CLI
important

Disconnected Spaces are a business critical feature of Upbound and requires a license token to successfully complete the installation. Contact Upbound if you want to try out Upbound with Disconnected Spaces.

Provision the hosting environment​

Create a cluster​

Configure the name and target region you want the EKS cluster deployed to.

export SPACES_CLUSTER_NAME=upbound-space-quickstart
export SPACES_REGION=us-east-1

Provision a 3-node cluster using eksctl.

cat <<EOF | eksctl create cluster -f -
apiVersion: eksctl.io/v1alpha5
kind: ClusterConfig
metadata:
  name: ${SPACES_CLUSTER_NAME}
  region: ${SPACES_REGION}
  version: "1.29"
managedNodeGroups:
  - name: ng-1
    instanceType: m5.xlarge
    desiredCapacity: 3
    volumeSize: 100
    iam:
      withAddonPolicies:
        ebs: true
iam:
  withOIDC: true
  serviceAccounts:
    - metadata:
        name: aws-load-balancer-controller
        namespace: kube-system
      wellKnownPolicies:
        awsLoadBalancerController: true
    - metadata:
        name: efs-csi-controller-sa
        namespace: kube-system
      wellKnownPolicies:
        efsCSIController: true
addons:
  - name: vpc-cni
    attachPolicyARNs:
      - arn:aws:iam::aws:policy/AmazonEKS_CNI_Policy
  - name: aws-ebs-csi-driver
    wellKnownPolicies:
      ebsCSIController: true
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=<your-upbound-org>

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="/path/to/token.json"

Set the version of Spaces software you want to install.

export SPACES_VERSION=<!-- spaces_version -->

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="proxy.upbound-127.0.0.1.nip.io"
important

Make sure to replace the placeholder text in SPACES_ROUTER_HOST and provide a real domain that you own.

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 ALB Load Balancer​

helm install aws-load-balancer-controller aws-load-balancer-controller --namespace kube-system \
  --repo https://aws.github.io/eks-charts \
  --set clusterName=${SPACES_CLUSTER_NAME} \
  --set serviceAccount.create=false \
  --set serviceAccount.name=aws-load-balancer-controller \
  --wait

Install Envoy Gateway​

Starting with Spaces v1.10.0, Upbound recommends using the [Gateway API] for routing traffic to Spaces. Gateway API is the official Kubernetes standard for ingress and replaces the legacy Ingress API.

This guide uses Envoy Gateway as the Gateway API controller and replaces ingress-nginx previously recommended.

info

If you need to continue to use ingress-nginx temporarily, use the [ingress-nginx migration guide][migration guide].

The Kubernetes community announced that ingress-nginx will be retired in March 2026 and you should plan to migrate to Gateway API before then.

First, install Envoy Gateway with Helm:

helm -n envoy-gateway-system upgrade --install --wait --wait-for-jobs \
  --timeout 360s --create-namespace envoy-gateway \
  oci://docker.io/envoyproxy/gateway-helm \
  --version "v1.2.4"

Next, create the Gateway API resources for your cloud provider:

Create EnvoyProxy configuration for AWS load balancer

kubectl apply -f - --server-side <<EOF
apiVersion: gateway.envoyproxy.io/v1alpha1
kind: EnvoyProxy
metadata:
  name: spaces-proxy-config
  namespace: envoy-gateway-system
spec:
  provider:
    type: Kubernetes
    kubernetes:
      envoyService:
        annotations:
          service.beta.kubernetes.io/aws-load-balancer-type: external
          service.beta.kubernetes.io/aws-load-balancer-scheme: internet-facing
          service.beta.kubernetes.io/aws-load-balancer-nlb-target-type: ip
          service.beta.kubernetes.io/aws-load-balancer-healthcheck-protocol: http
          service.beta.kubernetes.io/aws-load-balancer-healthcheck-path: /healthz
          service.beta.kubernetes.io/aws-load-balancer-healthcheck-port: "19002"
EOF

Create GatewayClass:

kubectl apply -f - --server-side <<EOF
apiVersion: gateway.networking.k8s.io/v1
kind: GatewayClass
metadata:
  name: spaces
spec:
  controllerName: gateway.envoyproxy.io/gatewayclass-controller
  parametersRef:
    group: gateway.envoyproxy.io
    kind: EnvoyProxy
    name: spaces-proxy-config
    namespace: envoy-gateway-system
EOF

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 "account=${UPBOUND_ACCOUNT}" \
  --set "authentication.hubIdentities=true" \
  --set "authorization.hubRBAC=true" \
  --wait

Create a DNS record​

important

If you chose to create a public ingress, you also need to create a DNS record for the load balancer of the public facing ingress. Do this before you create your first control plane.

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].hostname}'

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.

Configure the up CLI​

With your kubeconfig pointed at the Kubernetes cluster where you installed Upbound Spaces, create a new profile in the up CLI. This profile interacts with your Space:

up profile create --use ${SPACES_CLUSTER_NAME} --type=disconnected --organization ${UPBOUND_ACCOUNT}

Optionally, log in to your Upbound account using the new profile so you can use the Upbound Marketplace with this profile as well:

up login

Connect to your Space​

Use up ctx to create a kubeconfig context pointed at your new Space:

up ctx disconnected/$(kubectl config current-context)

Create your first control plane​

You can now create a control plane with the up CLI:

up ctp create ctp1

You can also create a control plane with kubectl:

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 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 control plane​

Connect to your 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 kubectl context. You're now connected to your control plane directly. Confirm this is the case by trying to list the CRDs in your control plane:

kubectl get crds

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

up ctx -
tip

Learn how to use the up CLI to navigate around Upbound by reading the up ctx command reference.