Install Polyaxon on MicroK8s

Install MicroK8s

For a new Linux installation, follow the MicroK8s installation requirements, including snap support and access to the microk8s group. Choose a Kubernetes release channel compatible with the Polyaxon chart you plan to use; replace the channel placeholder below before running it.

sudo snap install microk8s --classic --channel=REPLACE_WITH_MINOR/stable
sudo usermod -a -G microk8s "$USER"

Start a new login session so the group change takes effect. If you are returning to a stopped cluster, start it with microk8s start. Then wait for the cluster and enable the basic add-ons:

microk8s status --wait-ready
microk8s enable dns rbac hostpath-storage
microk8s kubectl get nodes
microk8s kubectl get storageclass

The host-path provisioner is suitable for a local learning environment; its volumes are tied to a node. Plan shared or external storage before distributing Polyaxon workloads across nodes.

MicroK8s also provides add-ons for the tools you may want around Polyaxon. Check microk8s status and the add-on catalog for availability and compatibility with your selected channel, then enable the ones you need:

If you do not already have a standalone kubectl, you can expose the bundled command under that name so the Polyaxon CLI can invoke it:

sudo snap alias microk8s.kubectl kubectl

Use a dedicated kubeconfig for Helm, kubectl, and the Polyaxon CLI. The following creates a private temporary directory and leaves your existing ~/.kube/config intact:

MICROK8S_CONFIG_DIR=$(mktemp -d)
microk8s config > "$MICROK8S_CONFIG_DIR/config"
chmod 600 "$MICROK8S_CONFIG_DIR/config"
export KUBECONFIG="$MICROK8S_CONFIG_DIR/config"
kubectl config current-context
kubectl get nodes

The exported configuration grants cluster access; retain it securely if you need it in another session. See the MicroK8s command reference and our Kubernetes context guide.

Polyaxon configuration

The remaining steps assume the selected MicroK8s cluster, Helm 3, and the Polyaxon CLI are available in this shell. Install the polyaxon Python package in your preferred isolated environment. You can use the Polyaxon CLI to validate, deploy, upgrade, and tear down the installation, or manage the same release directly with Helm.

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

Create a config file config.yaml, and set up all information you want to override in the default config.

RBAC

Keep RBAC enabled in the cluster and chart. Put the following in config.yaml:

rbac:
  enabled: true

For an existing cluster that intentionally runs without RBAC, use rbac.enabled: false so the chart matches that cluster. This walkthrough enables RBAC in both MicroK8s and Polyaxon.

Choose the service and artifact storage

Use an internal gateway and local port forwarding for the first installation. Add these values to config.yaml:

namespace: polyaxon
gateway:
  service:
    type: ClusterIP
ingress:
  enabled: false
artifactsStore:
  name: local-artifacts
  kind: volume_claim
  schema:
    mountPath: /artifacts
    volumeClaim: polyaxon-artifacts

The artifact connection references a PVC created below. For shared access, configure the gateway's service and network controls using the platform configuration reference.

Use a NodePort service

You can also access Polyaxon directly through the MicroK8s node's IP and a NodePort. To use this option, change the gateway service in config.yaml to:

gateway:
  service:
    type: NodePort

Keep ingress.enabled: false for this setup. Choose a node address reachable from your machine and allow the gateway's NodePort through the relevant firewall. The connection steps below cover both port forwarding and NodePort access.

Create a namespace for Polyaxon

Use a dedicated namespace for the installation. This guide uses polyaxon consistently:

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.

Save this claim as artifacts-pvc.yaml, adjusting capacity and the StorageClass to the installed provisioner:

apiVersion: v1
kind: PersistentVolumeClaim
metadata:
  name: polyaxon-artifacts
  namespace: polyaxon
spec:
  accessModes:
    - ReadWriteOnce
  storageClassName: microk8s-hostpath
  resources:
    requests:
      storage: 20Gi

kubectl apply -f artifacts-pvc.yaml

This example is for one MicroK8s node. A claim using delayed binding can remain Pending until a consuming Pod is scheduled. Artifact storage is separate from database persistence; configure both according to the selected Polyaxon edition and required recovery behavior.

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

Review the selected chart's release notes and values. Replace the placeholder with the version you intend to install:

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

Add these top-level keys to config.yaml, replacing REPLACE_WITH_CHART_VERSION with the same version selected above:

deploymentChart: platform
deploymentVersion: "REPLACE_WITH_CHART_VERSION"
releaseName: polyaxon

Together with namespace: polyaxon, these values tell the Polyaxon CLI which chart version and release to manage. Keep the version in config.yaml and POLYAXON_CHART_VERSION aligned when switching between the CLI and Helm. See the admin CLI reference.

Validate

Validate the deployment configuration and required local tools with the Polyaxon CLI:

polyaxon admin deploy -f config.yaml --check

For a deployment preview, use its dry-run mode:

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

You can also render the selected chart directly with Helm and inspect the resulting resources. These checks help catch configuration and rendering problems; they do not establish cluster readiness or the behavior of a running workload:

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

