yandex-cloud-cli

Yandex Cloud CLI (yc)

基础知识

命令结构

yc <service-group> <resource> <command> [<NAME|ID>] [flags] [global-flags]

全局标志

标志	用途
--profile NAME	使用命名配置文件
--cloud-id ID	覆盖云
--folder-id ID	覆盖文件夹
--folder-name NAME	按名称覆盖文件夹
--token TOKEN	覆盖 OAuth 令牌
--impersonate-service-account-id ID	以服务账号身份操作
--format text|yaml|json|json-rest	输出格式
--jq EXPR	筛选 JSON 输出（jq 语法）
--async	非阻塞（返回操作 ID）
--retry N	gRPC 重试次数（0=禁用，默认 5）
--debug	调试日志
--no-user-output	禁止面向用户的输出
-h, --help	查看任意命令的帮助

输出与脚本

编写脚本时，始终结合 jq 使用 --format json：

# Get resource ID by name
yc compute instance get my-vm --format json | jq -r .id

# List all instance external IPs
yc compute instance list --format json | jq -r '.[].network_interfaces[0].primary_v4_address.one_to_one_nat.address'

# Use --jq shortcut (no piping needed)
yc compute instance get my-vm --format json --jq .id

# Get multiple fields
yc compute instance list --format json | jq -r '.[] | [.name, .status] | @tsv'

配置与配置文件

yc init                              # Interactive setup (OAuth, cloud, folder)
yc config list                       # Current config
yc config set folder-id <ID>         # Set default folder
yc config set compute-default-zone ru-central1-d
yc config set format json            # Default output format

# Profile management
yc config profile create <NAME>
yc config profile activate <NAME>
yc config profile list
yc config profile get <NAME>
yc config profile delete <NAME>

# S3 storage config
yc config set storage-endpoint storage.yandexcloud.net

身份验证方法

1. OAuth 令牌（个人使用）：yc config set token <OAUTH-TOKEN>
2. 服务账号密钥（自动化）：yc config set service-account-key key.json
3. 实例元数据（在 YC VM 上）：yc config set instance-service-account true
4. 联合身份验证（SSO）：yc init --federation-id <ID>

yc config list           # Show current profile, cloud, folder, token
yc iam create-token      # Get IAM token for API calls

操作

可以跟踪长时间运行的操作（创建集群等）：

yc <service> <resource> create ... --async   # Returns operation ID
yc operation get <OPERATION-ID>              # Check status (poll until done=true)

不使用 --async 时，命令会阻塞，直到操作完成。

可用区

• ru-central1-a — 莫斯科，A 区
• ru-central1-b — 莫斯科，B 区
• ru-central1-d — 莫斯科，D 区

注意：ru-central1-c 已弃用。创建新资源时请使用 ru-central1-d。

服务快速参考

所有服务组

分组	别名	用途
计算与基础设施
compute	—	虚拟机、磁盘、映像、快照、实例组、文件系统、GPU 集群
vpc	—	网络、子网、安全组、地址、网关、路由表
dns	—	DNS 区域和记录
cdn	—	CDN 资源、源站组、缓存管理
load-balancer	lb	网络负载均衡器（L4）
application-load-balancer	alb	应用负载均衡器（L7）
身份与安全
iam	—	服务账号、角色、密钥、令牌
resource-manager	resource	云、文件夹
organization-manager	—	组织、联合、群组、OS Login
kms	—	对称加密密钥
lockbox	—	密钥管理
certificate-manager	cm	TLS 证书（Let's Encrypt、导入的证书）
smartwebsecurity	sws	WAF 安全配置文件（规则、智能防护、地理位置/IP 过滤）
smartcaptcha	sc	验证码管理（复选框、滑块、挑战）
quota-manager	—	查看配额并申请提高限制
容器与无服务器
managed-kubernetes	k8s	Kubernetes 集群、节点组
container	—	容器注册表、仓库、映像
serverless	sls	函数、触发器、容器、API 网关
数据库
managed-postgresql	postgres	PostgreSQL 集群
managed-mysql	—	MySQL 集群
managed-clickhouse	—	ClickHouse 集群
managed-mongodb	—	MongoDB 集群
managed-redis	—	Redis 集群
managed-kafka	—	Kafka 集群
managed-opensearch	opensearch	OpenSearch 集群
managed-greenplum	—	Greenplum 集群
ydb	—	YDB 数据库（无服务器或专用）
数据与分析
dataproc	—	DataProc（Hadoop/Spark）集群和作业
datatransfer	dt	Data Transfer 端点和传输
存储
storage	—	对象存储（兼容 S3）、存储桶
可观测性
logging	log	Cloud Logging（分组、读取、写入）
audit-trails	—	审计跟踪管理
其他
backup	—	Cloud Backup（虚拟机、策略）
iot	—	IoT Core（注册表、设备、MQTT）
marketplace	—	Marketplace 产品
loadtesting	—	负载测试

