Orka Glossary

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

Use Ctrl+F or Cmd+F to 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

Back to top

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. 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.100.

For information about the remaining fields and how to access the document, see IP Plan.

Back to top

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

Back to top

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).

Back to top

instance

This term is deprecated. See environment.

Back to top

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?

You can get the IP for your Orka endpoint from your IP Plan. It's the .100 address for your Private-1 network. Usually, 10.221.188.100 or 10.10.10.100. You need to use http with the IP.

To get the custom domain for your Orka cluster, if enabled:

  1. Log into your MacStadium account.
  2. Go to Subscriptions (from the top right corner) and select your Orka cluster.
  3. In the Subscription & Plan details, find your custom domain at the bottom. If you don't see a custom domain field, it's not enabled for your environment yet.
    You need to use https with your custom domain.

Note that you can use both http://<orka-IP> and https://<orka-custom-domain> 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 OpenConnect to access your Orka cluster via VPN, you need to add a DNS server to your network configuration.

If you're using Cisco AnyConnect on macOS or Linux, you're already set and you don't need to make any changes. If you're using Cisco AnyConnect on Windows, you need to add a DNS server.

You can run Orka CLI commands and API calls against the API URL only if you are connected via VPN to your Orka environment.

Back to top

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.

Back to top

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.

Back to top

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.

Back to top

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.

Back to top

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.

Back to top

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, .qcow2, and .vmdk. Orka converts .vmdk files to .img automatically.

Back to top

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.

Back to top

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.

Back to top

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.

Back to top

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.

Back to top

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.

Back to top

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.

Back to top

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.

Back to top

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.

Back to top

resource

See: computational resource and Orka resource

Back to top

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).

Back to top

Orka resources

The combined occupied and free computational resources in your Orka environment.

Back to top

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.

Back to top

Kubernetes node

Related: Orka node

A Kubernetes node is a physical machine that runs your containers.

For more information, see Kubernetes Documentation: Nodes.

Back to top

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:

Back to top

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.

Back to top

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.

Back to top

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.

Back to top

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:

Back to top

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.

Back to top

Updated 2 months ago


Orka Glossary


Commonly used Orka terms and their definitions: nodes, VM configurations, images, etc.

Suggested Edits are limited on API Reference Pages

You can only suggest edits to Markdown body content, but not to the API spec.


© 2019-2020 Copyright MacStadium, Inc. – Documentation built with readme.io. Orka is a registered trademark of MacStadium, Inc.