Installing Using Kubernetes

There are several ways in which you can install BitBroker, depending on what you are trying to achieve.

Are you trying to deploy to a public cloud or to a local environment? Are you wanting to use BitBroker in a production environment, or as a local sandbox, perhaps you are developing data connectors or even trying to enhance BitBroker itself?

In this section, we will cover in detail and step-by-step, all the different ways in which you can install a BitBroker instance using Kubernetes, to help you achieve your goals.

Bootstrapping Fresh Installations

For all Kubernetes installations, you should be aware of the ways in which fresh installations perform certain bootstrap operations.

Bootstrap User

Every fresh installation of BitBroker comes with one preinstalled user (uid: 1). This user is automatically created when the system is bought-up for the first time.

As we will explain below, this user is linked to the authorization of API calls. The user is also important for the up-coming web portal BitBroker control interface.

Bootstrap Coordinator Token

All interactions with BitBroker stem, ultimately, from interactions with the Coordinator API. This is the main administrative API for the whole system. In order to use this API, you need an access token.

Using this API, new users can be created and then promoted to have coordinator status. This results in the production of a new coordinator access token for them. But this act of promotion itself, requires permission. So how can we get started with this circular scenario?

Whenever a fresh system is installed using Kubernetes, a special bootstrap coordinator authorization token is produced. This token is valid for use with the Coordinator API. You can use this token to get going with the process of then creating your own users and giving them coordinator status.

The detailed install steps below, will contain more information about how to extract and use this bootstrap token.

Cloud Kubernetes Installation

In the section, we will explore how to you can use our pre-prepared Helm charts to install a complete BitBroker instance into your cloud of choice. These charts will be downloaded directly from Docker Hub.

Prerequisites

Start with a clean machine, with no remnants of previous BitBroker installations. Please ensure you have the following software installed, configured and operational:

• Kubernetes command line tools
• Helm command line tools
• cURL command line tool (used for testing installs only)

Create a brand new directory to act as a workspace for your installation:

mkdir bbk
cd bbk

Make sure that your current Kubernetes context is pointing at your cloud of choice:

kubectl config get-contexts

Installation

First, let’s prepare the context we want to install:

helm repo add bit-broker https://bit-broker.github.io/charts
JWKS=$(docker run bbkr/auth-service:latest npm run --silent create-jwks)
kubectl apply -f https://app.getambassador.io/yaml/emissary/2.2.2/emissary-crds.yaml

Next, let’s extract and save the default chart values:

helm show values bit-broker/bit-broker > values.yaml

Next update values.yaml with your required values:

Now we are ready to run the cloud installation with the selected values:

helm install --values values.yaml \
             --create-namespace bit-broker \
             --set bbk-auth-service.JWKS=$JWKS \
             --namespace bit-broker \
               bit-broker/bit-broker

This step takes a few moments to complete. After it has finished, you will see a series of notes which discuss some key points about your installation. The sections on JWKS, Auth Service and Rate Service are for advanced use cases, and you can ignore these for now.

It can take a few moments for the system to come into existence and for it to complete its initialization steps. You can test that the system is up-and-ready, by the using this command:

