命令结构

OpenStackClient 对所有命令都具有一致且可预测的格式。

命令的形式为

openstack [<global-options>] <object-1> <action> [<object-2>] [<command-arguments>]

注意

所有长选项名称都以两个破折号 (--) 开头，并在单词之间使用单个破折号 (-) (例如 --like-this)。下划线 (_) 不用于选项名称。

全局选项

全局选项在某种程度上是全局性的，即它们适用于每个命令调用，无论执行的操作如何。它们包括身份验证凭据和 API 版本选择。大多数全局选项都有一个相应的环境变量，也可以用来设置该值。如果两者都存在，命令行选项优先。环境变量名称是通过删除前导破折号 (--)，将每个嵌入的破折号 (-) 转换为下划线 (_)，并转换为大写派生的。

例如，--os-username 的默认值可以通过定义环境变量 OS_USERNAME 来设置。

命令对象和动作

命令由一个或多个单词描述的对象后跟一个动作组成。需要两个对象的命令将主要对象放在动作之前，将次要对象放在动作之后。标识对象的任何位置参数应按与对象相同的顺序出现。用不太规范的英语表达为“(执行) 对象1 (并执行) 动作 (使用) 对象2 (对其)”。

<object-1> <action> <object-2>

示例

$ group add user <group> <user>

$ volume type list   # 'volume type' is a two-word single object

命令参数和选项

每个命令可能有自己的一组选项，与全局选项不同。它们遵循与全局选项相同的风格，并且始终出现在命令及其所需的任何位置参数之间。

对象

