alexeiled/aws-ssm-agent

kube-ssm-agent

!Docker Pulls

镜像概述和主要用途

kube-ssm-agent 是一组 Dockerfile 和 Kubernetes 清单文件，用于在 Kubernetes 节点上部署 aws-ssm-agent。通过容器化方式运行 AWS SSM Agent，实现无需直接在节点安装二进制文件即可通过 AWS Systems Manager Sessions Manager 访问和管理 Kubernetes 节点。

核心功能和特性

• 容器化部署：无需在节点主机直接安装 aws-ssm-agent 二进制文件，通过容器方式运行
• 版本灵活更新：可随时部署更新版本的 SSM Agent，无需对节点主机进行修改
• 安全访问：通过 AWS SSM Sessions Manager 提供命令执行和交互式终端会话，支持审计
• 无需 SSH 基础设施：替代传统 SSH 访问方式，减少***面和维护成本

使用场景和适用范围

适用于需要安全访问 Kubernetes 节点（尤其是 Amazon EKS 集群）但不想直接安装 SSM Agent 或开放 SSH 访问的场景。特别适合需要临时节点访问权限、需审计会话记录或希望避免维护 SSH 密钥/基础设施的用户。

使用方法和配置说明

前置要求

创建新的 Kubernetes 服务账户（例如 ssm-sa），并将其关联到附加了 AmazonEC2RoleforSSM 策略的 IAM 角色。

sh
# 导出集群名称和服务账户名称
$ export CLUSTER_NAME=gaia-kube
$ export SA_NAME=ssm-sa

# 为 EKS 集群启用 IAM OIDC 提供商
$ eksctl utils associate-iam-oidc-provider --region=us-west-2 --name=$CLUSTER_NAME --approve

# 在 kube-system 命名空间创建关联 IAM 角色的 Kubernetes 服务账户
$ eksctl create iamserviceaccount --name $SA_NAME --cluster $CLUSTER_NAME --namespace kube-system \
  --attach-policy-arn arn:aws:iam::aws:policy/service-role/AmazonEC2RoleforSSM \
  --override-existing-serviceaccounts \
  --approve

[ℹ]  使用区域 us-west-2
[ℹ]  包含 1 个 iamserviceaccount（kube-system/ssm-sa）（基于包含/排除规则）
[!]  已存在于 Kubernetes 中的服务账户将被排除，使用 --override-existing-serviceaccounts 覆盖
[ℹ]  1 个任务：{ 2 个顺序子任务：{ 为服务账户 "kube-system/ssm-sa" 创建 IAM 角色，创建服务账户 "kube-system/ssm-sa" } }
[ℹ]  构建 iamserviceaccount 堆栈 "eksctl-gaia-kube-addon-iamserviceaccount-kube-system-ssm-sa"
[ℹ]  部署堆栈 "eksctl-gaia-kube-addon-iamserviceaccount-kube-system-ssm-sa"
[ℹ]  创建了服务账户 "kube-system/ssm-sa"

配置 SSM DaemonSet

配置 DaemonSet 使用上述创建的服务账户：

yaml
apiVersion: apps/v1
kind: DaemonSet
metadata:
  name: ssm-agent
  labels:
    k8s-app: ssm-agent
  namespace: kube-system
spec:
  ...
  template:
    ...
    spec:
      serviceAccountName: ssm-sa
      containers:
      - image: alexeiled/aws-ssm-agent:2.3.687
        name: ssm-agent
        ...

快速开始

克隆仓库并部署 DaemonSet：

console
# 应用 DaemonSet 配置
$ kubectl apply -f daemonset.yaml

# 使用 AWS CLI 启动会话（替换 <instance-id> 为实际节点实例 ID）
$ AWS_DEFAULT_REGION=us-west-2 aws ssm start-session --target <instance-id>

starting session with SessionId: ...

sh-4.2$ ls
sh-4.2$ pwd
/opt/amazon/ssm
sh-4.2$ bash -i
[ssm-user@ip-192-168-84-111 ssm]$

[ssm-user@ip-192-168-84-111 ssm]$ exit
sh-4.2$ exit

Exiting session with sessionId: ...

注意：不需要节点访问时应删除 DaemonSet，以防止没有 K8S API 访问权限但有 SSM 会话管理器访问权限的***用户获取节点 root 访问权限。

设计理念

此方案是直接在节点上安装 aws-ssm-agent 二进制文件或启用 SSH 访问的替代方案。通过容器化方式运行 SSM Agent，可在不修改主机的情况下使用更新版本的 SSM Agent。结合 AWS SSM Sessions Manager，能够在不维护 SSH 基础设施的前提下，运行命令并打开可审计的交互式终端会话。

故障排除

Q1. start-session 失败，错误信息如下：

console
$ aws ssm start-session --target i-04ffadbaae98a5bd0

An error occurred (TargetNotConnected) when calling the StartSession operation: i-04ffadbaae98a5bd0 is not connected.

SessionManagerPlugin is not found. Please refer to SessionManager Documentation here: http://docs.aws.amazon.com/console/systems-manager/session-manager-plugin-not-found

解决提示：需安装 SessionManagerPlugin。请参考 AWS 官方文档安装适用于您操作系统的 Session Manager 插件。