CLI Quick Start

🚧

Quick navigation

Time to read: 9 minutes, 19 seconds

Jump to: 1. Before you begin | 2. Download and configure the Orka CLI | 3. Create a user | 4. Some CLI basics | 5. Create and deploy your first VM instance | 6. Experience your VM instance | 7. Update the base image | 8. Time to say goodbye

🚧

The ultimate quick start

If you want to skip the detailed explanations, just run through these steps on your own:

1. orka config
2. orka user create (enable immediate login)
3. orka node list
4. orka vm list (you should see 0 results)
5. orka image list (you should see at least 90GBVenturaSSH.orkasi)
6. orka vm create (use 90GBVenturaSSH.orkasi and set CPU and vCPU to 6)
7. orka vm list and orka vm status
8. Run Apple Screen Sharing to connect to the VM instance. Use vnc://<VM-IP>:<Screenshare-port> with the IP and port from Step 7. Use the admin/admin credentials.
9. On the VM, change the login credentials, apply the latest OS updates, and install (or upgrade) the Orka VM Tools.
10. If you are the sole user of the environment, run orka image commit (use the VM instance ID as listed by orka vm list). Otherwise, run orka image save (use the VM instance ID as listed by orka vm list).
11. orka vm deploy -v <NAME> -y (use the name of your VM config)
12. Run Apple Screen Sharing and connect to the newly deployed VM. Use the connection information printed by orka vm deploy.
13. orka vm delete -v <NAME> -y
14. orka vm list

The Orka CLI is the easiest way to get started with Orka. It provides guided, interactive completion of commands and built-in help.

The Orka CLI will be most useful to:

• beginner users
• users with predominantly manual workflows
• advanced users who need to tap into the Kubernetes layer and work with kubectl

1. Before you begin

1. Get your IP Plan. You can download it from the MacStadium portal.
2. Connect to your Orka cluster via VPN.
   1. Download and install a VPN client. Note that if you're using a custom Orka domain, you might need to make some additional configuration changes.
   2. Use the server address and credentials from the VPN section at the top of your IP Plan.

2. Download and configure the Orka CLI

1. Download and install the latest Orka CLI that matches your environment version.
   • On macOS, run the pkg executable.
   • On Linux, unpack the archive and move the executable to /usr/local/bin.
   • On Windows, add the directory of the executable to your PATH.

👍

TIP: Using Homebrew?

Try brew install orka.

2. Launch your preferred command-line tool (e.g., the Terminal on macOS) and run the following command:

orka config

This operation is a one-time effort. With it, you set the Orka service endpoint and your license key. The license key is required for administrative actions.

📘

What's your Orka endpoint?

You can get the IP for your Orka endpoint from your IP Plan:

• For clusters deployed before Orka 2.1, it's the .100 address for your Private-1 network (usually, 10.221.188.100).
• For clusters deployed with Orka 2.1 or later, it's the .20 address for your Private-1 network (usually 10.221.188.20).
  You need to use http with the IP.

📘

Known limitation

Due to Node.js limitations, the Orka CLI cannot work with the built-in Orka domains and can work only with a limited number of external custom domains.

The Orka CLI works only with valid TLS certificates issued by the certificate authorities recognized by Node.js.

3. Create a user

Orka requires you to create a dedicated Orka user for your cluster. This operation also creates a dedicated namespace in the cluster. You are the owner of this namespace. When you create a VM config and/or deploy a VM instance from it, they become associated with your namespace. Other users will not be able to manage your VM configs and your VMs and vice versa. Administrators will be able to list, delete, and purge your VM configs and instances.

• In your preferred command-line tool, run the following command:

orka user create

When you log in, the Orka CLI caches your token locally and uses it to identify you uniquely with the Orka service endpoint.

👍

Are you logged out?

If you already have a user or you get logged out from your account, you can log in with orka login.

4. Some CLI basics

The Orka CLI is a powerful tool in the hands of both inexperienced and advanced users. You can work with it one of two ways:

• Interactive mode: This is the default working mode of the Orka CLI. The CLI prompts you to fill in the missing configuration parameters for the commands that require it. It also requires explicit confirmation for some operations.
• Direct mode: For advanced users, non-interactive consoles, and scripting purposes, the Orka CLI lets you pass the configuration parameters along with the command.

If you're working mostly in interactive mode, keep in mind:

• Just start typing. Most Orka commands require strictly Latin alphanumeric input with dashes, underscores, and periods sometimes allowed (depending on the command).
• To confirm the current input, hit Enter or arrow-up or arrow-down from the keyboard.
• To correct the current input, use Delete or Backspace.
• To return to an already filled-in line and correct it, use arrow-up or arrow-down from the keyboard.
• To navigate between prompt lines, use arrow-up or arrow-down.
• To submit a command and execute it, hit Enter at the last prompt.
• To discard the entire command without executing it, just press Ctrl+C.

If you're working mostly in direct mode, get to know the -y flag or the --json flag. It lets you bypass any confirmation prompts.

