K8s Native: Overview

Everything you need to tap into the underlying Kubernetes layer of Orka.


Quick navigation

Jump to: Workflow | Limitations

Starting with Orka 3.0, all Orka resources are Kubernetes-native. They are custom resources with detailed custom resource definitions.

This lets you work with Orka resources straight from kubectl, if that's your preferred tool. You can also run custom pods in namespaces, created with the enable custom pods setting.



The recommended way to work with Orka resources is via the Orka3 CLI, Orka3 API, or the Orka Web UI.

You can still use kubectl instead. However, exercise caution and consider managing only VMs and VM configs via YAML. Working with images, ISOs, or nodes directly requires both advanced Orka3 CRD and Kubernetes knowledge, and might result in unexpected issues.


  1. Install kubectl locally or upgrade your existing installation. For example:
brew install kubectl


brew upgrade kubectl
  1. Authenticate with your Orka cluster:
orka3 login


orka3 user set-token
  1. Manage Orka resources with kubectl:
kubectl apply -f <FILE_NAME> --namespace=<NAMESPACE>


kubectl get <RESOURCE> --namespace=<NAMESPACE>


kubectl edit <RESOURCE> --namespace=<NAMESPACE>


kubectl delete <RESOURCE> --namespace=<NAMESPACE>
  1. Create and configure a namespace for running custom pods.
    First, you need to create a namespace with enabled custom pods. Next, you must grant access to the namespace to the users who need to deploy to it. And finally, you need to assign computational resources to the namespace.
    Note that you will not be able to deploy Orka resources to this namespace.
orka3 create namespace <NAMESPACE_NAME> --enable-custom-pods
orka3 rb add-subject --user <EMAIL_ADDRESS> --namespace <NAMESPACE_NAME>
orka3 node namespace <NODE_NAME> <NAMESPACE_NAME>
  1. Manage your custom pods with kubectl.
kubectl apply -f <FILE_NAME> --namespace=<NAMESPACE_NAME>


kubectl get <CUSTOM_POD> --namespace=<NAMESPACE_NAME>


kubectl edit <CUSTOM_POD> --namespace=<NAMESPACE_NAME>


kubectl delete <CUSTOM_POD> --namespace=<NAMESPACE_NAME>

For any custom pods you need to run, add the following toleration to the pod:

{"key": "orka.macstadium.com/namespace-reserved", "value": "<NAMESPACE_NAME>"}


  • Your access to Orka resources depends on the role of the user you authenticated with. For more information, see here.
  • You can run custom pods only in a namespace created with the enable custom pods setting.
  • You cannot run custom pods in the orka-default namespace.
  • For any custom pods you want to run, you must add the following toleration:
{"key": "orka.macstadium.com/namespace-reserved", "value": "<NAMESPACE_NAME>"}

See also

Β© 2019-2023 Copyright MacStadium, Inc. – Documentation built with readme.com. Orka is a registered trademark of MacStadium, Inc.