Commonly used Orka terms and their definitions: nodes, VM configurations, images, etc.
This page provides a list of common MacStadium, Orka, and Kubernetes terms used throughout the Orka documentation, CLI, and RESTful API.
TIP: Quick navigation across this page
Cmd+Fto quickly navigate to the term that you're looking for.
MacStadium is the leading supplier of enterprise-class Apple Mac infrastructure providing scalable, reliable, and secure private clouds and dedicated servers for workloads that require macOS.
MacStadium is the vendor of your cloud environment.
In this documentation, MacStadium may refer to:
- the legal entity
- the teams at the company
- the cloud solution
The IP Plan is a document, prepared and provided by MacStadium, that contains the access, configuration, and information for your Orka environment.
Pay special attention to Appendix A: IP Allocation and the information for your
Private-1 network. This is the private network of your Orka environment and it's where the Orka service endpoint (the API URL) lives.
Subnet ID for
For clusters initially deployed with Orka 2.1+, if you replace the last octet with
20, you'll get your Orka service endpoint.
For clusters initially deployed before Orka 2.1, if you replace the last octet with
100, you'll get your Orka service endpoint.
For example, if the
Subnet ID for
10.221.188.0, your service endpoint is
10.221.188.20 (for clusters initially deployed with Orka 2.1+) or
10.221.188.100 (for clusters initially deployed before Orka 2.1).
For information about the remaining fields and how to access the document, see IP Plan.
Orka is MacStadium's cloud orchestration and containerization service. It simplifies and automates the management of macOS containers. Docker and Kubernetes sit at its core.
In this documentation, Orka may refer to:
- the service
- the technology
- the environment
- the command in the CLI
Also: instance, Orka instance, Orka environment
An Orka environment is a MacStadium cloud environment with an enabled Orka service. To be able to orchestrate your cloud with the Orka service, you need to connect via VPN to the Orka environment. After you are connected, you can run Orka CLI commands or execute Orka API calls to the service.
Every Orka environment consists of an Image Manager NFS storage space that stores and pulls Docker Images, an Orka Services namespace (currently set to default), and one shared user namespace (the sandbox namespace).
The Image Manager and the Orka Services namespace are managed entirely by MacStadium and serve the needs of Orka. The Image Manager stores the base images. The Orka Services namespace provides the control interfaces for the environment (the CLI and the API).
This term is deprecated. See environment.
Also: Orka endpoint, Orka service endpoint
The Orka API service runs at a specific URL. Orka CLI commands and Orka API calls are executed against the Orka API URL.
What's your Orka endpoint?
YYou can get the IP for your Orka endpoint from your IP Plan:
- For clusters deployed before Orka 2.1, it's the
.100address for your
- For clusters deployed with Orka 2.1 or later, it's the
.20address for your
You need to use
httpwith the IP.
To get the Orka domain for your Orka cluster, contact MacStadium. To use an external custom domain, see here.
Note that you can use
https://<custom-domain>interchangeably in your workflows.
The first time you run the Orka CLI, you need to configure the API URL using the
orka config -a command.
If you want to use the Orka RESTful API instead, you can use the following endpoint format:
Using a custom domain?
If you're using an Orka domain, see here.
If you're using an external custom domain, see here.
You can run Orka CLI commands and API calls against the API URL only if you are connected via VPN to your Orka environment.
This term is deprecated in the context of Orka account. See user.
Not to be confused with kube-account.
When used as MacStadium account, this term refers to your account in the MacStadium portal.
Labels are key/value pairs that are attached to objects, such as pods. Labels are intended to be used to specify identifying attributes of objects that are meaningful and relevant to users, but do not directly imply semantics to the core system. Labels can be used to organize and to select subsets of objects. Labels can be attached to objects at creation time and subsequently added and modified at any time. Each object can have a set of key/value labels defined. (Source)
For more information about labels in Kubernetes, see here.
Also: account, Orka user
To work with Orka, you need to have a user with an assigned license. You will use this user and the respective credentials to authenticate against the Orka service. After being authenticated against the service, you can run Orka CLI commands and Orka API calls.
Orka users work in a shared namespace. However, they can only see their own VM configurations and VMs.
One Orka environment might have multiple users working inside it.
You can create a
kube-account with the
orka kube create command. The command generates a
.kubeconfig-orka file per user. You can regenerate the file with a POST API call to the
http://<API-URL>/resources/kube-account/regenerate endpoint. This request must pass a valid email address and token.
You can generate a token with a POST API call to the
Also: image file
Not to be confused with ISO.
A disk image that represents a VM's storage and its contents, including the OS and any installed software.
Based on context, might refer to base image or snapshot image.
An existing disk image file stored in Orka and used exclusively for the creation of VM configurations. The actual storage for newly created VM configurations is based on a base image specified by the user.
Base images remain unchanged over time and can be used again and again for the creation of VMs.
Base images are stored as
.img files in the Orka storage. Base images live in the Image Manager namespace and are shared across the same Orka environment. All users can access them and use them to create VM configurations.
You can upload an image file to Orka to use it as a base image. Orka supports the following image files for upload:
To use a
.vmdk image you need to uninstall VMware Tools application, found in /Library/Application Support/VMware Tools and convert it to
.img using the command:
qemu-img convert -f vmdk -O raw image.vmdk image.img
Represents a VM's storage and its contents. It's created as a separate image file during the creation of the VM. It's always based on an existing base image but changes over time.
It's attached to the VM it was created for.
You can also generate an empty snapshot image (with the
orka image generate command) and attach it to a VM to extend its storage.
Not to be confused with image.
.iso disk image used exclusively for the installation of macOS on a virtual machine. You must attach the ISO to the VM during deployment. After the installation is complete and the VM has booted successfully, you need to restart the VM to detach the ISO.
For more information, see ISOs.
Also: host, Orka node
Related: Kubernetes node
A physical or logical host that provides computational resources for your VMs. Usually, an Orka node is a genuine Apple physical host with a host OS on top. You have no direct access (via VNC, SSH, or Screen Sharing) to your nodes.
When deploying a VM configuration, you need to select a node with sufficient free computational resources to meet the configuration requirements, or allow Orka to use its default system to select a free node.
When you let Orka allocate a node for a single VM, the service uses a random algorithm to select a node and then checks for available resources. When Orka needs to allocate resources for multiple VMs, the default Kubernetes scheduler is used.
You can sandbox an Orka node to limit its management with the Orka CLI. When a node is sandboxed, you can manage it as a Kubernetes node with configured Tiller and Role-Based Access Control. You can use
kubectl and Helm as well.
TIP: If you need to run services on multiple nodes, sandbox one node and use a DaemonSet.
Also: VM template
A template configuration (a container template) consisting of a base image, a snapshot image, and the number of CPU cores to be used. To become a VM that you can run in the cloud, a VM configuration needs to be deployed to a node.
You can deploy multiple VMs from a single VM configuration. Once created, you can no longer modify a VM configuration.
Deleting a VM does not delete the VM configuration it was deployed from.
Also: virtual machine
A virtual machine deployed on a node from an existing VM configuration or cloned from an existing virtual machine. In the case of macOS VMs, this is a full macOS VM inside of a Docker container.
Pending (VM status)
Related: Orphaned (VM status), VM
This status indicates that the VM is queued for deployment. If not deleted by a user or a script, it will be deployed as soon as sufficient resources are available.
You can remove
Pending VMs with the
Orphaned (VM status)
Related: Pending (VM status), VM
This status indicates that the VM no longer has an owner in the database.
Orphaned VMs usually occur as the result of actions being performed on a
You can remove
Orphaned VMs with the
See: computational resource and Orka resource
All the computational resources of your Orka environment: the CPU cores and memory.
There are three types of computational resources: reserved, occupied, and free.
Reserved computational resources are resources reserved by Orka for operational purposes (for example, the Kubernetes masters). These resources will never be used for the deployment of VM configurations or the cloning and migration of VMs.
Occupied resources are resources currently in use by a VM.
Free resources are any computational resources that are not reserved or occupied. To be able to deploy a VM configuration, you need to have enough free resources on the same node to match the configuration (i.e., enough free storage and CPU cores).
The combined occupied and free computational resources in your Orka environment.
Kubernetes (K8s) is an open-source system for automating deployment, scaling, and management of containerized applications. (Source)
Kubernetes sits at the core of Orka.
Related: Orka node
A Kubernetes node is a physical machine that runs your containers.
For more information, see Kubernetes Documentation: Nodes.
By default, your Orka environment comes with three Kubernetes masters. This ensures availability and redundancy. Based on your requirements, MacStadium can configure a larger number of masters.
The master is a collection of processes that maintains the state of your nodes, VM configurations, and VMs.
For more information about Kubernetes masters, see:
- Kubernetes Documentation: Kubernetes Control Plane
- Kubernetes Documentation: Master-Node communication
- Kubernetes Documentation: Master Components
Kubernetes namespaces are a way to divide the computational resources of an Orka environment between its users.
Every Orka user works in the same shared namespace but only has view permissions for their own VMs. In this shared namespace, users can manage VM configurations and VMs. Currently, VM configurations and VMs are not shared across user namespaces.
For more information about Kubernetes namespaces, see Kubernetes Documentation: Namespaces.
A container is a standard unit of software that packages up code and all its dependencies so the application runs quickly and reliably from one computing environment to another. (Source)
In Orka, VM configurations and VMs are Docker containers.
For more information about containers and Kubernetes, see Kubernetes Documentation: What is Kubernetes.
A group of one or more containers with shared storage and network and a specification for how to run the containers. (Source and more information)
In Orka, a pod consists of one container holding one macOS VM. To work with pods with multiple containers, you need to manage your deployments with
kubectl instead of Orka.
A type of Kubernetes configuration that takes care of the deployment of containers. This term also refers to the Deployment controller which monitors and maintains the state of your pods.
In Orka, deployment and deploy refer to the deployment of a single VM configuration on a single node. You have no control over the actual deployment configuration, you cannot interact with the controller, and you cannot deploy replica sets. To gain control over these, you manage your deployments with
kubectl instead of Orka.
For more information about the deployment configuration and the Deployment controller, see:
You can allow access to and manage the networking and connectivity for your Orka VMs through Kubernetes services.
Not to be confused with Orka service.
For more information about Kubernetes services, see Kubernetes Documentation: Service.
Updated 4 months ago