Deploy

Install Polyaxon with your saved configuration using the CLI:

polyaxon admin deploy -f config.yaml

Or install the same release directly with Helm. Choose one deployment command:

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 name already exists, inspect helm status polyaxon --namespace polyaxon and its history before deciding whether to upgrade. Do not uninstall an existing deployment merely to clear the name.

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.

Connect the CLI and dashboard

Use port forwarding

In the same shell with the dedicated kubeconfig selected, run:

polyaxon port-forward

Keep the process running and open the localhost URL it prints. The command configures the CLI for that endpoint. Follow the release's Helm notes if you changed the release or namespace.

Use the NodePort address

If you selected NodePort, inspect the gateway service and node addresses:

kubectl get services --namespace polyaxon
kubectl get nodes -o wide

For the default release and namespace, the gateway is named polyaxon-polyaxon-gateway. Set POLYAXON_IP to a node IP reachable from your machine, then read the service's allocated port and configure the CLI:

export POLYAXON_IP=REPLACE_WITH_REACHABLE_NODE_IP
export POLYAXON_PORT=$(kubectl get service polyaxon-polyaxon-gateway \
  --namespace polyaxon -o jsonpath='{.spec.ports[0].nodePort}')
polyaxon config set --host="http://${POLYAXON_IP}:${POLYAXON_PORT}"

Open that same URL in your browser to access the dashboard. If you changed the release name, use the gateway service reported by kubectl get services. For a shared deployment, configure TLS and access controls according to the platform setup guides.

Upgrade Polyaxon

Review the target release's migration and backup requirements, then update deploymentVersion in config.yaml and POLYAXON_CHART_VERSION to that version. Keep the release name and namespace unchanged. Preview and apply the upgrade with the Polyaxon CLI:

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

Or apply the reviewed version to the existing release 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. Review the target chart's release notes, migration requirements, and backups.

2. Edit config.yaml, keeping deploymentVersion at the installed version when only changing configuration. Check it with polyaxon admin upgrade -f config.yaml --check and preview it with polyaxon admin upgrade -f config.yaml --dry-run or helm template.

3. Apply the values to the same release and namespace with the CLI:

   polyaxon admin upgrade -f config.yaml

   Or use Helm with POLYAXON_CHART_VERSION set to the same chart version:

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

   The first argument is the release name selected during installation.

   Find releases with helm list --namespace polyaxon.

4. Inspect readiness, bound volumes, gateway access, and the ability to submit a small operation and retrieve its artifacts.

Issues

DNS issues

Start with the DNS add-on, its Pods, and the workload's events:

microk8s status
microk8s kubectl --namespace kube-system get pods,services
microk8s inspect

Use the MicroK8s troubleshooting guide to distinguish DNS, firewall forwarding, proxy, and CNI issues. If Pods cannot reach the internet or each other while the host can, microk8s inspect can identify a blocked forwarding policy. On a dedicated development host where allowing forwarded traffic matches your firewall policy, the documented remedy is:

sudo iptables -P FORWARD ACCEPT

This changes the host's forwarding policy, so apply it only after identifying that cause. Hosts managed with UFW or a different firewall need the corresponding rules from the troubleshooting guide. Inspect diagnostic bundles for sensitive configuration before sharing them.

Build failure

MicroK8s uses its own container runtime. An image built by a host Docker daemon is not automatically available to cluster nodes. Publish it to a reachable registry or use the documented MicroK8s image-import workflow, then verify its reference and pull credentials. Follow our image pull troubleshooting guide before changing builders.

If an older Docker-based build process fails because it expects a host Docker daemon, use a container-build component configured for your cluster. Polyaxon's Kaniko integration documents a daemonless build approach, and the Buildah integration provides another option. Configure the builder's registry connection and choose an image/version maintained for your environment.

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 and preserve needed outputs before uninstalling. The chart includes a pre-delete hook that cleans up Polyaxon operations. The CLI asks whether to execute these hooks during teardown; choose yes for that cleanup. If you skip the hooks, you must clean up remaining operations yourself. Release removal does not guarantee that external storage has been cleaned up.

Delete Helm release

Uninstall the release after reviewing its resources, hooks, and retained data. Use the same configuration file so the Polyaxon CLI targets the correct release and namespace:

polyaxon admin teardown -f config.yaml

Or remove that release directly with Helm:

helm uninstall polyaxon --namespace polyaxon

If a failed installation leaves a hook that cannot complete, inspect its Job and logs first. After accounting for any workload cleanup the hook would have performed, you can remove the release without running hooks:

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

CRDs, retained claims, and externally managed resources may remain after uninstalling.

Delete the namespace

Delete the namespace only when its remaining resources are no longer needed. Removing PVCs can delete backing storage according to each PV's reclaim policy; node-local files and external stores require separate lifecycle decisions.

kubectl delete namespace polyaxon

Use microk8s stop when you only want to pause the local cluster. Confirm that valuable data has a recoverable copy before removing MicroK8s or its host-path storage.