对象由一个或多个单词组成，以构成唯一的名称。偶尔，当多个 API 具有通用名称和通用重叠用途时，将会有选项来选择要使用的对象，或者 API 资源将被合并，如具有引用 Compute 和 Volume 配额的选项的 quota 对象。

  • access token: (Identity) 长期的基于 OAuth 的令牌

  • address scope: (Network) IPv4 或 IPv6 地址的范围

  • aggregate: (Compute) 计算主机的分组

  • availability zone: (Compute, Network, Volume) 主机或块存储或网络服务的逻辑分区

  • block storage cluster: (Volume) 卷服务的集群

  • block storage resource filter: (Volume) 卷服务资源的过滤器

  • catalog: (Identity) 服务目录

  • command: (Internal) OSC 进程中安装的命令

  • compute agent: (Compute) 可用于 Hypervisor 的云计算代理

  • compute service: (Compute) 在主机上运行的云计算进程

  • configuration: (Internal) OpenStack 客户端配置

  • consistency group: (Volume) 卷的一致性组

  • consistency group snapshot: (Volume) 一致性组的某个时间点的副本

  • console log: (Compute) 服务器控制台文本转储

  • console url: (Compute) 服务器远程控制台 URL

  • consumer: (Identity) 基于 OAuth 的委托人

  • container: (Object Storage) 对象的分组

  • credential: (Identity) 特定于身份提供商

  • domain: (Identity) 项目的分组

  • ec2 credentials: (Identity) 兼容 AWS EC2 的凭据

  • endpoint: (Identity) 用于联系特定服务的基本 URL

  • endpoint group: (Identity) 用作过滤器的端点组

  • extension: (Compute, Identity, Network, Volume) OpenStack 服务器 API 扩展

  • federation protocol: (Identity) 在联合身份时使用的底层协议

  • flavor: (Compute) 预定义的服务器配置：ram、root 磁盘等

  • fixed ip: (Compute) 分配给服务器的内部 IP 地址

  • floating ip: (Network) 可以映射到服务器的公共 IP 地址

  • floating ip pool: (Network) 公共 IP 地址池

  • group: (Identity) 用户的分组

  • host: (Compute) 运行计算服务的物理计算机

  • hypervisor: (Compute) 虚拟机管理器

  • hypervisor stats: (Compute) 所有计算节点上的 Hypervisor 统计信息

  • identity provider: (Identity) 用户和身份验证的来源

  • image: (Image) 磁盘镜像

  • image member: (Image) 是 Image 成员的项目

  • ip availability: (Network) 网络 IP 使用情况的详细信息

  • keypair: (Compute) SSH 公钥

  • limits: (Compute, Volume) 资源使用限制

  • mapping: (Identity) 将身份提供商属性转换为 Identity 概念的定义

  • module: (Internal) OSC 进程中安装的 Python 模块

  • network: (Compute, Network) 连接服务器和其他资源的虚拟网络

  • network agent: (Network) 用于实现虚拟网络的代理

  • network auto allocated topology: (Network) 项目的自动分配拓扑

  • network flavor: (Network) 允许用户通过一组通告的服务功能（例如 LOADBALANCER、FWAAS、L3、VPN 等）选择服务类型，而不是通过提供商类型或命名供应商

  • network flavor profile: (Network) 预定义的 Neutron 服务配置：驱动程序

  • network meter: (Network) 允许网络流量计量

  • network meter rule: (Network) 网络流量计量的规则

  • network rbac: (Network) 网络资源的 RBAC 策略

  • network qos rule: (Network) 网络资源的 QoS 规则

  • network qos policy: (Network) 网络资源的 QoS 策略

  • network qos rule type: (Network) 可用的 QoS 规则类型列表

  • network segment: (Network) 虚拟网络的片段

  • network segment range: (Network) 用于租户网络段分配的段范围

  • network service provider: (Network) 提供网络服务的驱动程序

  • object: (Object Storage) 对象存储中的单个文件

  • object store account: (Object Storage) 拥有 Object Storage 资源组

  • policy: (Identity) 确定授权

  • port: (Network) 连接服务器和其他资源到网络的虚拟端口

  • project: (Identity) 拥有资源组

  • quota: (Compute, Volume) 资源使用限制

  • region: (Identity) OpenStack 部署的子集

  • request token: (Identity) 临时基于 OAuth 的令牌

  • role: (Identity) 用于确定授权的策略对象

  • role assignment: (Identity) 角色、用户或组与域或项目之间的关系

  • router: (Network) 虚拟路由器

  • security group: (Compute, Network) 网络访问规则组

  • security group rule: (Compute, Network) 定义协议/IP/端口访问的单个规则

  • server: (Compute) 虚拟机实例

  • server backup: (Compute) 使用快照方法备份服务器磁盘镜像

  • server dump: (Compute) 由 kdump 等功能创建的服务器转储文件

  • server event: (Compute) 服务器事件

  • server group: (Compute) 服务器分组

  • server image: (Compute) 保存的服务器磁盘镜像

  • service: (Identity) 云服务

  • service provider: (Identity) 消耗来自 identity provider 的断言的资源

  • subnet: (Network) 分配给网络的连续 IP 地址范围

  • subnet pool: (Network) 子网池

  • token: (Identity) 由 Identity 服务管理的 bearer 令牌

  • trust: (Identity) 用户之间的项目特定角色委托，可选的身份模拟

  • usage: (Compute) 显示正在使用的主机资源

  • user: (Identity) 个人云资源用户

  • user role: (Identity) 分配给用户的角色

  • volume: (Volume) 块卷

  • volume attachment: (Volume) 卷附加到服务器

  • 卷 备份：(卷) 卷的备份

  • 卷 后端 能力：(卷) 卷后端存储能力

  • 卷 后端 池：(卷) 卷后端存储池

  • 卷 备份 记录：(卷) 可导入或导出的卷记录

  • 卷 后端：(卷) 卷后端存储

  • 卷 组：(卷) 卷组

  • 卷 组 快照：(卷) 卷组的某个时间点的副本

  • 卷 组 类型：(卷) 可用的部署特定类型的卷组

  • 卷 宿主：(卷) 卷的物理计算机

  • 卷 消息：(卷) 卷 API 内部消息，详细说明卷故障消息

  • 卷 QoS：(卷) 卷的服务质量 (QoS) 规范

  • 卷 快照：(卷) 卷的某个时间点的副本

  • 卷 类型：(卷) 可用的部署特定类型的卷

  • 卷 服务：(卷) 用于管理块存储操作的服务

  • 卷 转移 请求：(卷) 卷所有权转移请求

