CLI User Guide

🚧

Quick navigation

Time to read: 9 minutes, 19 seconds

Jump to: 1. Before you begin | 2. Download and configure the Orka3 CLI | 3. Authenticate with your cluster | 4. Some CLI basics | 5. Create and deploy your first VM instance | 6. Experience your VM instance | 7. Preserve the image changes | 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. orka3 config set --api-url <ORKA_API_URL>
2. orka3 completion {bash|fish|powershell|zsh}
3. orka3 login
4. orka3 node list(This shows the list of worker nodes in the cluster)
5. orka3 vm list (This shows the running VMs in the cluster. This will change as VMs are deployed or destroyed.)
6. orka3 image list (This shows the images that are saved to the clusters NFS storage)
7. orka3 imagecache add ghcr.io/macstadium/orka-images/sequoia:latest --all (This will cache a pre-configured MacStadium macOS Sequoia image from the MacStadium GitHub Container Repository onto all nodes in the cluster, allowing for rapid subsequent deployments.)
8. orka3 vm deploy --image ghcr.io/macstadium/orka-images/sequoia:latest(This will deploy a vm using an already configured MacStadium provided macOS Sequoia image.)
9. orka3 vm list <VM_NAME> and orka3 vm list <VM_NAME> -o wide(This shows which vms are running in the cluster.)
10. 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.
11. On the VM, change the login credentials, apply the latest OS updates, and install (or upgrade) the Orka VM Tools for added security and functionality.
12. orka3 vm commit <VM_NAME> or orka3 vm save <VM_NAME>
13. orka3 vm deploy --image <IMAGE_NAME> -y (use the name of the newly saved image or the original image, if you committed the changes to it).
14. Run Apple Screen Sharing and connect to the newly deployed VM. Use the connection information printed by orka3 vm deploy. Verify that your changes are there.
15. orka3 vm delete -v <NAME>
16. orka3 vm list

The Orka3 CLI is the most immersive way to get started with Orka. It provides easy-to-use commands, command auto-completion, and comprehensive built-in help.

The Orka3 CLI will be helpful to:

• Beginner and advanced users.
• Users with manual workflows.
• Users with workflows that require automation.

1. Before you begin

1. Ensure you can access your cluster account in the MacStadium Customer Portal. See Cluster Access Management: Overview.
2. Get your VPN connection information from your IP Plan. You can download it from the MacStadium portal.
3. Connect to your Orka cluster via VPN.
   1. Download and install a VPN client. Note that you might need to make additional configuration changes if you're using a custom Orka domain.
   2. Use the server address and credentials from the VPN section at the top of your IP Plan.

2. Download and configure the Orka3 CLI

1. Download and install the latest Orka3 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 orka3.

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

orka3 config set --api-url <ORKA_API_URL>

This operation is a one-time effort. With it, you set the Orka service endpoint for your cluster.

📘

What's your Orka API URL?

You can get your Orka API URL 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), prefixed with http. For example: http://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). prefixed with http. For example: http://10.221.188.20.
• You can also use https://<orka-domain> and https://<custom-domain>(if configured). 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>, and https://<custom-domain> interchangeably in your workflows.

📘

Known limitation

The Orka3 CLI works only with trusted custom domains and valid TLS certificates issued by trusted certificate authorities.

3. Enable command autocompletion for the Orka3 CLi.

orka3 completion {bash|fish|powershell|zsh}

The Orka3 CLI prints detailed instructions for the selected shell type.

3. Authenticate with your cluster

Orka lets you log in with your MacStadium Customer Portal credentials. Your access privileges are based on the role configured by your account admin in the Customer Portal. By default, you will have access to the orka-default namespace. You can access additional namespaces if you have been added to additional role bindings.

orka3 login

Orka will launch a new browser tab (or window) and let you log in via the provided form. After you log in, you can return to the command line and run additionalorka3 commands. Your token is stored locally in the ~/.kube/config file. Note that your token has a validity duration of one hour. Afterward, you must obtain and pass a new token in your CLI or API calls.

4. Some CLI basics

The Orka3 CLI is a powerful tool in the hands of both inexperienced and advanced users.

The default Orka3 CLI output for list commands is table-formatted. You can switch to an expanded table format with the --output wide flag or to JSON with the --output json flag.

To get help, run:

orka3 help
orka3 <command> --help
orka3 <parent_command> <command> --help

5. Create and deploy your first VM instance

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

orka3 nodes list

This command shows basic information about the nodes in the orka-default namespace. 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).

📘

Glossary: Namespace

A way to isolate and dedicate resources to users and teams within the cluster.

The resources within a namespace are completely isolated from one another and cannot be shared between namespaces. By default, users and service accounts limited to a specific namespace cannot access the resources in other namespaces, unless added to the respective role bindings.

