From b1813a2a92ef9ddf68f6a221a0a237109ca00b09 Mon Sep 17 00:00:00 2001
From: Fedor Korotkov <fedor.korotkov@gmail.com>
Date: Fri, 24 Mar 2023 09:49:06 -0400
Subject: [PATCH] Deployment guide to GCP (#44)

* Deployment guide to GCP

* Update DeploymentGuide.md

* Refer to Ansible Playbook

* read permissions as well
---
 DeploymentGuide.md | 75 ++++++++++++++++++++++++++++++++++++++++++++++
 Development.md     |  7 +++++
 README.md          | 22 ++++++--------
 3 files changed, 91 insertions(+), 13 deletions(-)
 create mode 100644 DeploymentGuide.md
 create mode 100644 Development.md

diff --git a/DeploymentGuide.md b/DeploymentGuide.md
new file mode 100644
index 0000000..2c9b979
--- /dev/null
+++ b/DeploymentGuide.md
@@ -0,0 +1,75 @@
+# Orchard Cluster Deployment Guide
+
+Orchard cluster consists of two components: Orchard Controller and a pool of Orchard Workers. Orchard Controller is
+responsible for managing the cluster and scheduling of resources. Orchard Workers are responsible for executing the VMs.
+
+The following guide is split in two parts. First, we'll [deploy an Orchard Controller](#deploying-orchard-controller) and then we'll
+[configure and register Orchard Workers](#configuring-orchard-workers) with Ansible.
+
+## Deploying Orchard Controller
+
+Orchard API is secured by default: all requests must be authenticated with credentials of a service account.
+When you first run Orchard Controller, you can specify `ORCHARD_BOOTSTRAP_ADMIN_TOKEN` which will automatically
+create a service account named `bootstrap-admin` with all privileges. Let's first generate `ORCHARD_BOOTSTRAP_ADMIN_TOKEN`:
+
+```bash
+export ORCHARD_BOOTSTRAP_ADMIN_TOKEN=$(openssl rand -hex 32)
+```
+
+Now you can run Orchard Controller on a server of your choice. In the following sections you'll find several examples of
+how to run Orchard Controller in various environments. Feel free to submit PRs with more examples.
+
+### Google Cloud Compute Engine
+
+An example below will deploy a single instance of Orchard Controller in Google Cloud Compute Engine in `us-central1` region.
+
+First, let's create a static IP address for our instance
+
+```bash
+gcloud compute addresses create orchard-ip --region=us-central1
+export ORCHARD_IP=$(gcloud compute addresses describe orchard-ip --format='value(address)' --region=us-central1)
+```
+
+Once we have the IP address, we can create a new instance with Orchard Controller running inside a container:
+
+```bash
+gcloud compute instances create-with-container orchard-controller \
+  --machine-type=e2-micro \
+  --zone=us-central1-a \
+  --image-family cos-stable \
+  --image-project cos-cloud \
+  --tags=https-server \
+  --address=$ORCHARD_IP \
+  --container-image=ghcr.io/cirruslabs/orchard:latest \
+  --container-env=PORT=443 \
+  --container-env=ORCHARD_BOOTSTRAP_ADMIN_TOKEN=$ORCHARD_BOOTSTRAP_ADMIN_TOKEN \
+  --container-mount-host-path=host-path=/home/orchard-data,mode=rw,mount-path=/data
+```
+
+Now you can create a new context for your local client:
+
+```bash
+orchard context create --name production \
+  --service-account-name bootstrap-admin \
+  --service-account-token $ORCHARD_BOOTSTRAP_ADMIN_TOKEN \
+  https://$ORCHARD_IP:443
+```
+
+And select it as the default context:
+
+```bash
+orchard context default production
+```
+
+## Configuring Orchard Workers
+
+```bash
+orchard create service-account worker-pool-m1 --roles "worker" --roles "compute:write" --roles "compute:read"
+orchard get bootstrap-token worker-pool-m1
+```
+
+## Configuring Orchard Workers
+
+If you have a set of machines that you want to use as Orchard Workers, you can use Ansible to configure them.
+Please refer a [separate repository](https://github.com/cirruslabs/ansible-orchard) where we prepared a basic
+Ansible playbook for convenient setup.
diff --git a/Development.md b/Development.md
new file mode 100644
index 0000000..2566301
--- /dev/null
+++ b/Development.md
@@ -0,0 +1,7 @@
+## Development
+
+Development is done as one would normally develop any Golang package, however, if you did modify any `*.proto` files in the `rpc/` directory, install [Buf](https://buf.build/) and run the following command from the project's root directory to re-generate the code:
+
+```shell
+buf generate
+```
diff --git a/README.md b/README.md
index 4869f48..03223ec 100644
--- a/README.md
+++ b/README.md
@@ -4,20 +4,20 @@ Orchard is an orchestration system for [Tart](https://github.com/cirruslabs/tart
 
 Create a cluster of bare-metal Apple Silicon machines and manage dozens of VMs with ease!
 
-## Installation
-
-```
-go install github.com/cirruslabs/orchard/...@latest
-```
-
 ## Quick start
 
-Start the Orchard Controller and the Worker in a single inocation:
+Start the Orchard in local development mode:
 
 ```shell
+brew install cirruslabs/cli/orchard
 orchard dev
 ```
 
+This will start Orchard Controller and a single Orchard Worker on your local machine.
+For production deployments, please refer to the [Deployment Guide](./DeploymentGuide.md).
+
+### Creating Virtual Machines
+
 Create a Virtual Machine resource:
 
 ```shell
@@ -30,10 +30,6 @@ Check a list of VM resources to see if the Virtual Machine we've created above i
 orchard list vms
 ```
 
-## Development
+### Accessing Virtual Machines
 
-Development is done as one would normally develop any Golang package, however, if you did modify any `*.proto` files in the `rpc/` directory, install [Buf](https://buf.build/) and run the following command from the project's root directory to re-generate the code:
-
-```shell
-buf generate
-```
+TBD