标准 CRUD 模式

大多数资源遵循以下模式：

yc <service> <resource> list [--folder-id ID]
yc <service> <resource> get <NAME|ID>
yc <service> <resource> create [<NAME>] [flags]
yc <service> <resource> update <NAME|ID> [flags]
yc <service> <resource> delete <NAME|ID>

许多资源还支持：add-labels、remove-labels、list-operations、list-access-bindings、add-access-binding、remove-access-binding、move（在文件夹之间移动）。

详细参考

请阅读与你需要的服务对应的参考文件：

• 计算（虚拟机、磁盘、镜像、快照、快照计划、实例组、文件系统、置放群组、GPU 集群）→ references/compute.md
• 网络（VPC 网络、子网、安全组、地址、网关、路由表、DNS 区域/记录）→ references/networking.md
• IAM 和资源管理器（服务帐号、角色、各类密钥、访问绑定、云、文件夹）→ references/iam.md
• 无服务器（函数、版本、触发器、容器、API 网关、运行时、扩缩容）→ references/serverless.md
• Kubernetes（集群、节点组、kubeconfig、自动扩缩容、完整设置示例）→ references/kubernetes.md
• 数据库（PostgreSQL、MySQL、ClickHouse、Redis、MongoDB、OpenSearch、Greenplum、YDB、Kafka — 集群、用户、数据库、备份、资源预设）→ references/databases.md
• 存储、密钥、证书（S3 存储桶、s3/s3api 命令、Lockbox 密钥、KMS 加密、Certificate Manager — Let's Encrypt 和导入的证书）→ references/storage-secrets-certs.md
• 容器注册表（注册表、存储库、镜像、Docker 身份验证、生命周期策略）→ references/container-registry.md
• 负载均衡器（ALB — 目标组、后端组、HTTP 路由器、虚拟主机、路由、侦听器；NLB — 网络负载均衡器、目标组、运行状况检查）→ references/load-balancers.md
• CDN（源站组、CDN 资源、缓存、SSL、压缩、标头、安全、清除/预热缓存）→ references/cdn.md
• 日志记录和审计（Cloud Logging 组/读取/写入、Audit Trails、Cloud Backup）→ references/logging-audit.md
• 数据平台（DataProc 集群/子集群/作业、Data Transfer 端点/传输）→ references/data-platform.md
• 组织、安全和配额（Organization Manager、联合身份、群组、OS Login、含规则/条件的 Smart Web Security WAF、SmartCaptcha、Quota Manager、IoT Core）→ references/organization.md

指南

• 执行变更命令前，务必确认当前配置文件和文件夹：yc config list
• 在脚本中使用 --format json | jq 提取 ID 和值
• 长时间运行的操作使用 --async，然后检查：yc operation get <OP-ID>
• 交互式使用时优先选择 --name 而非 --id；脚本中优先使用 --id，以确保可靠性
• 对于不熟悉的命令，运行 yc <service> <resource> <command> --help — 内置帮助是权威且始终最新的
• 创建依赖其他资源的资源时（虚拟机需要子网，子网需要网络），先创建依赖项
• 对生产数据库、集群和密钥使用 --deletion-protection
• 对于 S3 操作，通过 yc iam access-key create 创建静态访问密钥
• 没有规则的自定义安全组会拒绝所有流量；自动创建的默认安全组允许所有流量 — 生产环境务必创建明确配置的安全组
• 统一使用标签（--labels env=prod,team=backend）进行成本跟踪和筛选
• 对于托管数据库，务必指定 --security-group-ids 以限制访问
• 创建 K8s 集群时，指定两个服务帐号（可以相同）：--service-account-name 用于集群资源，--node-service-account-name 用于节点操作（注册表、日志）