Skip to content
ALTAIRA LABS
DocsBlog
OmniaOmnia

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

Section titled “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.

Section titled “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.

    Terminal window
    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.

    Terminal window
    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.

    Terminal window
    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.

    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). 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

Section titled “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).

    Terminal window
    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.

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

  3. Create the Provider.

    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

Section titled “Attach the Provider to an agent”

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

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

Section titled “Verify”
Terminal window
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:

Terminal window
kubectl logs deployment/my-agent -n agents -c runtime

Troubleshooting

Section titled “Troubleshooting”

AuthConfigured is False

Section titled “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

Section titled “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.

    Terminal window
    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

Section titled “The Vertex AI API is not enabled”
Terminal window
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

Section titled “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.

Section titled “Related pages”