Skip to content

SSH Authentication — Overview

The model: the container starts with an empty ssh-agent on a fixed socket (/tmp/ansible-ssh-agent.sock). A playbook, run once, fetches the private key from wherever it's stored and pipes it into that agent. Every terminal already has SSH_AUTH_SOCK pointed at the socket, so the key becomes usable everywhere the instant it's loaded — including terminals opened before the playbook ran.

This page is a quick-reference for setting up a production / customer deployment. For the full walkthrough, deeper detail, or the dev-environment equivalent, follow the links below.

Quick setup

  1. Store the key in the customer's own secret store — AWS Secrets Manager, Azure Key Vault, or (no cloud secrets manager available) an ansible-vault-encrypted file in extra_vars/.
  2. Grant the container's identity read access to that secret — the task role / instance profile (AWS) or the managed identity (Azure).
  3. Confirm startup.sh starts the empty agent on container boot. Already wired for Coder workspaces; for a non-Coder container this is the one piece that needs adding. 
    SSH_AUTH_SOCK=/tmp/ansible-ssh-agent.sock ssh-add -l
# "The agent has no identities." => empty agent is up, ready for the playbook to populate it
# "Could not open a connection to your authentication agent." => not started, fix startup.sh
  4. Run the matching playbook once per container start (see Choosing a playbook if unsure which):
  5. ansible-playbook playbooks/load-ssh-key.yml — cloud secret store, cloud auto-detected
  6. ansible-playbook playbooks/load-ssh-key-vault.yml -e @extra_vars/ssh_key.yml — ansible-vault route
  7. Verify: 
    ssh-add -l
ansible -m ping all --limit _Red_Hat_Enterprise_Linux

Choosing where the key lives

Situation Store Playbook
AWS, with a task role / instance profile AWS Secrets Manager load-ssh-key.yml
Azure, with a managed identity Azure Key Vault load-ssh-key.yml
No cloud secrets manager (air-gapped / on-prem) Ansible Vault load-ssh-key-vault.yml

Where to go next

  • Production (Customers) — the full walkthrough: exact commands for creating the secret and granting access in each cloud, the startup.sh snippet, security notes.
  • Development Environment — how Sapphire's own Coder workspaces do this (coder_script instead of a one-time playbook), useful for comparison.
  • Secret Management — the vault password itself, and the broader vault/env-var convention used across roles.