Install Beamlit controller

The open-source Beamlit controller allows to remotely create and control objects (such as models) on a destination cluster. The destination cluster can be Beamlit Global Inference Network or any of your Kubernetes clusters. The Beamlit controller can also monitor the health of any AI app deployed in your cluster. A Beamlit gateway (installed in your cluster alongside the controller) load-balances requests between your deployment and the one in the destination when needed.

​

Prerequisites

Before you begin, ensure that you have the following:

1. A Kubernetes Cluster: A running Kubernetes cluster (version 1.27 or later is recommended). You can use managed services like Amazon EKS, Google GKE, Azure AKS, or set up your own cluster.

2. kubectl: Installed and configured to interact with your Kubernetes cluster. Installation Guide.

3. Helm. Version 3.8.0 or later is recommended in order to use OCI-based registries. Check out the Installation Guide.

4. A service account created in your Beamlit workspace, for which you have retrieved the client ID and client secret

​

Install the controller with Helm

​

Configure custom values (optional)

The Helm chart comes with default configurations, but you can customize them as needed.

1. Fetch default values.yaml:

   wget https://raw.githubusercontent.com/beamlit/beamlit-controller/refs/heads/main/chart/values.yaml
   

2. Edit values.yaml:

   Open values.yaml in your preferred text editor and modify the parameters as needed.

   beamlitApiToken is a required parameter that is the base64 encoding of the concatenation of clientId and clientSecret with a colon in between, like so: clientId:clientSecret

   Example:

   allowedNamespaces:
     - default
   config:
     namespaces: default
   	defaultRemoteBackend:
   		authConfig:
         # -- client-id
         clientId: "REPLACE_ME"
         # -- client-secret
         clientSecret: "REPLACE_ME"
   beamlitApiToken: "REPLACE_ME"
   

​

Install the controller

Once you have configured your settings, proceed to install the controller. It is recommended to create a new namespace for this.

1. Basic installation (with default values.yaml)

   helm install beamlit-controller oci://ghcr.io/beamlit/beamlit-controller-chart
   

2. Installation with custom values.yaml:

   If you’ve customized the values.yaml, use the -f flag to apply your configurations.

   helm install beamlit-controller oci://ghcr.io/beamlit/beamlit-controller-chart -f values.yaml
   

3. Verify installation:

   helm list
   

​

Verify the installation

Ensure that all components of the controller are running correctly.

1. Check pods:

   kubectl get pods
   

   You should see pods related to the Beamlit controller and gateway in the Running state.

2. Check logs:

   To troubleshoot or verify operations, view the logs of the controller pod.

   kubectl logs -l app.kubernetes.io/name=beamlit
   

​

Upgrading the controller

To upgrade the controller to a newer version, follow these steps:

1. Upgrade the release. You can refer to this Helm documentation on subcommands:

   helm upgrade beamlit-controller oci://ghcr.io/beamlit/beamlit-controller-chart
   

   If you have a custom values.yaml, include the -f flag:

   helm upgrade beamlit-controller oci://ghcr.io/beamlit/beamlit-controller-chart -f values.yaml
   

2. Verify the upgrade:

   Check the status of the release to ensure the upgrade was successful.

   helm status beamlit-controller
   

​

Uninstalling the controller

If you need to remove the controller from your cluster, run this command:

helm uninstall beamlit-controller

​

Additional Resources

• Helm Documentation: https://helm.sh/docs/
• Kubernetes Documentation: https://kubernetes.io/docs/

​

Troubleshooting Tips

• Helm Not Found Error: Ensure Helm is installed and added to your system’s PATH.
• Permission Denied: Verify that your Kubernetes context has the necessary permissions to install resources in the target namespace.
• Pod CrashLoopBackOff: Check the pod logs for errors and ensure that all required configurations (e.g., API keys) are correctly set in values.yaml.
• Network Issues: Ensure that your cluster can reach the control plane endpoint specified in the configuration.