Quick Glance at Using Orka

🚧

Time to read: 5 minutes, 22 seconds

Every Orka user has a unique use case and requirements. Whether you're looking to run single Xcode builds or create an automated CI/CD pipeline with daily and nightly builds, your Orka journey will go through the following simple steps.

1. Get ready

1. Get an Orka subscription.
   Contact MacStadium to discuss your requirements. Based on your use case, the team will recommend and provide the best hardware option for your business.

2. Choose your tools.

   • The Orka Web UI provides a quick and user-friendly way to manage your Orka cluster. Currently, the Web UI offers limited functionality compared to the Orka3 CLI and the Orka3 API.
   • The Orka3 CLI is the easiest way to start with Orka. It's perfect for manual use and automation alike.
   • If you want to build an automated CI/CD system, look into the available Orka integrations - from Jenkins to Drone, the Orka team continuously adds to the list of supported solutions.
   • The Orka3 API enables you to be tool-agnostic or develop an in-house solution.

3. Learn to the Orka terminology:

2. Get set

1. Make sure you are added as a user to the MacStadium Customer Portal account for your cluster.

2. Connect to your cluster via VPN. Ensure you have an up-and-running VPN connection every time you work with Orka.

   1. Get your IP Plan.
   2. Get a VPN client and use it to connect to your cluster using the firewall IP and credentials you obtained in the previous step.
   3. Keep the VPN connection to your cluster live.

3. Configure your environment. This step is a one-time effort.

   • In the Orka3 CLI, run orka3 config set --api-url <ORKA_API_URL>.
   • For Orka3 API calls, target your Orka API endpoint or use the Swagger UI at <ORKA_API_URL>/api/v1/swagger.
   • For the Orka Web UI, go to <ORKA_API_URL> in your browser.
   • For CI/CD integrations, configure your Orka API URL as prompted during the setup.

📘

What's your Orka API URL?

If you are an Orka Enterprise user, 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.

If you are an Orka Small Teams user, you can get the Orka API URL from the How to tab for your cluster in the MacStadium Customer Portal. It's your Controller IP prefixed with http://. Usually http://10.221.188.20.

3. If you want to use the Orka3 CLI, log in to your cluster and obtain an authentication token.
   Your token authenticates you uniquely with Orka. This operation stores your token locally in your ~/.kube/config file.

   Shell

   orka3 login
   

   When prompted, provide your MacStadium Customer Portal credentials in the login form in the browser.

4. If you want to use the Orka3 API, provide the Authorization: Bearer <TOKEN> header in your API calls or authorize the Swagger UI at <ORKA_API_URL>/api/v1/swagger. Use your authentication token.
   In the Orka3 CLI, obtain a token by running:

   Shell

   orka3 user get-token
   

5. If you want to use the Orka Web UI, log in with your authentication token.
   In the Orka3 CLI, obtain a token by running:

   Shell

   orka3 user get-token
   

6. For CI/CD integrations, authenticate based on the integration version.

   • If running a 2.x-compatible version, continue using your old user and password.

   • If you are running a 3.0.0-compatible version, authenticate with a dedicated service account.

     Orka3 CLIOrka3 API

     orka3 sa create <SERVICE_ACCOUNT_NAME>
     orka3 sa token <SERVICE_ACCOUNT_NAME> [--duration <DURATION>]
     

     curl --request POST \
          --url <ORKA_API_URL>/api/v1/namespaces/{namespace}/serviceaccounts/{serviceaccount} \
          --header 'Authorization: Bearer <TOKEN>' \
          --header 'accept: application/json'
     
     curl --request POST \
          --url <ORKA_API_URL>/api/v1/namespaces/{namespace}/serviceaccounts/{serviceaccount}/token \
          --header 'Authorization: Bearer <TOKEN>' \
          --header 'accept: application/json' \
          --header 'content-type: application/json'
     

3. Go

1. Deploy VMs. Deploy as many or as few as you need.

To deploy a VM, you need an image. Check what images are available locally in your cluster. Check out the remote and pull an image if the local image list is empty. Or, even better, use an image from an OCI-compatible registry. Check https://github.com/macstadium/orka-images for the latest available OCI-compatible images provided by MacStadium. The images available out-of-the-box provide a pre-configured disk size and a pre-installed OS.

(Intel-only) If you want to use a different disk size or prefer to install an OS yourself, you can go the ISO way. Create an empty image of sufficient size and attach an ISO to your VM.

2. Work with your VMs.

You can connect to your VMs via VNC, SSH, or Apple Screen Sharing. Once connected, you can change the VM by installing extra software, enabling OS features, and others. For more information, see VNC, SSH, and Screen Sharing for Orka VMs.

You can preserve the changes from one VM and deploy new VMs with these exact changes. Save or commit your changes, or push them to a remote OCI-compatible registry, to preserve and make them available for future configs and deployments.

3. (Optional) Delete unused VMs.

What's next

Choose how you want to get started with Orka.