From 2da8bc0fb565940c0fb38057d134be82bedf50df Mon Sep 17 00:00:00 2001 From: Fedor Korotkov Date: Thu, 28 Sep 2023 15:53:13 -0400 Subject: [PATCH] Document XL Cirrus Runners (#613) * Document XL Cirrus Runners Also tried to put everything about Cirrus Runners in one place rather than having the information spreaded between https://tart.run and https://github.com/apps/cirrus-runners. Plus updated docs to use Sonoma. * Apply suggestions from code review Co-authored-by: Nikolay Edigaryev --------- Co-authored-by: Nikolay Edigaryev --- .cirrus.yml | 10 +- README.md | 4 +- .../posts/2023-04-28-orchard-ssh-over-grpc.md | 8 +- docs/integrations/cirrus-cli.md | 4 +- docs/integrations/github-actions.md | 108 +++++++++++++++--- docs/integrations/gitlab-runner.md | 2 +- docs/integrations/vm-management.md | 8 +- docs/quick-start.md | 14 +-- integration-tests/test_run.py | 2 +- scripts/run-signed.sh | 2 +- 10 files changed, 118 insertions(+), 44 deletions(-) diff --git a/.cirrus.yml b/.cirrus.yml index ab33267..1f372bf 100644 --- a/.cirrus.yml +++ b/.cirrus.yml @@ -4,7 +4,7 @@ env: XCODE_TAG: 15 task: - name: Test on Ventura + name: Test on Sonoma alias: test use_compute_credits: $CIRRUS_USER_COLLABORATOR == 'true' persistent_worker: @@ -35,7 +35,7 @@ task: alias: lint use_compute_credits: $CIRRUS_USER_COLLABORATOR == 'true' macos_instance: - image: ghcr.io/cirruslabs/macos-ventura-xcode:$XCODE_TAG + image: ghcr.io/cirruslabs/macos-sonoma-xcode:$XCODE_TAG lint_script: - swift package plugin --allow-writing-to-package-directory swiftformat --cache ignore --lint --report swiftformat.json . always: @@ -49,7 +49,7 @@ task: alias: build use_compute_credits: $CIRRUS_USER_COLLABORATOR == 'true' macos_instance: - image: ghcr.io/cirruslabs/macos-ventura-xcode:$XCODE_TAG + image: ghcr.io/cirruslabs/macos-sonoma-xcode:$XCODE_TAG build_script: swift build --product tart sign_script: codesign --sign - --entitlements Resources/tart-dev.entitlements --force .build/debug/tart binary_artifacts: @@ -63,7 +63,7 @@ task: - build use_compute_credits: $CIRRUS_USER_COLLABORATOR == 'true' macos_instance: - image: ghcr.io/cirruslabs/macos-ventura-xcode:$XCODE_TAG + image: ghcr.io/cirruslabs/macos-sonoma-xcode:$XCODE_TAG env: MACOS_CERTIFICATE: ENCRYPTED[552b9d275d1c2bdbc1bff778b104a8f9a53cbd0d59344d4b7f6d0ca3c811a5cefb97bef9ba0ef31c219cb07bdacdd2c2] AC_PASSWORD: ENCRYPTED[4a761023e7e06fe2eb350c8b6e8e7ca961af193cb9ba47605f25f1d353abc3142606f412e405be48fd897a78787ea8c2] @@ -99,7 +99,7 @@ task: - build use_compute_credits: $CIRRUS_USER_COLLABORATOR == 'true' macos_instance: - image: ghcr.io/cirruslabs/macos-ventura-xcode:$XCODE_TAG + image: ghcr.io/cirruslabs/macos-sonoma-xcode:$XCODE_TAG env: MACOS_CERTIFICATE: ENCRYPTED[552b9d275d1c2bdbc1bff778b104a8f9a53cbd0d59344d4b7f6d0ca3c811a5cefb97bef9ba0ef31c219cb07bdacdd2c2] AC_PASSWORD: ENCRYPTED[4a761023e7e06fe2eb350c8b6e8e7ca961af193cb9ba47605f25f1d353abc3142606f412e405be48fd897a78787ea8c2] diff --git a/README.md b/README.md index 4339cf4..472890e 100644 --- a/README.md +++ b/README.md @@ -68,8 +68,8 @@ Try running a Tart VM on your Apple Silicon device running macOS 13.0 (Ventura) ```bash brew install cirruslabs/cli/tart -tart clone ghcr.io/cirruslabs/macos-ventura-base:latest ventura-base -tart run ventura-base +tart clone ghcr.io/cirruslabs/macos-sonoma-base:latest sonoma-base +tart run sonoma-base ``` Please check the [official documentation](https://tart.run) for more information and/or feel free to use [discussions](https://github.com/cirruslabs/tart/discussions) diff --git a/docs/blog/posts/2023-04-28-orchard-ssh-over-grpc.md b/docs/blog/posts/2023-04-28-orchard-ssh-over-grpc.md index 5781537..edbbfc9 100644 --- a/docs/blog/posts/2023-04-28-orchard-ssh-over-grpc.md +++ b/docs/blog/posts/2023-04-28-orchard-ssh-over-grpc.md @@ -74,25 +74,25 @@ Secondly, we’ve exposed three commands in the Orchard CLI that all use this en Opens a TCP port locally and forwards everything sent to it to the specified VM (and vice versa). -For example, `orchard port-forward vm ventura-builder 2222:22` will forward traffic from the local TCP port `2222` to the `ventura-builder` VM’s TCP port `22`. +For example, `orchard port-forward vm sonoma-builder 2222:22` will forward traffic from the local TCP port `2222` to the `ventura-builder` VM’s TCP port `22`. ### `orchard ssh` Connects to the specified VM on the default SSH port `22`, optionally only launching a command (if specified), similarly to what the official OpenSSH client does. -For example, `orchard ssh vm ventura-builder` will open an interactive session with the `ventura-builder` VM. +For example, `orchard ssh vm sonoma-builder` will open an interactive session with the `ventura-builder` VM. You can also send local scripts for execution by utilizing redirection: ```shell -orchard ssh vm ventura-builder 'sh -s' < script.sh +orchard ssh vm sonoma-builder 'sh -s' < script.sh ``` ### `orchard vnc` Establishes a port forwarding to the specified VM’s default VNC port `5900` and opens the default macOS Screen Sharing app. -For example, `orchard vnc vm ventura-builder` will establish a port-forwarding to the `ventura-builder` VM's port `5900` under the hood and launch macOS Screen Sharing app. +For example, `orchard vnc vm sonoma-builder` will establish a port-forwarding to the `ventura-builder` VM's port `5900` under the hood and launch macOS Screen Sharing app. Note that the SSH and VNC commands expect the VM resource to specify credentials in it’s definition (can be done via `orchard create vm`), and will otherwise fall back to the credentials specified by `--username` and `--password`, or if none specified — to de-facto standard of `admin:admin` credentials. diff --git a/docs/integrations/cirrus-cli.md b/docs/integrations/cirrus-cli.md index 89670e4..effaa9e 100644 --- a/docs/integrations/cirrus-cli.md +++ b/docs/integrations/cirrus-cli.md @@ -13,7 +13,7 @@ task: name: hello macos_instance: # can be a remote or a local virtual machine - image: ghcr.io/cirruslabs/macos-ventura-base:latest + image: ghcr.io/cirruslabs/macos-sonoma-base:latest hello_script: - echo "Hello from within a Tart VM!" - echo "Here is my CPU info:" @@ -45,7 +45,7 @@ exposes it via [`artifacts` instruction](https://cirrus-ci.org/guide/writing-tas task: name: Build macos_instance: - image: ghcr.io/cirruslabs/macos-ventura-xcode:latest + image: ghcr.io/cirruslabs/macos-sonoma-xcode:latest build_script: swift build --product tart binary_artifacts: path: .build/debug/tart diff --git a/docs/integrations/github-actions.md b/docs/integrations/github-actions.md index 3b8e908..28425bf 100644 --- a/docs/integrations/github-actions.md +++ b/docs/integrations/github-actions.md @@ -1,33 +1,107 @@ -# GitHub Actions +# Cirrus Runners for GitHub Actions -Tart already powers several CI services mentioned above including our own [Cirrus CI](https://cirrus-ci.org/guide/macOS/) which offers unlimited concurrency with per-second billing. -For services that haven't leveraged Tart yet, we offer fully managed runners via a monthly subscription. *Cirrus Runners* is the fastest way to get your current CI workflows to benefit from Apple Silicon hardware. No need to manage infrastructure or migrate to another CI provider. +Your actions will be executed in clean macOS virtual machines with 4 Apple M2 cores, compared to GitHub's own macOS runners with just 3 cores and only supporting the outdated Apple–Intel architecture. ## Testimonials from customers -Sebastian Jachec, Mobile Engineer at [Daybridge](https://www.daybridge.com/). - -> It’s been plain-sailing with the Cirrus Runners — they’ve been great! They’re consistently 60+% faster on workflows that we previously used Github Actions’ macOS runners for. - -Max Lapides, Senior Mobile Engineer at [Tonal](https://www.tonal.com/). +Max Lapides, Senior Mobile Engineer at [Tonal](https://www.tonal.com/): > Previously, we were using the GitHub‑hosted macOS runners and our iOS build took ~30 minutes. Now with Cirrus Runners, the iOS build only takes ~12 minutes. That’s a huge boost to our productivity, and for only $150/month per runner it is much less expensive too. +John A., Software Engineer at [GitKraken](https://www.gitkraken.com/): + +> GitHub Actions MacOS-x86 runners have become increasingly unreliable, so we're moving our Mac builds over to arm64 because Cirrus Labs' M1 runners are not only ~3 times faster, they've also been far more stable. + +Sebastian Jachec, Mobile Engineer at [Daybridge](https://www.daybridge.com/): + +> It’s been plain-sailing with the Cirrus Runners — they’ve been great! They’re consistently 60+% faster on workflows that we previously used Github Actions’ macOS runners for. + +## Pricing + +Each Cirrus Runner costs $150 a month and there is no limit on the amount of minutes for your actions. +We recommend to purchase several Cirrus Runners depending on your team size, so you can run actions in +parallel. Note that you can change your subscription at any time via [this page](https://billing.stripe.com/p/login/3cs7vNbzo92p7fy3cc) +or by emailing [support@cirruslabs.org](mailto:support@cirruslabs.org). + +### Priority Support + +Subscriptions of 20 or more Cirrus Runners include access to [Priority Support](../licensing.md#priority-support). +Please contact [sales@cirruslabs.org](mailto:sales@cirruslabs.org) in order to get all the details. + +### CPU and Memory resources of Cirrus Runners + +By default, a single Cirrus Runner is allocated with 4 M2 cores and 12 GB of unified memory which is enough for most of the workloads. +For workloads that require more resources it is possible to use XL Cirrus Runners which have twice the resources: a full M2 chip with 8 cores +and 24 GB of unified memory. Note that a single XL Cirrus Runner also uses twice the concurrency. + +In order to use an XL Cirrus Runner for a job please append `-xl` suffix to your `runs-on` property. More on that down below. + +## Installation + +Once you configure [Cirrus Runners App](https://github.com/apps/cirrus-runners) for your organization, you'll be redirected +to a checkout page powered by Stripe. During the checkout process you'll be able to configure a subscription for +a desired amount of parallel Cirrus Runners and try it for free for 10 days. + +Once configured, please follow instruction below. If you have any questions please contact [support@cirruslabs.org](mailto:support@cirruslabs.org). +Subscriptions with more than 10 runners also include Priority Support ## Configuring Cirrus Runners -Configuring Cirrus Runners for GitHub Actions is as simple as installing [Cirrus Runners App](https://github.com/apps/cirrus-runners). -After successful installation and subscription configuration, use any of [Ventura images managed by us](https://github.com/cirruslabs/macos-image-templates) in `runs-on`: +In order for Cirrus Runners to be used by your GitHub Actions workflow jobs, specify a desired image in the `runs-on` property. -```yaml -name: Test Suite -jobs: - test: - runs-on: ghcr.io/cirruslabs/macos-ventura-xcode:latest -``` +=== "Default Cirrus Runner" + + ```yaml + name: Tests + jobs: + test: + runs-on: ghcr.io/cirruslabs/macos-sonoma-xcode:latest + ``` + +=== "XL Cirrus Runner" + + ```yaml + name: Integration Tests + jobs: + test: + runs-on: ghcr.io/cirruslabs/macos-sonoma-xcode:latest-xl + ``` + +List of all available images can be found in [this repository](https://github.com/cirruslabs/macos-image-templates). + +Note that Tart VM images don't have the same set of pre-installed packages as the official Intel GitHub runners. +If something is missing please [create an issue within this repository](https://github.com/cirruslabs/macos-image-templates/issues/new). When workflows are executing you'll see Cirrus on-demand runners on your organization's settings page at `https://github.com/organizations//settings/actions/runners`. -Note that Cirrus Runners will get added to the default runner group. By default, only private repositories can access runners in a default runner group, but you can override this in your organization's settings. +Note that Cirrus Runners will get added to the default runner group. + +!!! tip "Using Cirrus Runners with public repositories" + + By default, only private repositories can access runners in a default runner group, but you can override this in your organization's settings: + + ```https://github.com/organizations//settings/actions/runner-groups/1``` ![](/assets/images/TartGHARunners.png) + +## Data handling flow + +By design Cirrus Runners service never sees any of your secrets or source code and acts as compute platform with the lastest +Apple Silicon hardware that can quickly allocate CPU/Memory resources for your jobs. + +Here is a high-level overview of how Cirrus Runners service manages runners for your organization: + +- Cirrus Runner GitHub App is subscribed to [`workflow_job`](https://docs.github.com/en/webhooks/webhook-events-and-payloads#workflow_job). +- Upon receiving a new event targeting Cirrus Runners via `runs-on` property the following steps take place: + + * Non-personal information about your job is saved to perform health checking of Cirrus Runners execution. + * Cirrus Runners GitHub App has only one permission that allows generating temporary registration tokens for + self-hosted GitHub Actions Runners. Note that Cirrus Runners GitHub App itself doesn't have access to contents of + repositories in your organization. + * Cirrus Runners Service creates a new single use Tart VM, generates a temporary registration tokens for self-hosted runners + and passes it without storing inside the VM for the GitHub Actions Runner service to [start a ephemeral runner](https://github.blog/changelog/2021-09-20-github-actions-ephemeral-self-hosted-runners-new-webhooks-for-auto-scaling/). + +- Cirrus Runners service continuously monitors health of the Tart VM executing your job to make sure it runs to completion. +- After the job finishes the ephemeral Tart VM is getting destroyed with all the information of the job run. + +If you have any questions or concerns please feel free to reach out to [support@cirruslabs.org](mailto:support@cirruslabs.org). diff --git a/docs/integrations/gitlab-runner.md b/docs/integrations/gitlab-runner.md index 0b3e19e..332fe27 100644 --- a/docs/integrations/gitlab-runner.md +++ b/docs/integrations/gitlab-runner.md @@ -37,7 +37,7 @@ Now you can use Tart Images in your `.gitlab-ci.yml`: ```yaml # You can use any remote Tart Image. # Tart Executor will pull it from the registry and use it for creating ephemeral VMs. -image: ghcr.io/cirruslabs/macos-ventura-base:latest +image: ghcr.io/cirruslabs/macos-sonoma-base:latest test: tags: diff --git a/docs/integrations/vm-management.md b/docs/integrations/vm-management.md index 13bdca4..a3cee86 100644 --- a/docs/integrations/vm-management.md +++ b/docs/integrations/vm-management.md @@ -11,8 +11,8 @@ Tart can create VMs from `*.ipsw` files. You can download a specific `*.ipsw` fi use `latest` instead of a path to `*.ipsw` to download the latest available version: ```bash -tart create --from-ipsw=latest ventura-vanilla -tart run ventura-vanilla +tart create --from-ipsw=latest sonoma-vanilla +tart run sonoma-vanilla ``` After the initial booting of the VM you'll need to manually go through the macOS installation process. As a convention we recommend creating an `admin` user with an `admin` password. After the regular installation please do some additional modifications in the VM: @@ -67,8 +67,8 @@ packer { } source "tart-cli" "tart" { - vm_base_name = "ghcr.io/cirruslabs/macos-ventura-base:latest" - vm_name = "my-custom-ventura" + vm_base_name = "ghcr.io/cirruslabs/macos-sonoma-base:latest" + vm_name = "my-custom-sonoma" cpu_count = 4 memory_gb = 8 disk_size_gb = 70 diff --git a/docs/quick-start.md b/docs/quick-start.md index 7f9c1dd..2a28343 100644 --- a/docs/quick-start.md +++ b/docs/quick-start.md @@ -7,8 +7,8 @@ Try running a Tart VM on your Apple Silicon device running macOS 13.0 (Ventura) ```bash brew install cirruslabs/cli/tart -tart clone ghcr.io/cirruslabs/macos-ventura-base:latest ventura-base -tart run ventura-base +tart clone ghcr.io/cirruslabs/macos-sonoma-base:latest sonoma-base +tart run sonoma-base ``` ??? info "Manual installation from a release archive" @@ -17,8 +17,8 @@ tart run ventura-base ```bash curl -LO https://github.com/cirruslabs/tart/releases/latest/download/tart.tar.gz tar -xzvf tart.tar.gz - ./tart.app/Contents/MacOS/tart clone ghcr.io/cirruslabs/macos-ventura-base:latest ventura-base - ./tart.app/Contents/MacOS/tart run ventura-base + ./tart.app/Contents/MacOS/tart clone ghcr.io/cirruslabs/macos-sonoma-base:latest sonoma-base + ./tart.app/Contents/MacOS/tart run sonoma-base ``` Please note that `./tart.app/Contents/MacOS/tart` binary is required to be used in order to trick macOS @@ -33,7 +33,7 @@ tart run ventura-base If the guest VM is running and configured to accept incoming SSH connections you can conveniently connect to it like so: ```bash -ssh admin@$(tart ip ventura-base) +ssh admin@$(tart ip sonoma-base) ``` !!! tip "Running scripts inside Tart virtual machines" @@ -42,8 +42,8 @@ ssh admin@$(tart ip ventura-base) ```bash brew install sshpass - sshpass -p admin ssh -o "StrictHostKeyChecking no" admin@$(tart ip ventura-base) "uname -a" - sshpass -p admin ssh -o "StrictHostKeyChecking no" admin@$(tart ip ventura-base) < script.sh + sshpass -p admin ssh -o "StrictHostKeyChecking no" admin@$(tart ip sonoma-base) "uname -a" + sshpass -p admin ssh -o "StrictHostKeyChecking no" admin@$(tart ip sonoma-base) < script.sh ``` ## Mounting directories diff --git a/integration-tests/test_run.py b/integration-tests/test_run.py index 3a259c2..b3060ae 100644 --- a/integration-tests/test_run.py +++ b/integration-tests/test_run.py @@ -7,7 +7,7 @@ def test_run(tart): vm_name = f"integration-test-run-{uuid.uuid4()}" # Instantiate a VM with admin:admin SSH access - tart.run(["clone", "ghcr.io/cirruslabs/macos-ventura-base:latest", vm_name]) + tart.run(["clone", "ghcr.io/cirruslabs/macos-sonoma-base:latest", vm_name]) # Run the VM asynchronously tart_run_process = tart.run_async(["run", vm_name]) diff --git a/scripts/run-signed.sh b/scripts/run-signed.sh index 4d33e8c..4144623 100755 --- a/scripts/run-signed.sh +++ b/scripts/run-signed.sh @@ -1,7 +1,7 @@ #!/bin/sh # helper script to build and run a signed tart binary -# usage: ./scripts/run-signed.sh run ventura-base +# usage: ./scripts/run-signed.sh run sonoma-base set -e