Install Polyaxon on Minikube

Quick start

The easiest way to deploy Polyaxon on Minikube is with the Polyaxon CLI. The quick start uses the default chart values; the following sections show how to customize the same deployment and manage it with either the CLI or Helm.

Note: Minikube is not meant to be a production environment.

Before you can deploy Polyaxon, make sure you have the following:

• Minikube and a driver supported on your operating system.
• kubectl compatible with the cluster.
• Helm 3, whose commands below do not require Tiller.
• Polyaxon CLI.

Start a dedicated profile with enough room for the platform and a small CPU workload:

minikube start --profile polyaxon-local --cpus 4 --memory 8192 --disk-size=40g
kubectl config use-context polyaxon-local
kubectl get nodes

Check the deployment tools and chart repository, then deploy Polyaxon with the Minikube shortcut:

polyaxon admin deploy -t minikube --check
polyaxon admin deploy -t minikube

The CLI manages the Helm installation and creates the polyaxon namespace if needed. The -t minikube shortcut selects a NodePort gateway. To choose a chart version, storage, or other settings before installing, use the custom configuration below instead.

Once installed, inspect readiness:

kubectl get pods -n polyaxon

Expose Polyaxon UI on your localhost:

polyaxon port-forward

Custom Minikube deployment

Please consider reading our configuration setup guides to have a deeper knowledge about how to configure and customize Polyaxon to fit your needs.

If you already installed the quick-start release, save the custom configuration and apply it with the upgrade instructions rather than installing a second release.

Choose a Minikube driver that supports your host and workload. CPU architecture, virtualization, networking, and GPU support vary by driver; a local CPU installation does not establish GPU compatibility.

The quick-start allocation is a starting budget, not a guarantee that every training job will fit. Inspect the profile before adjusting its resources:

minikube status --profile polyaxon-local
kubectl describe nodes

Account for the host operating system as well as the platform, images, artifact storage, and jobs. Read our resource sizing guide before increasing workload concurrency.

RBAC

Keep Kubernetes RBAC and the chart's RBAC resources enabled. Disabling authorization is not a remedy for a deployment permission error. Inspect the intended identity and resolve the missing permission:

kubectl auth can-i create deployments --namespace polyaxon

Create a namespace for Polyaxon

Polyaxon uses a dedicated namespace to keep its installation and operations separate from other applications. This guide uses polyaxon consistently. If the quick start already created it, reuse it; otherwise, create it before the manual Helm installation:

kubectl create namespace polyaxon

If you would like to use a different value, you must keep in mind to update the namespace value in your config.

Configuration

This section will help you create a configuration file to deploy Polyaxon. Polyaxon ships with default values, however and depending on your use case you might need to override some of these values. To do so, you need to create a configuration file and we recommend to save it somewhere safe so that you can reuse it in the future.

Create config.yaml with the values you want to override, and retain it with your deployment record.

Set Minikube deployment type

Set deploymentType: minikube in the saved configuration. Also retain releaseName, namespace, and deploymentVersion so subsequent CLI upgrades and teardown target the same installation. Replace the version placeholder with the chart version selected in the installation section.

Configure RBAC, ingress, and local storage

Use config.yaml consistently for the rest of this guide. This configuration keeps RBAC enabled, disables ingress, and uses an internal gateway with a node-local artifact store for this single-node learning environment:

deploymentType: minikube

rbac:
  enabled: false
gateway:
  service:
    type: ClusterIP
ingress:
  enabled: false
artifactsStore:
  name: local-artifacts
  kind: host_path
  schema:
    hostPath: /data/polyaxon-artifacts
    mountPath: /artifactsStore

Here gateway.service.type: ClusterIP uses local port forwarding. For access through minikube service, change it to NodePort as described in the Minikube IP section. Use polyaxon admin deploy -f config.yaml for this custom configuration; adding the -t minikube shortcut overrides the gateway service type to NodePort.

The host path belongs to the Minikube node, which may be inside a VM or container. Create the directory there if needed and set access for the workload identity before submitting work. It is not a shared multi-node store or a backup, and deleting the profile can destroy its data. For persistent installations, configure an artifact connection and database persistence appropriate to the chosen edition.

Install Polyaxon

First, add the Polyaxon Helm repository to your helm, so you can install Polyaxon from it. This makes it easy to refer to Polyaxon chart without having to use a long URL each time.

helm repo add polyaxon https://charts.polyaxon.com
helm repo update
helm search repo polyaxon/polyaxon --versions

Select a chart release supported by your Kubernetes version and review its values and release notes. Set POLYAXON_CHART_VERSION and the deploymentVersion value in config.yaml to that same version before continuing:

export POLYAXON_CHART_VERSION=REPLACE_WITH_CHART_VERSION
helm show values polyaxon/polyaxon --version "$POLYAXON_CHART_VERSION"

Validate

Use the Polyaxon admin CLI to check the deployment configuration and required tools:

polyaxon admin deploy -f config.yaml --check

Then inspect a dry run of the selected chart:

polyaxon admin deploy -f config.yaml --dry-run

Alternatively, render it directly with Helm. Rendering reveals the Kubernetes objects but does not prove that storage, images, or workloads will work:

helm template polyaxon polyaxon/polyaxon --namespace polyaxon \
  --version "$POLYAXON_CHART_VERSION" -f config.yaml

Deploy

Install the selected chart with your config.yaml file using the Polyaxon CLI:

polyaxon admin deploy -f config.yaml

Or perform the installation directly with Helm. Choose one installation command for this release:

