Setting Up Local Kubernetes Infrastructure on MacOS Using Minikube

Overview

Running machine learning workloads locally on MacOS requires a reliable yet lightweight Kubernetes environment. This guide walks you through creating a complete Kubernetes setup on your laptop, workstation, or a single local server. It is designed for development or small-scale workloads where you want full control without depending on cloud infrastructure.

You will create a single-node cluster, configure storage, and then deploy the tracebloc client. The result is a local platform for securely training and benchmarking AI models while keeping all data on your machine.

The entire setup can be completed in about 1 hour.

Note: MacOS GPU setup with Minikube is not possible.

Prerequisites

Before proceeding with the local infrastructure setup, make sure the following requirements are met:

System Requirements

Hardware Specifications

• Minimum: 4 CPU cores, 8 GB RAM for basic workloads
• Recommended: 8+ CPU cores, 16+ GB RAM for heavy computer vision or NLP workloads
• Your machine must have sufficient disk space for container images, training data, and model artifacts

Required Tooling & Tracebloc Account

Tool	Purpose	Installation Link
Docker	Container runtime	Docker
Minikube	Runs a local Kubernetes cluster	Minikube
kubectl	Command-line tool to interact with Kubernetes clusters	kubectl
Helm 3.x	Package manager for Kubernetes, used to install and manage applications	Helm

Tracebloc Account

• Client ID and Password from the tracebloc client view (client ID, password)
• Docker Hub registry credentials (username, token/password, email)

Recommended for Monitoring: Use k9s

You can use k9s, a terminal-based Kubernetes dashboard, to monitor jobs, pods, and logs in real time. Run k9s -n <NAMESPACE> to get a live view of resources, switch between them instantly, and inspect logs or events with a few keystrokes. Compared to kubectl, it is faster and more convenient.

Components

The local deployment consists of two main parts: Core Infrastructure and Client Deployment. Together, they provide a secure, scalable environment for running ML workloads with the tracebloc client.

Core Infrastructure

Local Kubernetes cluster: A single-node Kubernetes control plane and worker combined, provisioned with Minikube.

Docker Runtime: Provides the runtime environment for all workloads.

Persistent Storage: hostPath-based directories mounted into the cluster to store datasets, logs, and artifacts.

Local Networking: DNS for pod-to-pod networking.

Client Deployment

tracebloc Client Application: Deployed into the local Minikube cluster using Helm, configured with credentials, registry access, and storage.

Monitoring and Verification: Kubernetes tools to confirm pods, services, and persistent volumes are running correctly.

Process Flow

1. Infrastructure Setup – Create local cluster, configure storage and networking
2. Client Deployment – Configure and deploy the tracebloc client application
3. Verification – Validate that everything is running correctly

Security

Security is a core consideration even when running workloads on a local machine. This setup follows Kubernetes best practices to ensure your data remains protected and workloads are isolated, while still allowing external models to be evaluated safely.

Data Protection

• Data Locality: Training data stays on your local machine.
• Model Encryption: Model weights are encrypted and never leave your environment.
• Secure Communication: All communication is protected with TLS.

Tracebloc Backend Security

• Code Analysis: Submitted models scanned with Bandit for vulnerabilities.
• Input Validation: Training scripts and code validated before execution.
• Container Isolation: Training runs inside Docker containers with restricted system access.
• Namespace Isolation: Kubernetes namespace separates workloads from other applications.

Required Outbound Access

• *.docker.io – Container image downloads
• *.tracebloc.io – Platform communication
• pypi.org and similar – Dependency installation during training

Proxy Support

If your machine is behind a proxy, configure the following in values.yaml:

HTTP_PROXY_HOST: your-proxy.company.com
HTTP_PROXY_PORT: 8080

Quick Setup

Purpose

Spin up a Minikube cluster and deploy the tracebloc client in one go.

What this script does:

• Starts Minikube with recommended resources
• Creates host-path storage directories (datasets, logs, MySQL)
• Deploys the tracebloc client with Helm

Prerequisites:

Docker, Minikube, kubectl, Helm installed and configured.

Run the setup script (example placeholder, adjust to your needs):

# Download and run the automated setup script
tbd

Cleanup:

Delete Minikube cluster and remove created directories.

Tips:

• Network model: local Docker bridge networking.
• Resource limits: increase Minikube memory/CPU for heavy workloads.

If you prefer more control and customization, follow the detailed step-by-step guide below.

Detailed Setup

This section walks through a step-by-step build with Minikube and kubectl. It mirrors the Quick Setup but lets you choose your own resource settings (CPUs, memory, storage paths, namespace, Helm release name, etc.). Expect about 1 hour end-to-end.

What you’ll do (Steps 1–4):

1. Local Cluster Setup — Start a single-node Kubernetes cluster with Minikube. Configure CPU and memory to match your workload requirements and ensure Docker is running as the container runtime. This provides a functional control plane and worker node in one instance.

2. Storage — Create hostPath directories on your machine for datasets, logs, and MySQL files. Mount them as persistent volumes in Kubernetes so data, logs, and model artifacts persist across pod restarts.