The default Orka CLI output is table-formatted. To switch to JSON format (where supported), pass the --json flag to your Orka CLI commands. To switch to raw format (where supported), pass the --raw flag to your Orka CLI commands. See also: CLI Commands: Change the output.

To get help, run:

orka help

5. Create and deploy your first VM instance

1. Open a new command-line prompt and run:

orka nodes

This command shows the current status of all your nodes. Re-run this command, as you deploy VM instances later on, to keep track of the available resources on your nodes.

📘

Glossary: Node

A genuine Apple physical host that provides computational resources (RAM and CPU) for your workloads.

A host OS runs on top and you have no direct access (via VNC, SSH, or Screen Sharing) to it.

2. Run:

orka vms

If this is the first time you're using Orka, you will get Deployed: 0, Not Deployed: 0.

This command lists the VM configs and VM instances associated with your user.

👍

Do you want to see all VMs on the environment?

Run the administrative orka vm list -f all.

Note that this operation requires a valid Orka license key to be set with orka config.

3. List the available base images that you can use to create a VM config.

orka images

You will likely see a 90GBVenturaSSH.orkasi item. It is a fully installed and configured Apple Silicon-based macOS Ventura image with a 90GB disk size. It also has an admin user configured and SSH and Apple Screen Sharing access enabled.

📘

Glossary: Image

A disk image that represents VM storage. Base images are bootable disk images that provide the OS, file system, and storage for your VM configs and VMs. Empty images provide added storage or serve as the base image during manual OS installs from ISO.

4. Create your first VM config and deploy its first instance with a single command:

orka vm create

The Orka CLI prompts you to complete the configuration manually:

• VM Name: Set any user-friendly name that will help you recognize the VM.
• Base image: Set to 90GBVenturaSSH.orkasi.
• CPU: Set to 6. This is the number of CPUs for the VM.
• vCPU: Set to 6. Unless CPU is 3, it must be half of or the exact amount of CPUs. This setting indicates if hyperthreading is enabled. If vCPU equals CPU, hyperthreading is on.
• Memory (G): Skip. Manually sets the memory allotted to the VM. Must not exceed the maximum available memory on the node. If not specified, Orka automatically allots the memory.
• Node Name: Skip. Manually selects the node that will host the VM. If not specified, Orka chooses automatically based on the available resources and any node dedication or node affinity settings.
• Attach ISO: Skip. Not applicable to Apple Silicon images. Use this configuration parameter to deploy a clean Intel-based VM and install its OS from ISO.
• Attach Disk: Skip. Not applicable to Apple Silicon images. Use this configuration parameter to attach additional storage to an Intel-based VM.
• GPU: Skip. Not applicable to Apple Silicon images. By default, no. This setting enables or disables GPU passthrough (when enabled on the cluster) for Intel-based VMs.
• Tag: Skip. Sets a tag for the VM and indicates that the VM should (or must) be deployed only on nodes with the specified tag (node affinity).
• Tag Required: Skip. When a tag is also specified, indicates if the VM should (N) or must (y) be deployed on nodes with the specified tag.
  By default, N. If left blank, defaults to N.
• VNC Console: Skip. By default, yes. This setting controls the VNC connectivity of the VM.

📘

VM name limitations

The name you specify under VM Name must meet the following requirements:

• Doesn't exceed 38 characters.
• Contains only lowercase Latin alphanumeric characters (0-9, a-z) and dashes (-).
• Begins and ends with an alphanumeric character.

This command creates a VM config and deploys an instance from it.

📘

Glossary: VM config

A template for an Orka virtual machine. You can deploy multiple VM instances (VMs) from a single VM config.
To list all VM configs associated with your user, run orka vm configs.

📘

Glossary: VM instance (VM)

A deployed instance of a VM config. VMs take up resources from your nodes and require a certain amount of CPU and memory to run.
To deploy more instances of the same config, run orka vm deploy.

5. Check your nodes and your VMs.
   • Re-run orka node list. Did the number of available resources change?
   • List your VMs:

orka vm list

You should now see Deployed: 1 and Not Deployed: 0. Although it might seem so, a VM config doesn't disappear when you deploy an instance. It's just that the Orka CLI doesn't distinguish between a VM config and a VM instance. It works in terms of Deployed and Not Deployed.

orka vm list is a powerful command. It shows a lot of system information for the VM, along with the unique identifier of the instance (ID), its IP, and several connection ports. Note that even though Screenshare and SSH are always listed and configured for every VM, you won't be able to use them unless the respective connection type is enabled in the macOS as well. This behavior is a security limitation of the OS.

👍

In a pool of many VMs, are you looking for that special one?

When you have a lot of VMs, the output of orka vm list might become too crowded to use efficiently. Run orka vm status instead and get the system information for a single VM.

Note that orka vm status is also the only way to get detailed information for scaled VMs.

6. Experience your VM instance

