Software Setup

After successful setup of the hardware, it is time to refresh your software. All the required software are already installed and tested, but you SHOULD update them to the latest version to get all the features.

Command Line Interface (CLI) Setup

CLI is distributed as a Snap package, and you receive automatic update for it once installed. The Snap is installed by default in your control-plane and devops machines. To use it for another machine, you need to install it manually.

sudo snap install br-t9s --channel=beta

You can upgrade it to the latest version by running the following command:

sudo snap refresh br-t9s --channel=beta

danger

Due the bugs in Canonical Snapd, it does not automatically create the user configuration unless you run the Snap once as the user. Hence, please after installation, BEFORE DOING ANYTHING ELSE, just run the following command as your user:

br-t9s.cli help

tip

After the delivery, it is always a good idea to check if there is a new version of the Snap package.

In the Bronze release, it contains the following applications:

• Command Line Interface (CLI): br-t9s.cli
• Container Development Kit (CDK): br-t9s.cdk

Credentials

Most of the applications in the CLI require one or more credentials to be able to connect to the Kubernetes cluster or container registries. To be consistent with Kubernetes, we follow the same credential management approach.

Copy the Kubernetes configuration file from the USB stick given to you to ~/snap/br-t9s/current/.kube/config. Perhaps before that you need to create the directory ~/snap/br-t9s/current/.kube/ if it does not exist.

danger

NEVER use sudo to interact with the CLI applications. This will mess up the permissions, and you will not be able to use the applications properly.

caution

If you open the configuration file, you find the following structure:

apiVersion: v1
clusters:
    -   cluster:
            certificate-authority-data: DATA+OMITTED
            server: https://192.168.0.2:6443
        name: kubernetes
contexts:
    -   context:
            cluster: kubernetes
            user: kubernetes-admin
        name: kubernetes-admin@kubernetes
current-context: kubernetes-admin@kubernetes
kind: Config
preferences: { }
users:
    -   name: kubernetes-admin
        user:
            client-certificate-data: REDACTED
            client-key-data: REDACTED

The server field is the IP address and port number of the Kubernetes API server. You should be able to access it from the machine where you have CTL installed. Make sure the firewalls are configured properly in between the CTL machine and the Kubernetes cluster. You could use port forwarding or similar techniques to make it work. Contact BubbleRAN support if you have any issues.

For OCI ORAS you need to log into the container registry. For this matter you need to run the following command AFTER you have set up the aliases.

oras login hub.bubbleran.com

Use the credentials provided to you by BubbleRAN in your USB stick to log in.

tip

DevOps customers that need to log into their private container registry should follow the same approach, but perhaps skip the TLS verification, if you have not set up the certificate properly.

Aliases

To make the usage of the CTL applications easier, we have created a set of aliases. You add the following lines to the end of the file ~/.aliases:

# bubbleran cli aliases
alias cli=br-t9s.cli
alias brc=br-t9s.cli
alias t9s-cli=br-t9s.cli
alias br-cli=br-t9s.cli
alias br-ctl=br-t9s.cli
alias t9s-ctl=br-t9s.cli

# bubbleran cdk aliases
alias cdk=br-t9s.cdk
alias t9s-cdk=br-t9s.cdk
alias br-cdk=br-t9s.cdk

tip

You need to create a new shell session to make the aliases available or source the file ~/.aliases.

tip

Debugging aliases:

• In bash, check whether in the file ~/.bashrc there is a line source ~/.aliases.
• In zsh, check whether in the file ~/.zshrc there is a line source ~/.aliases.
• In fish, check whether in the file ~/.config/fish/config.fish there is a line source ~/.aliases.
• In other shells, check whether in the file ~/.profile there is a line source ~/.aliases.

Autocompletion

To make the best out of the CTL applications, we enable autocompletion for the commands. Based on your shell follow one of the following instructions.

Bash

Run the following commands:

cli completion bash >/tmp/cli.bash
cdk completion bash >/tmp/cdk.bash
kubectl completion bash >/tmp/kubectl.bash
helm completion bash >/tmp/helm.bash

sudo cp /tmp/cli.bash /usr/share/bash-completion/completions/cli
sudo cp /tmp/cdk.bash /usr/share/bash-completion/completions/cdk
sudo cp /tmp/kubectl.bash /usr/share/bash-completion/completions/kubectl
sudo cp /tmp/helm.bash /usr/share/bash-completion/completions/helm