插件对象

以下是 OpenStack 插件 使用的已知 对象。此处列出这些对象是为了避免在创建新插件时发生名称冲突。有关完整列表，请查看 插件命令。

  • acl：(密钥管理器 (Barbican))

  • acl 用户：(密钥管理器 (Barbican))

  • 动作 定义：(工作流引擎 (Mistral))

  • 动作 执行：(工作流引擎 (Mistral))

  • appcontainer：(应用程序容器 (Zun))

  • appcontainer 宿主：(应用程序容器 (Zun))

  • appcontainer 镜像：(应用程序容器 (Zun))

  • appcontainer 网络：(应用程序容器 (Zun))

  • appcontainer 服务：(应用程序容器 (Zun))

  • baremetal：(裸机 (Ironic))

  • claim：(消息传递 (Zaqar))

  • coe ca：(容器编排引擎 (Magnum))

  • coe 集群：(容器编排引擎 (Magnum))

  • coe 集群 模板：(容器编排引擎 (Magnum))

  • coe 配额：(容器编排引擎 (Magnum))

  • coe 服务：(容器编排引擎 (Magnum))

  • coe 统计：(容器编排引擎 (Magnum))

  • cron 触发器：(工作流引擎 (Mistral))

  • database flavor：(数据库 (Trove))

  • loadbalancer：(负载均衡器 (Octavia))

  • loadbalancer 健康监控：(负载均衡器 (Octavia))

  • loadbalancer l7policy：(负载均衡器 (Octavia))

  • loadbalancer l7rule：(负载均衡器 (Octavia))

  • loadbalancer 监听器：(负载均衡器 (Octavia))

  • loadbalancer 成员：(负载均衡器 (Octavia))

  • loadbalancer 池：(负载均衡器 (Octavia))

  • message-broker 集群：(消息代理 (Cue))

  • messaging：(消息传递 (Zaqar))

  • messaging flavor：(消息传递 (Zaqar))

  • network 子端口：(网络 (Neutron))

  • network 干道：(网络 (Neutron))

  • orchestration 资源：(编排 (Heat))

  • orchestration 模板：(编排 (Heat))

  • pool：(消息传递 (Zaqar))

  • ptr 记录：(DNS (Designate))

  • queue：(消息传递 (Zaqar))

  • recordset：(DNS (Designate))

  • secret：(密钥管理器 (Barbican))

  • secret 容器：(密钥管理器 (Barbican))

  • secret 订单：(密钥管理器 (Barbican))

  • share：(共享 (Manila))

  • share 访问：(共享 (Manila))

  • share 可用区：(共享 (Manila))

  • share 备份：(共享 (Manila))

  • share 导出 位置：(共享 (Manila))

  • share 组：(共享 (Manila))

  • share 组 快照：(共享 (Manila))

  • share 组 类型：(共享 (Manila))

  • share 实例：(共享 (Manila))

  • share 限制 显示：(共享 (Manila))

  • share 锁：(共享 (Manila))

  • share 消息：(共享 (Manila))

  • share 迁移：(共享 (Manila))

  • share 网络：(共享 (Manila))

  • share 配额：(共享 (Manila))

  • share 副本：(共享 (Manila))

  • share 安全 服务：(共享 (Manila))

  • share 服务器：(共享 (Manila))

  • share 服务器 迁移：(共享 (Manila))

  • share 服务：(共享 (Manila))

  • share 快照：(共享 (Manila))

  • share 快照 访问：(共享 (Manila))

  • share 快照 导出 位置：(共享 (Manila))

  • share 快照 实例：(共享 (Manila))

  • share 转移：(共享 (Manila))

  • share 类型：(共享 (Manila))

  • software config：(编排 (Heat))

  • software deployment：(编排 (Heat))

  • stack event：(编排 (Heat))

  • stack hook：(编排 (Heat))

  • stack output：(编排 (Heat))

  • stack resource：(编排 (Heat))

  • stack snapshot：(编排 (Heat))

  • stack template：(编排 (Heat))

  • subscription：(消息传递 (Zaqar))

  • task execution：(工作流引擎 (Mistral))

  • tld：(DNS (Designate))

  • workbook：(工作流引擎 (Mistral))

  • workflow：(工作流引擎 (Mistral))

  • workflow execution：(工作流引擎 (Mistral))

  • zone：(DNS (Designate))

  • zone blacklist：(DNS (Designate))

  • zone export：(DNS (Designate))

  • zone import：(DNS (Designate))

  • zone transfer：(DNS (Designate))

