# Configure GCP Vertex AI provider

Configure an Omnia Provider that calls Google Vertex AI and attach it to an AgentRuntime, authenticating with Workload Identity (no key to store) or a service account key.

Vertex AI hosts the `gemini` and `claude` wire protocols (Claude through the Anthropic publisher). The examples use `gemini`; set `spec.type: claude` to run Anthropic models. `openai` on Vertex is rejected at admission.

## Prerequisites

- A GKE cluster with Workload Identity enabled (Workload Identity option only)
- The Vertex AI API enabled in your project: `gcloud services enable aiplatform.googleapis.com --project=my-gcp-project`
- `gcloud` and `kubectl` authenticated
- Omnia installed, and a namespace for your agents (the examples use `agents`)

Replace `my-gcp-project`, the region and the model name in the examples with your own. The model name is illustrative; use one that is enabled in your project and region.

## Option 1: Workload Identity (recommended)

The agent pod calls Vertex with the identity of the Kubernetes ServiceAccount it runs as. Omnia reads no key or email from the Provider for this.

1. Create the GCP service account and grant it the Vertex AI user role.

   ```bash
   gcloud iam service-accounts create omnia-vertex --project=my-gcp-project

   gcloud projects add-iam-policy-binding my-gcp-project \
     --member="serviceAccount:omnia-vertex@my-gcp-project.iam.gserviceaccount.com" \
     --role="roles/aiplatform.user"
   ```

2. Create a Kubernetes ServiceAccount for the agent and annotate it with the GCP service account.

   ```bash
   kubectl create serviceaccount vertex-agent -n agents

   kubectl annotate serviceaccount vertex-agent -n agents \
     iam.gke.io/gcp-service-account=omnia-vertex@my-gcp-project.iam.gserviceaccount.com
   ```

3. Let that ServiceAccount act as the GCP service account.

   ```bash
   gcloud iam service-accounts add-iam-policy-binding \
     omnia-vertex@my-gcp-project.iam.gserviceaccount.com \
     --role="roles/iam.workloadIdentityUser" \
     --member="serviceAccount:my-gcp-project.svc.id.goog[agents/vertex-agent]"
   ```

4. Create the Provider.

   ```yaml
   apiVersion: omnia.altairalabs.ai/v1alpha1
   kind: Provider
   metadata:
     name: vertex-gemini
     namespace: agents
   spec:
     type: gemini
     model: gemini-1.5-pro   # illustrative
     platform:
       type: vertex
       region: us-central1
       project: my-gcp-project
     auth:
       type: workloadIdentity
   ```

5. Run the agent as the annotated ServiceAccount: set `spec.podOverrides.serviceAccountName: vertex-agent` on the AgentRuntime (see [Attach the Provider to an agent](#attach-the-provider-to-an-agent)). To give every agent in a workspace the same identity, set `spec.runtime.serviceAccountName` on the Workspace instead. An AgentRuntime that sets its own ServiceAccount ignores the workspace default.

   Without either setting, the pod runs as the operator-created `<agentruntime-name>-facade` ServiceAccount, which has no GCP identity.

## Option 2: service account key

Use a key where Workload Identity is not available. The key is stored in a Secret in the Provider's namespace.

1. Create a key for the GCP service account (created and granted the role as in step 1 of Option 1).

   ```bash
   gcloud iam service-accounts keys create key.json \
     --iam-account=omnia-vertex@my-gcp-project.iam.gserviceaccount.com
   ```

2. Store it in a Secret. The default key name is `credentials.json`; set `credentialsSecretRef.key` to use another.

   ```bash
   kubectl create secret generic gcp-credentials \
     --namespace agents \
     --from-file=credentials.json=key.json
   ```

3. Create the Provider.

   ```yaml
   apiVersion: omnia.altairalabs.ai/v1alpha1
   kind: Provider
   metadata:
     name: vertex-gemini
     namespace: agents
   spec:
     type: gemini
     model: gemini-1.5-pro   # illustrative
     platform:
       type: vertex
       region: us-central1
       project: my-gcp-project
     auth:
       type: serviceAccount
       credentialsSecretRef:
         name: gcp-credentials
   ```

## Attach the Provider to an agent

Reference the Provider by name from an AgentRuntime in the same namespace. Omit `podOverrides` for the key option.

```yaml
apiVersion: omnia.altairalabs.ai/v1alpha1
kind: AgentRuntime
metadata:
  name: my-agent
  namespace: agents
spec:
  promptPackRef:
    name: my-prompts
  providers:
    - name: default
      providerRef:
        name: vertex-gemini
  podOverrides:
    serviceAccountName: vertex-agent   # Workload Identity only
  facades:
    - type: websocket
```

## Verify

```bash
kubectl get provider vertex-gemini -n agents -o jsonpath='{.status.conditions}'
```

`AuthConfigured` and `Ready` are `True`. `AuthConfigured` checks the Provider spec and, for a key, that the Secret and key exist. It does not call GCP, so it stays `True` when an IAM binding is missing.

To confirm the identity works, send the agent a message and read the runtime container logs:

```bash
kubectl logs deployment/my-agent -n agents -c runtime
```

## Troubleshooting

### `AuthConfigured` is `False`

With `auth.type: serviceAccount`, the reason `CredentialsSecretNotFound` means the Secret or the named key is missing from the Provider's namespace. `CredentialsSecretRefRequired` means `credentialsSecretRef` is unset.

### The first request fails with a permission or authentication error

Check the runtime container logs, then:

- The annotation on the ServiceAccount the pod runs as is `iam.gke.io/gcp-service-account`. Confirm the pod's `spec.serviceAccountName` is the annotated one.
- The `workloadIdentityUser` binding lists `PROJECT.svc.id.goog[NAMESPACE/SERVICEACCOUNT]` with the same namespace and ServiceAccount name as the pod. A new binding can take a few minutes to take effect.

  ```bash
  gcloud iam service-accounts get-iam-policy \
    omnia-vertex@my-gcp-project.iam.gserviceaccount.com
  ```

- The GCP service account holds `roles/aiplatform.user` on `spec.platform.project`.

### The Vertex AI API is not enabled

```bash
gcloud services list --enabled --project=my-gcp-project \
  --filter="config.name:aiplatform.googleapis.com"
```

If it is missing, run `gcloud services enable aiplatform.googleapis.com --project=my-gcp-project`.

### The project is wrong

Admission requires `spec.platform.project` to be non-empty. The value goes into the Vertex request URL, so it must be the project where the API is enabled.

## Related pages

- [Provider reference](/reference/core/provider/) for every `platform` and `auth` field and the full list of conditions
- [Configure pod overrides](/how-to/operations/configure-pod-overrides/)
- [Configure AWS Bedrock Provider](/how-to/providers/configure-bedrock-provider/)
- [Configure Azure AI Provider](/how-to/providers/configure-azure-ai-provider/)