2. Run:

orka3 vm list

This command lists all VM instances in the orka-default namespace. If nothing prints, no one has created any VM instances yet.

👍

Do you want to see more information about the available VMs?

Run orka3 vm list --output wide.

3. View the available base images that you can use to deploy a VM. MacStadium provides images in a GitHub Container Repo that you can view in a web browser at MacStadium Image Respository.

You will see a list of Sequoia, Sonoma, and Ventura images, amongst potentially others. Use the orka3 imagecache add ghcr.io/macstadium/orka-images/<IMAGE_NAME>:<IMAGE_TAG> --allto cache the image to all nodes in your cluster.

📘

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.

(Intel-only) Empty images provide added storage or serve as the base image during manual OS installs from ISO.

5. Deploying a VM is as simple as just specifying a base image. Run:

orka3 vm deploy --image ghcr.io/macstadium/orka-images/sequoia:latest

Orka creates a simple VM with the specified image and an amount of vCPU and vRAM and assigns a randomly generated name.

6. Check your nodes and your VMs.

• Re-run orka3 node list. Did the number of available resources change?
• List your VMs:

orka3 vm list

You should now see your VM in the list.

For more detailed output, you can run orka vm list --output wide. In addition to the name, IP, and connection ports of the VM, it also shows its architecture, base image, and CPU and memory configuration. 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 macOS. 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 orka3 vm list might become too crowded to use efficiently. Run orka3 vm list <VM_NAME> instead and get the system information for a single VM.

6. Experience your VM instance

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

📘

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

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

One more thing to remember is that Screen Sharing must already be enabled on macOS. However, this is usually not the case (especially on clean OS installs or after an ISO install, Intel-Only), and you must enable the setting yourself.

The good news is images provided by MacStadium: ghcr.io/macstadium/orka-images/sonoma:latest are already preconfigured for you, and you can enjoy out-of-the-box Screen Sharing and SSH connectivity.

📘

Are you not using the official MacStadium images?

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 again - 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 Orka3 CLI.

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

7. Preserve the image changes

Changing a running VM's configuration or file system 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 ensure that changes persist and appear on future deployments, you can commit them to the base image, save them as a new image, or push them to an OCI-compatible registry, the recommended and preferred method.

📘

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.

This operation restarts the VM.

Run orka3 vm commit --help for more information.

📘

(Intel & NFS) 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.

(Intel-only) This operation restarts the VM. Apple Silicon based VMs are not restarted.

Run orka3 vm save --help for more information.

📘

(Apple Silicon VM) Glossary: Push changes

Push your changes to the specified OCI-compatible registry, image, and image tag. Registry credentials are required to push an image. For more information, run orka3 regcred --help.

Run orka3 vm push --help for more information. Once the command is run, all the changes within the VM at that moment in time are captured and pushed to the image warehouse of your choice.

Examples:

shellshell

Usage:
  orka3 vm push VM_NAME IMAGE[:TAG] [flags]

Flags:
  -h, --help   help for push

Global Flags:
  -n, --namespace string   (Optional) If set, changes the namespace scope for the operation from 'orka-default' to the specified namespace. (default "orka-default")

# Push an image to GitHub Packages from the running 'vm-5rjn4' VM
orka3 vm push vm-5rjn4 ghcr.io/myorg/orka-images/base:latest

# Push an image to GitHub Packages from the running 'vm-fxwj5' VM in the 'orka-test' namespace
orka3 vm push vm-fxwj5 ghcr.io/myorg/orka-images/base:latest --namespace orka-test

1. Commit the changes, save a new image, or push to a private OCI-compatible registry.

This operation will retain the new admin password and the latest OS updates. You might need to share the new admin password with future users who follow this guide.

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

orka3 vm commit <VM_NAME>

OR

orka3 vm save <VM_NAME> <NEW_IMAGE_NAME>

OR

orka3 regcred <SERVER> --username <USER> --password <PASSWORD> [--allow-insecure]
orka3 vm push <VM_NAME> <IMAGE[:TAG]>

You can get the <VM_NAME> from the orka3 vm list output you ran earlier.

Registry credentials are required to push an image. For more information, run orka3 regcred --help.

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

orka3 vm deploy --image <IMAGE_NAME>

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 instances have served their purpose, you can delete them.

1. Remove all VM instances you created until now:

orka3 vm delete <VM_NAME>

2. List your VMs again.

orka3 vm list

What's next

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

• Run orka3 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.
• File a support ticket in the MacStadium portal.
• Is a feature missing? Please share your feedback by filing a ticket using the Customer Portal.
• If you want to tap into Kubernetes, see this page.