ssmctl은 AWS SSM을 활용하여 EC2 인스턴스에 셸 접속, 파일 전송 및 포트 포워딩 기능을 제공하는 도구입니다. 기존의 복잡한 `aws ssm start-session` 명령어 대신 간편하게 사용할 수 있도록 사용자 경험을 개선했습니다. 이 도구를 사용하면 배스천 서버나 개방된 포트, SSH 키 없이도 안전하고 효율적으로 인프라에 접근할 수 있습니다.
AI 자동 생성 콘텐츠
본 콘텐츠는 GitHub AI Tools의 원문을 AI가 자동으로 요약·번역·분석한 것입니다. 원 저작권은 원저작자에게 있으며, 정확한 내용은 반드시 원문을 확인해 주세요.
원문 바로가기OpenSSF Scorecard
CI
Security
codecov
Go
Version
License
Stars
Forks
Linux
macOS
Windows
EC2 인스턴스에 셸을 연결하거나 프라이빗 데이터베이스로 포트를 포워딩하는 것은 오늘날 다음과 같이 보입니다:
# 인스턴스에 연결하기
aws ssm start-session --target i-0abc1234def5678ab
...
ssmctl을 사용하면:
# 인스턴스에 연결하기
ssmctl connect web-1
...
동일한 AWS API와 보안 모델이지만 사용자 경험이 극적으로 향상되었습니다.
# 홈브루 (macOS / Linux)
brew tap rhysmcneill/ssmctl
brew install ssmctl
...
모든 릴리스에서 Linux, macOS 및 Windows용 바이너리를 제공합니다. 세션 매니저 플러그인 설정 및 셸 자동 완성 지침은 설치 가이드를 참조하세요.
셸 자동 완성 (Shell completion) — Homebrew 사용자는 자동으로 탭 완성을 얻습니다. 바이너리 설치의 경우 다음 명령을 한 번 실행하십시오:
# Bash
echo 'source <(ssmctl completion bash)' >> ~/.bashrc
...
# 이름 태그로 인스턴스 찾기
ssmctl list --filter api
...
보안 그룹 변경 불필요, SSH 키 생성 및 순환(rotation) 불필요, 그리고 유지 관리할 Bastion 호스트도 필요 없습니다.
ssmctl forward web-1 --local 5432 --remote prod-db.cluster-xyz.eu-west-1.rds.amazonaws.com:5432
이후 다른 터미널에서, 마치 데이터베이스가 로컬에 있는 것처럼 모든 Postgres 클라이언트를 사용합니다:
psql -h localhost -p 5432 -U admin mydb
MySQL, Redis, Elasticsearch, Kafka 등 TCP 기반의 모든 서비스에 동일하게 작동합니다.
ssmctl run web-1 -- systemctl status nginx
ssmctl run web-1 -- tail -n 100 /var/log/app.log
ssmctl run web-1 -- df -h /
표준 출력(Stdout)과 표준 에러(stderr)가 터미널로 스트리밍되며, 종료 코드도 전파됩니다.
ssmctl run --filter api -- systemctl status nginx
[api-server-1] active (running) since Mon 2026-07-21
[api-server-2] active (running) since Mon 2026-07-21
일치하는 모든 온라인 인스턴스가 명령어를 병렬로 실행하며, 각 출력 줄은 해당 인스턴스 이름으로 접두사(prefix)가 붙습니다.
ssmctl cp web-1:/var/log/app.log ./app.log
SCP나 Bastion 점프 호스트(jump host)가 필요 없습니다. 약 36 KB를 초과하는 파일의 경우, S3 기반 경로를 사용하십시오:
ssmctl cp --via s3://my-bucket/staging web-1:/var/log/access.log.2 ./access.log.2
# SecureString 값을 환경 변수로 직접 파이프합니다.
export DB_PASS=$(ssmctl param get /myapp/prod/DB_PASSWORD)
...
AWS 콘솔로 컨텍스트를 전환하거나 aws ssm get-parameter --with-decryption 구문을 외울 필요가 없습니다.
| 작업 | AWS CLI |
|---|---|
| 대화형 셸 | aws ssm start-session --target i-0abc... |
| ... |
ssmctl은 동일한 API를 래핑(wrap)합니다. 이는 다른 보안 모델이 아니라, 단지 훨씬 더 나은 인터페이스일 뿐입니다.
| 명령어 | 설명 |
|---|---|
ssmctl list | 계정에서 관리되는 모든 SSM 관리 인스턴스를 검색합니다. |
| ... | |
<대상(target)>은 인스턴스 ID(i-0abc...) 또는 이름 태그(web-1)입니다. 전체 명령어 참조는 [docs/commands.md]를 참고하세요. |
ssmctl은 모든 인증을 AWS SDK for Go v2에 위임합니다. 자격 증명(Credentials)과 리전(Region)은 다음 우선순위에 따라 해결되며, 첫 번째로 일치하는 항목이 승리합니다.
| 우선순위 | 출처 | 상세 내용 |
|---|---|---|
| 1 | --profile 플래그 | ~/.aws/config 및 ~/.aws/credentials에서 이름 지정된 프로필을 로드합니다. |
| ... |
| 우선순위 | 출처 |
|---|---|
| 1 | --region 플래그 (또는 -r) |
| ... |
# 이름 지정된 프로필 사용
ssmctl --profile prod connect web-1
...
[!중요]
ssmctl은 자체적으로 자격 증명을 저장하거나 관리하지 않습니다. AWS SDK가 해결하는 내용을 읽어옵니다. 인증 오류로 인해 명령이 실패하면, 버그를 신고하기 전에aws sts get-caller-identity --profile <name>을 실행하여 자격 증명이 유효한지 확인하세요.
| Command reference | 모든 명령어, 플래그 및 예시 |
| ... |
ssmctl에 기여해주신 모든 분들께 감사드립니다!
팀은 여러분의 제출을 진심으로 소중하게 생각합니다. 여러분은 ssmctl의 미래를 만드는 데 도움을 주고 있습니다.
기여는 환영합니다. 시작하려면 [CONTRIBUTING.md]를 참고하세요.