1. Look at the last output of orka vm list again. Get that IP and Screenshare port. (10.221.188.16 and 5901, respectively, in the example above.)
2. Launch Apple Screen Sharing on your local machine (Cmd+K in Finder). Type vnc://<VM-IP>:<Screenshare-port> (vnc://10.221.188.16:5901 in the example above).

📘

Are you not working on macOS?

This step works only on macOS. If you're working on a Linux or Windows machine instead, launch your preferred VNC client and connect to <VM-IP>:<VNC-port> (10.221.188.16:5999 in the example above).

For more information, see VNC, SSH, and Screen Sharing for Orka VMs.

One more thing to remember is that Screen Sharing needs to be already enabled on the macOS. Most of the time, this is not the case (especially on clean OS installs or after an ISO install), and you will need to enable the setting yourself.

The good news is that 90GBVenturaSSH.orkasi is already preconfigured for you, and you can enjoy out-of-the-box Screen Sharing and SSH connectivity.

📘

Are you not using the 90GBVenturaSSH.orkasi image?

If you're using another image as your starting point or if you are installing your OS from ISO, you will likely not have SSH or Screen Sharing enabled by default (even though the respective ports will be mapped by default). In this case, you need to connect to the VM via VNC. You can then enable SSH and Screen Sharing connectivity in the OS.

3. When prompted by Apple Screen Sharing, provide the credentials for the VM (admin/admin). You will be prompted for the password one more time - when Apple connects to the VM.

4. On the VM, launch System Preferences > Users & Groups. Select the Admin user and click Change password. Set the Admin user password to whatever works for you.

5. (Optional) Launch the Terminal and run the following command.

brew install orka-vm-tools

OR

brew upgrade orka-vm-tools

This action ensures that your VM is running the latest version of the Orka VM Tools. This collection of services lets Orka manage the guest operating system on Apple silicon-based VMs more efficiently and enables key features, such as shared VM storage.

If your cluster and CLI are not running the latest Orka version, download and install an Orka VM Tools that matches the versions of your cluster and Orka CLI.

6. Apply the latest OS updates and restart the VM.

7. Update the base image

Making changes to the configuration or the file system of a running VM does not affect its base image. As soon as you delete the VM, your changes will be lost, and you will need to recreate them manually on other VMs.

To create changes that stick and appear on future deployments, you can commit your changes to the base image, or you can save the changes as a new image.

📘

Glossary: Commit changes

Commit modifies the original base image of the respective VM instance. With this operation, you apply the current state of a VM instance over the base image of its VM config. This way, newly deployed instances will launch in the same state as your current VM.

For commit to work, the base image must not be in use by any other VM instances (regardless if they were spun from the same VM config or another VM config).

This operation restarts the VM.

Run orka image commit --help for more information.

📘

Glossary: Save changes

Save creates a new base image from the current state of the respective VM instance. To use it, you need to create a new VM config that references the new base image.

This operation restarts the VM.

Run orka image save --help for more information.

1. If you are sure that you are the only Orka user who's using 90GBVenturaSSH.orkasi, you can commit the changes. Otherwise, save a new image.

This operation will persist the new admin password and the latest OS updates. Note that you might need to share the new admin password with future users who might follow this guide.

Return to the command line on your local machine and run:

orka image commit

When prompted, provide the ID of the VM instance. (You can get it from the orka vm list output you ran earlier.

2. See how the changes are preserved for yourself. Deploy a new VM instance from your VM config:

orka vm deploy -v <NAME> -y

This syntax gives you a taste of running Orka commands in direct mode and bypassing the manual line-by-line input. Note the output of the command. The connection info for your VM shows as soon as the deployment completes.

3. Launch Apple Screen Sharing and connect to the newly deployed VM instance. Use the updated admin credentials to log in.

8. Time to say goodbye

This section is optional.

When your VM configs and instances have served their purpose, you can remove them. Orka provides two ways to do that: delete and purge.

📘

Glossary: Delete VM

This operation removes the specified instance(s). You can delete a VM by:

• name (deletes all VM instances with that name)
• name and node (deletes all VM instances with that name from that node)
• ID (deletes the VM instance with that ID)

Delete always preserves the original VM config, and you can deploy new VM instances from it.

Run orka vm delete --help for more information.

📘

Glossary: Purge VM

This operation removes all VM instances and the VM config of that name. You can perform a purge even if there are no VM instances deployed.

Run orka vm purge --help for more information.

1. Remove all VM instances you created until now:

orka vm delete -v <NAME> -y

2. List your VMs again.

orka vm list

You should see Deployed: 0 and Not Deployed: 1.

What's next

You're ready to explore the Orka CLI on your own. You might find the following resources helpful:

• Run orka help to get a list of all the available commands.
• Explore Orka Docs for more advanced tasks and tutorials.
• Seek help from the Orka community in the MacStadium Community Slack.
• Get support in the MacStadium portal.
• Is a feature missing? Please share your feedback with us.
• If you're looking to tap into Kubernetes, see this page.