diff --git a/docs/hackathon/0-onboarding.mdx b/docs/hackathon/0-onboarding.mdx index 8ad8d2ca..ec824969 100644 --- a/docs/hackathon/0-onboarding.mdx +++ b/docs/hackathon/0-onboarding.mdx @@ -1,6 +1,6 @@ --- sidebar_position: 1 -unlisted: true +unlisted: false slug: onboarding title: Onboarding description: Step-by-step guide for setting up infrastructure, credentials, and cloud instances for the Verifiable AI Hackathon. @@ -151,13 +151,33 @@ VM instances in `verifiable-ai-hackathon` are continuously monitored. - **gcloud CLI Authentication Problems:** - - Run `gcloud auth login --no-launch-browser` if the browser auth flow fails + - If the browser auth flow fails: + + ```bash + gcloud auth login --no-launch-browser + ``` + - Check if you have multiple Google accounts in your browser and select the correct one - **Windows-specific gcloud issues** + - On Windows, when installing the gcloud CLI, gcloud installs its own basic shell as well. - We recommend using [git BASH](https://gitforwindows.org) for access to a full set of linux commands. +- **Multiple GCP Projects** + + - Set `verifiable-ai-hackathon` as default GCP project: + + ```bash + gcloud config set project verifiable-ai-hackathon + ``` + + - Set quota to use `verifiable-ai-hackathon`: + + ```bash + gcloud auth application-default set-quota-project verifiable-ai-hackathon + ``` + ## Need Help? If you're stuck, reach out to the Flare team on [Telegram](https://t.me/+StI5VEIvtIg2ODlh). Include: diff --git a/docs/hackathon/1-VM-Setup.mdx b/docs/hackathon/1-VM-Setup.mdx deleted file mode 100644 index ec98f815..00000000 --- a/docs/hackathon/1-VM-Setup.mdx +++ /dev/null @@ -1,144 +0,0 @@ ---- -sidebar_position: 2 -unlisted: true -title: Setting up a VM -description: Step-by-step guide for setting up a VM the Verifiable AI Hackathon. -keywords: [flare, ai, confidential-compute, hackathon, google-cloud, onboarding] ---- - -### Option A: Using gcloud CLI (Recommended) - -Follow these steps to set up a GCP instance using Confidential Space with Cloud Logging. - -#### Prerequisites - -1. **Install the gcloud CLI** - - Follow the [gcloud CLI installation guide](https://cloud.google.com/sdk/docs/install) steps for your OS - - Verify installation: - - ```bash - gcloud version - ``` - -2. **Authenticate your CLI** - - Use the same account used for hackathon registration - - ```bash - gcloud auth login - ``` - - Verify project access: - - ```bash - gcloud projects list # Should show verifiable-ai-hackathon - ``` - -#### Create VM Instance - -:::warning[Number of VM instances] - -Each hackathon team is limited to **one** continuously running VM. -You can briefly set up more than one instance for testing, but make sure you don't leave it running. - -::: - -Use the following command template, replacing the highlighted placeholder variables (`<>`): - -```bash -# highlight-next-line -gcloud compute instances create \ - --project=verifiable-ai-hackathon \ - --zone=us-central1-c \ - --machine-type=n2d-standard-2 \ - --network-interface=network-tier=PREMIUM,nic-type=GVNIC,stack-type=IPV4_ONLY,subnet=default \ - # highlight-next-line - --metadata=tee-image-reference=,tee-container-log-redirect=true,tee-env-=,tee-env-=\ - --maintenance-policy=MIGRATE \ - --provisioning-model=STANDARD \ - --service-account=confidential-sa@flare-network-sandbox.iam.gserviceaccount.com \ - --scopes=https://www.googleapis.com/auth/cloud-platform \ - --min-cpu-platform="AMD Milan" \ - --tags=flare-ai-core,http-server,https-server \ - --create-disk=auto-delete=yes,boot=yes,\ - # highlight-next-line - device-name=,\ - image=projects/confidential-space-images/global/images/confidential-space-debug-250100,mode=rw,size=11,type=pd-standard \ - --shielded-secure-boot \ - --shielded-vtpm \ - --shielded-integrity-monitoring \ - --labels=goog-ec-src=vm_add-gcloud \ - --reservation-affinity=any \ - --confidential-compute-type=SEV -``` - -Key parameters explained: - -- `--zone=us-central1-c`: Required zone for hackathon resources -- `--machine-type=n2d-standard-2`: Optimized for AI workloads -- `--min-cpu-platform="AMD Milan"`: Required for confidential computing - -**Required Variables:** - -- ``: Your instance name in the format `-`, e.g. `agent-gemini-team1` -- ``: Image path (e.g., `ghcr.io/flare-foundation/flare-ai-defai:main`) -- `` and ``: First environment variable name (e.g. `GEMINI_API_KEY`) and first environment variable value -- Add additional comma separated environment variables as needed - -## Post Setup Verification - -- Check the VM status in your Google Cloud Console -- Ensure all services are running correctly -- Monitor system logs through Serial Port console -- Verify container logs in Cloud Logging - -### Quick Start Steps After VM Creation - -1. Test your VM connection: - ```bash - gcloud compute ssh - ``` -2. Verify container is running: - ```bash - docker ps - ``` -3. Check application logs: - ```bash - docker logs - ``` - -### Development Workflow - -- Use `gcloud compute scp` to transfer files to/from VM -- Set up port forwarding for local development -- Use VS Code Remote SSH extension for easier development - -### Resource Monitoring - -Monitor your VM resources through: - -- Google Cloud Console Dashboard -- `top` command in VM -- Container metrics via `docker stats` - -:::tip[Accessing Container Logs] -View container logs in multiple ways: - -- Cloud Logging interface in Google Cloud Console -- Serial console output -- Docker logs in the VM -- Cloud Logging API for programmatic access - ::: - -- **VM Creation Fails** - - - Verify project permissions - - Check quota limits - - Ensure correct service account access - -- **Container Startup Problems** - - Review metadata configuration - - Check image URL validity - - Verify environment variables diff --git a/docs/hackathon/1-cookbook.mdx b/docs/hackathon/1-cookbook.mdx new file mode 100644 index 00000000..42165e23 --- /dev/null +++ b/docs/hackathon/1-cookbook.mdx @@ -0,0 +1,240 @@ +--- +sidebar_position: 2 +unlisted: false +title: Cookbook +description: Cookbook commands for managing Confidential VMs. +keywords: [flare, ai, confidential-compute, hackathon, google-cloud, onboarding] +--- + +Reference for commands you will encounter when interacting with Confidential VMs. + +## Restarting VMs + +During testing, you often need to restart a VM to pull updated docker images. + +Use the following two commands (ensure you have the `gcloud` CLI installed and configured): + +1. **Stop the VM:** + + ```bash + gcloud compute instances stop $INSTANCE_NAME + ``` + +2. **Start the VM:** + + ```bash + gcloud compute instances start $INSTANCE_NAME + ``` + + - Replace `$INSTANCE_NAME` with the actual name of your VM instance. + +## Reading logs + +When you need to read logs for a single Google Compute Engine (GCE) VM instance using the `gcloud` CLI, you'll primarily interact with Cloud Logging. Here's how you can do it, combining filtering with the appropriate `gcloud` commands: + +```bash +gcloud logging read "resource.type=gce_instance AND resource.labels.instance_id=YOUR_INSTANCE_ID" --project=verifiable-ai-hackathon +``` + +- Replace `YOUR_INSTANCE_ID` with the actual instance ID of your VM. +- Replace `YOUR_VM_NAME` with the name of your VM. +- Replace `YOUR_ZONE` with the zone your VM is in. + +:::tip[Using GCP Console] + +You can also view logs in the Google Cloud Console by navigating to the Logging section and selecting your project. + +::: + +## Deploying AMD SEV Confidential VMs + +This command creates a Confidential Computing VM instance using AMD SEV ([Secure Encrypted Virtualization](https://www.amd.com/content/dam/amd/en/documents/epyc-business-docs/white-papers/memory-encryption-white-paper.pdf)), with a specific image, network configuration, and security settings. +The metadata section is critical for configuring the Trusted Execution Environment (TEE). +The command is broken down in the following sections. + +```bash +# highlight-next-line +gcloud compute instances create $INSTANCE_NAME \ + --project=verifiable-ai-hackathon \ + --zone=us-central1-c \ + --machine-type=n2d-standard-2 \ + --network-interface=network-tier=PREMIUM,nic-type=GVNIC,stack-type=IPV4_ONLY,subnet=default \ + # highlight-next-line + --metadata=tee-image-reference=$TEE_IMAGE_REFERENCE,\ + # highlight-next-line + tee-container-log-redirect=true,\ + # highlight-next-line + tee-env-=,tee-env-=\ + --maintenance-policy=MIGRATE \ + --provisioning-model=STANDARD \ + --service-account=confidential-sa@flare-network-sandbox.iam.gserviceaccount.com \ + --scopes=https://www.googleapis.com/auth/cloud-platform \ + --min-cpu-platform="AMD Milan" \ + --tags=flare-ai-core,http-server,https-server \ + --create-disk=auto-delete=yes,boot=yes,\ + device-name=$INSTANCE_NAME,\ + # highlight-next-line + image=projects/confidential-space-images/global/images/confidential-space-debug-250100,mode=rw,size=11,type=pd-standard \ + --shielded-secure-boot \ + --shielded-vtpm \ + --shielded-integrity-monitoring \ + --labels=goog-ec-src=vm_add-gcloud \ + --reservation-affinity=any \ + # highlight-next-line + --confidential-compute-type=SEV +``` + +### Core command & instance name + +```bash +gcloud compute instances create $INSTANCE_NAME \ +``` + +- `gcloud compute instances create`: This is the base command for creating a new Compute Engine virtual machine (VM) instance. +- `$INSTANCE_NAME`: You need to replace this with the desired name for your VM instance. + +### Project and zone + +```bash + --project=verifiable-ai-hackathon \ + --zone=us-central1-c \ +``` + +- `--project=verifiable-ai-hackathon`: Specifies the Google Cloud project where the VM will be created. +- `--zone=us-central1-c`: Defines the zone within the `us-central1` region where the instance will reside. Choosing a zone is important for latency and resource availability. + +### Machine type & network configuration + +```bash + --machine-type=n2d-standard-2 \ + --network-interface=network-tier=PREMIUM,nic-type=GVNIC,stack-type=IPV4_ONLY,subnet=default \ +``` + +- `--machine-type=n2d-standard-2`: Selects the machine type, which determines the CPU, memory, and other hardware resources allocated to the VM. `n2d-standard-2` indicates a machine with 2 vCPUs and a balanced amount of memory, using AMD processors. +- `--network-interface=network-tier=PREMIUM,nic-type=GVNIC,stack-type=IPV4_ONLY,subnet=default`: Configures the network interface: + - `network-tier=PREMIUM`: Uses Google's premium network tier for better performance. + - `nic-type=GVNIC`: Uses Google Virtual NIC for better network performance. + - `stack-type=IPV4_ONLY`: Specifies that the instance will use IPv4 only. + - `subnet=default`: Attaches the instance to the default subnet in the specified zone's VPC network. + +### Metadata (crucial for Confidential Computing) + +```bash + --metadata=tee-image-reference=$TEE_IMAGE_REFERENCE,tee-container-log-redirect=true,tee-env-=,tee-env-=\ +``` + +- This section is very important for Confidential Computing. Metadata is used to pass configuration data to the VM. + - `tee-image-reference=$TEE_IMAGE_REFERENCE`: Specifies the URL of the Trusted Execution Environment (TEE) image. This is essential for enabling confidential computing. Replace `$TEE_IMAGE_REFERENCE` with the actual image URL. + - `tee-container-log-redirect=true`: Enables redirecting container logs to both Cloud Logging and serial logging, which can be helpful for debugging. + - `tee-env-=,tee-env-=`: Sets environment variables within the TEE environment. Replace ``, ``, ``, and `` with your desired environment variable names and values. This is how you would pass secrets or other configuration data to the application running inside the TEE. + +### Other instance settings + +```bash + --maintenance-policy=MIGRATE \ + --provisioning-model=STANDARD \ + --service-account=confidential-sa@flare-network-sandbox.iam.gserviceaccount.com \ + --scopes=https://www.googleapis.com/auth/cloud-platform \ + --min-cpu-platform="AMD Milan" \ + --tags=flare-ai-core,http-server,https-server \ +``` + +- `--maintenance-policy=MIGRATE`: Specifies that the VM should be migrated to another host during maintenance events. +- `--provisioning-model=STANDARD`: Uses the standard provisioning model for the VM. +- `--service-account=confidential-sa@flare-network-sandbox.iam.gserviceaccount.com`: Attaches a service account to the VM, granting it specific permissions. +- `--scopes=https://www.googleapis.com/auth/cloud-platform`: Grants the VM full access to all Google Cloud Platform APIs. **Use with caution** and prefer more granular scopes if possible. +- `--min-cpu-platform="AMD Milan"`: Ensures that the VM runs on a host with an AMD Milan CPU, which is required for Confidential Computing with SEV. +- `--tags=flare-ai-core,http-server,https-server`: Applies network tags to the VM, which can be used for firewall rules and network routing. + +### Boot disk configuration + +```bash + --create-disk=auto-delete=yes,boot=yes,\ + device-name=$INSTANCE_NAME,\ + image=projects/confidential-space-images/global/images/confidential-space-debug-250100,mode=rw,size=11,type=pd-standard \ +``` + +- `--create-disk=...`: Configures the boot disk for the VM. + - `auto-delete=yes`: The disk will be deleted when the VM is deleted. + - `boot=yes`: This is the boot disk. + - `device-name=`: Sets the device name of the disk to the instance name. + - `image=projects/confidential-space-images/global/images/confidential-space-debug-250100`: Specifies the image to use for the boot disk. This is a confidential space image. + - `mode=rw`: The disk is mounted in read-write mode. + - `size=11`: The disk size is 11 GB. + - `type=pd-standard`: Uses a standard persistent disk. + +### Shielded VM options + +```bash + --shielded-secure-boot \ + --shielded-vtpm \ + --shielded-integrity-monitoring \ +``` + +- These options enable Shielded VM features, which enhance the security of the VM. + - `--shielded-secure-boot`: Enables secure boot. + - `--shielded-vtpm`: Enables virtual Trusted Platform Module (vTPM). + - `--shielded-integrity-monitoring`: Enables integrity monitoring. + +### Labels, reservation affinity, and confidential compute + +```bash + --labels=goog-ec-src=vm_add-gcloud \ + --reservation-affinity=any \ + --confidential-compute-type=SEV +``` + +- `--labels=goog-ec-src=vm_add-gcloud`: Adds a label to the VM for tracking purposes. +- `--reservation-affinity=any`: If you have reservations, this allows the VM to use any available reservation. +- `--confidential-compute-type=SEV`: Enables AMD SEV (Secure Encrypted Virtualization) Confidential Computing. This is the core flag that makes this instance a confidential VM. + +## Deploying Intel TDX Confidential VMs + +This command creates a Confidential Computing VM instance using Intel TDX ([Trust Domain Extensions](https://www.intel.com/content/www/us/en/developer/tools/trust-domain-extensions/documentation.html)), with a specific image, network configuration, and security settings. +The command instructions differing from [Deploying AMD SEV Confidential VMs](#deploying-amd-sev-confidential-vms) are highlighted. + +```bash +gcloud compute instances create $INSTANCE_NAME \ + --project=verifiable-ai-hackathon \ + --zone=us-central1-a \ + # highlight-next-line + --machine-type=c3-standard-4 \ + --network-interface=network-tier=PREMIUM,nic-type=GVNIC,stack-type=IPV4_ONLY,subnet=default \ + --metadata=tee-image-reference=$TEE_IMAGE_REFERENCE,\ + tee-container-log-redirect=true,\ + tee-env-=,tee-env-=\ + # highlight-next-line + --maintenance-policy=TERMINATE \ + --provisioning-model=STANDARD \ + --service-account=confidential-sa@verifiable-ai-hackathon.iam.gserviceaccount.com \ + --scopes=https://www.googleapis.com/auth/cloud-platform \ + --tags=flare-ai,http-server,https-server \ + --create-disk=auto-delete=yes,\ +boot=yes,\ +device-name=$INSTANCE_NAME,\ +# highlight-next-line +image=projects/confidential-space-images/global/images/confidential-space-debug-0-tdxpreview-c38b622,\ +mode=rw,\ +size=11,\ +# highlight-next-line +type=pd-balanced \ + --shielded-secure-boot \ + --shielded-vtpm \ + --shielded-integrity-monitoring \ + --reservation-affinity=any \ + # highlight-next-line + --confidential-compute-type=TDX +``` + +**Differences:** + +- Use the `c3-standard-*` series of machines running on Intel Sapphire Rapids +- Set the maintenance policy to `TERMINATE`, as TDX does not support migration +- Use the preview TDX images of Confidential Space, to see all Confidential Space images run: + + ```bash + gcloud compute images list --project=confidential-space-images --no-standard-images + ``` + +- Set the boot disk to `pd-balanced` as required by `c3-standard-*` series of machines +- Set the confidential compute type to `TDX` diff --git a/sidebars.ts b/sidebars.ts index ba65adfb..317d384a 100644 --- a/sidebars.ts +++ b/sidebars.ts @@ -21,7 +21,7 @@ const sidebars: SidebarsConfig = { type: "doc", id: "hackathon/onboarding", }, - items: ["hackathon/onboarding", "hackathon/VM-Setup"], + items: ["hackathon/onboarding", "hackathon/cookbook"], }, { type: "category",