diff --git a/docs.json b/docs.json index 35a035021..fb7a5ffe2 100644 --- a/docs.json +++ b/docs.json @@ -537,6 +537,7 @@ "enterprise/enterprise-vs-oss", "enterprise/sizing-guide", "enterprise/quick-start", + "enterprise/vm-install/google", { "group": "Custom Sandbox Images", "icon": "box", diff --git a/enterprise/quick-start.mdx b/enterprise/quick-start.mdx index 57d398478..8d42cc0d8 100644 --- a/enterprise/quick-start.mdx +++ b/enterprise/quick-start.mdx @@ -35,6 +35,8 @@ Before you begin, make sure you have the following ready: You will need a VM to host OpenHands Enterprise. Choose one of the options below to provision your infrastructure. +For Google Compute Engine with Vertex AI, follow the [Google Cloud Quick Start](/enterprise/vm-install/google). + The requirements below are the trial baseline, which comfortably supports about 15 concurrent sandboxes. For a larger rollout, pick your VM from the [Sizing Guide](/enterprise/sizing-guide) before provisioning. diff --git a/enterprise/vm-install/google.mdx b/enterprise/vm-install/google.mdx new file mode 100644 index 000000000..cffb119b0 --- /dev/null +++ b/enterprise/vm-install/google.mdx @@ -0,0 +1,338 @@ +--- +title: Google Cloud Quick Start +description: Install OpenHands Enterprise on Google Compute Engine with Replicated Embedded Cluster and configure Vertex AI. +icon: google +--- + +Install OpenHands Enterprise on a dedicated Google Compute Engine VM using +Replicated Embedded Cluster. The installer manages Kubernetes on the VM. + +For an existing Kubernetes cluster, see [Install with Helm](/enterprise/k8s-install/installation). +This guide covers provisioning, DNS and TLS, installation, Vertex AI configuration +and a completed conversation. Use the +[Admin Console Configuration reference](/enterprise/vm-install/admin-console-configuration) +for optional settings. + +## Prerequisites + +- An Enterprise trial or licensed installer account. +- Google Cloud CLI authenticated to a project with Compute Engine and Cloud DNS enabled. +- Permission to create a VM, persistent disk, VPC, subnet, firewall rules and static external IP. +- Regional N2 vCPU, SSD and external-IP quota for the resources below. +- A dedicated SSH key pair and the public IPv4 /32 of your workstation or VPN. +- A base domain you control, a wildcard DNS record and a publicly trusted wildcard certificate. +- Credentials for your LLM provider and a GitHub account that can create and install a GitHub App. + +## Plan the Google Cloud Resources + +| Resource | Purpose | +| --- | --- | +| Dedicated VPC and subnet | Isolate the VM's network and firewall rules | +| Regional static external IPv4 | Stable address for DNS and inbound access | +| VM-specific network tag | Target firewall rules to this installation | +| Ubuntu 24.04 LTS x86-64 VM | Run the installer and embedded cluster | +| Persistent SSD boot disk | Store cluster, database and sandbox data | +| Wildcard DNS and trusted TLS | Secure services and dynamic sandbox hostnames | + +The evaluated VM uses `n2-standard-16` (16 vCPUs, 64 GiB RAM) and a 500 GiB +`pd-ssd` boot disk. The public trial baseline is 16 vCPUs, 64 GB RAM and +200 GB storage, with disk P99 write latency no higher than 10 ms. Provisioned +storage capacity alone does not establish latency: the installer preflight +must pass. Use the [Sizing Guide](/enterprise/sizing-guide) for larger deployments. + +The example uses persistent storage rather than Local SSD. The VM has no attached +Google Cloud service account; provider credentials are configured separately +through the Admin Console. A VM's infrastructure identity and its model-inference +identity are separate decisions. + +## Provision Infrastructure + +Use a dedicated resource name and pass the target project explicitly to each +command. Inspect existing resources before creating new ones. + +```bash +export PROJECT="" +export ZONE="us-central1-a" +export REGION="us-central1" +export VM="openhands-replicated-eval" +export NETWORK="$VM" +export ADMIN_CIDR="/32" +export SSH_PUBLIC_KEY_FILE="$HOME/.ssh/openhands-google.pub" +export BASE_DOMAIN="google.openhands.example.com" + +gcloud auth login +gcloud compute regions describe "$REGION" --project="$PROJECT" +gcloud compute machine-types describe n2-standard-16 \ + --project="$PROJECT" --zone="$ZONE" +gcloud compute images describe-from-family ubuntu-2404-lts-amd64 \ + --project=ubuntu-os-cloud +gcloud compute instances list --project="$PROJECT" +``` + +Generate a dedicated SSH key without replacing an existing file: + +```bash +ssh-keygen -t ed25519 -f "$HOME/.ssh/openhands-google" -C openhands-google +``` + +### Create Networking and Ingress Rules + +```bash +gcloud compute networks create "$NETWORK" --project="$PROJECT" --subnet-mode=custom +gcloud compute networks subnets create "$NETWORK" --project="$PROJECT" \ + --region="$REGION" --network="$NETWORK" --range=10.90.0.0/24 +gcloud compute addresses create "$VM" --project="$PROJECT" \ + --region="$REGION" --network-tier=PREMIUM +export VM_IP=$(gcloud compute addresses describe "$VM" --project="$PROJECT" \ + --region="$REGION" --format='value(address)') +gcloud compute firewall-rules create "$VM-web" --project="$PROJECT" \ + --network="$NETWORK" --direction=INGRESS --allow=tcp:80,tcp:443 \ + --source-ranges=0.0.0.0/0 --target-tags="$VM" +gcloud compute firewall-rules create "$VM-admin" --project="$PROJECT" \ + --network="$NETWORK" --direction=INGRESS --allow=tcp:22,tcp:30000 \ + --source-ranges="$ADMIN_CIDR" --target-tags="$VM" +``` + +Keep SSH and the Admin Console restricted to an administrator address or approved +network. Application HTTPS must be reachable by users and configured OAuth or +webhook providers. Choose a subnet range that does not overlap your connected networks. + +### Create the VM + +Resolve and review the current Ubuntu image, then pin the chosen image name. + +```bash +export IMAGE="" +KEY_METADATA=$(mktemp) +printf 'openhands:%s\n' "$(cat "$SSH_PUBLIC_KEY_FILE")" > "$KEY_METADATA" +gcloud compute instances create "$VM" --project="$PROJECT" --zone="$ZONE" \ + --machine-type=n2-standard-16 --image="$IMAGE" --image-project=ubuntu-os-cloud \ + --boot-disk-type=pd-ssd --boot-disk-size=500GB \ + --subnet="$NETWORK" --address="$VM_IP" --tags="$VM" \ + --no-service-account --no-scopes --metadata=block-project-ssh-keys=true \ + --metadata-from-file=ssh-keys="$KEY_METADATA" +rm "$KEY_METADATA" +ssh -i "$HOME/.ssh/openhands-google" "openhands@$VM_IP" +``` + +### Verify the OS and Kernel + +```bash +cat /etc/os-release +uname -r +nproc +free -h +df -h / /var/lib +sudo -n true +``` + +Sysbox requires Linux kernel 6.3 or newer. Verify your image's actual kernel +against the [sandbox requirements](/enterprise/docker-in-sandbox) and run the +installer's host preflights before proceeding. Do not change the kernel solely +because its version differs from the tested configuration. + + +The validated installation used Ubuntu's generic kernel `6.8.0-146`. The +Google image initially booted `7.0.0-1011-gcp`, which was not tested with Sysbox; +this does not establish that it is incompatible. If you encounter a compatibility +failure, use the documented troubleshooting process and OpenHands Support to +select a supported kernel. + + +## Configure DNS and TLS + +Create a wildcard A record in your domain's managed zone: + +```bash +export DNS_PROJECT="" +export DNS_ZONE="" +gcloud dns record-sets create "*.${BASE_DOMAIN}." --project="$DNS_PROJECT" \ + --zone="$DNS_ZONE" --type=A --ttl=300 --rrdatas="$VM_IP" +``` + +Obtain a publicly trusted certificate for `*.${BASE_DOMAIN}`. Let's Encrypt wildcard +issuance uses DNS-01 validation. Follow the +[Certbot manual DNS instructions](https://eff-certbot.readthedocs.io/en/stable/using.html#manual) +or your certificate authority's procedure. Keep private keys outside source control, +copy the full chain and key securely to the VM, and record how renewal and certificate +replacement will be handled. Manual issuance does not configure automatic renewal. + +Run the shared Quick Start's DNS and outbound checks **from the VM**, and confirm +all service names and a test runtime name resolve to its static IP. Verify the +certificate chain, wildcard SAN, key match and expiration before installation. + +## Prepare Vertex AI Access + +Use a Google Cloud project with billing enabled, the Vertex AI API enabled and +access to your chosen model in the selected location. The inference project can +be different from the project hosting the VM. + +```bash +export VERTEX_PROJECT="" +export VERTEX_LOCATION="us-central1" +gcloud services enable aiplatform.googleapis.com --project="$VERTEX_PROJECT" +``` + +Have your Google Cloud administrator provide a service-account JSON key for the +inference project with permission to invoke the selected model. The +[Vertex AI User role](https://cloud.google.com/vertex-ai/docs/general/access-control) +(`roles/aiplatform.user`) provides model-use permissions; an administrator can +choose a narrower custom role under your organization's access policy. +Follow Google's [service-account key procedure](https://cloud.google.com/iam/docs/keys-create-delete) +if a new key is needed. Keep the JSON file outside source control, restrict access +and follow your organization's key rotation policy. If organization policy +prevents JSON keys, resolve the supported authentication path with OpenHands +Support before proceeding. + +The tested Replicated configuration uploads this JSON file through the Admin +Console. Signing in to `gcloud` on your workstation or attaching a service account +to the VM does not configure that field. Check +[model and location availability](https://cloud.google.com/vertex-ai/generative-ai/docs/learn/locations) +before choosing your model. The validated combination was `gemini-2.5-flash` in +`us-central1`; other models and locations require their own validation. + +## Preflight Validation + +Before opening the installer dashboard, confirm that: + +- The VM meets the CPU, memory, storage, OS and kernel requirements. +- Wildcard DNS resolves to the static external IP from the VM. +- Ports 80 and 443 are reachable by application clients, and port 30000 is reachable from your administrator network. +- The VM can reach the [distribution endpoints](/enterprise/quick-start#outbound-connectivity-checks), GitHub, `oauth2.googleapis.com` and the Vertex endpoint for your selected location. +- Your trusted certificate covers service and dynamic sandbox hostnames, and its private key matches. +- Vertex credentials and GitHub App prerequisites are ready. + +Run the shared [DNS checks](/enterprise/quick-start#dns-checks) and +[outbound connectivity checks](/enterprise/quick-start#outbound-connectivity-checks) +on the VM. An HTTP response establishes network reachability; authenticate and +run a conversation after deployment to validate inference. + +## Run the Installer + +### 1. Open the Installer Dashboard + +[Register for an Enterprise trial](https://install.r9.all-hands.dev/openhands/signup) +or log in with your licensed account. Select **View install guide**, name the +instance and choose **Outbound requests allowed** for this connected deployment. + +### 2. Download and Run the Installation Commands + +SSH into the Google VM. Select a release, then copy the instance-specific download, +extract and install commands from the dashboard. The extracted assets include +your license. Use the current dashboard commands rather than commands from a +previous installation. + +Run the interactive installer in a real terminal. Supply the trusted full-chain +certificate and matching private key already copied to the VM: + +```bash +sudo ./openhands install --license license.yaml \ + --hostname "admin.${BASE_DOMAIN}" \ + --tls-cert /path/to/fullchain.pem \ + --tls-key /path/to/privkey.pem +``` + +Set `BASE_DOMAIN` in this VM shell before running the command. Replace the file +paths with your actual certificate files. Set the Admin Console password when +prompted and require the host and storage-latency preflights to pass. + +If installation fails after preflights pass, follow +[Troubleshooting](/enterprise/troubleshooting) to generate a support bundle. + +### 3. Open the Admin Console + +Open `https://admin.:30000` from your administrator network and +log in with the password created during installation. For a single-node install, +continue past the additional-node screen. + +The tested installer printed an HTTP URL despite being invoked with TLS options. +Use the HTTPS endpoint and confirm that the browser trusts the supplied certificate. + +## Configure OpenHands + +Select **Config** in the Admin Console. The +[Admin Console Configuration reference](/enterprise/vm-install/admin-console-configuration) +describes all available fields for the installed release. + +### Domain and Certificates + +Keep **Hostname Configuration Mode** set to **Simple (default)** and enter your +base domain. Upload the trusted full-chain **TLS Certificate** and matching +**TLS Private Key** for the application. The certificate supplied to the installer +and the certificate configured for the application serve different setup steps. + +### Vertex AI Models + +In **LLM Configuration**, configure the administrator-managed provider: + +| Setting | Value | +| --- | --- | +| LLM Provider | Google | +| Google API Type | Google Cloud Platform (Vertex AI) | +| Google Cloud Project ID | Your Vertex inference project ID | +| Google Cloud Location | Your model's supported location; tested with `us-central1` | +| Google Cloud Service Account JSON file | Upload your service-account JSON file | +| Vertex AI Models | One model ID per line; tested with `gemini-2.5-flash` | + +Leave **Allow users to configure their own LLM providers (BYOK)** disabled when +users should use the administrator-managed models. Save and deploy these values +through the Admin Console. The deployment configures the bundled gateway and +makes the model available in OpenHands. + +### Database and Sandbox Configuration + +The tested configuration uses bundled PostgreSQL, the default Sysbox isolation +runtime and subdomain routing. For an external database, follow +[External PostgreSQL](/enterprise/external-postgres). Size storage for your +workload and establish backup and recovery procedures for the persistent data. + +### GitHub Authentication + +Enable GitHub Authentication and run the +[official GitHub App helper](https://github.com/OpenHands/OpenHands-Cloud/tree/main/scripts/create_github_app) +with your instance's base domain. Use the default flat DNS layout for Simple mode. +Create a dedicated GitHub App and install it on the repositories you want this +instance to access. + +Map the helper's output to **GitHub App Client ID**, **Client Secret**, **App ID**, +**App Slug** and **Webhook Secret**. Upload the generated private key in +**GitHub App Private Key**. Keep the generated secrets outside source control. +See [GitHub integration](/enterprise/integrations/github) for repository and +webhook configuration. + +Configure optional integrations after the baseline workflow passes. + +## Deploy and Verify + +Save the configuration, review application preflights and deploy the new sequence. +Wait for **Ready** on the Admin Console dashboard. + +1. Open `https://app.` and sign in with GitHub. +2. Check that the administrator-managed model appears in the model selector. The tested default profile displayed `openhands/gemini-2.5-flash`. +3. Start a small conversation that asks the agent to print its working directory and write and read a temporary marker file. Confirm terminal output and a completed response. +4. Open **Open Repository**, select an installed repository and branch, and run a read-only conversation that reads its README and reports `git status`. +5. Verify persistent database storage and record the installation versions and test results. + +Deployment readiness and an HTTP response are useful checks. The completed +conversations verify that authentication, model inference, sandbox startup, +terminal tools and repository access work together. + +## Agent-Assisted Installation + +The [Replicated installation skill](https://github.com/OpenHands/extensions/blob/e945ed649aa78500c393bccee4390e72e6add991/skills/install-openhands-replicated/SKILL.md) +provides an agent workflow for resource planning, preflights, installation and +end-to-end checks. Use this guide and the Replicated Admin Console as the +reference for release-specific requirements and configuration fields. + +## Validation Scope + + +Validated with Replicated `0.74.0`, installer `v2.19.2+k8s-1.36` and Ubuntu +24.04 with generic kernel `6.8.0-146`: host and application preflights, trusted +HTTPS, GitHub login, persistent PostgreSQL storage, administrator-managed Vertex +Gemini 2.5 Flash inference, sandbox terminal file operations, and a read-only +GitHub repository conversation. + +Backup/restore, upgrades, additional nodes and automatic certificate renewal +were not covered by these checks. +