> ## Documentation Index
> Fetch the complete documentation index at: https://docs.nebuly.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Self-hosting Nebuly on GCP

## Overview

Nebuly on GCP is deployed on a Google Kubernetes Engine (GKE) cluster provisioned
via a Terraform module, with all platform components managed through an official Helm chart.

The setup involves two layers:

* **Infrastructure** — Terraform provisions GKE, Cloud SQL (PostgreSQL), Google Cloud
  Storage, Secret Manager, and supporting IAM and networking resources.
* **Platform** — the `nebuly-platform` Helm chart deploys all Nebuly services onto the
  provisioned cluster, configured using the values produced by Terraform.

A bootstrap Helm chart (`bootstrap-gcp`) handles GKE-specific dependencies (ingress,
Workload Identity, Secret Manager integration, storage classes) and must be installed
before the platform chart.

## Terraform module

Terraform module for provisioning Nebuly Platform resources on GCP.

Available on [Terraform Registry](https://registry.terraform.io/modules/nebuly-ai/nebuly-platform/google/latest).

## Helm chart

The Nebuly Platform Helm chart is the official way to deploy and manage the Nebuly Platform
on Kubernetes. It packages all platform components and is configured using the values
produced by the Nebuly Terraform module.

Available on [GHCR](https://github.com/nebuly-ai/helm-charts).

## Prerequisites

### Nebuly Credentials

Before using this Terraform module, ensure that you have your Nebuly credentials ready.
These credentials are necessary to activate your installation and should be provided as input via the `nebuly_credentials` input.

### Required GCP APIs

Before using this Terraform module, ensure that the following GCP APIs are enabled in your Google Cloud project:

* [sqladmin.googleapis.com](https://cloud.google.com/sql/docs/mysql/admin-api)
* [servicenetworking.googleapis.com](https://cloud.google.com/service-infrastructure/docs/service-networking/getting-started)
* [cloudresourcemanager.googleapis.com](https://cloud.google.com/resource-manager/reference/rest)
* [container.googleapis.com](https://cloud.google.com/kubernetes-engine/docs/reference/rest)
* [secretmanager.googleapis.com](https://cloud.google.com/secret-manager/docs/reference/rest)

You can enable the APIs using either the GCP Console or the gcloud CLI, as explained in the [GCP Documentation](https://cloud.google.com/endpoints/docs/openapi/enable-api#gcloud).

### Required GCP Quotas

Ensure that your GCP project has the necessary quotas for the following resources over the regions you plan to deploy Nebuly:

* **Name**: GPUs (all regions)

  **Min Value**: 2
* **Name**: NVIDIA L4 GPUs

  **Min Value**: 1

For more information on how to check and increase quotas, refer to the [GCP Documentation](https://cloud.google.com/docs/quotas/view-manage).

## Quickstart

To get started with installing Nebuly on GCP, follow the steps below.
This guide uses the standard configuration provided by the official Nebuly Helm chart.

For advanced configurations or support, feel free to reach out via the Nebuly Slack channel or email us at [support@nebuly.ai](mailto:support@nebuly.ai).

Additional examples are available:

* [Basic](./examples/basic/README.md): Minimal setup with default settings.
* [Microsoft SSO](./examples/microsoft-sso/README.md): Setup with Microsoft SSO authentication.

### 1. Terraform setup

Import Nebuly into your Terraform root module, provide the necessary variables, and apply the changes.

For configuration examples, you can refer to the [Examples](#examples).

Once the Terraform changes are applied, proceed with the next steps to deploy Nebuly on the provisioned Google Kubernetes Engine (GKE) cluster.

### 2. Connect to the GKE Cluster

For connecting to the created GKE cluster, you can follow the steps below. For more information,
refer to the [GKE Documentation](https://cloud.google.com/kubernetes-engine/docs/how-to/cluster-access-for-kubectl).

* Install the [GCloud CLI](https://cloud.google.com/sdk/docs/install-sdk).

* Install [kubectl](https://kubernetes.io/docs/reference/kubectl/):

```shell theme={null}
gcloud components install kubectl
```

* Install the Install the gke-gcloud-auth-plugin:

```shell theme={null}
gcloud components install gke-gcloud-auth-plugin
```

* Fetch the command for retrieving the credentials from the module outputs:

```shell theme={null}
terraform output gke_cluster_get_credentials
```

* Run the command you got from the previous step

### 3. Create image pull secret

The auto-generated Helm values use the name defined in the k8s\_image\_pull\_secret\_name input variable for the Image Pull Secret. If you prefer a custom name, update either the Terraform variable or your Helm values accordingly.
Create a Kubernetes [Image Pull Secret](https://kubernetes.io/docs/tasks/configure-pod-container/pull-image-private-registry/) for
authenticating with your Docker registry and pulling the Nebuly Docker images.

Example:

```shell theme={null}
kubectl create secret generic nebuly-docker-pull \
  -n nebuly \    
  --from-file=.dockerconfigjson=dockerconfig.json \
  --type=kubernetes.io/dockerconfigjson
```

### 4. Bootstrap GKE cluster

Install the bootstrap Helm chart to set up all the dependencies required for installing the Nebuly Platform Helm chart on GKE.

Refer to the [chart documentation](https://github.com/nebuly-ai/helm-charts/tree/main/bootstrap-gcp) for all the configuration details.

```shell theme={null}
helm install nebuly-bootstrap oci://ghcr.io/nebuly-ai/helm-charts/bootstrap-gcp \
  --namespace nebuly-bootstrap \
  --create-namespace 
```

### 5. Create Secret Provider Class

Create a Secret Provider Class to allow GKE to fetch credentials from the provisioned Key Vault.

* Get the Secret Provider Class YAML definition from the Terraform module outputs:
  ```shell theme={null}
  terraform output secret_provider_class
  ```

* Copy the output of the command into a file named secret-provider-class.yaml.

* Run the following commands to install Nebuly in the Kubernetes namespace nebuly:

  ```shell theme={null}
  kubectl create ns nebuly
  kubectl apply --server-side -f secret-provider-class.yaml
  ```

### 6. Install nebuly-platform chart

Retrieve the auto-generated values from the Terraform outputs and save them to a file named `values.yaml`:

```shell theme={null}
terraform output helm_values
```

Install the Nebuly Platform Helm chart.
Refer to the [chart documentation](https://github.com/nebuly-ai/helm-charts/tree/main/nebuly-platform) for detailed configuration options.

```shell theme={null}
helm install <your-release-name> oci://ghcr.io/nebuly-ai/helm-charts/nebuly-platform \
  --namespace nebuly \
  -f values.yaml \
  --timeout 45m 
```

> ℹ️  During the initial installation of the chart, all required Nebuly LLMs are uploaded to your model registry.
> This process can take approximately 5 minutes. If the helm install command appears to be stuck, don't worry: it's simply waiting for the upload to finish.

### 7. Access Nebuly

Retrieve the external Load Balancer IP address to access the Nebuly Platform:

```shell theme={null}
kubectl get svc -n nebuly-bootstrap -o jsonpath='{range .items[?(@.status.loadBalancer.ingress)]}{.status.loadBalancer.ingress[0].ip}{"\n"}{end}'
```

You can then register a DNS A record pointing to the Load Balancer IP address to access Nebuly via the custom domain you provided
in the input variable `platform_domain`.

## Examples

You can find examples of code that uses this Terraform module in the [examples](https://github.com/nebuly-ai/terraform-google-nebuly-platform/tree/main/examples) directory.