3. Client Configuration — Add the tracebloc Helm repository and generate a values.yaml file. Configure authentication credentials, registry access, and storage paths so the client can run securely in your environment.

4. Client Deployment — Install the Helm chart into your chosen namespace. Deploy and verify that the tracebloc client pods and persistent volumes are running and bound correctly.

Helm Usage: Helm is used to install and manage Kubernetes applications. In steps 3 and 4 you will deploy the tracebloc client via the tracebloc/bm (bare metal) chart from the tracebloc Helm repository.

1. Local Cluster Setup

A local Kubernetes cluster is the foundation of this deployment. Minikube packages both the control plane and the worker node into a single instance, running inside Docker. This setup gives you a fully functional Kubernetes environment without the overhead of a cloud provider.

Docker Runtime

Minikube depends on Docker to run its virtualized node. If Docker is not running, Minikube cannot start. Make sure Docker Desktop or the Docker daemon is active before proceeding.

Set Memory and CPU Limit in Docker Settings

By default, Docker Desktop caps memory to around 2 GB, which is insufficient for training workloads. It is strongly recommended to raise the Docker Desktop memory allocation to at least 12 GB. This prevents pods from being evicted under memory pressure and avoids out-of-memory (OOM) errors during training. CPU and memory must be sized appropriately based on the kind of models you expect to train and the resources they demand. Consider dataset size, model type and the number of parallel workloads.

Set up a Local Kubernetes Cluster

Start a Kubernetes cluster using Minikube. By default Minikube can run as a VM (using VirtualBox, HyperKit, etc.) or inside Docker. In this guide we use --driver=docker, which runs the control plane and worker node as containers inside your local Docker daemon. It is lightweight, provides faster startup and less resource overhead and integrates seamlessly with Docker Desktop.

minikube start --memory=8192 --cpus=4 --driver=docker

Starts a local Kubernetes cluster with 8GB RAM and 4 CPU cores. his is the minimum recommended resource configuration. Ensure these values fit within your Docker runtime limits, and increase them for resource-intensive workloads such as computer vision or large language models.

By default Minikube can run as a VM (using VirtualBox, HyperKit, etc.) or inside Docker. In this guide we use --driver=docker, which means the Kubernetes control plane and worker node run as containers inside your local Docker daemon. This avoids the overhead of spinning up a separate VM and integrates smoothly with Docker Desktop.

Verify cluster status:

kubectl get nodes

Create a namespace for your workloads:

kubectl create namespace <NAMESPACE>

Namespaces let you isolate your workloads from system components and other running applications.

Add mandatory node labels to nodes for workload management. Get the nodename, then label nodes:

kubectl label nodes minikube type=system trainingset=cpu

2. Storage

Unlike cloud deployments that use managed storage services, local deployments use hostPath which are real paths on your local machine. Create persistent storage directories for:

• shared-data: For training datasets (json, txt, jpeg, png, etc.), model checkpoints and weights during training
• logs: For application and pod logs for tracebloc client operations
• mysql: For metadata and training data labels

mkdir -p data/shared-data 
mkdir -p data/logs
mkdir -p data/mysql 

These directories will be mounted as Persistent Volumes in Kubernetes.

3. Client Configuration

You can now prepare the Helm chart that deploys the tracebloc client itself: The client is the component that runs your model evaluation and training jobs inside Minikube. To install it, you use a Helm chart, which bundles all required Kubernetes manifests into a single, configurable package. A values.yaml file controls this deployment, where you specify credentials (to authenticate with tracebloc), registry access (to pull container images), and storage settings. This configuration ensures the client can securely connect, schedule workloads, and store results.

Add Helm Repository

Install and update the tracebloc client using Helm instead of managing raw YAML. For details, refer to the public GitHub Repository.

helm repo add tracebloc https://tracebloc.github.io/client/
helm repo update

Adds the official tracebloc Helm repository to your local configuration so you can install the client with a single Helm command.

Configure your Deployment Settings

Export the chart’s default configuration into a local file that you can edit:

helm show values tracebloc/bm > values.yaml

Downloads the default configuration template for the tracebloc client for bm (bare metal). Open and update the following sections in values.yaml:

Deployment Namespace

Use the defined namespace:

namespace: <NAMESPACE>

Defines where the client will be deployed.

Tracebloc Authentication

Client ID

Provide your client ID from the tracebloc client view.

jobsManager:
  env:
    CLIENT_ID: "<YOUR_CLIENT_ID>"

Client Password

Set create: true to generate the secret during installation:

# Secrets configuration
secrets:
  # Whether to create the secret or use existing secret
  create: true
  # Client password
  clientPassword: "<YOUR_CLIENT_PASSWORD>"

Docker Registry Configuration

The tracebloc client images are stored in a private container registry. Kubernetes needs valid Docker Hub credentials to pull these images onto your nodes.

dockerRegistry:
  create: true
  secretName: regcred
  server: https://index.docker.io/v1/
  username: <DOCKER_USERNAME>
  password: <DOCKER_PASSWORD or TOKEN>
  email: <DOCKER_EMAIL>