if [ $(curl --max-time 5 --write-out '%{http_code}' --silent --head --output /dev/null https://your-cloud-host/coordinator/v1) == "401" ]; then echo "Ready"; else echo "Not Ready"; fi;

This will output Not Ready until all the servers are up, after which it will output Ready. Keep trying this command until it signals it’s OK to proceed.

Installing a DNS Alias

If you want to add an alias to this installation into your DNS record, then you need to first get the service load balancer address:

kubectl get svc --no-headers -o custom-columns=":status.loadBalancer.ingress[0].hostname" --selector=app.kubernetes.io/name=bbk-emissary-ingress -n bit-broker | head -1

Then you can use this to add an ALIAS into your DNS record. Depending on the domain and the registrar, the procedure and naming terminology will be different. Here is an example procedure for AWS’s Route 53.

Bootstrap Coordinator Token

A key thing to note in the results output, is the section which says: “Here is how to get the Coordinator token”. Extracting and recording this token is a vital step to proceed with the install. This is the bootstrap coordinator token, which we outlined earlier in this document.

As the results output states, you can get hold of this bootstrap coordinator token as follows:

kubectl exec $(kubectl get pods --no-headers -o custom-columns=":metadata.name" --selector=app=bit-broker-bbk-auth-service -n bit-broker | head -1) -n bit-broker -c auth-service -- npm run sign-token coordinator $(kubectl get secret --namespace bit-broker bit-broker-bbk-admin-jti -o jsonpath="{.data.ADMIN_JTI}" | base64 --decode)

This is a long command and it will take a few seconds to complete. It will output the token, which will be in the format of a long string. Copy this token and store in a secure location. Be careful if sharing this token, as it has full rights to the entire Coordinator API.

Testing Your Installation

If everything worked as expected, the BitBroker API servers will be up-and-running in your cloud waiting for calls. You can test this by using the sample call below:

curl https://your-cloud-host/coordinator/v1 \
     --header "x-bbk-auth-token: bootstrap-token-goes-here"

The base end-points of all the three API servers respond with a small announcement:

{
    "now": "2022-06-16T10:44:53.970Z",
    "name": "bit-broker coordinator service",
    "base": "https://your-cloud-host/coordinator/v1",
    "status": "production"
}

Like all BitBroker API end-points, these require a working authorization to be in place. Hence, this announcement can be used for testing or verification purposes.

Uninstallation

If you want to completely uninstall this instance of BitBroker, you should follow these steps:

helm uninstall bit-broker -n bit-broker
kubectl delete -f https://app.getambassador.io/yaml/emissary/2.2.2/emissary-crds.yaml
kubectl delete namespace bit-broker
helm repo remove bit-broker
docker ps -a | grep "bbkr/" | awk '{print $1}' | xargs docker rm
rm values_local.*

This will remove all the key elements which were created as part of the installation. If you want to go further and clear out all the images which were downloaded too, use the following:

docker images -a | grep "bbkr/" | awk '{print $3}' | uniq | xargs docker rmi

Local Kubernetes Installation

In the section, we will explore how to you can use our pre-prepared Helm charts to install a complete BitBroker instance on your local machine. These charts will be downloaded directly from Docker Hub.

Prerequisites

Start with a clean machine, with no remnants of previous BitBroker installations. Please ensure you have the following software installed, configured and operational:

• Kubernetes command line tools
• Helm command line tools
• Docker Desktop
• cURL command line tool (used for testing installs only)

Create a brand new directory to act as a workspace for your installation:

mkdir bbk
cd bbk

Make sure that your current Kubernetes context is docker-desktop:

kubectl config get-contexts
kubectl config use-context docker-desktop

Installation

First, let’s prepare the context we want to install:

helm repo add bit-broker https://bit-broker.github.io/charts
JWKS=$(docker run bbkr/auth-service:latest npm run --silent create-jwks)
kubectl apply -f https://app.getambassador.io/yaml/emissary/2.2.2/emissary-crds.yaml

Our pre-prepared Helm charts are, by default, configured for production, cloud environments. However, here we want to install to localhost only. So we need to make some modifications to the default chart to cater for this:

helm show values bit-broker/bit-broker > values_local.yaml
sed -e 's/gateway[ ]*:/gateway: {}/g' \
    -e 's/acmeProvider/# acmeProvider/g' \
    -e 's/certificateIssuer/# certificateIssuer/g' \
    -e 's/#[ ]*host:[ ]*"https:\/\/bit-broker.io"/host: "http:\/\/localhost"/g' \
    -i '_old' \
    values_local.yaml

Now we are ready to run the local installation:

helm install --values values_local.yaml \
             --create-namespace bit-broker \
             --set bbk-auth-service.JWKS=$JWKS \
             --namespace bit-broker \
               bit-broker/bit-broker

This step takes a few moments to complete. After it has finished, you will see a series of notes which discuss some key points about your installation. The sections on JWKS, Auth Service and Rate Service are for advanced use cases, and you can ignore these for now.

It can take a few moments for the system to come into existence and for it to complete its initialization steps. You can test that the system is up-and-ready, by the using this command:

if [ $(curl --max-time 5 --write-out '%{http_code}' --silent --head --output /dev/null http://localhost/coordinator/v1) == "401" ]; then echo "Ready"; else echo "Not Ready"; fi;

This will output Not Ready until all the servers are up, after which it will output Ready. Keep trying this command until it signals it’s OK to proceed.

Bootstrap Coordinator Token

A key thing to note in the results output, is the section which says: “Here is how to get the Coordinator token”. Extracting and recording this token is a vital step to proceed with the install. This is the bootstrap coordinator token, which we outlined earlier in this document.

As the results output states, you can get hold of this bootstrap coordinator token as follows:

kubectl exec $(kubectl get pods --no-headers -o custom-columns=":metadata.name" --selector=app=bit-broker-bbk-auth-service -n bit-broker | head -1) -n bit-broker -c auth-service -- npm run sign-token coordinator $(kubectl get secret --namespace bit-broker bit-broker-bbk-admin-jti -o jsonpath="{.data.ADMIN_JTI}" | base64 --decode)

This is a long command and it will take a few seconds to complete. It will output the token, which will be in the format of a long string. Copy this token and store in a secure location. Be careful if sharing this token, as it has full rights to the entire Coordinator API.

Testing Your Installation

If everything worked as expected, the BitBroker API servers will be up-and-running on localhost waiting for calls. You can test this by using the sample call below:

curl http://localhost/coordinator/v1 \
     --header "x-bbk-auth-token: bootstrap-token-goes-here"

The base end-points of all the three API servers respond with a small announcement:

{
    "now": "2022-06-16T10:44:53.970Z",
    "name": "bit-broker coordinator service",
    "base": "http://localhost/coordinator/v1",
    "status": "production"
}

Like all BitBroker API end-points, these require a working authorization to be in place. Hence, this announcement can be used for testing or verification purposes.

Uninstallation

If you want to completely uninstall this instance of BitBroker, you should follow these steps:

helm uninstall bit-broker -n bit-broker
kubectl delete -f https://app.getambassador.io/yaml/emissary/2.2.2/emissary-crds.yaml
kubectl delete namespace bit-broker
helm repo remove bit-broker
docker ps -a | grep "bbkr/" | awk '{print $1}' | xargs docker rm
rm values_local.*

This will remove all the key elements which were created as part of the installation. If you want to go further and clear out all the images which were downloaded too, use the following:

docker images -a | grep "bbkr/" | awk '{print $3}' | uniq | xargs docker rmi