Skip to content

Local VM Cluster Setup

This guide provides detailed deployment instructions for a local cluster deployment in a VM. This is only recommended for testing and development purposes.

Below we provide two different deployment options, which are similar during deployment, and mainly differ in initial setup.

  • Lima VM
  • Minikube

VM cluster initialisation

Here you need to follow either the Lima VM or the Minikube instructions.

Lima VM setup

Prerequisites

  • Lima VM - v1.2.1 (currently incompatible with v2)
  • Helm - v3.19 (currently incompatible with v4)
  • OpenShift CLI
  • Kubectl (bundled with above)
  • jq - json command-line processor
  • yq - yaml command-line processor
  • Minimum 8GB RAM and 4 CPUs available for the VM (more recommended)

VM cluster initialization

  1. Install Lima VM. Needs to be v1.2.1 (not yet compatible with v2)

  2. Install Python dependencies: 

    pip install -f requirements.txt

  3. Start the Lima VM cluster: 

    limactl start --name=studio deployment-scripts/lima/studio.yaml

  4. Set up the kubectl context (NB: you will need to do this in each terminal prompt where you with to interact with the cluster, i.e. deploy, k9s): 

    export KUBECONFIG="$HOME/.lima/studio/copied-from-guest/kubeconfig.yaml"

  5. To monitor subsequent deployment on the cluster you can use a tool such as k9s.

Other lima commands that you might find useful are:

# List vms
limactl ls

# Open a shell for the vm
limactl shell studio

# Stop the vm
limactl stop studio

# Delete the vm (useful if you wish to do a clean deployment, also delete persisted data separately)
limactl delete studio --force

Minikube setup

Prerequisites

  • Docker / Podman installed and running
  • Helm - v3.19 (currently incompatible with v4)
  • OpenShift CLI
  • Kubectl (bundled with above)
  • jq - json command-line processor
  • yq - yaml command-line processor
  • Minimum 8GB RAM and 4 CPUs available for the VM (more recommended)

VM cluster initialization

  1. Follow the Getting started guide to setup and install your local minikube instance.

  2. Start the Minikube cluster. Ensure your container machine configuration has resource allocation for memory > 8g and cpu > 4

# Start with recommended resources for geospatial workloads
minikube start --driver=podman --container-runtime=containerd  --memory=8g --cpus=4

# Verify cluster is running
minikube status

  1. Install the following minikube addons: 

    minikube addons enable metrics-server
minikube addons enable storage-provisioner
minikube addons enable dashboard

  2. Setup the kubectl context: 

    # Set kubectl context to minikube
kubectl config use-context minikube

# Verify you're connected to the right cluster
kubectl config current-context

  3. To monitor deployment on the cluster you can use: 

    minikube dashboard

Geospatial Studio - Deployment instructions (automated)

9. API Testing Guide

To test the APIs using the provided payloads, follow this guide. You'll need an API client like curl or Insomnia.

Check the API's Swagger Page: [https://localhost:4181]

Authenticate with the API Key

The API requires an api-key or oauth-token for authentication. Use the default api-key used in your deployment flow to get started.

In your requests, you'll pass this key in a header: -H "X-API-Key: $STUDIO_API_KEY"

Test Payload

Use the default data provided under /tests/api-data/*.json as the payloads to hit the endpoints.

Sample POST requests:

  1. ADD a sandbox models resource

    bash curl -kX POST 'https://localhost:4181/v2/models' \ --header 'Content-Type: application/json' \ --header "X-API-Key: $STUDIO_API_KEY" \ --data @tests/api-data/00-inf-models.json

  2. SUBMIT a test inference

    bash curl -kX POST 'https://localhost:4181/v2/inference' \ --header 'Content-Type: application/json' \ --header "X-API-Key: $STUDIO_API_KEY" \ --data @tests/api-data/01-inf-inferences.json

    Check the UI, inference lab history to check the onboarded inference

  3. SUBMIT a test onboarding dataset

    bash curl -kX POST 'https://localhost:4181/v2/datasets/onboard' \ --header 'Content-Type: application/json' \ --header "X-API-Key: $STUDIO_API_KEY" \ --data @tests/api-data/02-ft-datasets.json

  4. SUBMIT a test onboarding finetuning base model

    bash curl -kX POST 'https://localhost:4181/v2/base-models' \ --header 'Content-Type: application/json' \ --header "X-API-Key: $STUDIO_API_KEY" \ --data @tests/api-data/04-ft-base-models.json

  5. SUBMIT a test onboarding finetuning template

    bash curl -kX POST 'https://localhost:4181/v2/tune-templates' \ --header 'Content-Type: application/json' \ --header "X-API-Key: $STUDIO_API_KEY" \ --data @tests/api-data/03-ft-templates.json