mirror of https://github.com/coder/coder.git synced 2026-06-03 21:18:24 +00:00

Files

T

Michael Suchacz e5707a13d6 feat: support multiple agents with shared instance-identity auth (#24325 )

> This PR was authored by Mux on behalf of Mike.

## Summary

Adds support for multiple peer root workspace agents sharing the same
`auth_instance_id`, so AWS, Azure, and GCP instance-identity auth can
issue the correct session token for a selected agent instead of assuming
a
single root agent per instance.

## Problem

When a Terraform template attaches two or more `coder_agent` resources
(with `auth = "aws-instance-identity"`) to a single compute instance,
every agent shares the same cloud instance ID. The existing singular
lookup picks whichever agent was created most recently, silently
ignoring
the others.

## Solution

Introduce an optional pre-auth agent selector (`CODER_AGENT_NAME`) and
make the server-side lookup ambiguity-aware.

**Database layer:**
- `GetWorkspaceAgentsByInstanceID` (`:many`): returns all matching root
  agents for an instance ID.
- `GetWorkspaceAgentByInstanceIDAndName` (`:one`): returns the named
root
  agent for disambiguation.

**SDK and CLI:**
- `agent_name` field added to AWS, Azure, and GCP request structs
  (`omitempty` for backward compatibility).
- `CODER_AGENT_NAME` env var and `--agent-name` flag wired into the
agent
  bootstrap before instance-identity auth runs.

**Server handler (`handleAuthInstanceID`):**
- When `agent_name` is present: direct lookup by (instance ID, name).
- When absent: legacy lookup, then resource-scoped ambiguity check.
  Returns 409 with available agent names if multiple root agents match.
- Whitespace-only names are trimmed and treated as unspecified.
- Sub-agents remain excluded (`parent_id IS NULL` filter).

**Verification template:**
- `examples/templates/aws-multi-agent/` provisions one EC2 instance with
  two agents (`main` and `dev`), both using instance-identity auth with
  `CODER_AGENT_NAME` set in the cloud-init user data.

## Backward compatibility

Existing single-agent deployments work unchanged. The `agent_name` field
is optional with `omitempty`, and the unnamed path preserves today's
behavior when only one root agent matches.

2026-04-16 13:59:09 +02:00

cloud-init

feat: support multiple agents with shared instance-identity auth (#24325 )

2026-04-16 13:59:09 +02:00

main.tf

feat: support multiple agents with shared instance-identity auth (#24325 )

2026-04-16 13:59:09 +02:00

README.md

feat: support multiple agents with shared instance-identity auth (#24325 )

2026-04-16 13:59:09 +02:00

README.md

display_name, description, icon, maintainer_github, verified, tags

display_name

description

icon

maintainer_github

verified

AWS multi-agent instance identity verification

This template verifies the multi-agent instance-identity authentication flow on AWS. It provisions a single EC2 instance with two peer root workspace agents, main and dev, that both use AWS instance identity authentication.

The key behavior under test is CODER_AGENT_NAME disambiguation. Each agent starts on the same VM with the same EC2 instance identity, but sets a distinct CODER_AGENT_NAME so the Coder server can issue a separate session token for that specific agent.

Prerequisites

AWS credentials configured for Terraform, such as environment variables or an attached IAM role.
A Coder deployment that includes the multi-agent instance-auth changes from this branch.
No special Coder server configuration. AWS instance identity certificates are built in.

What this template creates

One VPC, subnet, internet gateway, route table, and route table association.
One security group that allows SSH from anywhere for test access.
One Ubuntu 24.04 EC2 instance.
Two Coder agents, main and dev, on that single EC2 instance.
Two agent startup flows that set CODER_AGENT_NAME before launching the corresponding agent init script.

How to verify

cd examples/templates/aws-multi-agent
coder templates push verify-multi-agent

coder create test-multi-agent --template verify-multi-agent

coder list

After the workspace starts, verify that both agents are connected in the Coder Dashboard for test-multi-agent. You can also connect to each agent directly:

coder ssh test-multi-agent -a main true
coder ssh test-multi-agent -a dev true

Expected behavior

Both agents authenticate independently using AWS instance identity.
Each agent receives its own session token.
The workspace shows two connected agents in the Coder Dashboard.
If CODER_AGENT_NAME is omitted, the server should return 409 Conflict because the shared instance identity is ambiguous.

Troubleshooting

If one agent gets 409 Conflict, CODER_AGENT_NAME is not being set correctly for that agent.
If both agents fail, instance identity authentication is not working. Check EC2 metadata service access from the instance.
Check cloud-init logs with journalctl -u cloud-init.
Check agent logs at /tmp/coder-agent-main.log and /tmp/coder-agent-dev.log.

Cleanup

coder delete test-multi-agent
coder templates delete verify-multi-agent