helm install polyaxon polyaxon/polyaxon --namespace polyaxon \
  --version "$POLYAXON_CHART_VERSION" -f config.yaml --wait --timeout 10m

The first polyaxon is the release identifier used by Helm to refer to this deployment. You need it when you are changing the configuration of this install or deleting it. We recommend using RELEASE_NAME = polyaxon or RELEASE_NAME = plx.

--namespace should be the same value of the namespace you created in the first step, we again recommend using polyaxon to make it always easy to remember.

If the release already exists, inspect helm status polyaxon --namespace polyaxon and helm history polyaxon --namespace polyaxon. Use the upgrade procedure for an existing installation; deleting it merely to reuse the name can remove resources and interrupt workloads.

You can see the pods being created by entering in a different terminal:

kubectl --namespace polyaxon get pods,pvc,services

After installation, Helm prints chart-specific NOTES. Read them for the selected edition and gateway configuration.

Minikube IP

The gateway can be accessed with a local port forward without a NodePort or a public Minikube IP:

kubectl --namespace polyaxon port-forward service/polyaxon-polyaxon-gateway 8000:80

Open http://localhost:8000 while that command is running. Alternatively, polyaxon port-forward also configures the Polyaxon client. Choose one forwarding command, and inspect the actual Service name if you changed the release name.

You can also use Minikube's service access workflow. If you used the CLI's -t minikube shortcut, the gateway is already a NodePort service. For the custom configuration, set gateway.service.type: NodePort in config.yaml and apply it with an upgrade first. Then request the gateway URL:

minikube service --profile polyaxon-local --namespace polyaxon polyaxon-polyaxon-gateway --url

Use the returned URL for the dashboard and client. Depending on the driver, the command can open a local tunnel; keep that terminal running. When the node IP is directly reachable, you can also inspect it with:

minikube ip --profile polyaxon-local
kubectl get service polyaxon-polyaxon-gateway --namespace polyaxon

Use the Service's assigned NodePort with that IP, rather than assuming port 80 is exposed on the node. See Minikube's application access guide for driver-specific networking behavior.

These notes are important for setting the CLI, and getting access to the dashboard.

With the Polyaxon CLI installed, configure the endpoint from the service URL or chart notes. For example, when using the local port forward:

polyaxon config set --host=http://localhost:8000

Upgrade Polyaxon

Review the target release's migration and backup requirements, then set both deploymentVersion in config.yaml and POLYAXON_CHART_VERSION to the selected version. Check and preview the upgrade with your saved values:

polyaxon admin upgrade -f config.yaml --check
polyaxon admin upgrade -f config.yaml --dry-run

Apply it with the Polyaxon CLI:

polyaxon admin upgrade -f config.yaml

Or upgrade the same release directly with Helm:

helm upgrade polyaxon polyaxon/polyaxon --namespace polyaxon \
  --version "$POLYAXON_CHART_VERSION" -f config.yaml --wait --timeout 10m

Applying configuration changes

The general method to modify your Kubernetes deployment is to:

1. Save the existing values and review the target chart's release notes, database migrations, and backup requirements.

2. Change config.yaml, run polyaxon admin upgrade -f config.yaml --check, and inspect polyaxon admin upgrade -f config.yaml --dry-run or the Helm rendering. Keep deploymentVersion unchanged when you intend only to change configuration.

3. Apply the configuration with the CLI:

   polyaxon admin upgrade -f config.yaml

   Or use Helm for the same release:

   helm upgrade polyaxon polyaxon/polyaxon --namespace polyaxon \
     --version "$POLYAXON_CHART_VERSION" -f config.yaml --wait --timeout 10m

   Keep the release name, namespace, chart version, and values file together in your deployment record. helm list --namespace polyaxon shows the release.

4. Inspect Pod readiness, PVC binding, and the gateway, then confirm that a small operation can store and retrieve its artifacts.

Turn off Polyaxon

When you are done with Polyaxon, you can turn off the deployment, and depending on your persistence configuration you can keep all your data saved for future deployments.

You can also decide to completely turn off Polyaxon and remove the namespace and computational resources.

Stop/Delete running experiments/jobs

Stop active operations through Polyaxon and preserve the outputs you need before uninstalling. Review the selected chart's hooks and remaining Kubernetes resources; do not assume that every workload or external resource is removed by uninstalling the release.

Delete Helm release

Use the saved configuration to remove the deployment through the Polyaxon CLI:

polyaxon admin teardown -f config.yaml

For the default quick-start release, polyaxon admin teardown also uses the default release name and namespace. The CLI asks whether to execute pre-delete hooks; choose according to the cleanup you need.

Alternatively, uninstall the release with Helm. Helm removes its managed resources, subject to hooks and retention policies; CRDs, retained PVCs, and external storage need separate review.

helm uninstall polyaxon --namespace polyaxon

If cleanup fails, inspect the hook Job and its events before changing the procedure. For a failed installation where you have accounted for the remaining jobs and resources, you can skip hooks explicitly:

helm uninstall polyaxon --namespace polyaxon --no-hooks

Skipping hooks leaves their cleanup work to you; it is a recovery option rather than the normal teardown path.

Delete the namespace

Delete the namespace only after inspecting its remaining resources and backing up required data. Namespace deletion removes namespaced objects, including PVCs; the PV reclaim policy determines what happens to backing storage. Host-path files and external objects have their own lifecycle.

kubectl delete namespace polyaxon

To pause the local cluster instead of removing it, use minikube stop --profile polyaxon-local. Treat deletion of that profile as a separate decision affecting its local data.