Orka Glossary
Commonly used Orka terms and their definitions: nodes, VM configurations, images, etc.
Orka 2.4.x content
This page has not been updated to reflect the changes introduced in Orka 3.0. Some of the information might be outdated or incorrect. Use 2.4.x to 3.0.0: API Mapping and 2.4.x to 3.0.0: CLI Mapping to figure out the correct endpoints and commands.
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
Use
Ctrl+ForCmd+Fto quickly navigate to the term that you're looking for.
MacStadium
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
IP Plan
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.
Check the Subnet ID for Private-1.
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 Private-1 is 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
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
environment
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).
instance
This term is deprecated. See environment.
API URL
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 yourPrivate-1network (usually,10.221.188.100).- For clusters deployed with Orka 2.1 or later, it's the
.20address for yourPrivate-1network (usually10.221.188.20).
You need to usehttpwith 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
http://<orka-IP>,https://<orka-domain>, andhttps://<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: http://<API-URL>/<endpoint>.
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.
account
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.
label
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.
user
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.
kube-account
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 http://<API-URL>/token endpoint.
image
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.
base 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: .img and .qcow2.
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
snapshot image
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.
ISO
Not to be confused with image.
An .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.
node
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.
sandbox
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.
VM configuration
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.
VM
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 purge operation.
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 Pending VM.
You can remove Orphaned VMs with the purge operation.
resource
See: computational resource and Orka resource
computational 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).
Orka resources
The combined occupied and free computational resources in your Orka environment.
Kubernetes
Kubernetes (K8s) is an open-source system for automating deployment, scaling, and management of containerized applications. (Source)
Kubernetes sits at the core of Orka.
Kubernetes node
Related: Orka node
A Kubernetes node is a physical machine that runs your containers.
For more information, see Kubernetes Documentation: Nodes.
Kubernetes Master
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
namespace
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.
container
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.
pod
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.
deployment
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:
service
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 5 months ago