Connect AWS EC2 Nodes

This guide shows you how to connect AWS EC2 instances to Riptides using the AWSIID (AWS Instance Identity Document) verifier. With AWSIID, daemons authenticate automatically using the cryptographically signed instance identity document that every EC2 instance provides — no manual tokens required.

Prerequisites

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

How It Works

Every EC2 instance has access to an Instance Identity Document (IID) via the instance metadata service (IMDS). The Riptides daemon reads this document and presents it to the control plane during registration. The control plane verifies the document’s signature against AWS public certificates and checks that the instance metadata (account ID, region, etc.) matches the Verifier’s requiredMetadata constraints.

Step 1: Create an AWSIID Verifier

Create a Verifier that accepts daemons presenting a valid AWS Instance Identity Document. Use requiredMetadata to restrict which AWS accounts are allowed to register:

verifier-awsiid.yaml

apiVersion: auth.riptides.io/v1alpha1
kind: Verifier
metadata:
  name: awsiid
  namespace: riptides-system
spec:
  AWSIID: {}
  requiredMetadata:
    - awsiid:account:id: "123456789012"

Apply it:

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

Confirm the Verifier is available:

riptides-cli ctl get verifiers

Expected output:

NAME      STATE
awsiid    Available

Security note: Always set requiredMetadata with your AWS account ID to prevent instances from unauthorized accounts from registering daemons. You can add multiple entries to allow several accounts.

Filtering by Multiple Accounts

To allow instances from more than one AWS account:

spec:
  AWSIID: {}
  requiredMetadata:
    - awsiid:account:id: "123456789012"
    - awsiid:account:id: "987654321098"

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-aws.yaml

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

Apply it:

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

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

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

Kubernetes

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 AWSIID and enable the ec2 metadata collector so the daemon can read the Instance Identity Document from IMDS. Use the following values.yaml in place of the one shown in the getting-started guide:

daemon-values-aws.yaml

config:
  daemon:
    metadataCollectors:
      procfs:
        enabled: true
      linuxos:
        enabled: true
      ec2:
        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: AWSIID
    dataDir: /data/riptides

Note: The ec2 metadata collector must be enabled — the daemon reads the Instance Identity Document from http://169.254.169.254/latest/dynamic/instance-identity/document to authenticate with the control plane. The trustDomain must match the value configured on the control plane.

Then install with:

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

Verify the Daemon Connected

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

riptides-cli ctl get daemons

You should see entries like:

NAME                                   WORKLOAD-ID
a1b2c3d4-e5f6-7890-abcd-ef0123456789  riptides/daemon/123456789012/us-east-1/i-0123456789abcdef0

Virtual Machines / Bare Metal

One-line install (recommended)

Run the installer on each EC2 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 AWSIID automatically, writes the config, and starts the daemon — no token required.

To force AWSIID 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 \
  --awsiid

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
a1b2c3d4-e5f6-7890-abcd-ef0123456789  riptides/daemon/123456789012/us-east-1/i-0123456789abcdef0          Connected

How Authentication Happens

When the daemon starts on an EC2 instance, it:

1. Retrieves the Instance Identity Document from the EC2 metadata service (http://169.254.169.254/latest/dynamic/instance-identity/document)
2. Sends the signed document to the Riptides control plane
3. The control plane verifies the document signature against AWS public certificates
4. The control plane checks that the instance’s account ID matches the Verifier’s requiredMetadata
5. On success, the daemon is registered and receives a workload ID in the format riptides/daemon/<account-id>/<region>/<instance-id> (for example, riptides/daemon/123456789012/us-east-1/i-0123456789abcdef0)

No tokens, no secrets to distribute — the EC2 instance’s own identity is the credential.

Step 3: Assign Workload Identities

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

workload-identity-aws.yaml

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

Apply it:

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

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

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 security group rules between EC2 and the control plane endpoint
Daemon shows authentication error	Account ID mismatch	Check that the Verifier’s requiredMetadata includes the correct AWS account ID
Daemon shows authentication error	IMDS not accessible	Ensure IMDSv1 or IMDSv2 is enabled on the instance and the hop limit allows container access
DaemonGroup shows no daemons	Selector mismatch	Verify the linuxos:name selector matches the OS running on your instances (e.g., amazon for Amazon Linux)
VM daemon fails after config change	Stale process	Run sudo systemctl restart riptides-daemon and check journalctl -u riptides-daemon

Next Steps

• Connect GCP Instances — connect Google Cloud VMs using the GCPIIT verifier
• WorkloadIdentity Reference — full selector and TLS mode documentation
• Verifier Reference — all verifier types and metadata filtering options