行动

OpenStackClient 使用的操作定义如下，以便为每个操作提供一致的含义。其中许多操作具有逻辑相反的操作。如果存在相反的操作，则在括号中注明。

  • authorize - 授权令牌（用于 OAuth）

  • add (remove) - 将某个对象添加到容器对象；命令的构建顺序为 容器 添加 对象 <容器> <对象>，位置参数的出现顺序相同

  • create (delete) - 创建指定对象的新的实例

  • delete (create) - 删除指定对象的特定实例

  • expand (shrink) - 增加集群的容量

  • failover - 将卷宿主故障转移到不同的后端

  • issue (revoke) - 颁发令牌

  • list - 显示多个对象的摘要信息

  • lock (unlock) - 锁定一个或多个服务器，以便非管理员用户无法执行操作

  • migrate - 将服务器或卷迁移到不同的宿主；--live 如果可能，则执行实时服务器迁移

  • pause (unpause) - 停止一个或多个服务器并将其保留在内存中

  • query - 使用 Elasticsearch 查询字符串或 json 格式 DSL 查询资源。

  • cleanup - 灵活清理与特定项目关联的资源

  • reboot - 强制重启服务器

  • rebuild - 使用与原始创建相同的（大部分）参数重建服务器

  • remove (add) - 从对象组中删除一个对象

  • rescue (unrescue) - 以特殊救援模式重启服务器，允许访问原始磁盘

  • resize - 更改服务器的 flavor 或集群的容量

  • restore - 恢复 heat 堆栈快照或恢复处于软删除状态的服务器

  • resume (suspend) - 将一个或多个已暂停的服务器恢复到运行状态

  • revoke (issue) - 撤销令牌

  • save - 将对象下载到本地

  • set (unset) - 设置对象上的属性，以前称为元数据

  • shelve (unshelve) - 搁置一个或多个服务器

  • show - 显示特定对象的详细信息

  • shrink (expand) - 减小集群的容量

  • start (stop) - 启动一个或多个服务器

  • stop (start) - 停止一个或多个服务器

  • suspend (resume) - 停止一个或多个服务器并保存到磁盘，释放内存

  • unlock (lock) - 解锁一个或多个服务器

  • unpause (pause) - 将一个或多个暂停的服务器恢复到运行状态

  • unrescue (rescue) - 将服务器恢复到正常启动模式

  • unset (set) - 移除对象的某个属性

  • unshelve (shelve) - 恢复一个或多个服务器

实现

命令结构设计支持通过 Python 的入口点机制无缝添加插件命令模块。插件命令必须是 Cliff 的 command.Command 对象的子类。有关更多信息，请参阅 插件。

命令入口点

命令通过 setuptools 在 setup.cfg 中的入口点添加。有一个通用的公共组 openstack.cli 用于非版本化的命令，以及每个受支持的 OpenStack API 和版本组合的组。例如，为了支持 Identity API v3，有一个名为 openstack.identity.v3 的组，其中包含单个命令。命令入口点的形式是

action_object = fully.qualified.module.vXX.object:ActionObject

例如，Identity API 的 list user 命令在 setup.cfg 中被标识为

openstack.identity.v3 =
    # ...
    list_user = openstackclient.identity.v3.user:ListUser
    # ...