Teleport AWS Terraform 部署指南从单机 Starter 集群到 HA 自动扩缩容生产集群【免费下载链接】teleportThe easiest, and most secure way to access and protect all of your infrastructure.项目地址: https://gitcode.com/gh_mirrors/tel/teleport本文以 Teleport 开源仓库 examples/aws/terraform 中的官方 Terraform 定义为核心系统讲解如何用 Terraform 在 AWS 上部署两种 Teleport 集群一台 t3.nano/t4g.micro 即可跑通的全功能单机集群auth、proxy、node 三进程合一以及面向生产的 HA 高可用自动扩缩容集群。读完本文你将掌握 Teleport 预构建 AMI 的环境变量配置机制、make plan/apply/destroy的完整落地流程、全部TF_VAR_*参数的语义与默认值以及 HA 方案中 DynamoDB、S3、SSM、Route 53 等 AWS 服务在 Teleport 架构中的真实分工。目录速览两种官方部署模式该目录下包含两份相互独立的 Terraform 工程对应两种截然不同的部署诉求工程定位拓扑适用场景starter-cluster快速起步单台 EC2 承载 auth node proxyDemo、POC、学习ha-autoscale-cluster生产级参考多 ASG 分组承载 auth / proxy / node生产环境、高可用README 的立场非常明确如果要参考 Terraform 示例做生产部署应以 HA 自动扩缩容集群为准其背后还有完整的《生产部署指南》讲解 Teleport 在生产环境中的运行细节。Starter 集群则被反复强调不要用于生产仅作为演示与定制起点。前置条件使用前建议先熟悉两类知识Teleport 的整体架构auth 服务、proxy 服务、node 节点的分工与通信以及管理员日常操作指南。部署所需的本地工具链仅有两个Terraform v1.0注意starter-cluster 的data.tf中声明了required_version 1.0, 2.0.0HA 工程也有对应的versions.tf约束AWS CLI v1.14Starter 集群一台 EC2 跑通全功能 TeleportStarter 工程的核心思路是Teleport 官方 AMI 预置了完整运行环境你只需要通过环境变量告诉它集群拓扑与外部依赖实例启动后即可自举为完整集群。工作原理环境变量驱动的自举实例的引导依赖两件事data.tpl生成的/etc/teleport.d/conf配置文件——data.tpl 是一个 bash 模板启动时把 Terraform 变量渲染为TELEPORT_*环境变量写入配置目录一系列 systemd 单元与 bash 脚本——位于仓库 assets/aws/files/systemsystemd 单元与 assets/aws/files/bin引导脚本负责把环境变量翻译成 Teleport 的实际配置文件并拉起服务。如果你需要深度定制引导逻辑可以研究 assets/aws 下的 AMI 生成代码。从 data.tpl 可以看到单机集群的关键环境变量组合TELEPORT_ROLEauth,node,proxy # 单机三合一 TELEPORT_AUTH_SERVER_LBlocalhost TELEPORT_DOMAIN_NAME${domain_name} TELEPORT_EXTERNAL_HOSTNAME${domain_name} TELEPORT_PROXY_SERVER_LB${domain_name} TELEPORT_DYNAMO_TABLE_NAME${dynamo_table_name} TELEPORT_DYNAMO_EVENTS_TABLE_NAME${dynamo_events_table_name} TELEPORT_LOCKS_TABLE_NAME${locks_table_name} TELEPORT_S3_BUCKET${s3_bucket} USE_LETSENCRYPT${use_letsencrypt} USE_ACM${use_acm} USE_TLS_ROUTING${use_tls_routing}其中TELEPORT_ROLEauth,node,proxy是all-in-one拓扑的标志USE_ACMtrue时teleport-generate-config会自动启用 TLS routingUSE_LETSENCRYPT在启用 ACM 时会被自动关闭。该工程会创建哪些 AWS 资源必需资源单台 EC2auth node proxy 三进程合一三张 DynamoDB 表集群状态cluster state、集群事件cluster events、SSL 锁ssl lock一个 S3 桶会话录制session recording存储Route 53 A 记录安全组Security Groups与 IAM 角色可选资源Application Load BalancerALBACM 证书及 Route 53 验证记录项目布局文件说明acm.tfACM 证书创建与 DNS 验证记录cluster.tfEC2 实例模板与用户数据渲染cluster_iam.tfIAM 角色授权实例访问 ssm/s3/dynamodb 等cluster_lb.tf使用 ACM 时的应用负载均衡器cluster_sg.tf安全组与入站规则data.tf数据源VPC、子网、AMI、Route53 区、KMS 别名data.tplTeleport 配置模板dynamo.tfDynamoDB 表承载集群状态与事件outputs.tf输出用于获取集群信息route53.tfRoute53 区创建配置 SSL 需要托管区s3.tfS3 桶会话录制存储ssm.tf企业版 license 分发vars.tf输入变量定义源码细节实例如何被构建在 cluster.tf 中可以看到实例的完整定义ami data.aws_ami.base.id通过 data.tf 中的aws_ami数据源按 AMI 名称过滤most_recent trueowners [146628656107]Teleport 官方 AWS 账号 IDuser_data用templatefile渲染data.tpl把所有 Terraform 变量注入引导脚本默认使用默认 VPC 的第一个子网并分配公网 IP安全加固默认值metadata_options.http_tokens required强制 IMDSv2、root_block_device.encrypted true根卷加密。部署完成后outputs.tf 会输出instance_ip_public实例公网 IP、cluster_name、cluster_web_address形如https://cluster.example.com按是否启用 ACM 选择 Route 53 记录和key_name。变量全解析vars.tf中声明的输入变量对应 README 给出的TF_VAR_*环境变量用法变量类型默认值说明regionstring必填AWS 区域需与 AMI 发布区域匹配cluster_namestring必填集群唯一名称不含空格与特殊字符license_pathstring企业版 license 文件绝对路径复制到 SSM 后下发到 auth 节点ami_namestring必填AMI 名称内含 Teleport 版本与 OSS/Enterprise 标识route53_zonestring必填Route 53 托管区如example.comroute53_domainstring必填子域如cluster.example.com用户访问 proxy 使用add_wildcard_route53_recordbool—是否添加*.cluster.example.com通配符记录用于 Application Accessenable_mongodb_listenerboolfalse是否启用 MongoDB 监听同步修改 SG、LB 端口与 Teleport 配置enable_mysql_listenerboolfalse是否启用 MySQL 监听enable_postgres_listenerboolfalse是否启用 Postgres 监听s3_bucket_namestring必填会话录制存储桶emailstring必填Lets Encrypt 证书注册邮箱key_namestring必填区域内存在的 AWS SSH 密钥对名use_letsencryptbool—是否使用 Lets Encrypt 签发证书use_acmboolfalse是否使用 ACM 证书任何 ACM 用法都必须置 trueuse_tls_routingboolfalse是否启用 TLS routing启用后关闭所有独立监听端口allowed_ssh_ingress_cidr_blockslist(any)[0.0.0.0/0]允许访问 SSH 端口的 CIDRallowed_ingress_cidr_blockslist(any)[0.0.0.0/0]所有 Teleport 端口入站 CIDRallowed_egress_cidr_blockslist(any)[0.0.0.0/0]Teleport 出站 CIDRkms_alias_namestringalias/aws/ssmSSM 加密使用的 KMS 别名cluster_instance_typestring必填实例类型teleport_auth_typestringlocal集群默认认证类型其中teleport_auth_type的取值与版本约束需要注意Community 版支持local或githubEnterprise 版支持local、github、oidc、samlEnterprise FIPS 部署禁用了本地认证应使用github、oidc或saml。该参数在 DynamoDB 中已配置 SAML/OIDC/GitHub 连接器时可用于在 AMI 升级后保持默认认证类型不变。使用步骤先按需修改工程内 Makefile或环境文件中的变量# Region to run in - we currently have AMIs in the following regions: # ap-northeast-1, ap-northeast-2, ap-northeast-3, ap-south-1, ap-southeast-1, ap-southeast-2, ca-central-1, eu-central-1 # eu-north-1, eu-west-1, eu-west-2, eu-west-3, sa-east-1, us-east-1, us-east-2, us-west-1, us-west-2 TF_VAR_region ? us-west-2 # Cluster name is a unique cluster name to use, should be unique and not contain spaces or other special characters TF_VAR_cluster_name ? TeleportCluster1 # AWS SSH key pair name to provision in installed instances, must be a key pair available in the above defined region TF_VAR_key_name ? example # Full absolute path to the license file, on the machine executing Terraform, for Teleport Enterprise. TF_VAR_license_path ? /path/to/license # AMI name contains the version of Teleport to install, and whether to use OSS or Enterprise version # To list available AMIs: # OSS: aws ec2 describe-images --owners 146628656107 --filters Namename,Valuesteleport-oss-* # Enterprise: aws ec2 describe-images --owners 146628656107 --filters Namename,Valuesteleport-ent-* # FIPS images are also available for Enterprise customers, look for -fips on the end of the AMIs name TF_VAR_ami_name ? teleport-ent-18.10.0-arm64 # Route 53 hosted zone to use, must be a root zone registered in AWS, e.g. example.com TF_VAR_route53_zone ? example.com # Subdomain to set up in the zone above, e.g. cluster.example.com TF_VAR_route53_domain ? cluster.example.com # Set to true to add a wildcard subdomain entry to point to the proxy, e.g. *.cluster.example.com export TF_VAR_add_wildcard_route53_recordtrue # Enable adding MongoDB/MySQL/Postgres listeners in Teleport proxy, load balancer ports, and security groups # These will be ignored if TF_VAR_use_tls_routingtrue export TF_VAR_enable_mongodb_listenerfalse export TF_VAR_enable_mysql_listenerfalse export TF_VAR_enable_postgres_listenerfalse # Bucket name to store Teleport session recordings. export TF_VAR_s3_bucket_nameteleport.example.com # AWS instance type to provision for running this Teleport cluster export TF_VAR_cluster_instance_typet4g.micro # Email to be used for Lets Encrypt certificate registration process. export TF_VAR_emailsupportexample.com # Set to true to use Lets Encrypt to provision certificates export TF_VAR_use_letsencrypttrue # Set to true to use ACM (Amazon Certificate Manager) to provision certificates # If you wish to use a pre-existing ACM certificate, you can import it: # terraform import aws_acm_certificate.cert certificate_arn # Note that TLS routing is automatically enabled when using ACM with the starter-cluster Terraform, meaning: # - you must use Teleport and tsh v13 # - you must use tsh proxy commands for Kubernetes/database access export TF_VAR_use_acmfalse # Set to true to use TLS routing to multiplex all Teleport traffic over one port # Setting this will disable ALL separate listener ports. # This setting is automatically set to true when using ACM with the starter-cluster Terraform # and will be ignored. export TF_VAR_use_tls_routingtrue # This value can be used to change the default authentication type used for the Teleport cluster. # The default is local. # Teleport Community Edition supports local or github # Teleport Enterprise Edition supports local, github, oidc, or saml # Teleport Enterprise FIPS deployments have local authentication disabled, so should use github, oidc, or saml export TF_VAR_teleport_auth_typelocal # plan make plan然后执行三步操作make plan并核对计划是否符合预期make apply开始创建资源make destroy删除已创建的全部资源。实例就绪后的初始化流程ssh ec2-usercluster_domain登录新实例创建用户同时创建 Teleport 用户并授权以本地 ec2-user 登录OSSsudo tctl users add username --rolesaccess,editor --loginsec2-userEnterprisetctl users add --rolesaccess,editor username --loginsec2-user打开输出中的注册链接设置密码并配置 2FA token至此一个功能完整的 Teleport 集群即配置完成。HA Auto-Scaling 集群生产级高可用参考HA 工程是 Teleport 官方开发者推荐的生产部署模式参考将 auth、proxy、node 拆分为独立 Auto Scaling Group并对各类 AWS 服务进行了生产级组合。关键设计决策README 中明确指出了该方案的几个关键机制证书默认使用 Lets Encrypt 证书并走 DNS-01 挑战因此必须通过 Route 53 控制 DNS 区ACM 可作为替代但 Route 53 集成仍然必需Join Token 分发通过 SSM Parameter Store 分发 Teleport join token证书分发通过加密的 S3 桶分发证书单 auth 轮换保护利用 DynamoDB 锁保证同一时刻只有一个 auth 节点轮换 join token该技巧可替换不影响性能安全基线auth 与 proxy 不以 root 运行且只对其他组件暴露绝对最小端口集。组件与文件文件职责auth_asg.tf / auth_iam.tf / auth_network.tfauth 节点 ASG、IAM、网络proxy_asg.tf / proxy_iam.tf / proxy_network.tfproxy 节点 ASG、IAM、网络node_asg.tf / node_iam.tf / node_network.tfnode 节点 ASG、IAM、网络bastion.tf堡垒机dynamo.tfDynamoDB 后端表与自动扩缩容策略locks.tfjoin token 轮换锁vpc.tf独立 VPC默认 CIDR172.31.0.0/16network.tf子网、路由等网络资源route53.tfRoute 53 记录s3.tf证书加密存储桶ssm.tfSSM Parameter Storejoin token、licenseprovider.tf / versions.tfProvider 与版本约束auth-user-data.tpl / proxy-user-data.tpl / node-user-data.tpl各角色的用户数据模板ansible/升级与访问辅助access.yaml、upgrade.yaml 等connect.sh连接辅助脚本以 proxy-user-data.tpl 为例proxy 角色的引导与 starter 明显不同TELEPORT_ROLEproxy需要指定TELEPORT_AUTH_SERVER_LB指向 auth 的负载均衡地址并通过TELEPORT_PROXY_SERVER_NLB_ALIAS支持 ACM 场景下为 kubectl 等客户端准备的 NLB DNS 别名额外把EC2_REGION、TELEPORT_DOMAIN_NAME、TELEPORT_S3_BUCKET追加写入/etc/default/teleport。DynamoDB状态后端与容量自动扩缩容dynamo.tf 揭示了 HA 架构的数据面设计主表集群状态hash keyHashKey range keyFullPath默认读写容量各 20启用服务端加密demo 场景未使用 CMK代码中留有tfsec:ignore说明、PITR 点时间恢复、TTLExpires属性、流NEW_IMAGE事件表hash keySessionID range keyEventIndex并带timesearchV2全局二级索引CreatedAtDateCreatedAt用于审计事件的时间检索容量自动扩缩容通过aws_appautoscaling_targetaws_appautoscaling_policy按 DynamoDB 读写容量利用率目标跟踪伸缩配套 IAM 角色授权 autoscaling 服务执行dynamodb:DescribeTable/UpdateTable与 CloudWatch 告警管理。注释特别点明DynamoDB 仅 auth 服务器需要访问其他组件全部无状态——这是 HA 集群可水平扩展的关键前提。变量与部署完整变量清单见 vars.tf除 starter 中的公共项外HA 特有的关键变量包括变量默认值说明vpc_cidr172.31.0.0/16专用 VPC CIDRteleport_uid1007主机上 teleport 用户的 UID非 root 运行auth_instance_typem7g.largeauth ASG 实例类型需与 AMI 架构一致ARM/x86proxy_instance_typem7g.largeproxy ASG 实例类型node_instance_typet4g.mediumnode ASG 实例类型bastion_instance_typet4g.medium堡垒机实例类型route53_domain_acm_nlb_alias无可选ACM 且未启用 TLS routing 时生效为 NLB 添加 DNS 别名可配合tctl auth sign --userfoo --formatkubernetes --outkubeconfig --proxyhttps://cluster-nlb.example.com:3026生成 kubeconfigHA 工程同样以make plan起步其 README 给出的完整变量脚本覆盖 region、cluster_name、ami_name示例同样为teleport-ent-18.10.0-arm64、各类实例类型、key_name、ACM/TLS routing 开关、license_path、Route 53 域名、MongoDB/MySQL/Postgres 监听开关、S3 桶名、邮箱与teleport_auth_type完整内容可直接参考 ha-autoscale-cluster/README.md。公共 Teleport AMI 说明两个工程都通过ami_name变量按名称而非硬编码 ID选择 AMIteleport 官方账号owner ID146628656107在每次发布新版本时共享公共 AMI。命名规则为teleport-{oss|ent}-{version}-{arch}企业版另有-fips后缀的 FIPS 镜像。可用如下命令枚举# OSS aws ec2 describe-images --owners 146628656107 --filters Namename,Valuesteleport-oss-* # Enterprise aws ec2 describe-images --owners 146628656107 --filters Namename,Valuesteleport-ent-*当前发布列表以 v18.10.0 为例各区域 arm64 与 x86_64 均有对应 ID完整列表见 AMIS.mdOSS如 us-west-2ami-0f4171a117a7d59b1arm64、ami-02d9e8fab1541553fx86_64Enterprise如 us-west-2ami-0d387d9ddd831728darm64、ami-0615499c69008124bx86_64Enterprise FIPS如 us-west-2ami-0d0bb23d37cbee709arm64、ami-0664aee475cc5ffb2x86_64覆盖区域包括 ap-northeast-1/2/3、ap-south-1、ap-southeast-1/2、ca-central-1、eu-central-1、eu-north-1、eu-west-1/2/3、sa-east-1、us-east-1/2、us-west-1/2共 17 个区域。请注意 AMI ID 会随版本发布更新应以 AMIS.md 或describe-images的实时结果为准。澄清这不是 Teleport Terraform Provider需要明确区分本文介绍的examples/aws/terraform是用 Terraform 在 AWS 上部署 Teleport 集群本身而 Teleport 官方的Terraform Provider是另一种工具用于在已存在的 Teleport 集群内部声明式管理用户、角色、认证连接器auth connector等资源。后者源码位于 integrations/terraform对应仓库中的integrations/terraform目录是典型的基础设施即代码Infrastructure as Code能力二者职责互补、不可混用。故障排查与支持渠道部署或使用过程中遇到问题可参考官方 GitHub Discussions 社区讨论若确认是与本目录代码相关的缺陷可通过 GitHub Issues 提交附上 Terraform 版本、AWS CLI 版本、terraform plan输出与相关资源 ID便于定位。小结Teleport 官方在 examples/aws/terraform 中给出了两条清晰的 AWS 落地路径starter-cluster 用最少资源、最快速度验证 Teleport 的全部核心能力单实例 DynamoDB S3 Route 53可选 ALB/ACM/TLS routing适合 Demo 与 POCha-autoscale-cluster 则以最小暴露端口、非 root 运行、无状态组件可扩展、加密分发与锁保护为设计原则将 auth/proxy/node 拆分为独立 ASG配合 DynamoDB 自动扩缩容、SSM 分发 join token、S3 分发证书构成可直接借鉴的生产部署蓝图。无论选择哪条路径make plan都是开始任何变更前的第一道安全阀。【免费下载链接】teleportThe easiest, and most secure way to access and protect all of your infrastructure.项目地址: https://gitcode.com/gh_mirrors/tel/teleport创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考