• DOCKER_USERNAME: Docker Hub username
• DOCKER_PASSWORD: Password or access token (if 2FA enabled)
• DOCKER_TOKEN: Alternative token for automation or personal access
• DOCKER_EMAIL: Email linked to your Docker account

Storage

Your workloads need persistent storage that survives pod restarts and can be shared across all nodes. Minikube uses the local file system:

storageClass:
  # Set to true to create a new storage class, false to use existing. Be careful not to overwrite existing data files by setting it true.
  create: true
  parameters:
    osType: <darwin|linux|windows>

sharedData:
  name: shared-data
  storage: 50Gi
  hostPath: "/absolute/path/to/data/shared-data"

logsPvc:
  name: logs-pvc
  storage: 10Gi
  hostPath: "/absolute/path/to/data/logs"

mysqlPvc:
  name: mysql-pvc
  storage: 2Gi
  hostPath: "/absolute/path/to/data/mysql"

Set Resource Limits at Pod/Container Level

Kubernetes schedules pods based on declared resource requests and enforces limits to prevent a single workload from consuming all available resources. In Minikube this is especially critical since the entire cluster runs on a single node with a fixed CPU and memory budget defined at startup.

If you do not set requests, Kubernetes may over-schedule pods, leading to crashes when memory runs out. If you do not set limits, a single training job can monopolize the node, leaving no room for other workloads.

Size pod requests and limits according to your actual training requirements while keeping them within the CPU and memory you allocated to Minikube with --cpus and --memory.

  RESOURCE_REQUESTS: "cpu=2,memory=8Gi"
  RESOURCE_LIMITS: "cpu=2,memory=8Gi"
  GPU_REQUESTS: ""
  GPU_LIMITS: ""

These values define pod-level resource allocations. Kubernetes then schedules pods onto the Minikube node if the requested resources are available, otherwise the pod remains in a "Pending" state. Resource limits are optional, but they cap the maximum compute a pod can use, preventing it from consuming more than the defined values and starving other workloads.

In short: Set pod requests to what the training actually needs but keep limits well within the total CPU and memory you assigned to Minikube at startup.

Node, Pod, Job relationship

• One Minikube instance equals one node, and that single node runs all pods
• One pod contains one or more containers
• One training run equals one Job, which in most cases creates one pod by default

Pods are lightweight and share the same node within Minikube, but all of them must fit within the resources you allocated when starting Minikube.

Proxy Settings (Optional)

These settings are only needed if your machine connects to the internet through a corporate or institutional proxy or firewall.

  # proxy hostname.
  HTTP_PROXY_HOST: 
  # proxy port.
  HTTP_PROXY_PORT: 
  # username used for proxy authentication if needed.
  HTTP_PROXY_USERNAME: 
  # password used for proxy authentication if needed.
  HTTP_PROXY_PASSWORD:

If you are working on a private laptop or server with a direct internet connection, you can leave these fields empty.

4. Client Deployment

With the configuration ready, deploy the tracebloc client into your Minikube cluster using Helm.

Deploy the client with Helm

Install the tracebloc Helm chart into the specified namespace using your customized values file:

helm install <RELEASE_NAME> tracebloc/bm \
  --namespace <NAMESPACE> \
  --values values.yaml

This creates:

• One MySQL pod: mysql-...
• One tracebloc client pod: tracebloc-jobs-manager-...
• Supporting resources such as a Service, ConfigMap, Secret, and PVC

Install Metrics Server

The Metrics Server is the cluster-wide aggregator for resource usage data. It collects CPU and memory metrics for live resource monitoring. Install it to monitor resource usage:

minikube addons enable metrics-server

Deploys the Metrics Server in high-availability mode for reliable metric collection.

Verification and Maintenance

After deployment, confirm the client is running correctly and learn how to maintain it.

Verify Deployment

Check that all pods are running in your namespace:

Check pod status:

kubectl get pods -n <NAMESPACE>

A few minutes after running the install command, it should show two pods with status "Running". If pods are not running, check the pod logs for error details.

Check services:

kubectl get services -n <NAMESPACE>

It should show the database service "mysql-".

Check persistent volumes:

kubectl get pvc -n <NAMESPACE>

Verifies that all persistent volume claims are bound and storage is available.

Check registry secret:

kubectl get secret regcred -n <NAMESPACE>

Verifies that the Docker registry secret was created successfully for pulling container images.

Maintenance

Update your values:

helm show values tracebloc/bm > new-values.yaml

Edit new-values.yaml with your changes.

Upgrade the deployment:

helm upgrade <RELEASE_NAME> tracebloc/bm \
  --namespace <NAMESPACE> \
  --values new-values.yaml

Uninstall

Remove the Helm release:

helm uninstall <RELEASE_NAME> -n <NAMESPACE>

Clean up persistent resources (optional):

kubectl delete pvc --all -n <NAMESPACE>
kubectl delete namespace <NAMESPACE>

Next Steps

Create a New Use Case

• Prepare your dataset - Upload and configure your training data
• Create an AI use case - Set up a new use case Join an Existing Use Case
• Explore and join available use cases - Browse ongoing AI projects
• Start training models - Begin training on shared datasets

Need Help?

• Email: support@tracebloc.io
• Docs: tracebloc Documentation Portal