Connect GCP Instances

This guide shows you how to connect Google Cloud Platform (GCP) VM instances to Riptides using the GCPIIT (GCP Instance Identity Token) verifier. With GCPIIT, daemons authenticate automatically using the instance identity token provided by the GCP metadata server — no manual tokens required.

Choose the installation method that matches your infrastructure:

• Kubernetes — deploy the daemon as a Helm chart into an existing cluster
• Virtual Machines / Bare Metal — configure the daemon installed via .deb or .rpm packages

Prerequisites

• A running Riptides control plane (see Getting Started)
• kubectl configured to access the Riptides API
• One or more GCP Compute Engine VM instances you want to connect
• The VM instances must be able to reach the control plane endpoint over the network

How It Works

Every GCP VM instance can request a signed identity token from the GCP metadata server. The Riptides daemon retrieves this token and presents it to the control plane during registration. The control plane verifies the token signature using Google’s public OIDC certificates and checks that the instance metadata (project ID, zone, etc.) matches the Verifier’s requiredMetadata constraints.

The token includes an audience claim that the control plane validates, preventing tokens issued for other purposes from being used for daemon registration.

Step 1: Create a GCPIIT Verifier

Create a Verifier that accepts daemons presenting a valid GCP Instance Identity Token. Set the audience field to a value that the daemon will request in its token, and use requiredMetadata to restrict which GCP projects are allowed to register:

verifier-gcpiit.yaml

apiVersion: auth.riptides.io/v1alpha1
kind: Verifier
metadata:
  name: gcpiit
  namespace: riptides-system
spec:
  GCPIIT:
    audience: gcp-iit
  requiredMetadata:
    - gcpiit:project:id: "my-gcp-project-123"

Apply it:

riptides-cli ctl apply -f verifier-gcpiit.yaml

Confirm the Verifier is available:

riptides-cli ctl get verifiers

Expected output:

NAME      STATE
gcpiit    Available

Security note: Always set requiredMetadata with your GCP project ID to prevent instances from unauthorized projects from registering daemons. The audience field adds an additional layer of verification, ensuring only tokens explicitly requested for Riptides authentication are accepted.

Filtering by Multiple Projects

To allow instances from more than one GCP project:

spec:
  GCPIIT:
    audience: riptides-daemon-auth
  requiredMetadata:
    - gcpiit:project:id: "my-gcp-project-123"
    - gcpiit:project:id: "my-gcp-project-456"

Step 2: Create an DaemonGroup (Optional)

An DaemonGroup lets you organize daemons into logical groups based on OS or other metadata. This is useful for scoping WorkloadIdentity assignments to specific sets of nodes:

daemongroup-gcp.yaml

apiVersion: core.riptides.io/v1alpha1
kind: DaemonGroup
metadata:
  name: gcp-linux-nodes
  namespace: riptides-system
spec:
  workloadID: riptides/daemongroup/gcp-linux-nodes
  selectors:
    - linuxos:name: ubuntu
    - linuxos:name: fedora
    - linuxos:name: alpine

Apply it:

riptides-cli ctl apply -f daemongroup-gcp.yaml

This group will automatically include any connected daemon running Ubuntu, Fedora, or Alpine. You can later scope WorkloadIdentity resources to this group using the scope.daemonGroup.id field.

Kubernetes

Danger

Riptides does not support Container-Optimized OS (COS). COS restricts kernel module loading, which is required for the Riptides driver to function. Use a standard Linux node image (e.g. Ubuntu, Debian, or RHEL) instead.

Additional prerequisites for Kubernetes:

• Kubernetes cluster v1.26 or later
• Helm v3.12 or later

Daemon Configuration

When installing the daemon via Helm, set authPlugin.type to GCPIIT and enable the gcp metadata collector so the daemon can retrieve the instance identity token from the GCP metadata server. Use the following values.yaml in place of the one shown in the getting-started guide:

daemon-values-gcp.yaml

config:
  daemon:
    metadataCollectors:
      procfs:
        enabled: true
      linuxos:
        enabled: true
      gcp:
        enabled: true
      kubernetes:
        enabled: true
        kubeletHost: localhost
        kubeletPort: 10250
        kubeletCA: /etc/kubernetes/pki/ca.crt
        skipKubeletVerification: true
        credentials: /var/run/secrets/kubernetes.io/serviceaccount/token
    controlPlane:
      enabled: true
      url: https://<your-env-id>.console.riptides.io
      authPlugin:
        type: GCPIIT
        audience: gcp-iit  # must match the audience field in your GCPIIT Verifier
    dataDir: /data/riptides

Note: The gcp metadata collector must be enabled — the daemon requests the identity token from the GCP metadata server using the configured audience value to authenticate with the control plane. The audience value must match the audience field in your GCPIIT Verifier. If omitted, it defaults to gcp-iit.

Then install with:

helm install daemon oci://ghcr.io/riptides-packages/helm/daemon \
  --namespace riptides-system \
  --create-namespace \
  -f daemon-values-gcp.yaml

Verify the Daemon Connected

After deploying the daemon, check that your GCP nodes have registered:

riptides-cli ctl get daemons

You should see entries like:

NAME                                   WORKLOAD-ID                                                                     STATE
b1c2d3e4-f5a6-7890-bcde-f01234567890  riptides/daemon/my-gcp-project-123/us-central1-a/1234567890123456789             Connected

Virtual Machines / Bare Metal

One-line install (recommended)

Run the installer on each GCP instance:

curl -fsSL https://docs.riptides.io/install.sh | sudo bash -s -- \
  --controlplane-url https://<your-env-id>.console.riptides.io

The script detects IMDS, selects GCPIIT automatically, writes the config, and starts the daemon — no token required.

To force GCPIIT explicitly (e.g. in user-data scripts where auto-detection timing matters):

curl -fsSL https://docs.riptides.io/install.sh | sudo bash -s -- \
  --controlplane-url https://<your-env-id>.console.riptides.io \
  --gcpiit

Custom Audience

By default the daemon requests an identity token with the audience gcp-iit, which must match the audience field in your GCPIIT Verifier. If you configured your Verifier with a different audience, pass it as an argument to --gcpiit:

curl -fsSL https://docs.riptides.io/install.sh | sudo bash -s -- \
  --controlplane-url https://<your-env-id>.console.riptides.io \
  --gcpiit my-custom-audience

Verify the Daemon Connected

Confirm the daemon has registered with the control plane:

riptides-cli ctl get daemons

You should see an entry like:

NAME                                   WORKLOAD-ID                                                                     STATE
b1c2d3e4-f5a6-7890-bcde-f01234567890  riptides/daemon/my-gcp-project-123/us-central1-a/1234567890123456789             Connected

How Authentication Happens

When the daemon starts on a GCP VM, it:

1. Requests an identity token from the GCP metadata server (http://metadata.google.internal/computeMetadata/v1/instance/service-accounts/default/identity?audience=riptides-daemon-auth)
2. Sends the signed token to the Riptides control plane
3. The control plane verifies the token signature using Google’s public OIDC certificates
4. The control plane checks that the audience claim matches the Verifier’s configured audience
5. The control plane checks that the instance’s project ID matches the Verifier’s requiredMetadata
6. On success, the daemon is registered and receives a workload ID in the format riptides/daemon/<project-id>/<zone>/<instance-id> (for example, riptides/daemon/my-gcp-project-123/us-central1-a/1234567890123456789)

No tokens to distribute, no secrets to manage — the VM’s own cloud identity is the credential.

Step 3: Assign Workload Identities

Now that your GCP nodes are connected, create WorkloadIdentity resources to assign SPIFFE identities to workloads running on those VMs. Scope identities to your DaemonGroup so they only apply to your GCP fleet:

workload-identity-gcp.yaml

apiVersion: core.riptides.io/v1alpha1
kind: WorkloadIdentity
metadata:
  name: my-backend-service
  namespace: riptides-system
spec:
  workloadID: my-app/backend-service
  scope:
    daemonGroup:
      id: riptides/daemongroup/gcp-linux-nodes
  selectors:
    - process:name: backend-service
      k8s:pod:namespace: my-app
      k8s:label:app: backend-service
  connection:
    tls:
      mode: PERMISSIVE

Apply it:

riptides-cli ctl apply -f workload-identity-gcp.yaml

Any process named backend-service running on a node in the gcp-linux-nodes daemon group will receive the SPIFFE ID spiffe://example.com/my-app/backend-service.

For full details on WorkloadIdentity configuration, see the WorkloadIdentity reference.

Troubleshooting

Symptom	Possible Cause	Resolution
Daemon does not appear in riptides-cli ctl get daemons	Daemon cannot reach control plane	Verify network connectivity and firewall rules between the GCP VM and the control plane endpoint
Daemon shows authentication error	Project ID mismatch	Check that the Verifier’s requiredMetadata includes the correct GCP project ID
Daemon shows authentication error	Audience mismatch	Ensure the audience in the Verifier matches the audience the daemon requests from the metadata server
Daemon shows authentication error	Metadata server not accessible	Confirm the VM can reach http://metadata.google.internal (this is available by default on GCP VMs)
DaemonGroup shows no daemons	Selector mismatch	Verify the linuxos:name selector matches the OS running on your instances (e.g., ubuntu for Ubuntu-based images)
VM daemon fails after config change	Stale process	Run sudo systemctl restart riptides-daemon and check journalctl -u riptides-daemon

Next Steps

• Connect AWS EC2 Nodes — connect Amazon EC2 instances using the AWSIID verifier
• WorkloadIdentity Reference — full selector and TLS mode documentation
• Verifier Reference — all verifier types and metadata filtering options