game-ci · frostebite · May 19, 2022 · May 19, 2022 · May 19, 2022 · May 19, 2022
diff --git a/docs/04-github/06-remote-builder.md b/docs/04-github/06-remote-builder.md
diff --git a/docs/cloud-runner/01-introduction.md b/docs/cloud-runner/01-introduction.md
@@ -0,0 +1,80 @@
+# Introduction
+## Concept - What Does Cloud Runner Do
+
+**Cloud Runner enables you to run build and test workflows in the cloud, right from GitHub actions. Builder will automatically provision an environment at a Cloud Provider such as GCP and AWS. It will then send the project to be built and/or tested depending on your workflow configuration.** 
+
+**Cloud Runner is especially useful for game development because it supports large projects. Cloud Runner provides first class support for the Unity game engine.**
+
+Cloud Runner uses git to track and transfer your projects and uses native cloud services such as AWS Fargate and Kubernetes to run your jobs. Other version control systems are not actively supported.
+
+## Why cloud runner?
+1. Extended options and more control over disk size, memory and CPU. You can build projects of almost any size.
+2. Scale up to much larger numbers of builds easily and fully on demand.
+3. Run custom jobs and extend the system for any workload.
+4. Create resources on-demand, we have made an effort to make sure that it costs you nothing while there are no builds running (no guarantees).
+
+## Why not cloud runner?
+1. Your project is small in size. Below 5GB Cloud Runner should not be needed.
+2. You already have servers running you can use for capacity.
+3. You strongly prefer to avoid any delay in your pipeline. 
+
+Although speed of CI pipelines is an important metric, there are real challenges for game development pipelines. 
+
+This solution prefers ease of use, scalability, throughput and flexibility to maxiumum speed. 
+
+Faster solutions would all involve self-hosted hardware with an immediate local cache of the large project files and working directory. 
+
+## Cloud Runner Release Status
+Cloud Runner is in "active development" ⚠️🔨
+
+Cloud Runner overall release status: `preview`
+This means some APIs may change, features are still being added but the minimum feature set works and is stable.
+
+Release Stages: `experimental` ➡️ `preview` ➡️ `full release`
+
+You must use a provider with Cloud Runner, each provider's release status is described below. This indicates the stability and support for cloud runner features and workflows.
+
+### Development
+_Cloud Runner is actively maintained and kept stable by the Game CI open source project contributors._
+
+💬suggestions, 🐛bugs and ↕️Minor changes are tracked as GitHub issues:
+ - [Game CI Issues - GitHub](https://github.com/game-ci/unity-builder/labels/cloud-runner)
+
+You can also explore the [development roadmap page](development).
+
+### Community
+__Share your feedback with us!__
+ - [__Discord Channel__](https://discord.com/channels/710946343828455455/789631903157583923)
+ - [__Feedback Form__](https://forms.gle/3Wg1gGf9FnZ72RiJ9)
+
+### Supported Cloud Runner Platforms
+```md
+| Cloud Provider Platform | Release Status            |
+| ----------------------- | ------------------------- |
+| Kubernetes              | ✔️ experimental release |
+| AWS                     | ✔️ preview release      |
+| GCP                     | ⚠ Considered             |
+| Azure                   | ⚠ Considered             |
+```
+_Note for Kuberentes support:_
+_Usually the cluster needs to be up and running at all times, as starting up a cluster is slow._
+_Use Google Cloud's Kubernetes Autopilot you can scale down to the free tier automatically while not in use._
+
+```md
+| Git Platform          | Release Status       |
+| --------------------- | -------------------- |
+| GitHub                | ✔️ preview release |
+| GitLab                | ✔️ preview release |
+| Command Line          | ✔️ preview release |
+| Any Git repository    | ✔️ preview release |
+| Any Git automation/Ci | ✔️ preview release |
+```
+
+## Releases
+All cloud runner releases are currently packaged and released with game-ci's unity-builder module:
+[Game CI Releases - GitHub](https://github.com/game-ci/unity-builder/releases)
+
+History up to latest open incoming changes for release can be found here:
+[Cloud Runner PRs - GitHub](https://github.com/game-ci/unity-builder/pulls?q=is%3Apr+cloud+runner)
+
+You can see further information about configuring the release version on the [Configuration](configuration) page.
diff --git a/docs/cloud-runner/02-game-ci-vs-cloud-runner.md b/docs/cloud-runner/02-game-ci-vs-cloud-runner.md
@@ -0,0 +1,26 @@
+# Standard Game-CI vs Cloud Runner
+
+Game CI maintains a set of docker images that can be used to run workloads in many scenarios.
+
+Game CI also provides specific GitHub actions for running workflows on GitHub. And a similar workflow for running Game CI on GitLab and Circle CI.
+_All of these options use the build server resources provided by those systems, this can be a constraint or very convenient depending on the size of your project and the workloads you need to run._
+
+# Use Cases
+
+## Sending Builds to the cloud
+
+You may want to take advantage of cloud resources for lots of reasons (scale, speed, cost, flexibility) or may want to start remote builds from the command line without slowing down your development machine. Cloud Runner can help you do this.
+
+This may be a preference, more effecient or you may want to use systems that struggle to handle large game development projects (GitHub being a good example).
+
+### Large GitHub Projects
+
+GitHub Actions by default run on [build machines provided by GitHub](https://docs.github.com/en/actions/using-github-hosted-runners/about-github-hosted-runners). For Unity projects the available disk size is quite small. You may experience an error related to running out of disk space. You may also want to run the build on a server with more memory or processing resources.
+
+### GitHub Self-Hosted Runners vs Game CI Cloud Runner
+
+_GitHub users can consider: [GitHub self-hosted runners](https://docs.github.com/en/actions/hosting-your-own-runners/about-self-hosted-runners) and Cloud Runner. Both can enable you to build larger projects._
+
+_Cloud Runner can run itself as an ephemeral self hosted job to minimize your github actions runner usage, with the drawback of some extra startup time at the start of your workflow. Cloud Runner is better if you don't have a server setup or don't want to manage or maintain your own build server._
+
+_Self-hosted runners are best used when you already have a server available, running 24/7 that you can setup as a runner. And you're happy to maintain and keep that server available and running._
diff --git a/docs/cloud-runner/02-getting-started/aws.md b/docs/cloud-runner/02-getting-started/aws.md
@@ -0,0 +1,84 @@
+# AWS
+
+## Requirements
+
+- You must have an AWS account setup and ready to create resources.
+- Create a service account and generate an AWS access key and key id.
+
+## AWS Credentials
+
+Setup the following as `env` variables for cloud runner to use:
+
+- `AWS_ACCESS_KEY_ID`
+- `AWS_SECRET_ACCESS_KEY`
+- `AWS_DEFAULT_REGION` (should be the same AWS region as the base stack e.g `eu-west-2`)
+
+If you're using GitHub you can use a GitHub Action:
+```yaml
+- name: Configure AWS Credentials
+  uses: aws-actions/configure-aws-credentials@v1
+  with:
+    aws-access-key-id: ${{ secrets.AWS_ACCESS_KEY_ID }}
+    aws-secret-access-key: ${{ secrets.AWS_SECRET_ACCESS_KEY }}
+    aws-region: eu-west-2
+```
+
+_Note:_
+_This enables Cloud Runner access AWS._
+
+## Configuration For AWS Cloud Runner Jobs
+Refer to [Configuration page](../configuration) or the [example below](#example).
+
+### Allowed CPU/Memory Combinations
+
+There are some limitations to the CPU and Memory parameters. AWS will only accept the following combinations:
+[AWS Fargate Documentation, Allowed CPU and memory values (Task Definitions)](https://docs.aws.amazon.com/AmazonECS/latest/developerguide/task_definition_parameters.html#task_size)
+
+#### Summary Of Format
+- Values are represented as 1024:1 GB or CPU.
+- Do not include the vCPU or GB suffix.
+- 1 CPU can go to a max of 6 GB of memory. 2 CPU's are required to go higher.
+
+#### Valid CPU and Memory Values
+
+```yaml
+- cloudRunnerMemory: 4096
+- cloudRunnerCpu: 1024
+```
+
+## Example
+```yaml
+- uses: game-ci/unity-builder@cloud-runner-develop
+  id: aws-fargate-unity-build
+  timeout-minutes: 25
+  with:
+    cloudRunnerCluster: aws
+    versioning: None
+    projectPath: ${{ matrix.projectPath }}
+    unityVersion: ${{ matrix.unityVersion }}
+    targetPlatform: ${{ matrix.targetPlatform }}
+    githubToken: ${{ secrets.GITHUB_TOKEN }}
+    # You may want to export your builds somewhere external so you can access them outside of Cloud Runner jobs via the postBuildSteps:
+    postBuildSteps: |
+      - name: upload
+        image: amazon/aws-cli
+        commands: |
+          aws configure set aws_access_key_id $AWS_ACCESS_KEY_ID --profile default
+          aws configure set aws_secret_access_key $AWS_SECRET_ACCESS_KEY --profile default
+          aws configure set region $AWS_DEFAULT_REGION --profile default
+          aws s3 ls
+          aws s3 ls game-ci-test-storage
+          ls /data/cache/$CACHE_KEY
+          ls /data/cache/$CACHE_KEY/build
+          aws s3 cp /data/cache/$CACHE_KEY/build/build-$BUILD_GUID.zip s3://game-ci-test-storage/$CACHE_KEY/build-$BUILD_GUID.zip
+        secrets:
+        - name: awsAccessKeyId
+          value: ${{ secrets.AWS_ACCESS_KEY_ID }}
+        - name: awsSecretAccessKey
+          value: ${{ secrets.AWS_SECRET_ACCESS_KEY }}
+        - name: awsDefaultRegion
+          value: eu-west-2
+```
+_[Custom Steps](../advanced-topics/custom-steps)_
+
+A full workflow example can be seen in builder's [Cloud Runner GitHub sourcecode for AWS Pipeline](https://github.com/game-ci/unity-builder/blob/main/.github/workflows/cloud-runner-aws-pipeline.yml).
diff --git a/docs/cloud-runner/02-getting-started/kubernetes.md b/docs/cloud-runner/02-getting-started/kubernetes.md
@@ -0,0 +1,71 @@
+# Kubernetes
+
+## Requirements
+
+- You must have a Kuberentes cluster setup and ready that supports persistent volumes.
+- Create a kubeconfig and encode it as base64.
+
+## K8s Credentials
+
+Setup the following as `env` variables for the GitHub build step:
+
+- `kubeConfig` (should be encoded as base64)
+
+## Configuration For Kubernetes Cloud Runner Jobs
+Refer to [Configuration page](../configuration) or the [example below](#example).
+
+### Allowed CPU/Memory Combinations
+
+- `0.25 vCPU` - 0.5 GB, 1 GB, 2 GB
+- `0.5 vCPU` - 1 GB, 2 GB, 3 GB, 4 GB
+- `1 vCPU` - 2 GB, 3 GB, 4 GB, 5 GB, 6 GB, 7 GB, 8 GB
+- `2 vCPU` - Between 4 GB and 16 GB in 1-GB increments
+- `4 vCPU` - Between 8 GB and 30 GB in 1-GB increments
+
+Do not include the vCPU or GB suffix.
+
+#### Valid CPU and Memory Values
+```yaml
+- remoteBuildMemory: 2
+- remoteBuildCpu: 0.5
+```
+
+### Example
+```yaml
+- uses: game-ci/unity-builder@cloud-runner-develop
+  id: k8s-unity-build
+  timeout-minutes: 30
+  with:
+    cloudRunnerCluster: k8s
+    UNITY_LICENSE: ${{ secrets.UNITY_LICENSE }}
+    targetPlatform: ${{ matrix.targetPlatform }}
+    kubeConfig: ${{ steps.read-base64.outputs.base64 }}
+    githubToken: ${{ secrets.GITHUB_TOKEN }}
+    projectPath: test-project
+    unityVersion: ${{ matrix.unityVersion }}
+    versioning: None
+    # Currently kuberentes builds do not save their persistent volumes beyond a cloud runner job.
+    # So, you may want to export the results to cloud storage with a postBuildStep as follows:
+    postBuildSteps: |
+      - name: upload
+        image: amazon/aws-cli
+        commands: |
+          aws configure set aws_access_key_id $AWS_ACCESS_KEY_ID --profile default
+          aws configure set aws_secret_access_key $AWS_SECRET_ACCESS_KEY --profile default
+          aws configure set region $AWS_DEFAULT_REGION --profile default
+          aws s3 ls
+          aws s3 ls game-ci-test-storage
+          ls /data/cache/$CACHE_KEY
+          echo "/data/cache/$CACHE_KEY/build/build-$BUILD_GUID.zip s3://game-ci-test-storage/$CACHE_KEY/$BUILD_FILE"
+          aws s3 cp /data/cache/$CACHE_KEY/build/build-$BUILD_GUID.zip s3://game-ci-test-storage/$CACHE_KEY/build-$BUILD_GUID.zip
+        secrets:
+        - name: awsAccessKeyId
+          value: ${{ secrets.AWS_ACCESS_KEY_ID }}
+        - name: awsSecretAccessKey
+          value: ${{ secrets.AWS_SECRET_ACCESS_KEY }}
+        - name: awsDefaultRegion
+          value: eu-west-2
+```
+_[Custom Steps](../advanced-topics/custom-steps)_
+
+A full workflow example can be seen in builder's [Cloud Runner GitHub sourcecode for AWS Pipeline](https://github.com/game-ci/unity-builder/blob/main/.github/workflows/cloud-runner-k8s-pipeline.yml).