caution

All the users on the machine will have access to the autocompletion.

Zsh (but not Oh My Zsh)

Run the following commands:

cli completion zsh >/tmp/cli.zsh
cdk completion zsh >/tmp/cdk.zsh
kubectl completion zsh >/tmp/kubectl.zsh
helm completion zsh >/tmp/helm.zsh

sudo cp /tmp/cli.zsh /usr/share/zsh/site-functions/_cli
sudo cp /tmp/cdk.zsh /usr/share/zsh/site-functions/_cdk
sudo cp /tmp/kubectl.zsh /usr/share/zsh/site-functions/_kubectl
sudo cp /tmp/helm.zsh /usr/share/zsh/site-functions/_helm

caution

All the users on the machine will have access to the autocompletion.

OhMyZsh Plugin

Run the following commands:

mkdir --parents ~/.oh-my-zsh/custom/plugins/t9s/src
echo 'fpath+="${0:h}/src"' > ~/.oh-my-zsh/custom/plugins/t9s/t9s.plugin.zsh
cli completion zsh > ~/.oh-my-zsh/custom/plugins/t9s/src/_cli
cdk completion zsh > ~/.oh-my-zsh/custom/plugins/t9s/src/_cdk
kubectl completion zsh > ~/.oh-my-zsh/custom/plugins/t9s/src/_kubectl
helm completion zsh > ~/.oh-my-zsh/custom/plugins/t9s/src/_helm

Then enable t9s plugin by adding it into the list of plugins in the ~/.zshrc.

First Steps with the CLI

After you have the CLI ready, there are several initial steps you need to take to ensure integrity of your setup.

Performing a diagnostic

The first step is to perform a diagnostic of your setup. The command to perform the diagnostic is:

cli diag

In the Bronze release, the diagnostic will check the following:

1. Cluster availability
2. Nodes availability
3. Operators installation
4. Login information

Extracting infrastructure information

The command:

cli extract infra

generates a tabular output of the infrastructure information. It contains two tables:

1. Cluster information where the cluster nodes are listed.
2. Non-cluster information where the NiBs are listed.

The cluster information contains the following columns:

• CLUSTER - with REGION, ROLE, NAME, and IP address of each node.
• SYSTEM - with the OS, KERNEL, and RUNTIME of each node.
• COMPUTE - with the ARCH, VENDOR, CPU, and MEM of each node.
• RADIO - with DEVICE, TERMINALS, and SYNC status of each node.

tip

The REGION is a virtual grouping of the nodes, useful for simulating multi-region deployments.

Update Operators

You might not have the latest version of the operators installed on your machine, as during the delivery and setup time of your product, a newer version might have been released. As of the Bronze release, the following operators are available:

Operator Name	Provider	Latest Available Version
Athena	BubbleRAN	v1.5.0
ODIN	BubbleRAN	v0.6.0

To check the version of the installed operator, you could use either of the following commands:

cli list operators

which runs the diagnostics and prints the version of the installed operator, or

kubectl operator list -A

which lists all the installed operators.

We STRONGLY recommend to remove the older version of the operator and install the latest version, by running the following commands:

cli remove operator athena:{version}
cli install operator athena:v1.5.0

where {version} is the version of the operator you have installed.

Update Models

It is always a good idea to update the models to the latest version. Before that, you need to know which models are installed on your cluster.

cli list models

For each of the models that you see, you need to upgrade them by running:

cli upgrade model {model-name}

Several models are private and need authentication to be downloaded. You could provide the credentials either in the command-line or by using the enviromnet variables. For the username and password, you could use the following command:

cli upgrade model {model-name} --username {username} --password {password}

or you could use the environment variables:

export CLI_USERNAME={username}
export CLI_PASSWORD={password}
cli upgrade model {model-name}

tip

Putting your credentials into your default shell profile to have them available for all the commands is a good idea. Using the command-line arguments is not recommended as they will be visible in the shell history.

Update Device Plugins

In rare cases, you might need to update the device plugins. For doing so, you simply roll out the device plugin pods by running:

kubectl rollout restart daemonset --namespace gaia pontus
kubectl rollout status daemonset --namespace gaia pontus

tip

Check the release notes to see if you need to update the device plugins.