GuidesDiscussions
GuidesAPI ReferenceJoin the Mailing List

Orka on AWS: Getting Started

With Orka coming to AWS, you can now effortlessly integrate macOS development and macOS CI/CD into your AWS workflows and environments.

🚧

Quick navigation

Time to read: 4 minutes, 36 seconds

Jump to: How does Orka on AWS work? | Licensing and cost | Terms | Initial configuration | Using Orka on AWS at a glance

See also: Initial configuration guide | Known limitations | VNC and Screen Sharing to a VM | Accessing the Orka Web UI

Orka (Orchestration with Kubernetes on Apple) is a virtualization layer for Mac build infrastructures based on Docker and Kubernetes technology. Orka lets you orchestrate macOS in a cloud environment using Kubernetes on genuine Apple hardware.

With Orka coming to AWS, you can now effortlessly integrate macOS development and macOS CI/CD into your AWS workflows and environments.

How does Orka on AWS work?

Your Orka cluster is a Virtual Private Cloud (VPC) within a MacStadium-owned and operated account, dedicated exclusively to you and your cluster. The resources from your own VPC (the customer VPC) and the Orka cluster connect to and access each other via VPC peering.

The VPC peering between the Orka cluster and your customer VPC acts as a permanent VPN tunnel. After the MacStadium team completes the cluster and VPC peering configuration, you can use your Orka on the AWS cluster as a regular Orka cluster (with a few known limitations).

Licensing and cost

For licensing and cost information, reach out to [email protected].

For questions related to licensing management, reach out to [email protected].

Terms

  • The Orka prefix (Orka cluster, Orka network, Orka VPC, etc.) indicates that the term pertains to the Orka AWS infrastructure managed by MacStadium. To report issues with the Orka on AWS infrastructure or to request any changes, submit a ticket through the MacStadium portal.
  • The customer prefix indicates that the term pertains to your own AWS infrastructure, managed by you.

Initial configuration

❗️

CAUTION

Do not use the customer account root user to complete any steps of the configuration.

  1. Contact MacStadium for access to Orka on AWS.
  2. When prompted, provide the following information to the MacStadium team.
    • The region of your customer VPC
    • The account ID of your customer Amazon account
    • The VPC ID of your customer VPC that will have access to your Orka cluster
    • The customer network CIDR of the customer VPC network
    • The Orka network CIDR (it must not overlap with the customer network CIDR)
    • The Security groups IDs will have access to the Orka cluster
  3. The MacStadium team creates the AWS account for the Orka cluster and the VPC peering request, and returns the following information to you.
    • Peering connection ID
    • Requester owner ID
    • Requester VPC
  4. Accept the VPC peering request and notify the MacStadium team that the peering connection is active. Verify the request data against the information provided by MacStadium earlier.

🚧

Time to complete

The MacStadium team will take up to 24 hours to configure the request and send back the details. You will have up to 7 days to accept the pending request, before it expires.

As soon as you confirm the VPC peering request, the peering connection instantly becomes live and active.

  1. Modify the route tables of the customer VPC to enable communication between the instances in the customer VPC and the Orka VPC.
  2. The MacStadium team completes the security and traffic configuration of the Orka VPC and returns the following information to you.
    • Orka account ID
    • Orka VPC ID
    • Peering connection ID
    • Orka endpoint
    • Orka license key
    • Orka network CIDR
    • Orka security group ID (if configured)

Using Orka on AWS at a glance

The VPC peering between the Orka cluster and your customer VPC acts as a permanent VPN tunnel. After the MacStadium team completes the cluster and VPC peering configuration, you can use your Orka on AWS cluster as a regular Orka cluster (with a few known limitations).

πŸ“˜

IMPORTANT

You will run all CLI commands and API requests against the Orka endpoint. The MacStadium team will provide you with your Orka endpoint.

πŸ‘

Looking for the Orka Web UI?

You need to configure port forwarding to be able to use the Orka Web UI with Orka on AWS. See here.

Workflow overview

❗️

CAUTION

Never use the customer account root user when working with your Orka VPC.

  1. Deploy a VM in your customer VPC.

  2. Configure the VM in your customer VPC for access to the Orka cluster. For example, install the Orka CLI, configure your CI/CD plugins, or make sure that you can run API calls from the machine.

  3. Create your Orka user and obtain an access token.

    ToolCommand
    Orka CLIorka config -a <ORKA_API_URL> -l <ORKA_LICENSE_KEY> -y && orka user create -e <EMAIL> --password <PASSWORD> -y
    Orka APIcurl --location --request POST 'myOrkaEndpoint/users' --header 'Content-Type: application/json' --header 'orka-licensekey: myLicenseKey' --data-raw '{ "password": "password", "email": "[email protected]" }' && curl --location --request POST 'myOrkaEndpoint/token' --header 'Content-Type: application/json' --data-raw '{ "email": "[email protected]", "password": "password" }'
  4. Create a VM config and deploy an instance from it.

    ToolCommand
    Orka CLIorka vm create -v <NAME> -b <BASE_IMAGE> -c <CPU_COUNT> -C <vCPU_COUNT> -y
    Orka APIcurl --location --request POST 'myOrkaEndpoint/resources/vm/create' --header 'Content-Type: application/json' --header 'Authorization: Bearer myToken' --data-raw '{ "orka_vm_name": "myorkavm", "orka_base_image": "Ventura.orkasi", "orka_image": "myorkavm", "orka_cpu_core": 6, "vcpu_count": 6 }' && curl --location --request POST 'myOrkaEndpoint/resources/vm/deploy' --header 'Content-Type: application/json' --header 'Authorization: Bearer myToken' --data-raw '{ "orka_vm_name": "myorkavm" }'
  5. Connect to the Orka instance, make changes to the system, and save the VM image.

    ToolCommand
    Orka CLIorka image commit -v <VM_ID> -y
    Orka APIcurl --location --request POST 'myOrkaEndpoint/resources/image/commit' --header 'Content-Type: application/json' --header 'Authorization: Bearer myToken' --data-raw '{ "orka_vm_name": "myVmId" }'
  6. Deploy instances with the updated configuration.

    ToolCommand
    Orka CLIorka vm deploy -v <NAME> -y
    Orka APIcurl --location --request POST 'myOrkaEndpoint/resources/vm/deploy' --header 'Content-Type: application/json' --header 'Authorization: Bearer myToken' --data-raw '{ "orka_vm_name": "myorkavm" }'
  7. Delete your instances.

    ToolCommand
    Orka CLIorka vm delete -v <NAME> -y
    Orka APIcurl --location --request DELETE 'myOrkaEndpoint/resources/vm/delete' --header 'Content-Type: application/json' --header 'Authorization: Bearer myToken' --data-raw '{ "orka_vm_name": "myorkavm", "orka_node_name": "myNode" }'

Connecting to a VM in the Orka cluster

❗️

CAUTION

Never use the customer account root user when working with your Orka VPC.

When working from within the customer VPC, you need to connect to your Orka VMs via SSH from a VM in the customer VPC. You will not be able to use VNC and any GUI features of the Orka VM.

To connect to an Orka VM via VNC and be able to work with the GUI of the VM, you need to connect from your local machine. To achieve that, you need to configure port forwarding via the customer VPC.

Reporting issues

MacStadium handles all issues with your Orka cluster and respective AWS account and services.

If you experience any issues, submit a ticket through the MacStadium portal.

For more information about the available support tiers, see here.

For more information about how MacStadium support works, see here and here.

See also


Β© 2019-2023 Copyright MacStadium, Inc. – Documentation built with readme.com. Orka is a registered trademark of MacStadium, Inc.