Bring Your Own Instance Backend

This guide will walk you through the process of configuring your own Instance backend on a Kubernetes cluster for use with Ascend.

Prerequisites

• A Kubernetes cluster
• The ability to run commands in your terminal to interact with your Kubernetes cluster
• Helm CLI (Installation instructions) with minimum version 3.16.0

Preparing for Installation

To install the Ascend Instance backend on your Kubernetes cluster, you will need to use the Helm package manager.

Before installing into your cluster you'll need to find the OIDC issuer for your cluster, plus the name of the namespace you intend to install into, and send it to Ascend.

If you don't know how to find the issuer for your cluster, check with your cluster administrator. If you are the cluster admin, if you exec into a pod with a service account token mounted (e.g. kubectl exec -it -n NAMESPACE POD_NAME -- bash), you should be able to find the mounted token and copy it (this is safe, as they are rotated regularly by kubernetes). If the token is in the default location, you should be able to get it with the following:

cat /var/run/secrets/kubernetes.io/serviceaccount/token | pbcopy

To get the issuer, run the following (replace TOKEN_VAL with the value, or pbpaste if that's available on your system):

echo $TOKEN_VAL | cut -d "." -f 2 | base64 -D | jq '.iss'

Ascend will send you back a values.yaml file that you will use for install like the following:

instance:
  uuid: "01953933-14ed-7240-ba0c-36a6039b7de9"  # Required: Instance UUID
  organizationUuid: "018fbc9f-49a2-7909-bb26-dd017195e3d4"  # Required: Organization UUID
  subdomain: "acme-self-hosted-instance"  # Required: Subdomain for instance
managedIdentity:
  ascend:
    domainHash: "i5ft3k"
    instanceHash: "un2edj"
  aws:
    enabled: true
  clusterIssuerHash: "jh3t7v"
  enabled: true
environments:
  - id: dev
    uuid: 01953936-7c3f-7e83-be35-f6e84f860b4e
    hash: "aervpl"
  - id: stage
    uuid: 01953936-9892-7261-91ac-9e9d83cd4271
    hash: "xibnsu"
  - id: prod
    uuid: 01953936-add7-7905-81cf-a5f3b6163918
    hash: "6wdtcs"
msk:
  roleArn: "arn:aws:iam::905936477528:role/asc-a-i5ft3k-un2edj-i"
  clusterArn: "arn:aws:kafka:us-east-1:905936477528:cluster/app-dev/f696d209-f38c-4fc3-9b2a-6f591ccbb5bd-5"

Installing the Ascend Instance Backend

1. Save the values.yaml file provided by Ascend

2. Set the following bash variables

   
   export KUBE_CONTEXT=gke_<gcp-project>_<region>_<cluster-name>
   export NAMESPACE=<your-namespace>  # this should be the same as the subdomain
   export RELEASE_NAME=<your-release-name>  # ie, ascend-deploy-0
   export VALUES_FILE=<path/to/values.yaml>

3. Install the Helm chart

   # If the namespace doesn't exist yet
   helm install \
       ${RELEASE_NAME} \
       oci://quay.io/ascendio/charts/instance-backend \
       -f ${VALUES_FILE} \
       --namespace ${NAMESPACE} \
       --create-namespace
   tip

   If the namespace already exists, you can skip the --create-namespace flag.

Upgrading the Ascend Instance Backend

To upgrade the Ascend Instance backend on your Kubernetes cluster, you can run the following command:

helm upgrade \
    ${RELEASE_NAME} \
    oci://quay.io/ascendio/charts/instance-backend \
    -n ${NAMESPACE} \
    --reuse-values

tip

If you've changed the values.yaml file, you can remove the --reuse-values flag and pass in the new values with the -f flag.

Uninstalling the Ascend Instance Backend

To uninstall the Ascend Instance backend on your Kubernetes cluster, you can run the following command:

helm uninstall \
    ${RELEASE_NAME} \
    -n ${NAMESPACE}