Terraform用于实现基础设施即代码（infrastructure as code）—— 通过代码（配置文件）来描述基础设施的拓扑结构，并确保云上资源和此结构完全对应。Terraform有三个版本，我们主要关注Terraform CLI。

Terraform CLI主要包含以下组件：

1. 命令行前端
2. Terraform Language（以下简称TL，衍生自HashiCorp配置语言HCL）编写的、描述基础设施拓扑结构的配置文件。配置文件的组织方式是模块。本文使用术语“配置”（Configuration）来表示一整套描述基础设施的Terraform配置文件
3. 针对各种云服务商的驱动（Provider），实现云资源的创建、更新和删除

云上资源不单单包括基础的IaaS资源，还可以是DNS条目、SaaS资源。事实上，通过开发Provider，你可以用Terraform管理任何资源。

Terraform会检查配置文件，并生成执行计划。计划描述了那些资源需要被创建、修改或删除，以及这些资源之间的依赖关系。Terraform会尽可能并行的对资源进行变更。当你更新了配置文件后，Terraform会生成增量的执行计划。

直接到https://www.terraform.io/downloads.html下载，存放到$PATH下即可。

使用选项 

-chdir=DIR

使用

terraform -install-autocomplete

terraform -uninstall-autocomplete

很多子命令接受资源地址参数，下面是一些例子：

# 资源类型.资源名
aws_instance.foo
# 资源类型.资源列表名[索引]
aws_instance.bar[1]
# 子模块foo的子模块bar中的
module.foo.module.bar.aws_instance.baz

配置文件的路径可以通过环境变量

TF_CLI_CONFIG_FILE

$HOME/.terraformrc

# provider缓存目录
plugin_cache_dir   = "$HOME/.terraform.d/plugin-cache"
# 
disable_checkpoint = true

# 存放凭证信息，包括模块仓库、支持远程操作的系统的凭证
credentials "app.terraform.io" {
  token = "xxxxxx.atlasv1.zzzzzzzzzzzzz"
}

# 改变默认安装逻辑
provider_installation {
  # 为example.com提供本地文件系统镜像，这样安装example.com/*/*的provider时就不会去网络上请求
  # 默认路径是：
  # ~/.terraform.d/plugins/${host_name}/${namespace}/${type}/${version}/${target}
  # 例如：
  # ~/.terraform.d/plugins/hashicorp.com/edu/hashicups/0.3.1/linux_amd64/terraform-provider-hashicups_v0.3.1
  filesystem_mirror {
    path    = "/usr/share/terraform/providers"
    include = ["example.com/*/*"]
  }
  direct {
    exclude = ["example.com/*/*"]
  }
  
  # Terraform会在terraform init的时候，校验Provider的版本和checksum。Provider从Registry或者本地
  # 目录下载Provider。当我们开发Provider的时候，常常需要方便的测试临时Provider版本，这种Provider还
  # 没有关联版本号，也没有在Registry中注册Chencksum
  # 为了简化开发，可以配置dev_overrides，它能覆盖所有配置的安装方法
  dev_overrides {
    "hashicorp.com/edu/hashicups-pf" = "$(go env GOBIN)"
  }
}

配置工作目录，为使用其它命令做好准备。

Terraform命令需要在一个编写了Terraform配置文件的目录（配置根目录）下执行，它会在此目录下存储设置、缓存插件/模块，以及（默认使用Local后端时）存储状态数据。此目录必须进行初始化。

初始化后，会生成以下额外目录/文件：

.terraform目录，用于缓存provider和模块
如果使用Local后端，保存状态的terraform.tfstate文件。如果使用多工作区，则是terraform.tfstate.d目录。

对配置的某些变更，需要重新运行初始化，包括provider需求的变更、模块源/版本约束的变更、后端配置的变更。需要重新初始化时，其它命令可能会无法执行并提示你进行初始化。

命令

terraform get

运行

terraform init -upgrade

校验配置是否合法。

显示执行计划，即当前配置将请求（结合state）哪些变更。Terraform的核心功能时创建、修改、删除基础设施对象，使基础设施的状态和当前配置匹配。当我们说运行Terraform时，主要是指plan/apply/destroy这几个命令。

terraform plan命令评估当前配置，确定其声明的所有资源的期望状态。然后比较此期望状态和真实基础设施的当前状态。它使用state来确定哪些真实基础设施对象和声明资源的对应关系，并且使用provider的API查询每个资源的当前状态。当确定到达期望状态需要执行哪些变更后，Terraform将其打印到控制台，它并不会执行任何实际的变更操作。

terraform plan命令得到的计划可以保存起来，并被后续的terraform apply使用：

terraform plan -out=FILE 

plan命令支持两种备选的工作模式：

1. 销毁模式：创建一个计划，其目标是销毁所有当前存在于配置中的远程对象，留下一个空白的state。对应选项

   -destroy

2. 仅刷新模式：创建一个计划，其目标仅仅是更新state和根模块的输出值，以便和从Terraform之外对基础设施对象的变更匹配。对应选项

   -refresh-only

使用选项

-var 'NAME=VALUE'

使用选项

-var-file=FILENAME

选项

-parallelism=n

aws_instance.example[0]

应用执行计划，创建、更新设施对象。

apply会做plan的任何事情，并在其基础上，直接执行变更操作。默认情况下，apply即席的执行一次plan，你也可以直接使用已保存的plan

命令格式：

terraform apply [options] [plan file]

选项

-auto-approve

如果指定plan file参数，则读取先前保存的计划并执行。

支持plan命令中关于计划模式的选项。

-input=false、-parallelism=n等选项含义和plan命令相同。特有选项：

删除先前创建的基础设施对象。

当前配置（+工作区）管理的所有资源都会被删除，destroy会使用状态数据确定哪些资源需要删除。

在交互式命令中估算Terraform表达式。

格式化配置文件

强制解除当前工作区的状态锁。当其它terraform进程锁定状态后，没有正常解锁时使用。如果其它进程仍然在运作，可能导致状态不一致。

安装或升级远程Terraform模块。格式：

terraform get [options] PATH

选项：

-update 检查已经下载的模块的新版本，如果存在匹配约束的新版本则更新
-no-color 禁用彩色输出

生成操作中包含步骤的图形化表示。

导入现有的基础设施对象，让其关联到配置中的资源定义。

获取并保存远程服务（例如模块私服）的登录凭证。

删除远程服务（例如模块私服）的登录凭证。

显示根模块的输出值。格式：

terraform output [options] [NAME]

显示此模块依赖的providers

更新状态，使其和远程基础设施匹配。

显示当前状态或保存的执行计划。

将资源实例标记为“非功能完备（fully functional）”的。

所谓非功能完备，通常意味着资源创建过程出现问题，存在部分失败。此外taint子命令也可以强制将资源标记为非功能完备。

因为上述两种途径，进入tainted状态的资源，不会立即影响基础设施对象。但是在下一次的plan中，会销毁并重新创建对应基础设施对象。

命令格式：

terraform [global options] taint [options] <address>

解除资源的tainted状态。

管理和切换工作区。

配置文件由若干块（Block）组成，块的语法如下：

# Block header, which identifies a block
<BLOCK TYPE> "<BLOCK LABEL>" "<BLOCK LABEL>" "..." {
  # Block body
  <IDENTIFIER> = <EXPRESSION> # Argument
}

块是一个容器，它的作用取决于块的类型。块常常用来描述某个资源的配置。

取决于块的类型，标签的数量可以是0-N个。对于resource块，标签数量为两个。某些特殊的块，可能支持任意数量的标签。某些内嵌的块，例如network_interface，则不支持标签。

块体中可以包含若干参数（Argument），或者其它内嵌的块。参数用于将一个表达式分配到一个标识符，常常对应某个资源的一条属性。表达式可以是字面值，或者引用其它的值，正是这种引用让Terraform能够识别资源依赖关系。

直接位于配置文件最外层的块，叫做顶级块（Top-level Block），Terraform支持有限种类的顶级块。大部分Terraform特性，例如resource，基于顶级块实现。

下面是一个例子：

resource "aws_vpc" "main" {
  cidr_block = var.base_cidr_block
}

在HCL语言中，Argument被称作Attribute。但是在TL中，Attribute术语另有它用。例如各种resource都具有一个名为id的属性，它可以被参数表达式饮用，但是不能被赋值（因而不是参数）。

参数其实一个赋值表达式，它将一个值分配给一个名称。

上下文决定了哪些参数可用，其类型是什么。不同的资源（由resource标签识别）支持不同的参数集。

参数名、块类型名、大部分Terraform特有结构的名字（例如resource名，即其第二标签），都是标识符。

标识符由字母、数字、-、_组成，第一个字符不能是数字。

#

//

/**/

"hello"

6.02

true

false

["us-west-1a", "us-west-1c"]

{name = "Mabel", age = 52}

空值使用

null

转义字符：

\n

\r

\t

\"

\\

\uNNNN

\UNNNNNNNN

注意，在Heredoc中反斜杠不用于转义，可以使用：

$${

%%{

支持Unix的Heredoc风格的字符串：

block {
  value = <<EOT
hello
world
EOT
}

Heredoc还支持缩进编写：

block {
  value = <<-EOT
  hello
    world
  EOT
}

要将对象转换为JSON或YAML，可以调用函数：

example = jsonencode({
    a = 1
    b = "hello"
})

不管在普通字符串格式，还是Heredoc中，都可以使用字符串模板。模板需要包围在

${

%{}

# ${ ... } 中包含的是表达式
"Hello, ${var.name}!"


# %{ ... } 则定义了一条模板指令，可以用于实现条件分支或循环

# %{if <BOOL>}/%{else}/%{endif} 条件分支
"Hello, %{ if var.name != "" }${var.name}%{ else }unnamed%{ endif }!"

# %{for <NAME> in <COLLECTION>} / %{endfor} 循环
<<EOT
%{ for ip in aws_instance.example.*.private_ip }
server ${ip}
%{ endfor }
EOT

可以在模板指令开始或结尾添加

~

<<EOT
%{ for ip in aws_instance.example.*.private_ip ~} # 这后面的换行符被~去除
server ${ip}  # 这后面的换行符被保留
%{ endfor ~}
EOT

<RESOURCE TYPE>.<NAME>

1. 如果资源没有count/for_each参数，那么值是一个object，可以访问资源的属性
2. 如果资源使用count参数，那么值是list
3. 如果资源使用for_each参数，那么值是map

var.<NAME>

local.<NAME>

module.<MODULE NAME>

module.<MODULE NAME>.<OUTPUT NAME>

如果module块使用了for_each，则引用的值是一个map，其key是for_each中的每个key，其值是子模块输出。

如果module块使用了count，则引用的值是一个list，其元素是子模块输出。

data.<DATA TYPE>.<NAME>

path.module

path.root

path.cwd

terraform.workspace

在特定的块内部，在特定的上下文下（例如使用count/for_each的情况下），可以引用一些特殊值：

count.index

each.key

each.value

self

逻辑操作符：

!

&&

||

*

/

%

+

-

>, >=, <, <= ==, !=

函数调用：

<FUNCTION NAME>(<ARGUMENT 1>, <ARGUMENT 2>)

# 支持参数展开
min([55, 2453, 2]...)

condition ? true_val : false_val

var.a != "" ? var.a : "default-a"

使用for表达式可以通过转换一种复杂类型输出，生成另一个复杂类型结果。输入中的每个元素，可以对应结果的0-1个元素。任何表达式可以用于转换，下面是使用upper函数将列表转换为大写：

[for s in var.list : upper(s)]

作为for表达式的输入的类型可以是list / set / tuple / map / object。可以为for声明两个临时符号，前一个表示index或key：

[for k, v in var.map : length(k) + length(v)]

结果的类型取决于包围for表达式的定界符：

[] 表示生成的结果是元组
{} 表示生成的结果是object，你必须使用

=>

{for s in var.list : s => upper(s)}

包含一个可选的if子句可以对输入元素进行过滤：

[for s in var.list : upper(s) if s != ""]

示例：

variable "users" {
  type = map(object({
    is_admin = boolean
  }))
}

locals {
  admin_users = {
    for name, user in var.users : name => user
    if user.is_admin
  }
}

for表达式可能将无序类型（map/object/set）转换为有序类型（list/tuple）：

对于map/object，键/属性名的字典序，决定结果的顺序
对于set，如果值是字符串，则使用其字典序。如果值是其它类型，则结果的顺序可能随着Terraform的版本改变

如果输出是对象，通常要求键的唯一性。Terraform支持分组模式，允许键重复。要激活此模式，在表达式结尾添加

...

variable "users" {
  type = map(object({
    role = string
  }))
}

locals {
  users_by_role = {
    for name, user in var.users : user.role => name...
  }
}

对于顶级块，表达式仅能在给参数赋值的时候，用在右侧。某些情况下，我们需要在特定条件下，重复、启用/禁用某个子块，表达式就没法实现了，此时可以利用dynamic块。

dynamic块可以遍历一个列表，为每个元素生成一个块：

resource "aws_elastic_beanstalk_environment" "tfenvtest" {
  name                = "tf-test-name"
  application         = "${aws_elastic_beanstalk_application.tftest.name}"
  solution_stack_name = "64bit Amazon Linux 2018.03 v2.11.4 running Go 1.12.6"

  # 对于每个设置，生成一个setting子块。dynamic块的标签，对应生成的块类型
  dynamic "setting" {
    # 迭代对象
    for_each = var.settings
    # 子块的标签，可选
    labels: []
    # 子块的体（参数）
    content {
      namespace = setting.value["namespace"] # 块类型.key对应映射的键或者列表的索引，.value对应当前迭代的值
      name = setting.value["name"]
      value = setting.value["value"]
    }
  }
}

注意dynamic块仅可能为resource、data、provider、provisioner块生成参数（子块），不能用于生成源参数块，例如lifecycle。

允许dynamic块的多级嵌套。

splat表达式提供了更简单语法，在某些情况下代替for表达式：

[for o in var.list : o.id]
# 等价于
var.list[*].id

[for o in var.list : o.interfaces[0].name]
# 等价于
var.list[*].interfaces[0].name

注意splat表达式仅仅用于列表，不能用于map/object

splat表达式还有个特殊用途，将单值转换为列表：

for_each = var.website[*]

module/provider的作者可以利用类型约束来校验用户输入。Terraform的类型系统比较强大，比如他不但可以限制类型为map，还可以规定其中有哪些键，每个键的值是什么类型。

复杂类型可以将多个值组合为单个值，复杂类型由类型构造器（type constructor）定义，复杂类型分为两类：

1. 集合类型：组合相似（类型）的值
2. 结构类型：组合可能不同的值

集合类型包括map/list/set等，我们可以限制集合的成员类型：

# 字符串列表
list(string)
# 数字列表
list(number)

# 任意元素列表，等价于list
list(any)

结构类型包括object和tuple。

object定义了多个命名的属性，以及属性的类型：

object( { <KEY> = <TYPE>, <KEY> = <TYPE>, ... } )

# 示例
object({ name=string, age=number })

# 下面是符合此类型的实例
{
  name = "John"
  age  = 52
}

元组则是定义了限定元素个数、每个元素类型的列表： 

tuple([string, number, bool])
# 下面是符合此类型的实例
["a", 15, true]

大部分情况下，相似的集合类型和结构类型的行为类似。Terraform文档某些时候也不去区分，这是由于以下类型转换行为：

1. 可能的情况下，Terraform会自动在相似复杂类型之间进行转换：
   1. object和map是相似的，只要map包含object的schema所要求的键集合，即可自动转换。多余的键在转换过程中被丢弃，这意味着map - object - mapl两重转换可能丢失信息
   2. tuple和list是相似的，但是转换仅仅在list元素数量恰好满足tuple的schema时发生
   3. set和tuple/list是相似的：
      1. 当list/tuple转换为set，重复的值会被丢弃，元素顺序消失
      2. 当set转换为list/tuple，元素的顺序是任意的，一个例外是set(string)，将会按照元素字典序生成list/tuple
2. 可能的情况下，Terraform会自动转换复杂类型的元素的类型，如果元素是复杂类型，则递归的处理

每当提供的值，和要求的值类型不一致时，自动转换都会发生。

module/provider的作者应该注意不同类型的差别，特别是在限制输入方面能力的不同。

特殊关键字any用做尚未决定的类型的占位符，其本身并非一个类型。当解释类型约束的时候，Terraform会尝试寻找单个的实际类型，替换any关键字，并满足约束。

例如，对于list(any)这一类型约束，对于给定的值["a", "b", "c"]其实际类型是tuple([string, string, string])，当将该值赋值给list(any)变量时，Terraform分析过程如下：

1. tuple和list是相似类型，因此应用上问的tuple-list转换规则
2. tuple的元素类型是string，满足any约束，因此将其替换，结果类型是list(string)

从0.14开始，支持这一实验特性。可以在object类型约束中，标注某个属性为可选的： 

variable "with_optional_attribute" {
  type = object({
    a = string           # 必须属性
    b = optional(string) # 可选属性
  })
}

默认情况下，对于必须属性来说，如果类型转换时的源（例如map）不具备对应的键，会导致报错。

版本约束是一个特殊的字符串值，在引用module、使用provider时，或者通过terraform块的required_version时，需要用到版本约束：

# 版本范围区间
version = ">= 1.2.0, < 2.0.0"

# 操作符
=   等价于无操作符，限定特定版本
!=  排除特定版本
> >= < <= 限制版本范围
~>  允许最右侧的版本号片段的变化

所有可用函数：https://www.terraform.io/docs/language/functions/index.html

资源是TL语言中最重要的元素，由resource块定义。正如其名字所示，资源声明了某种云上基础设施的规格，这些基础设施可以是虚拟机、虚拟网络、DNS记录，等等。

数据源是一种特殊的资源，由data块定义。

当你第一次为某个资源编写配置时，它值存在于配置文件中，尚未代表云上的某个真实基础设施对象。通过应用Terraform配置，触发创建/更新/销毁等操作，实现云上环境和配置文件的匹配。

当一个新的资源被创建后，对应真实基础设施对象的标识符被保存到Terraform的State中。这个标识符作为后续更新/删除的依据。对于State中已经存在关联的标识符的那些Resource块，Terraform会比较真实基础设施对象和Resource参数的区别，并在必要的时候更新对象。

概括起来说，当Terraform配置被应用时：

1. 创建存在于配置文件中，但是在State中没有关联真实基础设施对象的资源
2. 销毁存在于State中，但是不存在于配置文件的资源
3. 更新参数发生变化的资源
4. 删除、重新创建参数发生变化，但是不能原地（in-palce）更新的资源。不能更新通常是因为云API的限制，例如腾讯云VPC的CIDR不支持修改

以上4点，适用于所有资源类型。但是需要注意，底层发生的事情，取决于Provider，Terraform只是去调用Provider的相应接口。

在相同模块中，你可以在表达式中访问某个资源的属性，语法

<RESOURCE TYPE>.<NAME>.<ATTRIBUTE>

除了配置文件中列出的资源参数之外，资源还提供一些只读的属性。属性表示了一些提供云API拉取到的信息。这些信息通畅需要在资源创建后才可获知，例如随机生成的资源ID vpc-d8o3c8vq

很多Provider还提供特殊的数据源（data）资源，这种特殊的资源仅仅用来查询信息。

某些资源必须在另外一些资源之后创建，例如CVM必须在其所属Subnet创建后才能创建，这意味着某些资源存在依赖关系。

Terraform能够自动分析资源依赖关系，其分析依据就是资源的参数的值表达式。如果表达式中引用了另一个资源，则当前资源依赖于该资源。

对于无法通过配置文件分析的隐含依赖，需要你手工配置

depends_on

Terraform会自动并行处理没有依赖关系的资源。

这类特殊的资源不会对应某个云上基础设施对象，而是仅仅存在于Terraform本地State中。Local-Only资源用于一些中间计算过程，包括生成随机ID、创建私钥等。

Local-Only资源的行为和普通资源一致，只是其结果数据仅仅存在于State中，删除时也仅仅是从State中移除对应数据。

resource "resource_type" "local_name" {
  # arguments...
}

两个标签分别代表资源的类型和本地名称。

资源类型提示正在描述的是那种云上基础设施，资源类型决定可用的参数集。本地名称用于在模块的其它地方饮用该资源，此外没有意义。资源类型+本地名称是资源的唯一标识，必须在模块范围内唯一。

每一种资源都由一个Provider来实现。Provider是Terraform的插件，它提供若干资源类型。通常一个云服务商提供提供一个Provider。初始化工作目录时Terraform能够自动从Terraform仓库下载大部分所需的Provider。

模块需要知道，利用哪些Provider才能管理所有的资源。此外Provider还需要经过配置才能工作，例如设置访问云API的凭证。这些配置由根模块负责。

元参数可以用于任何资源类型。

该元参数用于处理隐含的资源/模块依赖，这些依赖无法通过分析Terraform配置文件得到。从0.13版本开始，该元参数可用于模块。之前的版本仅仅用于资源。

depends_on的值是一个列表，其元素具必须是其它资源的引用，不支持任意表达式。

depends_on应当仅仅用作最后手段，避免滥用。

示例：

resource "aws_iam_role" "example" {
  name = "example"
  assume_role_policy = "..."
}

# 这个策略允许运行在EC2中的实例访问S3 API
resource "aws_iam_role_policy" "example" {
  name   = "example"
  role   = aws_iam_role.example.name
  policy = jsonencode({
    "Statement" = [{
      "Action" = "s3:*",
      "Effect" = "Allow",
    }],
  })
}


resource "aws_iam_instance_profile" "example" {
  # 这是可以自动分析出的依赖
  role = aws_iam_role.example.name
}


resource "aws_instance" "example" {
  ami           = "ami-a1b2c3d4"
  instance_type = "t2.micro"

  # 这是可以自动分析出的依赖，包括传递性依赖
  iam_instance_profile = aws_iam_instance_profile.example

  # 如果这个实例中的程序需要访问S3接口，我们需要用元参数显式的声明依赖
  # 从而分配策略
  depends_on = [
    aws_iam_role_policy.example,
  ]
} 

默认情况下，一个resource块代表单个云上基础设施对象。如果你想用一个resource块生成多个类似的资源，可以用count或for_each参数。

设置了此元参数的上下文中，可以访问名为

count

index

resource "aws_instance" "server" {
  # 创建4个类似的实例
  count = 4

  ami           = "ami-a1b2c3d4"
  instance_type = "t2.micro"

  tags = {
    #              实例的索引作为tag的一部分
    Name = "Server ${count.index}"
  }
}

在当前模块的其它地方，可以用这样的语法访问如上资源实例：

<RESOURCE_TYPE>.<NAME>[<INDEX>]

aws_instance.server[0]

如果资源的规格几乎完全一致，可以用count，否则，需要使用更加灵活的for_each元参数。

for_each的值必须是一个映射或set(string)，你可以在上下文中访问

each

key

value

resource "azurerm_resource_group" "rg" {
  for_each = {
    a_group = "eastus"
    another_group = "westus2"
  }
  # 对于每个键值对都会生成azurerm_resource_group资源
  name     = each.key
  location = each.value
}


resource "aws_iam_user" "the-accounts" {
  # 数组转换为集合
  for_each = toset( ["Todd", "James", "Alice", "Dottie"] )
  name     = each.key
}

调用子模块时使用for_each的示例：

# 父模块 my_buckets.tf
module "bucket" {
  for_each = toset(["assets", "media"])
  # 调用publish_bucket子模块
  source   = "./publish_bucket"
  # 将键赋值给子模块的name变量
  name     = "${each.key}_bucket"
}

# 子模块          文件名
# publish_bucket/bucket-and-cloudfront.tf

# 声明模块的输入参数
variable "name" {} 

resource "aws_s3_bucket" "example" {
  # 访问变量
  bucket = var.name
  # ...
}

关于for_each的值的元素，有如下限制：

1. 键必须是确定的值，如果应用配置前值无法确定会报错。例如，你不能引用CVM的ID，因为这个ID必须在配置应用之后才可知
2. 如果键是函数调用，则此函数不能是impure的（非幂等），impure函数包括uuid/bcrypt/timestamp等
3. 敏感（Sensitive）值不能用做键值。需要注意，大部分函数，在接受敏感值参数后，返回值仍然是敏感的

当使用集合的时候，你必须明确的将值转换为集合。例如通过

toset

flatten

for_each所在块定义的资源A，可以赋值给另一个资源B的for_each参数。这时，B那个for_each的键值对，值是资源的完整（创建或更新过的）实例。这种用法叫chaining：

variable "vpcs" {
  # 这里定义了map类型的变量，并且限定了map具有的键
  type = map(object({
    cidr_block = string
  }))
}


# 创建多个VPC资源
resource "aws_vpc" "example" {
  for_each = var.vpcs
  cidr_block = each.value.cidr_block
}
# 上述资源作为下面那个for_each的值

# 创建对应数量的网关资源
resource "aws_internet_gateway" "example" {
  # 为每个VPC创建一个网关
  #          资源作为值
  for_each = aws_vpc.example

  # 映射的值，在这里是完整的VPC对象
  vpc_id = each.value.id
}


# 输出所有VPC ID
output "vpc_ids" {
  value = {
    for k, v in aws_vpc.example : k => v.id
  }

  # 显式依赖网关资源，确保网关创建后，输出才可用
  depends_on = [aws_internet_gateway.example]
}

引用for_each创建的资源的实例时，使用如下语法： 

<TYPE>.<NAME>[<KEY>]

azurerm_resource_group.rg["a_group"]

这个参数用于指定使用的provider配置。可以覆盖Terraform的默认行为：将资源类型名的第一段（下划线分隔）作为provider的本地名称。同时使用provider的默认配置。例如资源类型google_compute_instance默认识别为google这个provider。

每个provider可以提供多个配置，配置常常用于管理多区域服务中的某个特定Region。每个provider可以有一个默认配置。

该参数的值必须是不被引号包围的

<PROVIDER>.<ALIAS>

# 默认配置
provider "google" {
  region = "us-central1"
}

# 备选配置
provider "google" {
  alias  = "europe"
  region = "europe-west1"
}

resource "google_compute_instance" "example" {
  # 通过使用该参数选择备选配置
  provider = google.europe

  # ...
}

注意：资源总是隐含对它的provider的依赖，这确保创建资源前provider被配置好。 

该参数可以对资源的生命周期进行控制。示例：

resource "azurerm_resource_group" "example" {
  # ...
  lifecycle {
    create_before_destroy = true
  }
}

lifecycle作为一个块，只能出现在resources块内。可用参数包括：

all

某些资源类型提供了特殊的

timeouts

resource /* ... */ {
  # ...
  timeouts {
    create = "60m"
    update = "30s"
    delete = "2h"
  }
}

资源的绝大部分参数由资源类型决定。需要翻阅Provider的文档了解哪些参数可用。

对于大部分公共的、托管在Terraform仓库的Provider来说，其文档可以直接在仓库网站上获得。

对于一些无法使用Terraform声明式模型来表达的某些行为，可以使用Provisioner作为最后（总是不推荐的）手段。

使用Provisioner会引入复杂性和不确定性：

1. Terraform无法将Provisioner执行的动作，作为计划的一部分。因为Provisioner理论上可以做任何事情
2. Provisioner通常需要使用更多细节信息，例如直接访问服务器的网络、使用Terraform的登录凭证

Provisioner块不能用名字访问其所在的上下文资源，你必须使用

self

该参数指定何时（create/update/destroy）运行Provisioner，下面是一个仅仅在删除资源时才执行的Provisioner：

resource "aws_instance" "web" {
  provisioner "local-exec" {
    # 在实际删除前调用
    when    = destroy
    command = "echo 'Destroy-time provisioner'"
  }
}

默认情况下，Provisioner在资源创建的时候调用，在更新/删除时不会调用。最常见的用法是使用Provisioner来初始化系统。如果Provisioner失败，则资源被标记为tainted，并且会在下一次

terraform apply

定制Provisioner失败时的行为：

1. continue

   忽略错误

2. fail

   默认行为，导致配置应用立即失败，如果正在创建资源，则taint该资源

大部分Provisioner要求通过SSH或WinRM来访问远程资源。你可以在

connection

1. resource，对资源的所有Provisioner生效
2. provisioner，仅仅对当前Provisioner生效

在connection块中，你也可以使用

self

示例：

provisioner "file" {
  # Linux
  connection {
    type     = "ssh"
    user     = "root"
    password = "${var.root_password}"
    host     = "${var.host}"
  }
}

provisioner "file" {
  # Windows
  connection {
    type     = "winrm"
    user     = "Administrator"
    password = "${var.admin_password}"
    host     = "${var.host}"
  }
}

关于如何通过证书进行身份验证，如何通过堡垒机连接，参考官方文档。 

如果你希望运行一个Provisioner，但是不想在任何真实的资源的上下文下运行，可以使用这种特殊的资源。

resource "aws_instance" "cluster" {
  count = 3

  # ...
}

resource "null_resource" "cluster" {
  # Provisioner的触发时机
  triggers = {
    # cluster中任何实例改变会触发Provisioner的重新执行
    #                                  这种通配符语法会得到一个列表
    cluster_instance_ids = "${join(",", aws_instance.cluster.*.id)}"
  }

  # 仅仅连接到第一个实例
  connection {
    #        该函数访问列表的特定元素
    host = "${element(aws_instance.cluster.*.public_ip, 0)}"
  }

  provisioner "remote-exec" {
    # 执行命令
    inline = [
      "bootstrap-cluster.sh ${join(" ", aws_instance.cluster.*.private_ip)}",
    ]
  }
}

resource "aws_instance" "web" {
  # ...

  # 文件到文件
  provisioner "file" {
    source      = "conf/myapp.conf"
    destination = "/etc/myapp.conf"
  }

  # 字符串到文件
  provisioner "file" {
    content     = "ami used: ${self.ami}"
    destination = "/tmp/file.log"
  }

  # 目录到目录，拷贝后生成/etc/configs.d目录
  provisioner "file" {
    source      = "conf/configs.d"
    destination = "/etc"
  }

  # Windows下的路径语法
  provisioner "file" {
    # apps/app1/下的所有文件拷贝到D:/IIS/webapp1下
    source      = "apps/app1/"
    destination = "D:/IIS/webapp1"
  }
}

resource "aws_instance" "web" {
  # ...

  provisioner "local-exec" {
    command = "echo ${self.private_ip} >> private_ips.txt"
    # 可选的工作目录
    working_dir = "/root"
    # 可选的解释器
    interpreter = [ "/bin/bash", "-c" ]
    # 可选的环境变量
    environment = {
      FOO = "bar"
    }
  }
}

resource "aws_instance" "web" {
  provisioner "remote-exec" {
    # 命令列表，逐个执行
    inline = [
      "puppet apply",
      "consul join ${aws_instance.web.private_ip}",
    ]
    # 单个脚本路径
    script = ""
    # 多个脚本路径
    scripts = []
  }
} 

数据资源，由data块来描述，让Terraform从数据源读取信息。Data是一种特殊的Resource，也是由Provider来提供。Data只支持读取操作，相对的，普通的Resource支持增删改查操作，普通资源也叫受管（Manged）资源，一般简称Resource。

数据资源要求Terraform去特定数据源（第1标签）读取数据，并将结果导出为本地名称（第2标签）：

# 读取匹配参数的aws_ami类型的数据源，并存放到example
data "aws_ami" "example" {
  # 这些参数是查询条件(query constraints)，具体哪些可用取决于数据源类型
  most_recent = true

  owners = ["self"]
  tags = {
    Name   = "app-server"
    Tested = "true"
  }
}

两个标签组合起来是data在模块中的唯一标识。

如果数据资源的查询约束（参数）都是常量值，或者是已知的变量值，那么数据资源的状态会在Terraform的Refresh阶段更新，这个阶段在创建执行计划之前。

查询约束可能引用了某些值，这些值在应用配置文件之前无法获知（例如资源ID）。这种情况下，读取数据源的操作将推迟到Apply之后。在Data读取完成之前，所有对它结果（导出名称）的引用都是不可用的。

大部分数据源都对应了某种云上基础设施，需要通过云API远程的读取。

某些特殊数据源仅仅供Terraform自己使用，例如Hashicorp的Provider template，它提供的template_file数据源，用于在本地渲染模板文件。这类数据源叫Local-Only数据源，其行为和一般数据源没有区别。

数据资源的依赖解析行为，和受管资源一致。

数据资源支持的元参数，和受管资源一致。

和传统编程语言对比，模块类似于函数，输入变量类似于函数参数，输出值类似于返回值，本地值则类似于函数内的局部变量。

输入变量作为Terraform模块的参数，从而实现模块的参数化、可跨多个配置复用。

对于定义在根模块中的变量，其值可以从Terraform CLI选项传入。对于子模块中定义的变量，则必须通过module块传入其值。

# 声明一个字符串类型的输入变量
#        变量名必须在模块范围内唯一
#        不得用做变量名：ource, version, providers, count, for_each, lifecycle, depends_on, locals
variable "image_id" {
  # 类型
  type = string
  # 描述
  description = ""
  # 校验规则
  validation {
    # 如果为true则校验成功
    condition = bool-expr
    # 校验失败时的消息
    error_message = ""
  }
  # 是否敏感，敏感信息不会现在Terraform UI上输出
  sensitive = false
}

# 声明一个字符串的列表，并给出默认值
variable "availability_zone_names" {
  type    = list(string)
  default = ["us-west-1a"]
}

# 声明一个对象的列表，并给出默认值
variable "docker_ports" {
  type = list(object({
    internal = number
    external = number
    protocol = string
  }))
  default = [
    {
      internal = 8300
      external = 8300
      protocol = "tcp"
    }
  ]
}

支持的简单类型：

string

number

bool

支持的容器类型：

1. 列表：

   list(<TYPE>)

2. 集合：

   set(<TYPE>)

3. 映射：

   map(<TYPE>)

4. 对象：

   object({<ATTR NAME> = <TYPE>, ... })

5. 元组：

   tuple([<TYPE>, ...])

关键字

any

如果同时指定了类型和默认值，则提供的默认值必须可以转换为类型。

validation是一个块，其中condition是一个bool表达式：

variable "image_id" {
  type        = string
  description = "The id of the machine image (AMI) to use for the server."

  validation {
    #               can函数将错误转换为false
    #                  regex函数在找不到匹配的时候会失败
    condition     = can(regex("^ami-", var.image_id))
    error_message = "The image_id value must be a valid AMI id, starting with \"ami-\"."
  }
}

在声明输入变量的模块中，可以使用

var.<NAME>

resource "aws_instance" "example" {
  instance_type = "t2.micro"
  ami           = var.image_id
}

要给根模块中定义的变量赋值，有以下几种方式：

1. 使用

   -var

   命令行选项，可以多次使用，每次赋值一个变量，示例：
   

   terraform apply -var="image_id=ami-abc123"
   terraform apply -var='image_id_list=["ami-abc123","ami-def456"]' -var="instance_type=t2.micro"
   terraform apply -var='image_id_map={"us-east-1":"ami-abc123","us-east-2":"ami-def456"}' 

2. 作为环境变量传入，示例：
   

   # 环境变量需要TF_VAR_前缀
   export TF_VAR_image_id=ami-abc123

3. 使用

   .tfvars

   文件，此文件可以自动载入或者通过命令行选项显式载入，示例：
   

   image_id = "ami-abc123"
   availability_zone_names = [
     "us-east-1a",
     "us-west-1c",
   ]

   
   

   terraform apply -var-file="testing.tfvars"

   注意以下文件可以自动识别并载入：

   1. 名为

      terraform.tfvars

      或

      terraform.tfvars.json

      的文件
   2. 以

      .auto.tfvars

      或

      .auto.tfvars.json

      结尾的文件

如果通过多种方式给变量赋值，则优先级高的生效。优先级顺序从低到高：

1. 环境变量文件
2. terraform.tfvars
3. terraform.tfvars.json
4. *.auto.tfvars和*.auto.tfvars.json文件，多个文件，按字典序，后面的优先级高
5. -var或-var-file命令行选项，多个选项，后面的优先级高

输出值是模块的“返回值”，具有以下用途：

1. 子模块使用输出值将它创建的资源的属性的子集暴露给父模块
2. 根模块可以利用输出值，将一些信息在terraform apply之后打印到控制台上
3. 当使用远程状态（remote state）时，根模块的输出可以被其它配置通过 terraform_remote_state 数据源捕获到

# 输出的名字
output "instance_ip_addr" {
  # 值
  value = aws_instance.server.private_ip
  # 描述
  description = ""
  # 是否敏感
  sensitive = ""
  # 依赖
  depends_on = []
}

子模块的输出值，通过这样的表达式访问：

module.<MODULE NAME>.<OUTPUT NAME>

# 访问子模块web_server的输出值instance_ip_addr
module.web_server.instance_ip_addr

使用depends_on参数可以明确指定输出值依赖什么：

output "instance_ip_addr" {
  value       = aws_instance.server.private_ip
  depends_on = [
    aws_security_group_rule.local_access,
  ]
}

在一个模块内部，将表达式分配给一个名称。你可以同时声明多个本地值：

locals {
  service_name = "forum"
  instance_ids = concat(aws_instance.blue.*.id, aws_instance.green.*.id)
  common_tags = {
    Service = local.service_name
    Owner   = local.owner
  }
}

引用本地值时，使用表达式： 

local.<NAME>

一套完整的配置文件（Configuration，简称配置），由1个根目录和若干文件/子目录组成。配置文件的扩展名为

.tf

.tf.json

所谓模块（Module）是存放在一个目录中的配置文件的集合。子目录中的文件不属于模块，不会自动包含到配置中。

将块存放在不同配置文件中仅仅是方便人类的阅读，和Terraform的行为无关。Terraform总是会评估模块中的所有文件，并将它们合并为单一的文档来看待。

Terraform命令总是在单个根模块的上下文中运行，根模块的目录通常作为命令的工作目录。此根模块会调用其它模块，这种调用关系会递归的发生，从而形成一个子模块树结构。

一个模块（通常是根模块）可以调用其它模块，从而将这些模块中定义的资源包含到配置中。当一个模块被其它模块调用时，它的角色是子模块。

子模块可以被同一个配置调用多次，不同模块也可以同时调用一个子模块。

引用子模块时，除了可以从本地文件系统获取，还可以从公共/私有仓库下载。

Terraform Registry托管了大量公共模块，用于管理各种各样的基础设施，这些模块可以被免费使用。Terraform能够自动下载这些模块的正确版本。Terraform Cloud / Enterprise版本都包含一个私服模块可以托管组织私有的模块。

使用名为

override.tf

override.tf.json

_override.tf

_override.tf.json

加载配置时，Terraform最初会跳过覆盖文件。加载完成功文件后，会按照字典序处理覆盖文件。对于覆盖文件中的每个顶级块，Terraform会尝试寻找已经存在的，定义在常规文件中的对应块，并将块的内容进行合并。内容合并规则如下：

1. 覆盖文件中的顶级块、普通配置文件中的顶级块，对应关系通过块头（块类型+标签）识别，相同块头的块被合并
2. 顶级块中的参数被替换
3. 顶级块中的内嵌块被替换，不会递归的进行合并
4. 多个覆盖文件覆盖了同一个块的定义时，按覆盖文件名的字典序依次合并

此外，对于resource / data块，有如下特殊规则：

1. 内嵌的lifecycle块不是简单的直接替换。假设覆盖文件仅仅设置了lifecycle的create_before_destroy属性，原始配置中任何ignore_changes参数保持原样
2. 对于内嵌的provisioner块，原始配置中的（不管有几个）provisioner块直接被忽略
3. 原始配置中的内嵌connection块被完全覆盖
4. 元参数（meta-argument）depends_on不能出现在覆盖文件中

对于variable（变量）块，有如下特殊规则：

1. 如果原始块定义了default参数（默认值）并且覆盖块修改了变量的type，则Terraform尝试将default转换为新的type，如果转换无法自动完成则报错
2. 如果覆盖块修改了default，那么其值必须匹配原始块中的type

不建议过多的使用覆盖文件，这会降低配置的可读性。

对于output块，有如下特殊规则：

1. 元参数depends_on不能出现在覆盖文件中

对于local块，有如下特殊规则：

1. 每个local块定义（或修改）了若干具有名字的值，覆盖时使用value-by-value的方式，至于值在何处定义不影响

对于terraform块，有如下特殊规则：

1. required_providers的值，按element-by-element的方式进行覆盖。这样，覆盖块可以仅仅调整单个provider的配置，而不影响其他providers
2. 覆盖required_version、required_providers时，被覆盖的元素被整个替换

下面是原始文件+覆盖文件的示例：

# example.tf
resource "aws_instance" "web" {
  instance_type = "t2.micro"
  ami           = "ami-408c7f28"
}

# override.tf
resource "aws_instance" "web" {
  ami = "foo"
}

所谓调用，就是将特定的值传递给子模块作为输入变量，从而将子模块中的配置包含进来。

module "servers" {
  # 源，必须，指定子模块的位置
  source = "./app-cluster"
  # 版本，如果模块位于仓库中，建议制定
  version = "0.0.5"
  
  # 支持一些元参数
  
  # 大部分其它参数，都是为子模块提供输入变量
  servers = 5
}

provider "aws" {
  alias  = "usw2"
  region = "us-west-2"
}

module "example" {
  source    = "./example"
  providers = {
    # 配置名称由provider块的第1标签（+可选的alias参数）构成
    # 键是子模块中的Provider配置名称
    # 值是父模块中的Provider配置名称
    aws = aws.usw2
  }
}

module块的source参数指定了从何处下载子模块的代码。

terraform init中有一个步骤，专门负责模块的安装。它支持从本地路径、Terraform Registry、GitHub、一般性Git仓库、HTTP URL、S3桶等多种来源下载模块。

对于紧密相关的模块，例如为了减少代码重复，从单一模块拆分得到的，建议使用本地路径方式存储。

module "consul" {
  #        必须以./或../开头，提示这是一个本地模块
  source = "./consul"
}

本地路径的源具有一个特殊的地方，它没有“安装”这个步骤。

对于希望公开分享的模块，可以存放在这个Terraform仓库中。这种仓库的源地址格式为

<HOSTNAME>/<NAMESPACE>/<NAME>/<PROVIDER>

# 这个模块创建一个Consul服务
module "consul" {
  # 为AWS提供的consule模块，使用Terraform公共仓库时HOSTNAME可以省略
  source = "hashicorp/consul/aws"
  version = "0.1.0"
}

为了访问私有仓库，你可能需要在CLI配置中添加访问令牌。

如果source以github.com开头，则Terraform会尝试到GitHub拉取模块源码：

module "consul" {
  # 通过HTTPS
  source = "github.com/hashicorp/example"
}

module "consul" {
  # 通过SSH
  source = "git@github.com:hashicorp/example.git"
}

如果source以

git::

module "vpc" {
  source = "git::https://example.com/vpc.git"
}

module "storage" {
  source = "git::ssh://username@example.com/storage.git"
}

Terraform使用git clone命令下载模块，因此本地机器的任何Git配置都可用，包括凭证信息。

默认情况下，使用Git仓库的HEAD，要选择其它修订版，使用ref参数：

module "vpc" {
  source = "git::https://example.com/vpc.git?ref=v1.2.0"
}

任何可以作为git checkout参数的值，都可以作为ref参数。

如果source指定为一个普通的URL，那么Terraform会：

1. 附加GET参数

   terraform-get=1

   ，请求那个URL
2. 如果得到2xx应答，那么尝试从以下位置读取模块实际地址：
   1. 响应头

      X-Terraform-Get

   2. HTML元素：
      

      <meta name="terraform-get" content="github.com/hashicorp/example" /> 

如果URL的结尾是可识别的压缩格式扩展名（zip tar.bz2  tbz2 tar.gz  tgz tar.xz txz）则Terraform会跳过上面处理过程，直接下载压缩包：

module "vpc" {
  source = "https://example.com/vpc-module?archive=zip"
}

如果需要的模块位于源的子目录中，可以使用特殊的

//

hashicorp/consul/aws//modules/consul-cluster
git::https://example.com/network.git//modules/vpc
https://example.com/network-module.zip//modules/vpc
s3::https://s3-eu-west-1.amazonaws.com/examplecorp-terraform-modules/network.zip//modules/vpc
git::https://example.com/network.git//modules/vpc?ref=v1.2.0

开发模块就是构思和编写TF文件的过程，你需要考虑模块的输入（变量）、输出（值），模块读取和创建哪些资源。你只需要将这些TF文件放在一个目录中就可以了。

如果开发的模块可能被很多配置复用，建议在独立的版本库中管理。

尽管内嵌多个子目录（作为子模块）是允许的，但是建议尽可能的让目录扁平化，可以使用模块组合，而避免深层次的目录树，这可以增强可复用性。

过度的模块化容易让配置难以理解。

一个好的模块应该通过描述架构中新概念来提升抽象层次，这个概念由一些Provider中的基本元素组成。例如，我们想基于一些CVM、一个CLB构建一个Redis集群，这样的集群就适合封装在一个模块中。

永远不要开发那种仅仅为了包装单个其它资源的模块。

$ tree complete-module/          # 根模块，这是标准模块结构中唯一必须的元素
.
├── README.md                    # 文档
├── main.tf                      # 建议文件名，模块主入口点，资源在此创建
├── variables.tf                 # 定义模块的输入变量
├── outputs.tf                   # 定义模块的输出值
├── ...
├── modules/                     # 嵌套的子模块
│   ├── nestedA/
│   │   ├── README.md
│   │   ├── variables.tf
│   │   ├── main.tf
│   │   ├── outputs.tf
│   ├── nestedB/
│   ├── .../
├── examples/                    # 使用模块的样例
│   ├── exampleA/
│   │   ├── main.tf
│   ├── exampleB/
│   ├── .../

一个简单的Terraform配置，仅仅包含一个根模块，我们在这个扁平的结构中创建所有资源： 

resource "aws_vpc" "example" {
  cidr_block = "10.1.0.0/16"
}

resource "aws_subnet" "example" {
  vpc_id = aws_vpc.example.id

  availability_zone = "us-west-2b"
  cidr_block        = cidrsubnet(aws_vpc.example.cidr_block, 4, 1)
}

当引入

modules

Terraform建议保持配置的扁平，仅仅引入一层子模块。假设我们需要在AWS上创建一个Consul集群，它依赖一个子网。我们可以将子网的创建封装到模块：

module "network" {
  source = "./modules/aws-network"

  base_cidr_block = "10.0.0.0/8"
}

将Consul集群的创建封装到另外一个模块：

module "consul_cluster" {
  source = "./modules/aws-consul-cluster"

  vpc_id     = module.network.vpc_id
  subnet_ids = module.network.subnet_ids
}

根模块通过上面两个module块使用这两个子模块，这种简单的单层结构叫模块组合（ module composition）

上面这个例子也体现了依赖反转的原则： consul_cluster需要一个网络，但是不是它（这个模块）自己去创建网络，而是由外部创建并注入给它。

在未来进一步的重构中，可能由另外一个配置负责创建网络，而仅仅通过数据资源将读取网络信息：

data "aws_vpc" "main" {
  tags = {
    Environment = "production"
  }
}

data "aws_subnet_ids" "main" {
  vpc_id = data.aws_vpc.main.id
}

module "consul_cluster" {
  source = "./modules/aws-consul-cluster"

  vpc_id     = data.aws_vpc.main.id
  subnet_ids = data.aws_subnet_ids.main.ids
}

开发可复用模块时，一个很常见的情况是，某个依赖的资源在某些条件下不需要创建 —— 例如在某些环境下，资源预先已经存在。

这种情况下同样要应用依赖反转原则：将这些可能需要创建的依赖资源作为模块的输入参数：

# 下面这个变量代表依赖的资源
variable "ami" {
  type = object({
    # 仅仅需要定义对于本模块有意义的属性
    id           = string
    architecture = string
  })
}

由模块的调用者决定创建依赖资源：

resource "aws_ami" "example" {
  name              = "local-copy-of-ami"
  source_ami_id     = "ami-abc123"
  source_ami_region = "eu-west-1"
}

module "example" {
  source = "./modules/example"
  ami = aws_ami.example
}

还是直接使用已经存在的依赖资源：

data "aws_ami" "example" {
  owner = "10000"
  tags = {
    application = "example-app"
    environment = "dev"
  }
}

module "example" {
  source = "./modules/example"
  ami = data.aws_ami.example
}

因为，只有调用者才清楚实际环境是什么样的。 

Terraform本身没有提供适配多个云服务商的相似资源的抽象，这会屏蔽云服务商的差异性。尽管如此，作为Terraform用户来说，进行多云抽象是常见需求，特别是云迁移这样的应用场景。 

举例来说，任何一个云服务商的域名系统都支持域名解析。但是某些云服务商可能提供智能负载均衡、地理位置感知的解析这样高级特性。我们可以将域名系统的公共特性抽象为模块：

module "webserver" {
  source = "./modules/webserver"
}

locals {
  fixed_recordsets = [
    {
      name = "www"
      type = "CNAME"
      ttl  = 3600
      records = [
        "webserver01",
        "webserver02",
      ]
    },
  ]
  server_recordsets = [
    for i, addr in module.webserver.public_ip_addrs : {
      name    = format("webserver%02d", i)
      type    = "A"
      records = [addr]
    }
  ]
}

上面的recordset，抽象了所有域名系统都应该支持的DNS记录集资源。

当针对某个云服务商实现此资源时，我们可以开发一个模块。

# 此模块在AWS Route53上实现了记录集资源
module "dns_records" {
  source = "./modules/route53-dns-records"
  route53_zone_id = var.route53_zone_id
  recordsets      = concat(local.fixed_recordsets, local.server_recordsets)
}

需要切换云服务商时，只需要替换上述dns_records模块的source即可，指向对应的模块即可。所有这些模块都需要定义输入参数：

variable "recordsets" {
  type = list(object({
    name    = string
    type    = string
    ttl     = number
    records = list(string)
  }))
}

大部分模块都会描述需要被创建和管理的基础设施对象，偶尔的情况下，模块仅仅去抓取需要的信息。

其中一种情况是，一套系统被划分为多个子系统，这些子系统都需要获取某种信息，这些信息可以用由一个data-only模块抓取。

出于复用目的的模块可以发布到Terraform Registry， 这样模块可以很容易被所有人使用。如果仅仅在组织内部共享，可以发布到私有仓库。

通过Git、S3、HTTP等方式发布模块也是可以的，模块支持多种源。

所谓提供者，就是Terraform的插件/驱动，负责和特定云厂商的API或者其它任何API打交道。

每个Provider都可以提供若干受管资源、数据资源，供Terraform使用。 反过来说，任何资源都是由Provider提供，没有Provider，Terraform什么都做不了。

Provider和Terraform完全独立的分发，公共的Provider托管在Terraform仓库（Registry）。

在每次Terraform运行过程中，需要的Provider会自动被安装。

Terraform CLI会在初始化工作目录的时候安装Provider，它能够自动从Terraform Registry下载Provider，或者从本地镜像/缓存加载。要指定缓存位置，在CLI配置文件中设置

plugin_cache_dir

TF_PLUGIN_CACHE_DIR

为了保证，针对一套配置，总是安装相同版本的Provider，可以使用CLI创建一个依赖锁文件，并将此文件和配置一起纳入版本管理。

每个模块都必须声明它需要哪些Provider，这样Terraform才能够安装和使用它们。声明在

required_providers

terraform {
  required_providers {
    # 该块的每个参数，启用一个Provider
    # key是Provider的本地名称，必须是模块范围内的唯一标识符
    mycloud = {
      # 源地址
      source  = "mycorp/mycloud"
      # 版本约束
      version = "~> 1.0"
    }
  }
}

在required_providers块之外，Terraform总是使用本地名称来引用Provider：

provider "mycloud" {
  # 配置mycloud这个Provider
}

Provider的源地址，是它的全局标识符，这个地址当然也指明了应该从何处下载Provider。

源地址的格式为：

[<HOSTNAME>/]<NAMESPACE>/<TYPE>

1. 可选的主机名，默认registry.terraform.io，即Terraform Registry的主机名
2. 命名空间，通常是发布Provider的组织
3. 类型，通常是Provider管理的平台/系统的简短名称

>= 1.0

~> 1.0.4

目前仅有一个内置于Terraform的Provider，名为terraform_remote_state。你不需要再配置文件中引入它，尽管如此它还是有自己的源地址terraform.io/builtin/terraform。

某些组织可能会开发自己的Provider，以管理特殊的基础设施。他们可能希望在Terraform中使用这些Provider，但是却不将其发布到公共仓库中。这种情况下，，构建自己的私有仓库。更简单的，可以使用更简单的Provider安装方法，例如自己将其存放在本地文件系统的特定目录。

任何Provider都必须有源地址，源地址必须包含（或者隐含默认值）一个主机名。如果通过本地文件系统分发Provider，则这个主机名只是个占位符，甚至不需要可解析。你通常可以使用terraform.yourcompany.com作为主机名。你可以这样引入私有Provider：

terraform {
  required_providers {
    mycloud = {
      source  = "terraform.example.com/examplecorp/ourcloud"
      version = ">= 1.0"
    }
  }
}

选择一个隐式本地镜像目录（implied local mirror directories ），并创建目录terraform.example.com/examplecorp/ourcloud/1.0.0，在此目录中创建一个代表运行平台的子目录，例如linux_amd64，并将Provider的可执行文件、以及任何其它需要的文件存放到其中即可。对于Windows，可执行文件的路径可能是terraform.example.com/examplecorp/ourcloud/1.0.0/windows_amd64/terraform-provider-ourcloud.exe

除了引入Provider，你可能还需要对其进行配置才能使用。

配置时，使用provider块。只有根模块才可以配置一个Provider。子模块会自动从根模块继承Provider配置。示例：

#        本地名称，引入Provider时指定
provider "google" {
  project = "acme-app"
  region  = "us-central1"
}

具体哪些配置参数可用，取决于Provider。配置时可以使用表达式，但是只能引用那些应用配置之前即可知的值 —— 可以安全的引用输入变量，但是不能使用那些由资源导出的属性。

Provider支持两个元参数，其中一个是alias，用于定义备选的Provider配置：

provider "aws" {
  alias  = "west"
  region = "us-west-2"
}

声明资源时，可以指定使用备选的Provider配置： 

resource "aws_instance" "foo" {
  provider = aws.west
} 

这个元参数已经弃用，是旧的管理Provider版本的方式。 

Terraform配置文件可以引用两类外部依赖：

1. Providers，如上个章节所述，用于和外部系统交互的插件
2. Modules，可复用的配置文件集合

这两类依赖都可以独立发布，并进行版本管理。引用这些依赖时，Terraform需要知道使用什么版本。

配置文件中的版本约束，指定了潜在的兼容性版本范围。但是到底选择（并锁定使用）依赖的哪个版本，由名为.terraform.lock.hcl的依赖锁文件决定。注意，当前依赖锁文件仅仅管理Provider的版本，对于Module，仍然总是拉取匹配版本约束的最新版本。

每当运行

terraform init

运行terraform init时，如果：

1. 依赖没有记录在依赖锁文件中，则尝试拉取匹配版本约束的最新版本。并将获取到的版本信息记录到依赖锁文件
2. 依赖已经记录，则使用记录的版本

运行

terraform init -upgrade

Terraform逻辑上划分为两个部分：核心和插件。Terraform核心通过RPC来调用插件。Terraform支持多种发现和加载插件的方式。Terraform插件有两类

1. Provider：通常用于对接到某特定云服务商，在其上创建基础设施对象
2. Provisioner：对接到某种provisioner，例如Bash

核心的职责包括：

1. 基础设施即代码：读取和解释配置文件和模块
2. 资源状态管理
3. 构造资源依赖图
4. 执行计划
5. 通过RPC和插件交互

插件和核心一样，基于Go语言编写。Terraform使用的所有Provider和Provisioner都是插件，它们在独立进程中运行。

Provider插件的职责是：

1. 初始化任何必要的库，用于进行API调用
2. 与基础设施提供者进行交互
3. 定义映射到特定服务的资源

Provisioner插件的职责是：

1. 在特定资源创建后、销毁前执行命令或脚本

当

terraform init

关于插件发现，有以下规则：

1. 如果已经安装了满足版本约束的插件，Terraform会使用其中最新的。即使Terraform Registry有更新的满足版本约束的插件，默认也不会主动下载。使用

   terraform init -upgrade

   可以强制下载最新版本
2. 如果没有安装满足版本约束的插件，且插件托管在Registry，则下载并存放到

   .terraform/providers/

   目录下

Provider应该基于单一API集合，或者SDK，例如仅仅针对腾讯云API，实现对腾讯云基础实施对象CRUD的封装。

Terraform插件定义的资源，应该对应单一的云资源，作为该云资源的声明式表示。资源通常应该提供创建/读取/删除，以及可选的更新方法。

对多个云资源的组合，或者其它高级特性，应该通过模块来实现。

名称、数据类型、结构，应当尽可能匹配，除非这样做会影响Provider用户的体验。

Terraform资源应该支持

terraform import

一旦Provider发布，后续就面临向后兼容性问题。

开发Provider时，有两个SDK可供选择：

1. SDKv2：当前大部分现有的Provider基于此SDK开发，提供稳定的开发体验
2. Terraform Plugin Framework：新的SDK，还在积极的开发中。目标是提升开发体验，对齐Terraform新的架构

如何选择：

1. 如果维护既有Provider，沿用它当前使用的SDK。如果开发全新的Provider，可以考虑使用Framework
2. 如果使用的Terraform版本小于v1.0.3，则只能基于SDKv2开发。Framework基于Terraform Protocol Version 6构建，旧版本的Terraform不能下载基于Version 6的Provider
3. Framework的接口可能发生改变，考虑成本
4. 是否需要Framework提供的新特性：
   1. 支持获知一个值是否在配置、状态或计划中设置
   2. 支持获知一个值是否null、unknown，或者是空白值
   3. 支持object这样的结构化类型
   4. 支持嵌套属性
   5. 支持以any类型为元素的map
   6. 支持获知何时一个optional或计算出的字段从配置中移除了
5. 是否需要Framework尚未实现的，SDKv2已经支持的特性：
   1. 超时支持
   2. 定义资源状态upgraders

构建Provider的时候，使用go build命令，按照构建二进制文件的常规方式即可。你也可以使用GoReleaser来自动化构建多平台的、包含checksum的、自动签名的Provider。

每个发布包含以下文件：

1. 一个或多个zip文件，其命名格式为

   terraform-provider-{NAME}_{VERSION}_{OS}_{ARCH}.zip

   1. zip中包含Provider的二进制文件，命名为

      terraform-provider-{NAME}_v{VERSION}

2. 一个摘要文件

   terraform-provider-{NAME}_{VERSION}_SHA256SUMS

   ，包含每个zip的sha256：
   

   shasum -a 256 *.zip > terraform-provider-{NAME}_{VERSION}_SHA256SUMS

3. 一个GPG二进制文件

   terraform-provider-{NAME}_{VERSION}_SHA256SUMS.sig

   ，使用密钥对上述摘要文件进行前面：
   

   gpg --detach-sign terraform-provider-{NAME}_{VERSION}_SHA256SUMS

4. 发布必须是finalized的（不是一个私有的草稿）

本章开发和使用一个Provider，它和虚构的咖啡店应用Hashicups进行交互。此咖啡店应用支持查看和订购咖啡，它开放公共API端点：

1. 列出咖啡品种
2. 列出特定咖啡的成分

以及需要身份认证的API端点：

1. CRUD咖啡订单

HashiCups Provider基于一个Golang客户端库，利用REST API访问以上API端点，管理咖啡订单。

首先我们从用户角度来感受一下，如何使用HashiCups Provider管理咖啡订单。本章后续会分析和重构该Provider的源码。

执行下面的命令下载使用HashiCups Provider的Terraform配置的空白项目。此项目没有Terraform配置，但是提供了在本地运行HashiCup咖啡店应用的脚本。

git clone https://github.com/hashicorp/learn-terraform-hashicups-provider
cd learn-terraform-hashicups-provider

执行下面的命令，在本地启动HashiCup咖啡店应用：

cd docker_compose && docker-compose up

API监听端口是19090。检查并确认服务器正常工作：

curl localhost:19090/health 

从0.13+开始，必须在Terraform配置中声明所有依赖的Provider及其源（从哪里下载）。源的格式为[hostname]/[namespace]/[name]，对于Terraform Registry中的hashicorp命名空间，hostname和namespace都是可选的。Terraform Registry对应的hostname为registry.terraform.io

这里用到的Provider没有托管在Registry，需要手工下载：

curl -LO https://github.com/hashicorp/terraform-provider-hashicups/releases/download/v0.3.1/terraform-provider-hashicups_0.3.1_linux_amd64.zip

或者从源码编译：

git clone https://github.com/hashicorp/terraform-provider-hashicups
go mod vendor
go build -o terraform-provider-hashicups
mv terraform-provider-hashicups ~/.terraform.d/plugins/hashicorp.com/edu/hashicups/0.3.1/linux_amd64

并且存放到：

~/.terraform.d/plugins/${host_name}/${namespace}/${type}/${version}/${target}
~/.terraform.d/plugins/hashicorp.com/edu/hashicups/0.3.1/linux_amd64/terraform-provider-hashicups_v0.3.1

curl -X POST localhost:19090/signup -d '{"username":"education", "password":"test123"}'

登录以获得Token：

curl -X POST localhost:19090/signin -d '{"username":"education", "password":"test123"}'
{"UserID":1,"Username":"education","token":"eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJleHAiOjE2MzUyNTA3ODAsInVzZXJfaWQiOjEsInVzZXJuYW1lIjoiZWR1Y2F0aW9uIn0.M4YWgRM-5Jzfy3TLj9MqeVR7nsfRmlG3vZyaeRASnhw"}

将Token设置到环境变量：

export HASHICUPS_TOKEN=eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJleHAiOjE2MzUyNTA3ODAsInVzZXJfaWQiOjEsInVzZXJuYW1lIjoiZWR1Y2F0aW9uIn0.M4YWgRM-5Jzfy3TLj9MqeVR7nsfRmlG3vZyaeRASnhw

添加下面的代码到main.tf：

terraform {
  required_providers {
    hashicups = {
      version = "~> 0.3.1"
      source  = "hashicorp.com/edu/hashicups"
    }
  }
}

并进行初始化：

terraform init

将以下内容添加到main.tf中：

# 配置Provider
provider "hashicups" {
  username = "education"
  password = "test123"
}

# 定义一个名为edu的订单资源
resource "hashicups_order" "edu" {
  # 订单包含2个品种3的咖啡
  items {
    coffee {
      id = 3
    }
    quantity = 2
  }
  # 订单包含2个品种2的咖啡
  items {
    coffee {
      id = 2
    }
    quantity = 2
  }
}

# 输出edu资源，这个输出在资源创建后可用
output "edu_order" {
  value = hashicups_order.edu
}

执行下面的命令获取执行计划：

terraform plan 

Terraform used the selected providers to generate the following execution plan. Resource actions are indicated with the following symbols:
  + create # +表示创建操作

Terraform will perform the following actions:
  # 这里会列出计划中包含的操作
  #                             这是一个创建操作
  # hashicups_order.edu will be created
  + resource "hashicups_order" "edu" {
      # 每个属性的值     这个表示未知值
      + id           = (known after apply)
      + last_updated = (known after apply)

      + items {
          + quantity = 2

          + coffee {
              + description = (known after apply)
              + id          = 3
              + image       = (known after apply)
              + name        = (known after apply)
              + price       = (known after apply)
              + teaser      = (known after apply)
            }
        }
      + items {
          + quantity = 2

          + coffee {
              + description = (known after apply)
              + id          = 2
              + image       = (known after apply)
              + name        = (known after apply)
              + price       = (known after apply)
              + teaser      = (known after apply)
            }
        }
    }

Plan: 1 to add, 0 to change, 0 to destroy.

# 这里显示输出值会发生的变更
Changes to Outputs:
  + edu_order = {
      + id           = (known after apply)
      + items        = [
          + {
              + coffee   = [
                  + {
                      + description = (known after apply)
                      + id          = 3
                      + image       = (known after apply)
                      + name        = (known after apply)
                      + price       = (known after apply)
                      + teaser      = (known after apply)
                    },
                ]
              + quantity = 2
            },
          + {
              + coffee   = [
                  + {
                      + description = (known after apply)
                      + id          = 2
                      + image       = (known after apply)
                      + name        = (known after apply)
                      + price       = (known after apply)
                      + teaser      = (known after apply)
                    },
                ]
              + quantity = 2
            },
        ]
      + last_updated = (known after apply)
    }

执行

terraform apply

terraform state show

terraform state show hashicups_order.edu 
# hashicups_order.edu:
resource "hashicups_order" "edu" {
    id = "1"

    items {
        quantity = 2

        coffee {
            id     = 3
            image  = "/nomad.png"
            name   = "Nomadicano"
            price  = 150
            teaser = "Drink one today and you will want to schedule another"
        }
    }
    items {
        quantity = 2

        coffee {
            id     = 2
            image  = "/vault.png"
            name   = "Vaulatte"
            price  = 200
            teaser = "Nothing gives you a safe and secure feeling like a Vaulatte"
        }
    }
}

可以看到Schema中所有属性均被填充。

我们修改一下订单配置，将items[*].quantity改一下，然后看看执行计划：

terraform plan
hashicups_order.edu: Refreshing state... [id=1]

Terraform used the selected providers to generate the following execution plan. Resource actions are indicated with the following symbols:
  ~ update in-place  # ~表示原地更新操作

Terraform will perform the following actions:
  # 这里会显示diff
  # hashicups_order.edu will be updated in-place
  ~ resource "hashicups_order" "edu" {
        id = "1"

      ~ items {
          ~ quantity = 2 -> 3

            # (1 unchanged block hidden)
        }
      ~ items {
          ~ quantity = 2 -> 1

            # (1 unchanged block hidden)
        }
    }

Plan: 0 to add, 1 to change, 0 to destroy.

Changes to Outputs:
  # 这里会显示diff
  ~ edu_order = {
      ~ items        = [
          ~ {
              ~ quantity = 2 -> 3
                # (1 unchanged element hidden)
            },
          ~ {
              ~ quantity = 2 -> 1
                # (1 unchanged element hidden)
            },
        ]
        # (2 unchanged elements hidden)
    }

通过apply命令应用上述执行计划。

本节我们来演示如何读取已经创建的订单的咖啡的配料表：

data "hashicups_ingredients" "first_coffee" {
  #                               声明多次的内嵌块，自动成为数组
  coffee_id = hashicups_order.edu.items[0].coffee[0].id
}

output "first_coffee_ingredients" {
  value = data.hashicups_ingredients.first_coffee
}

terraform destroy
hashicups_order.edu: Refreshing state... [id=1]

Terraform used the selected providers to generate the following execution plan. Resource actions are indicated with the following symbols:
  - destroy  # -表示删除操作

Terraform will perform the following actions:

  # hashicups_order.edu will be destroyed
  - resource "hashicups_order" "edu" {
      - id           = "1" -> null
      - last_updated = "Tuesday, 26-Oct-21 10:39:15 CST" -> null

      - items {
          - quantity = 3 -> null

          - coffee {
              - id     = 3 -> null
              - image  = "/nomad.png" -> null
              - name   = "Nomadicano" -> null
              - price  = 150 -> null
              - teaser = "Drink one today and you will want to schedule another" -> null
            }
        }
      - items {
          - quantity = 1 -> null

          - coffee {
              - id     = 2 -> null
              - image  = "/vault.png" -> null
              - name   = "Vaulatte" -> null
              - price  = 200 -> null
              - teaser = "Nothing gives you a safe and secure feeling like a Vaulatte" -> null
            }
        }
    }

Plan: 0 to add, 0 to change, 1 to destroy.

Changes to Outputs:
  - edu_order                = {
      - id           = "1"
      - items        = [
          - {
              - coffee   = [
                  - {
                      - description = ""
                      - id          = 3
                      - image       = "/nomad.png"
                      - name        = "Nomadicano"
                      - price       = 150
                      - teaser      = "Drink one today and you will want to schedule another"
                    },
                ]
              - quantity = 3
            },
          - {
              - coffee   = [
                  - {
                      - description = ""
                      - id          = 2
                      - image       = "/vault.png"
                      - name        = "Vaulatte"
                      - price       = 200
                      - teaser      = "Nothing gives you a safe and secure feeling like a Vaulatte"
                    },
                ]
              - quantity = 1
            },
        ]
      - last_updated = "Tuesday, 26-Oct-21 10:39:15 CST"
    } -> null
  - first_coffee_ingredients = {
      - coffee_id   = 3
      - id          = "3"
      - ingredients = [
          - {
              - id       = 1
              - name     = "ingredient - Espresso"
              - quantity = 20
              - unit     = "ml"
            },
          - {
              - id       = 3
              - name     = "ingredient - Hot Water"
              - quantity = 100
              - unit     = "ml"
            },
        ]
    } -> null

签出Provider源码：

git clone --branch boilerplate https://github.com/hashicorp/terraform-provider-hashicups

注意SDKv2的依赖：

github.com/hashicorp/terraform-plugin-sdk/v2 v2.8.0 

分支boilerplate包含一些样板文件。 程序的入口点如下：

package main

import (
	"github.com/hashicorp/terraform-plugin-sdk/v2/helper/schema"
	"github.com/hashicorp/terraform-plugin-sdk/v2/plugin"

	"terraform-provider-hashicups/hashicups"
)

func main() {
    // 启动插件的RPC服务器端
	plugin.Serve(&plugin.ServeOpts{
		ProviderFunc: func() *schema.Provider {
			return hashicups.Provider()
		},
	})
}

Provider函数：

package hashicups

import (
  "github.com/hashicorp/terraform-plugin-sdk/v2/helper/schema"
)

// 定义了一个Provider
func Provider() *schema.Provider {
  return &schema.Provider{
    // 资源映射，从资源类型名到Schema
    ResourcesMap: map[string]*schema.Resource{},
    // 数据资源映射，从资源类型名到Schema。注意资源和数据资源本质上是同一种结构
    DataSourcesMap: map[string]*schema.Resource{},
  }
}

上面已经定义了Provider的骨架，这里我们实现一个咖啡数据源，此数据源能够从HasiCups服务拉取所有售卖的咖啡信息。

建议每个数据源都在独立的源文件中编写，并且文件名以

data_source_

package hashicups

import (
  "context"
  "encoding/json"
  "fmt"
  "net/http"
  "strconv"
  "time"

  "github.com/hashicorp/terraform-plugin-sdk/v2/diag"
  "github.com/hashicorp/terraform-plugin-sdk/v2/helper/schema"
)

// 定义了一个Resource，其中包含Schema以及CRUD操作
func dataSourceCoffees() *schema.Resource {
  return &schema.Resource{
    // 由于数据资源仅仅支持读操作，因此仅声明ReadContext
    ReadContext: dataSourceCoffeesRead,
    Schema: map[string]*schema.Schema{},
  }
}

下面我们完善此数据资源的Schema，根据Terraform的最佳实践，Schema应该尽量和基础实施匹配：

// curl localhost:19090/coffees
[
  {
    "id": 1,
    "name": "Packer Spiced Latte",
    "teaser": "Packed with goodness to spice up your images",
    "description": "",
    "price": 350,
    "image": "/packer.png",
    "ingredients": [
      {
        "ingredient_id": 1
      },
      {
        "ingredient_id": 2
      },
      {
        "ingredient_id": 4
      }
    ]
  }
]

根据服务器返回的咖啡数据结构，编写对应的Schema并且添加到上面的dataSourceCoffees方法中：

Schema: map[string]*schema.Schema{
			"coffees": {
				// 注意这里是列表
				Type:     schema.TypeList,
				Computed: true,
				Elem: &schema.Resource{
					Schema: map[string]*schema.Schema{
						"id": {
							Type:     schema.TypeInt,
							// 此值是"计算得到的"，也就是在创建资源时（除非手工配置）会得到此值的结果
							Computed: true,
						},
						"name": {
							Type:     schema.TypeString,
							Computed: true,
						},
						"teaser": {
							Type:     schema.TypeString,
							Computed: true,
						},
						"description": {
							Type:     schema.TypeString,
							Computed: true,
						},
						"price": {
							Type:     schema.TypeInt,
							Computed: true,
						},
						"image": {
							Type:     schema.TypeString,
							Computed: true,
						},
						// 复杂类型，一个列表
						"ingredients": {
							Type:     schema.TypeList,
							Computed: true,
							// 列表元素的Schema
							Elem: &schema.Resource{
								Schema: map[string]*schema.Schema{
									"ingredient_id": {
										Type:     schema.TypeInt,
										Computed: true,
									},
								},
							},
							// 如果是list(string)，可以这样声明Elem
							Elem: schema.Schema{
								Type:             schema.TypeString,
							},
						},
					},
				},
			},
		},
	}
}

定义好Schema后，我们需要实现读操作： 

//                                              读结果存放在这里          这个m是meta，元参数，
//                                                                     是配置Provider的返回值，下文有说明
func dataSourceCoffeesRead(ctx context.Context, d *schema.ResourceData, m interface{}) diag.Diagnostics {
	client := &http.Client{Timeout: 10 * time.Second}

	// 这是一个切片，用于收集警告或者错误信息
	var diags diag.Diagnostics

	// 像云API发起请求
	req, err := http.NewRequest("GET", fmt.Sprintf("%s/coffees", "http://localhost:19090"), nil)
	if err != nil {
		// 收集错误
		return diag.FromErr(err)
	}
	r, err := client.Do(req)
	if err != nil {
		return diag.FromErr(err)
	}
	defer r.Body.Close()

	// 将响应反串行化到临时对象中
	coffees := make([]map[string]interface{}, 0)
	err = json.NewDecoder(r.Body).Decode(&coffees)
	if err != nil {
		return diag.FromErr(err)
	}

	// schema.ResourceData用于查询和设置资源属性
	//        此方法将响应设置到Terraform数据源，并且保证字段设置到Schema对应位置
	if err := d.Set("coffees", coffees); err != nil {
		return diag.FromErr(err)
	}

	// 设置数据资源的ID
	d.SetId(strconv.FormatInt(time.Now().Unix(), 10))

	return diags
}

数据资源的ID被设置为非空值，这提示Terraform，目标资源已经被创建。 作为一个列表，此数据资源没有真实的ID，因此我们这里设置为时间戳。

如果数据资源被从Terraform外部删除了，这里应该设置空ID：

if resourceDoesntExist {
  d.SetID("")
  return
}

这样Terraform会自动将state中的数据资源清除掉。

将上面的数据资源配置到Provider中：

func Provider() *schema.Provider {
	return &schema.Provider{
		ResourcesMap: map[string]*schema.Resource{},
		DataSourcesMap: map[string]*schema.Resource{
			"hashicups_coffees": dataSourceCoffees(),
		},
	}
}

现在我们开发一个模块，使用上面定义的咖啡数据源。首先需要编译好Provider：

make install

根模块配置：

terraform {
  required_providers {
    hashicups = {
      // 当前构建的版本是0.2
      version = "0.2"
      source  = "hashicorp.com/edu/hashicups"
    }
  }
}

// 目前Provider不支持配置
provider "hashicups" {}

// 调用coffee子模块
module "psl" {
  source = "./coffee"
  // 传递输入参数
  coffee_name = "Packer Spiced Latte"
}

// 打印coffee模块的coffee输出值
output "psl" {
  value = module.psl.coffee
}

coffee子模块配置：

// 子模块需要声明自己的依赖
terraform {
  required_providers {
    hashicups = {
      version = "0.2"
      source  = "hashicorp.com/edu/hashicups"
    }
  }
}

// 输入变量，咖啡品类
variable "coffee_name" {
  type    = string
  default = "Vagrante espresso"
}

// 调用上面开发的数据源，拉取所有咖啡品类
data "hashicups_coffees" "all" {}

# 输出所有咖啡
output "all_coffees" {
  value = data.hashicups_coffees.all.coffees
}

output "coffee" {
  value = {
    // 遍历所有咖啡
    for coffee in data.hashicups_coffees.all.coffees :
    // 返回咖啡ID到咖啡资源的映射
    coffee.id => coffee
    // 过滤，要求名称匹配输入参数
    if coffee.name == var.coffee_name
  }
}

应用根模块：

# terraform init && terraform apply --auto-approve

psl = {
  "1" = {
    "description" = ""
    "id" = 1
    "image" = "/packer.png"
    "ingredients" = tolist([
      {
        "ingredient_id" = 1
      },
      {
        "ingredient_id" = 2
      },
      {
        "ingredient_id" = 4
      },
    ])
    "name" = "Packer Spiced Latte"
    "price" = 350
    "teaser" = "Packed with goodness to spice up your images"
  }
}

本节我们来演示如何为Provider增加参数，Provider的实现又是如何读取这些参数的。

func Provider() *schema.Provider {
	return &schema.Provider{
		// ...
		// 定义Provider的配置参数
		Schema: map[string]*schema.Schema{
			"username": {
				Type:        schema.TypeString,
				Optional:    true,
				DefaultFunc: schema.EnvDefaultFunc("HASHICUPS_USERNAME", nil),
			},
			"password": {
				Type:        schema.TypeString,
				Optional:    true,
				// 敏感数据，在输出时会处理
				Sensitive:   true,
				// 默认值函数                        从环境变量读取默认值
				DefaultFunc: schema.EnvDefaultFunc("HASHICUPS_PASSWORD", nil),
			},
		},
		ConfigureContextFunc: providerConfigure,
	}
}

用户提供的username/password，如何被Provider的ReadContext函数访问呢？这需要配置Provider。配置过程是由

schema.Provider

ConfigureContextFunc

func providerConfigure(ctx context.Context, d *schema.ResourceData) (interface{}, diag.Diagnostics) {
	// 读取Provider的配置参数
	username := d.Get("username").(string)
	password := d.Get("password").(string)

	var diags diag.Diagnostics

	if (username != "") && (password != "") {
		c, err := hashicups.NewClient(nil, &username, &password)
		if err != nil {
			return nil, diag.FromErr(err)
		}

		return c, diags
	}

	c, err := hashicups.NewClient(nil, nil, nil)
	if err != nil {
		return nil, diag.FromErr(err)
	}

	return c, diags
}

可以看到配置Provider后，会返回一个interface{}，这个对象会传递给CRUD操作的最后一个参数：

// See Resource documentation.
type CreateContextFunc func(context.Context, *ResourceData, interface{}) diag.Diagnostics

// See Resource documentation.
type ReadContextFunc func(context.Context, *ResourceData, interface{}) diag.Diagnostics

// See Resource documentation.
type UpdateContextFunc func(context.Context, *ResourceData, interface{}) diag.Diagnostics

// See Resource documentation.
type DeleteContextFunc func(context.Context, *ResourceData, interface{}) diag.Diagnostics

一般情况下，这个interface{}是配置好的云API客户端，或者是云API配置结构。

本节我们演示如何在读操作中使用Provider参数，更精确的说是基于这些参数配置Provider后的结果。

首先我们创建几个咖啡订单（用于后续查询）：

curl -X POST -H "Authorization: ${HASHICUPS_TOKEN}" localhost:19090/orders -d '[{"coffee": { "id":1 }, "quantity":4}, {"coffee": { "id":3 }, "quantity":3}]'

看一下订单的数据结构：

// curl -X GET -H "Authorization: ${HASHICUPS_TOKEN}" localhost:19090/orders/2 

{
  "id": 2,
  "items": [
    {
      "coffee": {
        "id": 1,
        "name": "Packer Spiced Latte",
        "teaser": "Packed with goodness to spice up your images",
        "description": "",
        "price": 350,
        "image": "/packer.png",
        "ingredients": null
      },
      "quantity": 4
    },
    {
      "coffee": {
        "id": 3,
        "name": "Nomadicano",
        "teaser": "Drink one today and you will want to schedule another",
        "description": "",
        "price": 150,
        "image": "/nomad.png",
        "ingredients": null
      },
      "quantity": 3
    }
  ]
}

下面我们定义对应的数据源：

func dataSourceOrder() *schema.Resource {
	return &schema.Resource{
		// 读取操作，见下文
		ReadContext: dataSourceOrderRead,
		Schema: map[string]*schema.Schema{
			"id": {
				Type:     schema.TypeInt,
				Required: true,
			},
			"items": {
				Type:     schema.TypeList,
				Computed: true,
				Elem: &schema.Resource{
					Schema: map[string]*schema.Schema{
						"coffee_id": {
							Type:     schema.TypeInt,
							Computed: true,
						},
						"coffee_name": {
							Type:     schema.TypeString,
							Computed: true,
						},
						"coffee_teaser": {
							Type:     schema.TypeString,
							Computed: true,
						},
						"coffee_description": {
							Type:     schema.TypeString,
							Computed: true,
						},
						"coffee_price": {
							Type:     schema.TypeInt,
							Computed: true,
						},
						"coffee_image": {
							Type:     schema.TypeString,
							Computed: true,
						},
						"quantity": {
							Type:     schema.TypeInt,
							Computed: true,
						},
					},
				},
			},
		},
	}
}

注意这个数据源的Schema和API的结构没有做对应，进行了扁平化处理。

读取订单的操作如下：

func dataSourceOrderRead(ctx context.Context, d *schema.ResourceData, m interface{}) diag.Diagnostics {
	// 配置Provider后，得到的是一个客户端
	c := m.(*hc.Client)
	var diags diag.Diagnostics

	orderID := strconv.Itoa(d.Get("id").(int))

	// 基于此客户端进行订单查询
	order, err := c.GetOrder(orderID)
	if err != nil {
		return diag.FromErr(err)
	}

	// 订单结构和我们数据源的结构不一致，这里做转换
	orderItems := flattenOrderItemsData(&order.Items)
	if err := d.Set("items", orderItems); err != nil {
		return diag.FromErr(err)
	}

	d.SetId(orderID)

	return diags
}

将此资源注册到Provider：

func Provider() *schema.Provider {
	return &schema.Provider{
		// ...
		DataSourcesMap: map[string]*schema.Resource{
			// ...
			"hashicups_order":   dataSourceOrder(),
		},
		ConfigureContextFunc: providerConfigure,
	}
}

在配置文件中使用该数据源：

data "hashicups_order" "order" {
  id = 1
}

output "order" {
  value = data.hashicups_order.order
}

本节演示如何基于日志来调试Provider，我们会添加定制的错误消息，并且显示详细的Terraform Provider日志。

开发Provider时需要实现很多函数，这些函数常常具有一个返回值

diag.Diagnostics

type ConfigureContextFunc func(context.Context, *ResourceData) (interface{}, diag.Diagnostics)

警告/错误级别的调试信息，都要放到diag.Diagnostics中，执行Terraform CLI命令时，这些信息会自动打印。

当创建HashiCups客户端失败时，我们可以添加一条针对信息：

func providerConfigure(ctx context.Context, d *schema.ResourceData) (interface{}, diag.Diagnostics) {
	// ...
	if (username != "") && (password != "") {
		c, err := hashicups.NewClient(nil, &username, &password)
		if err != nil {
			diags = append(diags, diag.Diagnostic{
				Severity: diag.Error,
				Summary:  "Unable to create HashiCups client",
				Detail:   "Unable to auth user for authenticated HashiCups client",
			})
			return nil, diags
		}

		return c, diags
	}

	c, err := hashicups.NewClient(nil, nil, nil)
	if err != nil {
		diags = append(diags, diag.Diagnostic{
			Severity: diag.Error,
			Summary:  "Unable to create HashiCups client",
			Detail:   "Unable to auth user for authenticated HashiCups client",
		})
		return nil, diags
	}

	return c, diags
}

执行命令时，错误信息会打印出来：

terraform init && terraform apply --auto-approve
## ...
module.psl.data.hashicups_coffees.all: Refreshing state...

# 摘要
Error: Unable to create HashiCups client
# 详情
Unable to auth user for authenticated HashiCups client

资源支持创建、修改、删除等写操作，上面编写的数据源则仅支持读。尽管资源、数据源可能指向同一类实体，但是Schema不能共用。

资源的文件名前缀通常使用

resource_

package hashicups

import (
  "context"

  "github.com/hashicorp/terraform-plugin-sdk/v2/diag"
  "github.com/hashicorp/terraform-plugin-sdk/v2/helper/schema"
)

func resourceOrder() *schema.Resource {
  return &schema.Resource{
    CreateContext: resourceOrderCreate,
    ReadContext:   resourceOrderRead,
    UpdateContext: resourceOrderUpdate,
    DeleteContext: resourceOrderDelete,
    Schema: map[string]*schema.Schema{},
  }
}

func resourceOrderCreate(ctx context.Context, d *schema.ResourceData, m interface{}) diag.Diagnostics {
  // Warning or errors can be collected in a slice type
  var diags diag.Diagnostics

  return diags
}

func resourceOrderRead(ctx context.Context, d *schema.ResourceData, m interface{}) diag.Diagnostics {
  // Warning or errors can be collected in a slice type
  var diags diag.Diagnostics

  return diags
}

func resourceOrderUpdate(ctx context.Context, d *schema.ResourceData, m interface{}) diag.Diagnostics {
  return resourceOrderRead(ctx, d, m)
}

func resourceOrderDelete(ctx context.Context, d *schema.ResourceData, m interface{}) diag.Diagnostics {
  // Warning or errors can be collected in a slice type
  var diags diag.Diagnostics

  return diags
}

我们需要将其注册到Provider：

func Provider() *schema.Provider {
	return &schema.Provider{
		// ...
		ResourcesMap: map[string]*schema.Resource{
			"hashicups_order": resourceOrder(),
		},
		// ...
	}
}

不同于上问的订单数据源，这里我们设计了和API结构更加匹配的Schema：

Schema: map[string]*schema.Schema{
			"items": {
				Type:     schema.TypeList,
				Required: true,
				Elem: &schema.Resource{
					Schema: map[string]*schema.Schema{
						"coffee": {
							Type:     schema.TypeList, // coffee明明是一个，还非得声明为列表
							MaxItems: 1,
							Required: true,
							Elem: &schema.Resource{
								Schema: map[string]*schema.Schema{
									"id": {
										Type:     schema.TypeInt,
										Required: true,
									},
									"name": {
										Type:     schema.TypeString,
										Computed: true,
									},
									"teaser": {
										Type:     schema.TypeString,
										Computed: true,
									},
									"description": {
										Type:     schema.TypeString,
										Computed: true,
									},
									"price": {
										Type:     schema.TypeInt,
										Computed: true,
									},
									"image": {
										Type:     schema.TypeString,
										Computed: true,
									},
								},
							},
						},
						"quantity": {
							Type:     schema.TypeInt,
							Required: true,
						},
					},
				},
			},
		}

注意和订单数据源Schema的其它几个重要区别：

1. 在资源Schema中，顶级的id属性不存在。这是因为资源中你无法提前知道id，也不能将id作为输入参数。id是在资源创建过程中自动生成的
2. 在资源Schema中，items是必须字段，而不是计算出的字段。这是因为我们在配置中声明订单资源时必须提供订单项信息

func resourceOrderCreate(ctx context.Context, d *schema.ResourceData, m interface{}) diag.Diagnostics {
	// 元参数的真实类型是HashCups客户端
	c := m.(*hc.Client)
	var diags diag.Diagnostics

	// 从ResourceData中获得订单条目（的参数）
	items := d.Get("items").([]interface{})
	ois := []hc.OrderItem{}

	// 遍历订单条目，构造为HashCups客户端所需的OrderItem
	for _, item := range items {
		i := item.(map[string]interface{})

		co := i["coffee"].([]interface{})[0] // 只取第一个coffee，为何非要定义为列表
		coffee := co.(map[string]interface{})

		oi := hc.OrderItem{
			Coffee: hc.Coffee{
				ID: coffee["id"].(int),
			},
			Quantity: i["quantity"].(int),
		}

		ois = append(ois, oi)
	}

	// 调用客户端创建订单
	o, err := c.CreateOrder(ois)
	if err != nil {
		return diag.FromErr(err)
	}

	// 将生成的标识符设置为资源ID
	d.SetId(strconv.Itoa(o.ID))

	return diags
}

实现了创建操作后，必须同时实现读操作，并在创建操作中调用读操作，这样才能在创建资源后，立即以最新资源填充state：

func resourceOrderCreate(ctx context.Context, d *schema.ResourceData, m interface{}) diag.Diagnostics {
	// ...
	d.SetId(strconv.Itoa(o.ID))

	resourceOrderRead(ctx, d, m)

	return diags
}

func resourceOrderRead(ctx context.Context, d *schema.ResourceData, m interface{}) diag.Diagnostics {
  c := m.(*hc.Client)
  var diags diag.Diagnostics
  // 读操作时，资源的ID是已知的（从state中获取）
  orderID := d.Id()
  // 根据ID查询订单
  order, err := c.GetOrder(orderID)
  if err != nil {
    return diag.FromErr(err)
  }
  // 结构转换
  orderItems := flattenOrderItems(&order.Items)
  if err := d.Set("items", orderItems); err != nil {
    return diag.FromErr(err)
  }

  return diags
}

func flattenOrderItems(orderItems *[]hc.OrderItem) []interface{} {
  if orderItems != nil {
    ois := make([]interface{}, len(*orderItems), len(*orderItems))

    for i, orderItem := range *orderItems {
      oi := make(map[string]interface{})

      oi["coffee"] = flattenCoffee(orderItem.Coffee)
      oi["quantity"] = orderItem.Quantity
      ois[i] = oi
    }

    return ois
  }

  return make([]interface{}, 0)
}

func flattenCoffee(coffee hc.Coffee) []interface{} {
  c := make(map[string]interface{})
  c["id"] = coffee.ID
  c["name"] = coffee.Name
  c["teaser"] = coffee.Teaser
  c["description"] = coffee.Description
  c["price"] = coffee.Price
  c["image"] = coffee.Image

  return []interface{}{c}
}

下面的配置，创建了一个订单，并且输出其内容

resource "hashicups_order" "edu" {
  // 订单的Schema中，items是List，要为其声明多个元素，多次添加items块
  items {
    // 订单的Schema中，coffee也是一个List
    coffee {
      id = 3
    }
    quantity = 2
  }
  items {
    coffee {
      id = 2
    }
    quantity = 2
  }
}

output "edu_order" {
  value = hashicups_order.edu
}

func resourceOrder() *schema.Resource {
	return &schema.Resource{
		// ...
		UpdateContext: resourceOrderUpdate,
		Schema: map[string]*schema.Schema{
			"last_updated": &schema.Schema{
				Type:     schema.TypeString,
				Optional: true,  // 可选字段，允许配置时不提供
				Computed: true,  // 在创建时自动计算出（由Provider给出）
			},
			"items": &schema.Schema{ 
			/...

// 判断指定的键，对应的值是否改变了。通过对比比较配置文件前后的差异达成
	if d.HasChange("items") {
		items := d.Get("items").([]interface{})
		ois := []hc.OrderItem{}

		for _, item := range items {
			i := item.(map[string]interface{})

			co := i["coffee"].([]interface{})[0]
			coffee := co.(map[string]interface{})

			oi := hc.OrderItem{
				Coffee: hc.Coffee{
					ID: coffee["id"].(int),
				},
				Quantity: i["quantity"].(int),
			}
			ois = append(ois, oi)
		}
		// 调用HashCups API更新灯胆
		_, err := c.UpdateOrder(orderID, ois)
		if err != nil {
			return diag.FromErr(err)
		}

		// 更新 last_updated字段
		d.Set("last_updated", string(time.Now().Format(time.RFC850)))
	}
	
	// 总是重新读取订单最新状态
	return resourceOrderRead(ctx, d, m)

func resourceOrderDelete(ctx context.Context, d *schema.ResourceData, m interface{}) diag.Diagnostics {
	c := m.(*hc.Client)
	var diags diag.Diagnostics

	orderID := d.Id()
	// 调用HashiCups API执行删除
	err := c.DeleteOrder(orderID)
	if err != nil {
		return diag.FromErr(err)
	}

	// 注意：d.SetId("") 会在本方法无错误返回的情况下，自动调用
	// 通常不需要手工调用
	d.SetId("")

	return diags
}

Terraform处理该回调的返回值的逻辑：

1. 如果没有返回错误，则Terraform认为资源被删除，其所有状态信息被从state中移除
2. 如果返回了错误，则Terraform认为资源仍然存在，其所有状态信息会被保留

该回调：

1. 永远不应该更新资源的任何状态
2. 总是应当处理资源已经被删除的场景，这种情况下不应该返回错误
3. 如果云API不支持删除操作，则该回调应该检查资源是否存在，如果不存在则设置ID为""，确保资源从state中删除

导入操作能够通过API拉取已经存在的订单，并且同步到Terraform state中，不进行创建订单的操作。 导入的资源和通过Terraform创建的资源已有，被Terraform管理。

func resourceOrder() *schema.Resource {
	return &schema.Resource{
		// ...
		Importer: &schema.ResourceImporter{
			StateContext: schema.ImportStatePassthroughContext,
		},
	}
}

StateContext被设置为Terraform库提供的函数schema.ImportStatePassthroughContext，该函数签名为：

// StateContextFunc用于导入资源到Terraform state。入参是仅仅设置了ID的资源，这个ID
// 由用户提供，因此需要校验
// 返回值是ResourceData，代表需要存入state的资源状态。最简单的情况下，仅仅包含原封不动的入参
type StateContextFunc func(context.Context, *ResourceData, interface{}) ([]*ResourceData, error)

函数的实现很简单，就是直接把入参返回：

func ImportStatePassthroughContext(ctx context.Context, d *ResourceData, m interface{}) ([]*ResourceData, error) {
	return []*ResourceData{d}, nil
}

terraform import hashicups_order.sample <order_id>

上述命令将名为sample的hasicups_order和指定的订单ID关联起来。Terraform会调用Importer，并将ID传递给resourceOrderRead来读取完整的状态。

从导入操作我们可以看到，资源的唯一性ID很重要。某些情况下，我们可能需要从云API的多个字段去构造ID，例如

<region>:<resource_id>

Terraform Registry是Provider和Module的公共仓库。如果你开发了有复用价值的Provider，可以考虑上传到其中。

几乎所有Provider为用户提供配置参数，以实现云API的访问凭证、Region信息等的可定制化。下面的资源，允许你提供uuid、name两个参数：

func resourceExampleResource() *schema.Resource {
    return &schema.Resource{
        // 每个资源，从根上来说，是一个{键值}结构
        //                 需要为每个值指定Schema
        Schema: map[string]*schema.Schema{
            "uuid": {
                // 指定值的类型
                Type:     schema.TypeString,
                // 这个字段会在资源创建时，自动生成
                Computed: true,
            },

            "name": {
                Type:         schema.TypeString,
                // 这是必须字段，用户必须提供
                Required:     true,
                // 该字段改变后，资源会被删除、重新创建
                ForceNew:     true,
                // 该字段的校验逻辑
                ValidateFunc: validatName,
            },
        },
    }
}

类型可以分为两大类：基本类型、聚合类型。

基本类型包括：

"encrypted": {
  Type:     schema.TypeBool,
}, 

resource "example_volume" "ex" {
  encrypted = true
}

"encrypted": "true",

"cores": {
  Type:     schema.TypeInt,
},

resource "example_compute_instance" "ex" {
  cores = 16
}

"cores": "16",

"price": {
  Type:     schema.TypeFloat,
},

resource "example_spot_request" "ex" {
  price = 0.37
}

"price": "0.37",

"name": {
  Type:     schema.TypeString,
},

resource "example_spot_request" "ex" {
  description = "Managed by Terraform"
}

"description": "Managed by Terraform",

"expiration": {
  Type:         schema.TypeString,
  ValidateFunc: validation.ValidateRFC3339TimeString,
},

resource "example_resource" "ex" {
  expiration = "2006-01-02T15:04:05+07:00"
} 

"expiration": "2006-01-02T15:04:05+07:00",

聚合类型包括：

类型	Schema示例 配置示例	状态表示
TypeMap	(map[string]interface{}) "tags": { Type: schema.TypeMap, Elem: &schema.Schema{ Type: schema.TypeString, }, }, resource "example_compute_instance" "ex" { tags { env = "development" name = "example tag" } }	# 元素数量 "tags.%": "2", "tags.env": "development", "tags.name": "example tag",
TypeList	([]interface{}) "termination_policies": { Type: schema.TypeList, Elem: &schema.Schema{ Type: schema.TypeString, }, }, resource "example_compute_instance" "ex" { termination_policies = ["OldestInstance", "ClosestToNextInstanceHour"] }	# 元素数量 "name_servers.#": "4", "name_servers.0": "ns-1508.awsdns-60.org", "name_servers.1": "ns-1956.awsdns-52.co.uk",
TypeSet	(*schema.Set) "ingress": { Type: schema.TypeSet, Elem: &schema.Resource{ Schema: map[string]*schema.Schema{ "from_port": { Type: schema.TypeInt, Required: true, }, "to_port": { Type: schema.TypeInt, Required: true, }, }, } resource "example_security_group" "ex" { name = "sg_test" description = "managed by Terraform" ingress { protocol = "tcp" from_port = 80 to_port = 9000 cidr_blocks = ["10.0.0.0/8"] } ingress { protocol = "tcp" from_port = 80 to_port = 8000 cidr_blocks = ["0.0.0.0/0", "10.0.0.0/8"] } }	"ingress.#": "2", "ingress.1061987227.cidr_blocks.#": "1", "ingress.1061987227.cidr_blocks.0": "10.0.0.0/8", "ingress.1061987227.description": "", "ingress.1061987227.from_port": "80", "ingress.1061987227.ipv6_cidr_blocks.#": "0", "ingress.1061987227.protocol": "tcp", "ingress.1061987227.security_groups.#": "0", "ingress.1061987227.self": "false",

Schema的一些字段的设置，会对Terraform的plan/apply行为产生影响。

字段	影响
Optional	是否在配置中是可选的
Required	是否必须在配置中提供
Computed	提示字段不能由用户提供，并且在terraform apply之前，其值是未知的
ForceNew	对资源的该字段的修改，会导致删除并重新创建资源
Default	如果用户没有配置，使用的默认值
DiffSuppressFunc	用于计算该字段的（前后值的）差异，下面的例子，不区分大小写： "base_image": { Type: schema.TypeString, DiffSuppressFunc: func(k, old, new string, d *schema.ResourceData) bool { if strings.ToLower(old) == strings.ToLower(new) { return true } return false }, },
DefaultFunc	用于动态提供默认值
StateFunc	将字段转换为一个字符串，该字符串存储在state中
ValidateFunc	校验该字段

Terrafrom通过比较用户提供的配置、资源的state，来确定是否需要更新。

可以为schema.Resource传递CustomizeDiff，该回调和Terraform生成的Diff（表示资源的变更）一起工作，它可以：

1. 修改Diff
2. 否决Diff，终止计划

type CustomizeDiffFunc func(context.Context, *ResourceDiff, interface{}) error

云上的很多操作比较耗时，例如启动操作系统、跨越网络边缘复制状态。开发Provider时，应该注意考虑云API的延迟，Terraform支持为资源的各种操作设置超时：

func resourceExampleInstance() *schema.Resource {
    return &schema.Resource{
        // ...
        Timeouts: &schema.ResourceTimeout{
            Create: schema.DefaultTimeout(45 * time.Minute),
        },
    }
}

Terraform提供了一个重试助手函数：

type RetryFunc func() *RetryError

func RetryContext(ctx context.Context, timeout time.Duration, f RetryFunc) error

RetryContext能够反复重试RetryFunc：

1. timeout指定Terraform调用RetryFunc的最大用时。可以传递

   schema.TimeoutCreate

   给

   *schema.ResourceData.Timeout()

   获取用户配置的超时值
2. RetryFunc可以返回：
   1. resource.NonRetryableError，这样直接导致重试终止
   2. resource.RetryableError，这样会重试

基于测试用例来组织，每个用例使用1-N个Terraform配置，创建一些资源，并并验证实际创建的基础设施对象符合预期。

Terraform的

resource

Test()

*testing.T

TestCase

下面是一个例子，它测试一个名为Example的Provider，被测试的资源是Widget：

package example

var testAccProviders map[string]*schema.Provider
var testAccProvider *schema.Provider

func init() {
	testAccProvider = Provider()
	// 被测试Provider
	testAccProviders = map[string]*schema.Provider{
		"example": testAccProvider,
	}
}

// 方法命名约定TestAccXxx
func TestAccExampleWidget_basic(t *testing.T) {
	var widgetBefore, widgetAfter example.Widget
	rName := acctest.RandStringFromCharSet(10, acctest.CharSetAlphaNum)

	// 大部分可接受测试，都是仅仅调用Test方法并退出
	// 任何时候（不管是PreCheck还是Steps...）出错，框架都会调用t.Error()方法，导致测试失败并终止
	resource.Test(t, resource.TestCase{
		// 是否单元测试。该参数允许在不考虑TF_ACC环境变量的情况下运行测试。应当仅仅用于本地资源的快速测试
		// 默认情况下，如果没有设置环境变量TF_ACC，测试会立即失败
		IsUnitTest: false,
		// 在任何Steps之前，允许的回调，通常用来检查测试需要的值（例如用于配置Provider的环境变量）存在
		PreCheck: func() { testAccPreCheck(t) },

		// map[string]*schema.Provider类型，表示将被测试的Providers。配置文件中引用的任何Provider都
		// 需要在此配置，否则用例会报错
		Providers:    testAccProviders,
		// 注意：Providers已经废弃，请使用ProviderFactories代替
		ProviderFactories: map[string]func() (*schema.Provider, error),
		// 类似ProviderFactories，但是用于基于terraform-plugin-go ProviderServer接口实现
		// Protocol V5的Provider
		ProtoV5ProviderFactories map[string]func() (tfprotov5.ProviderServer, error)
		// 类似ProviderFactories，但是用于基于terraform-plugin-go ProviderServer接口实现
		// Protocol V6的Provider
		ProtoV6ProviderFactories map[string]func() (tfprotov6.ProviderServer, error)

		// 所有Steps运行之后，并且Terraform已经针对state运行了destroy命令之后执行的回调
		// 该方法以最后一次已知的staet作为入参，通常直接使用基础设施的SDK来确认目标对象已都不存在
		// 如果应该被删除的对象仍然存在，此方法应该报错
		CheckDestroy: testAccCheckExampleResourceDestroy,
		// 允许Provider有选择性的处理错误，例如基于特定错误，跳过某些测试
		ErrorCheck ErrorCheckFunc,
		// 一个TestStep，通常对应单次apply。基础的测试包含1-2个Step，验证资源可以被创建，然后更新
		Steps: []resource.TestStep{
			{
				Config: testAccExampleResource(rName),
				Check: resource.ComposeTestCheckFunc(
					testAccCheckExampleResourceExists("example_widget.foo", &widgetBefore),
				),
			},
			{
				Config: testAccExampleResource_removedPolicy(rName),
				Check: resource.ComposeTestCheckFunc(
					testAccCheckExampleResourceExists("example_widget.foo", &widgetAfter),
				),
			},
		},
	})
}

每个TestStep需要Terraform Configuration作为输入，提供多种验证被测试资源行为的方法。

Terraform的测试框架支持两个独立的测试模式：

1. Lifecycle模式，常用，提供1-N个配置文件并测试Provider在terraform apply时的行为
2. Import模式，测试Provider在terraform import时的行为

测试模式被传递给TestStep的字段隐式的确定。

每个TestStep包含一个需要被Apply的配置（由Config字段给出）、0-N个校验（在Check字段中编排），多个TestStep按顺序，依次执行。

当需要执行多个校验时，需要使用下面的函数之一来编排：

ComposeTestCheckFunc

ComposeAggregateTestCheckFunc

Steps: []resource.TestStep{
  {
    Check: resource.ComposeTestCheckFunc(
      // 检查资源是否存在于基础设施
      testAccCheckExampleResourceExists("example_widget.foo", &widgetBefore), 
      // 校验资源属性
      resource.TestCheckResourceAttr("example_widget.foo", "size", "expected size"),
    ),
  },
},

ComposeAggregateTestCheckFunc的区别是，尽管也是顺序执行校验，但是某个校验失败，并不会立即停止，还会继续执行其它校验，收集所有错误。 

Terratform将所有stderr的输出都通过gRPC协议传输到CLI，并打印到控制台。编写插件时，绝不要将日志打印到stdout，因为stdout作为Terraform内部到CLI的通信通道。

建议使用Go内置的

log.Println

log.Printf

log.Println("[DEBUG] Something happened!")

Terraform使用环境变量

TF_LOG

export TF_LOG=DEBUG

可以使用环境变量

TF_LOG_CORE

TF_LOG_PROVIDER

如果需要输出到文件，使用环境变量

TF_LOG_PATH

使用下面的代码，在Provider中启用单步跟踪支持：

func main() {
    var debugMode bool

    flag.BoolVar(&debugMode, "debug", false, "set to true to run the provider with support for debuggers like delve")
    flag.Parse()

    opts := &plugin.ServeOpts{ProviderFunc: provider.New}

    if debugMode {
        //            调试模式
        err := plugin.Debug(context.Background(), "registry.terraform.io/my-org/my-provider", opts)
        if err != nil {
            log.Fatal(err.Error())
        }
        return
    }
    //     正常模式
    plugin.Serve(opts)
}

关于调试模式，需要注意：

1. 在此模式下，Terraform不会启动Provider进程，你需要手工启动它：
   

   dlv exec --headless ./terraform-provider-my-provider -- --debug

2. 你需要将IDE连接到到dlv进程，这时Provider会打印日志：
   

   Provider started, to attach Terraform set the TF_REATTACH_PROVIDERS env var:
   
           TF_REATTACH_PROVIDERS='{"registry.terraform.io/my-org/my-provider":{"Protocol":"grpc","Pid":3382870,"Test":true,"Addr":{"Network":"unix","String":"/tmp/plugin713096927"}}}' 

3. 你需要export上述日志输出的环境变量，然后执行Terraform CLI
4. 在terraform init时不会对Provider进行约束检查
5. 当遍历了Terraform资源依赖图后，Provider进程不会被重启 

在运行可接受测试的时候，直接在当前测试进程中运行Provider，因此可以进行单步跟踪而不需要特别设置。

Terraform Plugin Framework是新的（但还不稳定）Provider开发方式，关于它的优缺点，上文已经介绍过。本章主要以例子说明如何使用该框架。

要使用TPF，在go.mod增加依赖：

github.com/hashicorp/terraform-plugin-framework v0.4.2 

package main

import (
    "context"
    "github.com/hashicorp/terraform-plugin-framework/tfsdk"
    "terraform-provider-hashicups/hashicups"
)

func main() {
    tfsdk.Serve(context.Background(), hashicups.New, tfsdk.ServeOpts{
        Name: "hashicups",
    })
}

tfsdk.Serve函数的第二个参数，就是任何Provider需要实现的接口：

type Provider interface {
	// 返回配置Provider的Schema，如果Provider不需要配置返回空的Schema
	GetSchema(context.Context) (Schema, diag.Diagnostics)

	// 在Provider生命周期的最初期此方法被调用，Terraform会此方法发送用户在provider块中
	// 提供的参数，并且存放在ConfigureProviderRequest中。注意，Terraform不保证此方法调用时，
	// 所有参数都是Known的。如果Provider在某些参数在Unknown的时候仍然可被配置，建议发出警告
	// 否则发出错误
	Configure(context.Context, ConfigureProviderRequest, *ConfigureProviderResponse)

	// 返回此Provider支持的资源类型列表
	// 资源列表的键，是资源的名字，并且应当以Provider名为前缀
	GetResources(context.Context) (map[string]ResourceType, diag.Diagnostics)

	// 返回此Provider支持的数据源类型列表
	// 资源列表的键，是资源的名字，并且应当以Provider名为前缀
	GetDataSources(context.Context) (map[string]DataSourceType, diag.Diagnostics)
}

package hashicups

import (
    "context"
    "os"

    "github.com/hashicorp-demoapp/hashicups-client-go"
    "github.com/hashicorp/terraform-plugin-framework/diag"
    "github.com/hashicorp/terraform-plugin-framework/tfsdk"
    "github.com/hashicorp/terraform-plugin-framework/types"
)

var stderr = os.Stderr

func New() tfsdk.Provider {
    return &provider{}
}

type provider struct {
    configured bool
    client     *hashicups.Client
}

GetSchema方法，获取Provider的配置参数的Schema： 

// GetSchema
func (p *provider) GetSchema(_ context.Context) (tfsdk.Schema, diag.Diagnostics) {
    return tfsdk.Schema{
        Attributes: map[string]tfsdk.Attribute{
            "host": {
                Type:     types.StringType,
                Optional: true,
                Computed: true,
            },
            "username": {
                Type:     types.StringType,
                Optional: true,
                Computed: true,
            },
            "password": {
                Type:      types.StringType,
                Optional:  true,
                Computed:  true,
                Sensitive: true,
            },
        },
    }, nil
}

// Provider schema struct
type providerData struct {
    Username types.String `tfsdk:"username"`
    Host     types.String `tfsdk:"host"`
    Password types.String `tfsdk:"password"`
}

// req 代表Terraform在配置Provider时，发送过来的请求
// resp 代表响应
func (p *provider) Configure(ctx context.Context, req tfsdk.ConfigureProviderRequest, 
                                                  resp *tfsdk.ConfigureProviderResponse) {

	var config providerData
	// 从用户给出的Provider配置中取出数据，存放到providerData中
	diags := req.Config.Get(ctx, &config)
	resp.Diagnostics.Append(diags...)
	if resp.Diagnostics.HasError() {
		return
	}

	// 校验username password host是否提供
	var username string
	// 值不能是未知的
	if config.Username.Unknown {
		// Cannot connect to client with an unknown value
		resp.Diagnostics.AddWarning(
			"Unable to create client",
			"Cannot use unknown value as username",
		)
		return
	}

	// 如果值没有设置（或者被明确的设置为null），则尝试从环境变量读取
	if config.Username.Null {
		username = os.Getenv("HASHICUPS_USERNAME")
	} else {
		username = config.Username.Value
	}

	// 如果配置是空字符串，并且也没有配置环境变量，则报错
	if username == "" {
		// Error vs warning - empty value must stop execution
		resp.Diagnostics.AddError(
			"Unable to find username",
			"Username cannot be an empty string",
		)
		return
	}
	// password, host类似...

	c, err := hashicups.NewClient(&host, &username, &password)
	if err != nil {
		resp.Diagnostics.AddError(
			"Unable to create client",
			"Unable to create hashicups client:\n\n"+err.Error(),
		)
		return
	}

	p.client = c
	p.configured = true
}

package hashicups

import (
    "github.com/hashicorp/terraform-plugin-framework/types"
)

// Order -
type Order struct {
    ID          types.String `tfsdk:"id"`
    Items       []OrderItem  `tfsdk:"items"`
    LastUpdated types.String `tfsdk:"last_updated"`
}

// OrderItem -
type OrderItem struct {
    Coffee   Coffee `tfsdk:"coffee"`
    Quantity int    `tfsdk:"quantity"`
}

// Coffee -
// This Coffee struct is for Order.Items[].Coffee which does not have an
// ingredients field in the schema defined in the provider code. Since the
// resource schema must match the struct exactly (any extra field will return an
// error), this struct has Ingredients commented out.
type Coffee struct {
    ID          int          `tfsdk:"id"`
    Name        types.String `tfsdk:"name"`
    Teaser      types.String `tfsdk:"teaser"`
    Description types.String `tfsdk:"description"`
    Price       types.Number `tfsdk:"price"`
    Image       types.String `tfsdk:"image"`
    // Ingredients []Ingredient   `tfsdk:"ingredients"`
}

注意：资源模型必须和资源的Schema（如下节）严格匹配，如果模型里面有某字段，而Schema没有，会导致出错。

TPF和SDKv2比起来，一个优势是实现了模型字段的自动绑定，不再需要一个个字段手工设置。但是这个模型不一定能和云API返回的资源结构自动的相互转换。

首先需要声明Provider支持哪些资源，即提供资源名称（对应resource块第2标签）到资源类型

tfsdk.ResourceType

func (p *provider) GetResources(_ context.Context) (map[string]tfsdk.ResourceType, diag.Diagnostics) {
    return map[string]tfsdk.ResourceType{
        "hashicups_order": resourceOrderType{},
    }, nil
}

资源类型需要实现下面的接口：

type ResourceType interface {
	// 返回资源的Schema
	GetSchema(context.Context) (Schema, diag.Diagnostics)

	// 创建该资源类型的Resource对象
	NewResource(context.Context, Provider) (Resource, diag.Diagnostics)
} 

type resourceOrderType struct{}

func (r resourceOrderType) GetSchema(_ context.Context) (tfsdk.Schema, diag.Diagnostics) {
    return tfsdk.Schema{
        Attributes: map[string]tfsdk.Attribute{
            "id": {
                Type: types.StringType,
                Computed: true,
            },
            "last_updated": {
                Type:     types.StringType,
                Computed: true,
            },
            "items": {
                Required: true,
                Attributes: tfsdk.ListNestedAttributes(map[string]tfsdk.Attribute{
                    "quantity": {
                        Type:     types.NumberType,
                        Required: true,
                    },
                    "coffee": {
                        Required: true,
                        Attributes: tfsdk.SingleNestedAttributes(map[string]tfsdk.Attribute{
                            "id": {
                                Type:     types.NumberType,
                                Required: true,
                            },
                            "name": {
                                Type:     types.StringType,
                                Computed: true,
                            },
                            "teaser": {
                                Type:     types.StringType,
                                Computed: true,
                            },
                            "description": {
                                Type:     types.StringType,
                                Computed: true,
                            },
                            "price": {
                                Type:     types.NumberType,
                                Computed: true,
                            },
                            "image": {
                                Type:     types.StringType,
                                Computed: true,
                            },
                        }),
                    },
                }, tfsdk.ListNestedAttributesOptions{}),
            },
        },
    }, nil
}

资源类型的NewResource方法返回的是Resource类型，它抽象了针对单个资源的CRUD操作：

type Resource interface {
	// 当Provider需要创建一个新资源的时候调用此方法。配置和planned state可以从
	// CreateResourceRequest读取。新的（实际完成创建后的）state则设置到
	// CreateResourceResponse
	Create(context.Context, CreateResourceRequest, *CreateResourceResponse)

	// 当Provider需要读取资源values来更新state时调用此方法。从
	// ReadResourceRequest读取planned state，新的state则设置到
	// ReadResourceResponse.
	Read(context.Context, ReadResourceRequest, *ReadResourceResponse)

	// 当Provider需要更新资源状态时调用此方法。配置和planned state可以从
	// UpdateResourceRequest读取。新的（更新后的）state则设置到
	// UpdateResourceResponse.
	Update(context.Context, UpdateResourceRequest, *UpdateResourceResponse)

	// 当Provider需要删除资源时调用此方法。配置从DeleteResourceRequest读取
	Delete(context.Context, DeleteResourceRequest, *DeleteResourceResponse)

	// 当前Provider需要导入一个资源时调用此方法。
	// 如果不支持导入，建议返回 ResourceImportStateNotImplemented()
	//
	// If setting an attribute with the import identifier, it is recommended
	// to use the ResourceImportStatePassthroughID() call in this method.
	ImportState(context.Context, ImportResourceStateRequest, *ImportResourceStateResponse)
}

创建操作的关键步骤：

1. 从请求中读取plan数据，读取为模型
2. 将模型转换为云API请求，并发送求
3. 将响应转换并同步到模型，写入state

需要注意：plan中的每个已知（known）值，必须和state中对应值的完全一样（逐字节相等），也就是说，用户指定的配置不能被改变，否则Terraform抛出错误。Provider只能修改计划中unknown的值，而且必须解析所有unknown的值，state中不会有任何unknown的值。

import (
    "context"
    "math/big"
    "strconv"
    "time"


    "github.com/hashicorp-demoapp/hashicups-client-go"
    "github.com/hashicorp/terraform-plugin-framework/diag"
    "github.com/hashicorp/terraform-plugin-framework/tfsdk"
    "github.com/hashicorp/terraform-plugin-framework/types"
)


func (r resourceOrder) Create(ctx context.Context, req tfsdk.CreateResourceRequest, resp *tfsdk.CreateResourceResponse) {
    // 必须确保Provider已经被配置过
    if !r.p.configured {
        resp.Diagnostics.AddError(
            "Provider not configured",
            "The provider hasn't been configured before apply, likely because it depends on an unknown value from another resource. This leads to weird stuff happening, so we'd prefer if you didn't do that. Thanks!",
        )
        return
    }

    // 从执行计划获取订单模型
    var plan Order
    //                注意这里会自动将配置绑定到模型，不需要手工处理
    diags := req.Plan.Get(ctx, &plan)
    resp.Diagnostics.Append(diags...)
    if resp.Diagnostics.HasError() {
        return
    }

    // 遍历订单项，将其适配为HashiCups客户端需要的入参
    var items []hashicups.OrderItem
    for _, item := range plan.Items {
        items = append(items, hashicups.OrderItem{
            Coffee: hashicups.Coffee{
                ID: item.Coffee.ID,
            },
            Quantity: item.Quantity,
        })
    }

    // 调用HashiCups客户端创建订单
    order, err := r.p.client.CreateOrder(items)
    if err != nil {
        resp.Diagnostics.AddError(
            "Error creating order",
            "Could not create order, unexpected error: "+err.Error(),
        )
        return
    }

    // 将HasiCups创建的完整订单对象，适配回模型OrderItem
    var ois []OrderItem
    for _, oi := range order.Items {
        ois = append(ois, OrderItem{
            Coffee: Coffee{
                ID:          oi.Coffee.ID,
                Name:        types.String{Value: oi.Coffee.Name},
                Teaser:      types.String{Value: oi.Coffee.Teaser},
                Description: types.String{Value: oi.Coffee.Description},
                Price:       types.Number{Value: big.NewFloat(oi.Coffee.Price)},
                Image:       types.String{Value: oi.Coffee.Image},
            },
            Quantity: oi.Quantity,
        })
    }

    // 完整订单模型
    var result = Order{
        ID:          types.String{Value: strconv.Itoa(order.ID)},
        Items:       ois,
        LastUpdated: types.String{Value: string(time.Now().Format(time.RFC850))},
    }

    // 设置状态
    diags = resp.State.Set(ctx, result)
    resp.Diagnostics.Append(diags...)
    if resp.Diagnostics.HasError() {
        return
    }
}

读取操作更新state，使其反映（通过云API得到的）云基础设施对象的最新的、真实状态。

实现读操作的时候，没有plan（用户提供的配置）可用。你需要从请求中读取当前的状态，从中取得执行调用云API所需的信息。

在更新时，Provider理论上可以修改state中的任何值，但是主要应当：

1. 处理值漂移（drift），也就是外部系统或人员修改了Terraform所拥有（创建并在状态中管理）的资源。漂移的值总应该反映到state中
2. 处理语义上没有改变的值，比如某个值是个JSON，它的字段顺序可能调整了，尽管新旧值并不是逐字节相等的，但是并不应当更新state

func (r resourceOrder) Read(ctx context.Context, req tfsdk.ReadResourceRequest, resp *tfsdk.ReadResourceResponse) {
    // 获取当前状态，状态和计划一样，都是模型
    var state Order
    diags := req.State.Get(ctx, &state)
    resp.Diagnostics.Append(diags...)
    if resp.Diagnostics.HasError() {
        return
    }

    // 得到状态中的ID，则是访问HashiCups所需参数
    orderID := state.ID.Value

    // 通过HashiCups客户端获取资源最新信息
    order, err := r.p.client.GetOrder(orderID)
    if err != nil {
        resp.Diagnostics.AddError(
            "Error reading order",
            "Could not read orderID "+orderID+": "+err.Error(),
        )
        return
    }

    // 转换为模型
    state.Items = []OrderItem{}
    for _, item := range order.Items {
        state.Items = append(state.Items, OrderItem{
            Coffee: Coffee{
                ID:          item.Coffee.ID,
                Name:        types.String{Value: item.Coffee.Name},
                Teaser:      types.String{Value: item.Coffee.Teaser},
                Description: types.String{Value: item.Coffee.Description},
                Price:       types.Number{Value: big.NewFloat(item.Coffee.Price)},
                Image:       types.String{Value: item.Coffee.Image},
            },
            Quantity: item.Quantity,
        })
    }

    // 设置到状态
    diags = resp.State.Set(ctx, &state)
    resp.Diagnostics.Append(diags...)
    if resp.Diagnostics.HasError() {
        return
    }
}

更新操作将用户对资源配置的修改，通过云API同步到基础设施对象，然后更新state。关键步骤：

1. 从请求中读取plan数据，并绑定到模型
2. 将模型转换为云API请求
3. 将响应转换并同步到模型，写入state

需要注意：known的值在更新前后，必须在state中逐字节对应。state不能包含任何unknown的值。

删除操作读取state信息，发起云API请求删除对应基础设施对象，然后从state中清除资源记录。

清除资源记录时调用

State.RemoveResource

ImportState方法可以创建一个初始的state，将资源纳管起来。此方法的实现必须确保后续读操作能够正常刷新状态。 

通常需要从请求中读取

req.ID

resp.State.SetAttribute(ctx, path, req.ID)

// 或者，直接调用：
tfsdk.ResourceImportStatePassthroughID()

数据源的资源模型和资源没有区别，数据源仅仅支持Read方法。该方法无法使用plan或state，它只能从

tfsdk.ReadDataSourceRequest

属性就是Provider、资源、数据源的Schema的字段，属性持有最终落地到state的值。每个属性都有对应的类型。当你从config、state或者plan访问属性时，实际上是访问属性的值。

任何类型的属性，都可以持有这两种值。

Null表示值不存在，通常是由于用户没有给optional属性赋值。required属性永远不会是Null。

Unknown表示属性的值尚不知道。Unknown值和Terraform的依赖管理有关。Terraform会构建资源之间的依赖DAG，当资源A引用了资源B的属性a，并且a此时的值是Unknown，则此时就Terraform就会转而去处理B，通过调用云API取得a的值，然后再处理A。资源创建/读取后，任何字段都不能是Unknown的。

TPF的

types

*big.Float

ElemType

ElementsAs

ElementsAs

AttrTypes

As

很多情况下Provider需要访问用户提供的配置数据、Terraform的状态、生成的执行计划中的数据。这些数据通常存放在请求对象中：

func (m myResource) Create(ctx context.Context,
    req tfsdk.CreateResourceRequest, resp *tfsdk.CreateResourceResponse)

最简单的访问配置/计划/状态的方法是，将其转换为一个Go类型（模型）：

type resourceData struct {
    Name types.String `tfsdk:"name"`
    Age types.Number `tfsdk:"age"`
    Registered types.Bool `tfsdk:"registered"`
    Pets types.List `tfsdk:"pets"`
    Tags types.Map `tfsdk:"tags"`
    Address types.Object `tfsdk:"address"`
}

func (m myResource) Create(ctx context.Context,
    req tfsdk.CreateResourceRequest, resp *tfsdk.CreateResourceResponse) {
    var plan resourceData
    diags := req.Plan.Get(ctx, &plan)
    resp.Diagnostics.Append(diags...)
    if resp.Diagnostics.HasError() {
        return
    }
    // 可以通过plan.Name.Value访问计划中的值，你需要检查
    // plan.Name.Null 判断值是否是null的
    // plan.Name.Unknown 判断值是否是unknown的
}

上面这些模型，字段类型都是

attr.Value

1. 这些类型都是Terraform私有的，不可能在云API的SDK中使用这些类型。因此将模型转换为SDK类型时就有了额外的负担，难以自动化转换

好在Get方法能够将值转换为Go类型，因此你可以这样声明模型：

type resourceData struct {
  Name string `tfsdk:"name"`
  Age int64 `tfsdk:"age"`
  Registered bool `tfsdk:"registered"`
  Pets []string `tfsdk:"pets"`
  Tags map[string]string `tfsdk:"tags"`
  Address struct{
    Street string `tfsdk:"street"`
    City string `tfsdk:"city"`
    State string `tfsdk:"state"`
    Zip int64 `tfsdk:"zip"`
  } `tfsdk:"address"`
}

警告：Null值/Unknown值可能无法转换，会导致报错。参考下文的转换规则。

另外一种访问配置/计划/状态的方法是，读取单个属性的值。这种情况下，不需要定义模型（除了ObjectType）：

func (m myResource) Create(ctx context.Context,
    req tfsdk.CreateResourceRequest, resp *tfsdk.CreateResourceResponse) {
    //                                          属性路径 
    attr, diags := req.Config.GetAttribute(ctx, tftypes.NewAttributePath().WithAttributeName("age"))
    resp.Diagnostics.Append(diags...)
    if resp.Diagnostics.HasError() {
        return
    }
    age := attr.(types.Number)
}

上面提到过，Terraform能够自动将属性值转换为Go类型，这里列出转换规则：

Get方法在进行转换时，会自动Go类型实现的特殊接口。

如果Go类型实现了

tftypes.ValueConverter

如果Go类型实现了

Unknownable

Nullable

配置、计划仅仅支持读操作，但是状态还支持写操作。

写状态的时候，调用响应的State.Set方法：

type resourceData struct {
    Name types.Strings `tfsdk:"name"`
}

func (m myResource) Create(ctx context.Context,
    req tfsdk.CreateResourceRequest, resp *tfsdk.CreateResourceResponse) {
    var newState resourceData
    newState.Name.Value = "J. Doe"

    // 持久化到状态中
    diags := resp.State.Set(ctx, &newState)
    resp.Diagnostics.Append(diags...)
    if resp.Diagnostics.HasError() {
        return
    }
}

写入单个属性：

func (m myResource) Create(ctx context.Context,
    req tfsdk.CreateResourceRequest, resp *tfsdk.CreateResourceResponse) {
    age := types.Number{Value: big.NewFloat(7)}
    diags := resp.State.SetAttribute(ctx, tftypes.NewAttributePath().WithAttributeName("age"), &age)
    resp.Diagnostics.Append(diags...)
    if resp.Diagnostics.HasError() {
        return
    }
}

目前TPF框架依赖SDKv2的可接受测试框架，你需要编写和SDKv2可接受测试一样的PreCheck、TestStep...主要区别之处，是如何在TestCase中指定被测试的Provider。

在SDKv2中，通过设置TestCase的Provider属性，来指定map[string]*schema.Provider。在TPF中，则需要指定

ProtoV6ProviderFactories

tfprotov6.ProviderServer

func TestAccTeleportFullVPCMigration(t *testing.T) {
	resource.Test(t, resource.TestCase{
		ProtoV6ProviderFactories: map[string]func() (tfprotov6.ProviderServer, error){
			// 返回每个需要被测试的Provider
			"teleport": func() (tfprotov6.ProviderServer, error) {
				return tfsdk.NewProtocol6Server(New()), nil
			},
		},
		Steps: []resource.TestStep{
			{
				Config: `
# 不需要使用terraform块声明从何处加载Provider，因为此Provider就在运行在测试进程内
provider "teleport" {
  endpoint = "http://127.0.0.1:6080"
  token = ""
}
resource "teleport_fullvpcmigration" "fvm" {
  region               = "eu-moscow"
  vpc_id               = "vpc-10"
  src_app_id           = "10"
  src_uin              = "10"
  src_sub_account_uin  = "11"
  dest_app_id          = "20"
  dest_uin             = "20"
  dest_sub_account_uin = "21"
  operator             = "alex"
  migrate_timeout      = "15s"
}
`,
				Check:  nil,
			},
		},
	})
}

参考SDKv2基于日志的调试。

目前TPF不支持向SDKv2那样，以调试模式启动Provider。

尽管如此，在可接受测试中，你可以单步跟踪Provider代码。

在开发阶段，你可以在.terraformrc中配置dev_overrides：

provider_installation {
  dev_overrides {
    "hashicorp.com/edu/hashicups-pf" = "/Users/Alex/.local/bin"
  }
}

dev_overrides必须放在所有安装方法的最前面。 dev_overrides会让Terraform跳过适用版本检查、Checksum匹配检查。但是dev_overrides不能参与正常的Provider安装流程，它没有提供满足版本的元数据、不能产生锁文件。

因此，为了使用dev_overrides，你需要将编译好的插件存放在指定目录。然后跳过terraform init，直接运行apply/plan等命令。如果没有配置dev_overrides，跳过init会导致报错，提示Provider的本地缓存不存在或者录制的元数据不匹配。

特殊的块

terraform

terraform {
  # 配置后端
  backend {
  }

  # 配置Terraform CLI的版本约束
  required_version = ""

  # 模块需要的所有provider的配置
  required_providers {
    aws = {
      version = ">= 2.7.0"
      source = "hashicorp/aws"
    }
  }

  # 启用实验特性
  experiments = [example]
}

每个Terraform配置，都可以指定一个后端：后端决定了操作在何处执行，状态快照在何处存储：

1. 所谓操作（operation）是指调用云API进行资源的CRUD
2. Terraform利用状态（state）来跟踪它管理的资源。它依赖于state来知晓配置文件中的资源和云上基础设施对象的对应关系，典型情况是将云上对象的ID和配置资源关联起来

根据能力的不同，后端分为两类：

1. 增强后端，同时支持存储状态、执行操作，只有两个增强后端：

   local

   、

   remote

2. 标准后端，仅仅存储状态，并且依赖于

   local

   后端执行操作

简单场景下可以使用local后端，不需要任何配置。后端配置仅仅被Terraform CLI使用，Terraform Cloud/Enterprise总是使用他们自己的状态存储，并忽略配置文件中的backend块。

该后端在本地文件系统存储状态，并且使用系统API锁定状态数据。该后端在本地直接执行操作。不进行任何backend配置，默认使用的就是该后端。

示例配置：

terraform {
  backend "local" {
    # 状态存储路径
    path = "relative/path/to/terraform.tfstate"
    # 如果使用非默认工作区
    workspace_dir = ""
  }
}

用在terraform_remote_state数据资源中：

data "terraform_remote_state" "foo" {
  backend = "local"
  config = {
    path = "${path.module}/../../terraform.tfstate"
  }
}

使用此后端时，大部分Terraform CLI的、从后端读写state快照的命令，都支持以下选项：

-state=FILENAME 读取先前状态快照时，使用的状态文件
-state-out=FILENAME 写入新的状态快照时，使用的状态文件
-backup=FILENAME 写入新状态快照时，先前状态的备份文件。取值 - 禁用备份

配合Terraform Cloud使用，在云端存储状态和执行操作。

在云端执行操作时，terraform plan / apply等命令在Terraform Cloud的运行环境下执行，日志则打印到本地终端。远程的plan/apply使用关联的Terraform云工作区中的变量。

这是个标准后端，只能用于存储状态。示例配置：

terraform {
  backend "etcdv3" {
    # Etcd服务器列表
    endpoints = ["etcd-1:2379", "etcd-2:2379", "etcd-3:2379"]
    # 是否锁定状态访问
    lock      = true
    # 存储前缀
    prefix    = "terraform-state/"
    # 基于口令的身份验证
    username = "$ETCDV3_USERNAME"
    password = "$ETCDV3_PASSWORD"
    # 基于证书的身份验证
    cacert_path = ""
    cert_path = ""
    key_path = ""
    # 最大发送的请求，增大此值可以存放更大的状态，必须配合Etcd服务器配置 --max-request-bytes，默认2MB
  }
}

data "terraform_remote_state" "foo" {
  backend = "etcdv3"
  config = {
    endpoints = ["etcd-1:2379", "etcd-2:2379", "etcd-3:2379"]
    lock      = true
    prefix    = "terraform-state/"
  }
}

Terraform需要存储被管理资源的状态，从而实现三个目的：

1. 将真实基础设施对象绑定到配置中定义的资源（最核心的用途）
2. 跟踪元数据，例如资源依赖关系。通常情况下，Terraform直接使用配置文件来跟踪资源依赖，但是当你删除配置文件片段后，此依赖关系可能被破坏，这是它会利用状态总存储的最近的依赖关系
3. 提升管理大规模基础设施时的性能。状态中存储了所有资源的属性值，这样可以避免每次访问属性时都需要请求provider

在执行任何操作之前，Terraform会执行refresh操作来将状态和基础设施同步。 当配置发生变动后，Terraform可能会：

1. 如果配置文件中定义了新的资源：调用Provider创建对应基础设施对象，并且将对象的标识符和配置中的资源定义绑定，存储在状态中。Terraform期望基础设施对象和资源定义的实例（使用count/foreach时一个块定义了多个实例）是一一对应关系
2. 如果配置文件中删除了资源定义：调用Provider删除对应基础设施对象，并且清除状态中对应数据

如上一章节所述，默认情况下后端local负责存储状态，它默认将状态存储到名为terraform.tfstate的文件中。Terraform还支持大量其它后端，将状态存储到Etcd、S3等各种存储服务中。

尽管状态就是JSON文本，也不要直接修改它。可以使用

terraform state

通过

terraform import

terraform state rm

该数据源能够从其它Terraform配置的最新状态快照拉取根模块的输出值。这个模块是内置的，不需要配置。

目标配置使用local后端，读取其输出值的例子：

data "terraform_remote_state" "vpc" {
  backend = "local"
  config = {
    # 目标配置的状态文件
    path = "..."
  }
}

# Terraform >= 0.12
resource "aws_instance" "foo" {
  #                                           读取输出值
  subnet_id = data.terraform_remote_state.vpc.outputs.subnet_id
}

# Terraform <= 0.11
resource "aws_instance" "foo" {
  # ...
  subnet_id = "${data.terraform_remote_state.vpc.subnet_id}"
}

注意：仅仅目标配置的根模块的输出值被暴露，其子模块的输出值是不可见的。你必须手工在根模块将子模块的输出值再次输出：

module "app" {
  source = "..."
}

output "app_value" {
  # This syntax is for Terraform 0.12 or later.
  value = module.app.example
}

如果后端支持，Terraform在执行任何可能修改状态的操作时，会锁定状态，防止并发修改损坏数据。

对于大部分命令，都可以使用命令行选项

-lock

命令

force-unlock

存储在backend中的状态数据，属于一个工作区。最开始仅有一个名为default的工作区，因而对于一个Terraform配置来说，只有一个关联的state。

某些backend支持多个工作区，包括S3、Local、Kubernetes等。

命令

terraform workspace

工作区可以用于区分测试/生产环境，开发人员可以在测试环境中创建并行的、完整的基础设施，并且测试配置文件的变更。

当管理大规模系统时，应该重构被拆分出多个配置（而不是引入新工作区），这些配置甚至可能由不同团队管理。

在Local后端中存储的状态，敏感数据直接明文保存在文件中。

The post Terraform快速参考 appeared first on 绿色记忆.

Ceph是一个高性能、可扩容的分布式存储系统，它提供三大功能：

1. 对象存储：提供RESTful接口，也提供多种编程语言绑定。兼容S3、Swift
2. 块存储：由RBD提供，可以直接作为磁盘挂载，内置了容灾机制
3. 文件系统：提供POSIX兼容的网络文件系统CephFS，专注于高性能、大容量存储

Ceph集群由一系列节点（机器）组成，在这些节点上运行以下组件：

1. Ceph OSDs：OSD即对象存储守护程序，但是它并非针对对象存储。OSD负责存储数据、处理数据复制、恢复、回填（Backfilling）、再平衡。此外OSD还对其它OSD进行心跳检测，检测结果汇报给Monitor
2. Monitors：监视器，维护集群状态的多种映射，同时提供认证和日志记录服务
3. MDSs：元数据服务器，存储CephFS的元数据信息

Ceph将客户端的数据作为对象存储在它的存储池中，基于CRUSH算法，Ceph计算出每个对象应该位于那个PG，计算哪个OSD负责存储PG

监视器维护集群状态的多种映射—— 包monmap、OSD map、PG map、CRUSH map、MDS map，同时提供认证和日志记录服务。Ceph会记录Monitor、OSD、PG的每次状态变更历史（此历史称作epoch）。客户端连到单个监视器并获取当前映射就能确定所有监视器、 OSD 和元数据服务器的位置。依赖于CRUSH算法和当前集群状态映射，客户端就能计算出任何对象的位置，直连OSD读写数据。

Ceph客户端、其它守护进程通过配置文件发现mon，但是mon之间的相互发现却依赖于monmap的本地副本。所有mon会基于分布式一致性算法Paxos，确保各自本地的monmap是一致的，当新增一个mon后，所有现有mon的monmap都自动更新为最新版本。

使用多个mon时，每个mon都会检查其它mon是否具有更新的集群状态映射版本 —— 存在一个或多个epoch大于当前mon的最高epoch。太过落后的mon可能会离开quorum，同步后再加入quorum。执行同步时，mon分为三类角色：

1. Leader：具有最新版本状态映射的mon
2. Provider：同上，但是它的最新状态是从Leader同步获得
3. Requester：落后于Leader，必须获取最新集群状态映射才能重回quorum

如果mon的时钟不同步，可能会导致：

1. 守护进程忽略收到的消息（时间戳过时）
2. 消息未及时收到时，超时触发得太快或太晚

OSD使用日志的原因有两个：

1. 速度： 日志使得 OSD 可以快速地提交小块数据的写入， Ceph 把小片、随机 IO 依次写入日志，这样，后端文件系统就有可能归并写入动作，并最终提升并发承载力。因此，使用 OSD 日志能展现出优秀的突发写性能，实际上数据还没有写入 OSD ，因为文件系统把它们捕捉到了日志
2. 一致性：OSD需要一个能保证原子化复合操作的文件系统接口。 OSD 把一个操作的描述写入日志，并把操作应用到文件系统。这确保了对象（例如归置组元数据）的原子更新。每隔一段时间（由filestore max sync interval 和 filestore min sync interval控制 ）， OSD 会停止写入，把日志同步到文件系统，这样允许 OSD 修整日志里的操作并重用空间。若失败， OSD 从上个同步点开始重放日志。日志的原子性表现在，它不使用操作系统的文件缓存（基于内存），避免断电丢数据的问题

注意：OSD进程在往数据盘上刷日志数据的过程中，是停止写操作的。 

通常使用独立SSD来存储日志，原因是：

1. 避免针对单块磁盘的双重写入 —— 先写日志，再写filestore
2. SSD性能好，可以降低延迟提升IOPS

在Luminous中，Bluestore已经代替Filestore作为默认的存储引擎。Bluestore直接管理裸设备，不使用OS提供的文件系统接口，因此它不会收到OS缓存影响。

使用Bluestore时，你不需要配备SSD作为独立的日志存储，Bluestore不存在双重写入问题，它直接把数据落盘到块上，然后在RockDB中更新元数据（指定数据块的位置）。

一个基于Bluestore的OSD最多可以利用到三块磁盘，例如下面的最优化性能组合：

1. 使用HDD作为数据盘
2. 使用SSD作为RockDB元数据盘
3. 使用NVRAM作为RockDB WAL

一些概念：

1. Acting Set：牵涉到PG副本的OSD集合
2. Up Set：指Acting Set中排除掉Down掉的OSD的子集

Ceph依赖于Up Set来处理客户端请求。如果 Up Set 和 Acting Set 不一致，这可能表明集群内部在重均衡或者有潜在问题。

写入数据前，归置组必须处于 active 、而且应该是 clean 状态。假设一存储池的归置组有 3 个副本，为让 Ceph 确定归置组的当前状态，一归置组的主 OSD （即 acting set 内的第一个 OSD ）会与第二和第三 OSD 建立连接，并就归置组的当前状态达成一致意见。

由于以下原因，集群状态可能显示为HEALTH WARN：

1. 刚刚创建了一个存储池，归置组还没互联好
2. 归置组正在恢复
3. 刚刚增加或删除了一个 OSD
4. 刚刚修改了 CRUSH 图，并且归置组正在迁移
5. 某一归置组的副本间的数据不一致
6. Ceph 正在洗刷一个归置组的副本
7. Ceph 没有足够空余容量来完成回填操作

这些情况下，集群会自行恢复，并返回 HEALTH OK 状态，归置组全部变为active+clean。

CRUSH 算法通过计算数据存储位置来确定如何存储和检索。 CRUSH授权Ceph 客户端直接连接 OSD ，而非通过一个中央服务器或代理。数据存储、检索算法的使用，使 Ceph 避免了单点故障、性能瓶颈、和伸缩的物理限制。

CRUSH 需要一张集群的 Map，利用该Map中的信息，将数据伪随机地、尽量平均地分布到整个集群的 OSD 里。此Map中包含：

1. OSD 列表
2. 把设备汇聚为物理位置的“桶”（Bucket，也叫失败域，Failure Domain）列表
3. 指示 CRUSH 如何复制存储池中的数据的规则列表

通过CRUSH map来建模存储设备的物理位置，Ceph能够避免潜在的关联性故障 —— 例如一个机柜中的设备可能共享电源、网络供应，它们更加可能因为断电而同时出现故障，Ceph会刻意的避免把数据副本放在同一机柜。

新部署的OSD自动被放置到CRUSH map中，位于一个host节点（OSD所在主机名）。在默认的CRUSH失败域（Failure Domain） 设置中，副本/EC分片会自动分配在不同的host节点上，避免单主机的单点故障。在大型集群中，管理员需要更加仔细的考虑失败域设置，将副本分散到不同的Rack、Row。

OSD在CRUSH map中的位置，称为CRUSH location。此Location以如下形式来描述：

# 一系列键值对，虽然是有层次结构的，但是列出的顺序无所谓
# 键必须是有效的CRUSH type。默认支持root,regin, datacenter, room, row, pod, pdu, rack, chassis, host
# 你不需要声明所有键，默认情况下Ceph自动把新OSD放在root=default host=hostname下，因此这两个键你可以不声明
root=default row=a rack=a2 chassis=a2a host=a2a1

你可以在Ceph配置文件中，用crush location选项来声明。每当OSD启动时，它会验证当前CRUSH map是否匹配crush location设置，如果不匹配会更新CRUSH map。设置下面的选项可以禁用此行为：

osd crush update on start = false

CRUSH map是一个树状的层次结构，它是对存储设备物理位置松散的建模。 

在这个层次结构中，叶子节点是Device，对应了OSD守护程序（通常管理一块或几块磁盘）。设备的以name.id来识别，通常是osd.N。设备可以关联一个设备类别（Device Class），取值例如hdd、ssd，CRUSH rule可以使用到设备类别。

除了叶子节点之外的，都称为桶（Bucket），每个桶都具有类型，默认支持的类型包括root,regin, datacenter, room, row, pod, pdu, rack, chassis, host。大部分集群仅仅使用一部分类型的桶。

每个节点都具有一个权重（Weight）字段，指示子树负责存储的数据的比例。权重应该仅仅在叶子节点上设置，由Ceph自动向上类加。权重的单位通常是TB。

执行命令

ceph osd crush tree

CRUSH rule定义了数据如何跨越设备分布的规则。大部分情况下你可以通过命令行来创建CRUSH rule，少数情况下需要手工便捷CRUSH map。

随着Ceph的发展，CRUSH算法被不断的优化。Ceph允许你自由选择新或旧的算法变体，这依赖Tunable实现。

要使用新的Tunable，客户端、服务器必须同时支持。Tunable的命名就是最初支持对应算法变体的那个Ceph版本的名称（例如jewel）。

用户空间的Ceph块设备实现（librbd）不能使用Linux的页面缓存，因此它自己实现了一套基于内存的LRU缓存——RBD Cacheing。

此缓存的行为类似于页面缓存，当OS发送屏障/Flush请求时，内存中的脏数据被刷出到OSD。

这是一个POSIX兼容的文件系统，它使用Ceph的存储集群来保存数据。

一个Ceph集群可以有0-N个CephFS文件系统，每个CephFS具有可读名称和一个集群文件系统ID（FSCID）。每个CephFS可以指定多个处于standby状态的MDS进程。 

每个CephFS包含若干Rank，默认是1个。Rank可以看作是元数据分片。CephFS的每个守护进程（ceph-mds）默认情况下无Rank启动，Mon会自动为其分配Rank。每个守护进程最多持有一个Rank。

如果Rank没有关联到ceph-mds，则其状态为failed，否则其状态为up。

每个ceph-mds都有一个关联的名称，典型情况下设置为所在的节点的主机名。每当ceph-mds启动时，会获得一个GID，在进程生命周期中，它都使用此GID。

如果MDS进程超过 mds_beacon_grace seconds没有和MON联系，则它被标记为laggy。

Ceph对象存储网关是基于librados构建的一套RESTful服务，提供对Ceph存储集群的访问。此服务提供两套接口：

1. S3兼容接口：Amazon S3的子集
2. Swift兼容接口： OpenStack Swift的子集

这两套接口可以混合使用。

对象存储网关由守护程序radosgw负责，它作为客户端和Ceph存储集群之间的媒介。radosgw具有自己的用户管理系统。

从firefly版本开始，对象存储网关在Civetweb上运行，Civetweb内嵌在ceph-radosw这个Daemon中。在老版本中，对象网关基于Apache+FastCGI。

Ceph仪表盘是一个内置的、基于Web的管理/监控工具。通过它你能够管理集群中各种资源。仪表盘作为Ceph Manager的模块实现。

包含一系列集群编排有关的命令。

列出对编排器可见的服务：

ceph orch ls [<service_type>] [<service_name>] [--export] [plain|json|json-pretty|yaml] [--refresh]

ceph orch ls
# 守护进程类型              数量                     归置规则               使用的镜像
NAME                       RUNNING  REFRESHED  AGE  PLACEMENT             IMAGE NAME                            IMAGE ID      
alertmanager                   1/1  77s ago    2w   count:1               docker.io/prom/alertmanager:v0.20.0   0881eb8f169f  
crash                          2/3  79s ago    2w   *                     docker.io/ceph/ceph:v15               mix           
grafana                        1/1  77s ago    2w   count:1               docker.io/ceph/ceph-grafana:6.7.4     80728b29ad3f  
mds.cephfs                     2/3  79s ago    2w   ceph-1;ceph-2;ceph-3  docker.io/ceph/ceph:v15               mix           
mgr                            1/1  77s ago    2w   ceph-1                docker.io/ceph/ceph:v15               5b724076c58f  
mon                            2/3  79s ago    40m  count:3               docker.io/ceph/ceph:v15               mix           
nfs.ganesha                    1/1  78s ago    7d   count:1               docker.io/ceph/ceph:v15               5b724076c58f  
node-exporter                  2/3  79s ago    2w   *                     docker.io/prom/node-exporter:v0.18.1  mix           
osd.all-available-devices      2/3  79s ago    2w   *                     docker.io/ceph/ceph:v15               mix           
prometheus                     1/1  77s ago    2w   count:1               docker.io/prom/prometheus:v2.18.1     de242295e225  
rgw.china.zircon               2/3  79s ago    2w   count:3               docker.io/ceph/ceph:v15               mix

列出对编排器可见的守护进程，守护进程是服务的实例：

orch ps [<hostname>] [<service_name>] [<daemon_type>] [<daemon_id>] [plain|json|json-pretty|yaml] [--refresh] 

ceph orch ps
NAME                            HOST    STATUS         REFRESHED  AGE  VERSION    IMAGE NAME                            IMAGE ID      CONTAINER ID  
alertmanager.ceph-1             ceph-1  running (69m)  3m ago     2w   0.20.0     docker.io/prom/alertmanager:v0.20.0   0881eb8f169f  bef9ab4dcc98  
crash.ceph-1                    ceph-1  running (69m)  3m ago     2w   15.2.10    docker.io/ceph/ceph:v15               5b724076c58f  3bb0c129d4d4  
crash.ceph-2                    ceph-2  error          3m ago     2w   <unknown>  docker.io/ceph/ceph:v15               <unknown>     <unknown>     
crash.ceph-3                    ceph-3  running (69m)  3m ago     2w   15.2.10    docker.io/ceph/ceph:v15               5b724076c58f  f5c22d2c854b  
grafana.ceph-1                  ceph-1  running (69m)  3m ago     2w   6.7.4      docker.io/ceph/ceph-grafana:6.7.4     80728b29ad3f  17d84abdd9e6  
mds.cephfs.ceph-1.nivqqf        ceph-1  running (69m)  3m ago     2w   15.2.10    docker.io/ceph/ceph:v15               5b724076c58f  4be1504a4c6f  
mds.cephfs.ceph-2.djnipz        ceph-2  error          3m ago     2w   <unknown>  docker.io/ceph/ceph:v15               <unknown>     <unknown>     
mds.cephfs.ceph-3.cgngbk        ceph-3  running (69m)  3m ago     2w   15.2.10    docker.io/ceph/ceph:v15               5b724076c58f  7e514989bc6c  
mgr.ceph-1.adpioc               ceph-1  running (69m)  3m ago     2w   15.2.10    docker.io/ceph/ceph:v15               5b724076c58f  a66dd815c2b1  
mon.ceph-1                      ceph-1  running (69m)  3m ago     2w   15.2.10    docker.io/ceph/ceph:v15               5b724076c58f  0c87ed6da097  
mon.ceph-2                      ceph-2  error          3m ago     2w   <unknown>  docker.io/ceph/ceph:v15               <unknown>     <unknown>     
mon.ceph-3                      ceph-3  running (69m)  3m ago     2w   15.2.10    docker.io/ceph/ceph:v15               5b724076c58f  836ec2a7c34d  
nfs.ganesha.ceph-3              ceph-3  running (68m)  3m ago     7d   3.3        docker.io/ceph/ceph:v15               5b724076c58f  440a1bcef7c5  
node-exporter.ceph-1            ceph-1  running (69m)  3m ago     2w   0.18.1     docker.io/prom/node-exporter:v0.18.1  e5a616e4b9cf  26bf34b93188  
node-exporter.ceph-2            ceph-2  error          3m ago     2w   <unknown>  docker.io/prom/node-exporter:v0.18.1  <unknown>     <unknown>     
node-exporter.ceph-3            ceph-3  running (69m)  3m ago     2w   0.18.1     docker.io/prom/node-exporter:v0.18.1  e5a616e4b9cf  fb60a5b31bfd  
osd.0                           ceph-2  error          3m ago     2w   <unknown>  docker.io/ceph/ceph:v15               <unknown>     <unknown>     
osd.1                           ceph-1  running (69m)  3m ago     2w   15.2.10    docker.io/ceph/ceph:v15               5b724076c58f  49cad5daf8f8  
osd.2                           ceph-3  running (69m)  3m ago     2w   15.2.10    docker.io/ceph/ceph:v15               5b724076c58f  17ef075e16a4  
prometheus.ceph-1               ceph-1  running (69m)  3m ago     2w   2.18.1     docker.io/prom/prometheus:v2.18.1     de242295e225  7b61f27c6a0e  
rgw.china.zircon.ceph-1.dsctvb  ceph-1  running (69m)  3m ago     2w   15.2.10    docker.io/ceph/ceph:v15               5b724076c58f  b7d6166aae36  
rgw.china.zircon.ceph-2.ulzfto  ceph-2  error          3m ago     2w   <unknown>  docker.io/ceph/ceph:v15               <unknown>     <unknown>     
rgw.china.zircon.ceph-3.qjhszd  ceph-3  running (69m)  3m ago     2w   15.2.10    docker.io/ceph/ceph:v15               5b724076c58f  5d1d6d6e6899

设置某种组件（服务/守护进程）的数量或者归置规则，格式：

# 更新守护程序副本数量、归置规则，或者apply一段YAML格式的配置
orch apply [mon|mgr|rbd-mirror|crash|alertmanager|grafana|node-exporter|prometheus] [<placement>]  
 [--dry-run] [plain|json|json-pretty|yaml] [--unmanaged] 

# 扩缩容iSCSI服务
orch apply iscsi <pool> <api_user> <api_password> [<trusted_ip_list>] [<placement>] [--dry-run]
 [plain|json|json-pretty|yaml] [--unmanaged]  

# 更新指定fs_name的MDS实例数
orch apply mds <fs_name> [<placement>] [--dry-run] [--unmanaged] [plain|json|json-pretty|yaml]

# 扩缩容NFS服务
orch apply nfs <svc_id> <pool> [<namespace>] [<placement>] [--dry-run] [plain|json|json-pretty|
 yaml] [--unmanaged] 

# 创建OSD守护进程
orch apply osd [--all-available-devices] [--dry-run] [--unmanaged] [plain|json|json-pretty|yaml]

# 为指定的Zone更新RGW实例的数量
orch apply rgw <realm_name> <zone_name> [<subcluster>] [<port:int>] [--ssl] [<placement>] 
[--dry-run] [plain|json|json-pretty|yaml] [--unmanaged]

下面是一些简单的例子：

# 指定副本数
ceph orch apply mon 3
# 制定归置规则
ceph orch apply mon ceph-1 ceph-2 ceph-3

# 为所有空闲设备创建OSD
ceph orch apply osd --all-available-devices

管理守护进程。

add子命令，添加一个守护进程：

# 添加守护进程
ceph orch daemon add [mon|mgr|rbd-mirror|crash|alertmanager|grafana|node-exporter|prometheus [<placement>]

ceph orch daemon add iscsi <pool> <api_user> <api_password> [<trusted_ip_list>] [<placement>]
ceph orch daemon add mds <fs_name> [<placement>] 
ceph orch daemon add nfs <svc_id> <pool> [<namespace>] [<placement>]
ceph orch daemon add osd [<svc_arg>]
ceph orch daemon add rgw <realm_name> <zone_name> [<subcluster>] [<port:int>] [--ssl] [<placement>]

redeploy子命令，重新部署某个守护进程，可以指定使用的镜像：

ceph orch daemon redeploy <name> [<image>]

如果节点上的守护进程容器被意外删除，也就是

podman ps

rm子命令，删除某个守护进程：

ceph orch daemon rm <names>... [--force]

你也可以启动、停止、重启、重新配置某个守护进程：

ceph orch daemon start|stop|restart|reconfig <name>

如果需要启动、停止、重启、重新配置某种服务的所有守护进程：

ceph orch start|stop|restart|redeploy|reconfig <service_name> 

管理块设备。

显示某些主机上的块设备：

ceph orch device ls [<hostname>...] [plain|json|json-pretty|yaml] [--refresh] [--wide]

清除块设备上的内容：

ceph orch device zap <hostname> <path> [--force]

管理主机。

添加主机，可选的，添加标签：

ceph orch host add <hostname> [<addr>] [<labels>...]

为主机添加/移除标签：

ceph orch host label add <hostname> <label>
ceph orch host label rm <hostname> <label>

列出主机：

ceph orch host ls [plain|json|json-pretty|yaml]

检查是否可以在不损害可用性的前提下，停止主机：

ceph orch host ok-to-stop <hostname>

删除主机：

ceph orch host rm <hostname>

修改主机地址：

ceph orch host set-addr <hostname> <addr>

删除OSD实例：

ceph orch osd rm <svc_id>... [--replace] [--force]

检查删除OSD操作的进度：

ceph orch osd rm status [plain|json|json-pretty|yaml]

暂停编排器的后台任务

恢复暂停的编排器后台任务

选择编排器后端：

ceph orch set backend <module_name>

显示使用的编排器后端，以及它的状态：

ceph orch status [plain|json|json-pretty|yaml]

ceph orch status
Backend: cephadm
Available: True

cephadm就是一个编排器后端，下文会有介绍。

升级相关操作：

orch upgrade check [<image>] [<ceph_version>]    # 检查镜像可用版本
orch upgrade pause                               # 暂停升级
orch upgrade resume                              # 恢复暂停的省级
orch upgrade start [<image>] [<ceph_version>]    # 触发升级
orch upgrade status                              # 升级状态
orch upgrade stop                                # 停止进行中的升级

查看日志：

ceph log last [<num:int>] [debug|info|sec|warn|error] [*|cluster|audit|cephadm]

# 查看cephadm的最新日志
ceph log last cephadm

Cephadm是最新的Ceph部署工具，他利用容器和Systemd，仅仅支持Octopus或者更新的版本。

Cephadm的外部依赖包括容器运行时（Docker或者Podman），以及Python3。

cd /tmp
curl --silent --remote-name --location https://github.com/ceph/ceph/raw/octopus/src/cephadm/cephadm
chmod +x cephadm

安装支持cephadm命令及其依赖：

./cephadm add-repo --release octopus
./cephadm install

cephadm bootstrap --mon-ip 10.0.2.1
cephadm shell -- ceph -s

上述命令会安装一个单MON节点的Ceph集群。改命令会：

1. 创建MON和MGR守护进程到本机
2. 为Ceph集群生成SSH密钥，并添加到roo用户的/root/.ssh/authorized_keys
3. 生成最小化配置的 /etc/ceph/ceph.conf，用于和新集群通信
4. 生成Ceph管理密钥 /etc/ceph/ceph.client.admin.keyring
5. 复制公钥副本到/etc/ceph/ceph.pub

cephadm install ceph-common

这样你就可以直接使用ceph命令了：

ceph status

你需要提前为节点安装好Python3

列出现有节点：

ceph orch host ls

orch子命令用于Ceph集群相关的编排。

将集群的公钥安装到新节点的authorized_keys：

ssh-copy-id -f -i /etc/ceph/ceph.pub root@10.0.2.2
ssh-copy-id -f -i /etc/ceph/ceph.pub root@10.0.2.3

添加节点，注意要提供主机名：

ceph orch host add ceph-2
ceph orch host add ceph-3

ceph orch host set-addr ceph-1 ceph-1.gmem.cc 

# 设置哪些子网中的主机可以作为MON
ceph config set mon public_network 10.0.2.0/24

# 确保三个MON
ceph orch apply mon 3

# 你也可以强制指定在哪些主机上部署MON
ceph orch apply mon ceph-1 ceph-2 ceph-3

使用下面的命令，可以将集群主机所有空闲设备作为OSD：

ceph orch apply osd --all-available-devices

将特定主机的特定磁盘作为OSD：

ceph orch daemon add osd ceph-1:/dev/vdb

ceph fs volume create cephfs --placement="ceph-1 ceph-2 ceph-3"

ceph orch apply rgw china beijing '--placement=3' --port=80

NFS Ganesha是一个用户模式的NFS，支持v3  4.0 4.1 4.2，可以同时运行这些协议。

使用下面的命令来部署NFS Ganesha网关。

# 为NFS创建存储池
ceph osd pool create nfs-ganesha 64 replicated
#                   服务ID  存储池      命名空间
ceph orch apply nfs ganesha nfs-ganesha china

ceph-deploy是一个ceph部署工具，服务器只需要提供SSH、sudo、一些Python包即可完成ceph的安装部署。

准备好服务器集群后，选取一台作为管理主机，在其上执行：

wget -q -O- 'https://download.ceph.com/keys/release.asc' | sudo apt-key add -
#                                  debian-luminous
echo deb https://download.ceph.com/debian-jewel/ $(lsb_release -sc) main | sudo tee /etc/apt/sources.list.d/ceph.list
sudo apt-get update
sudo apt-get install ceph-deploy


# 也可以通过pip安装
apt install python-pip
pip install ceph-deploy


# BUG太多，直接Git最新源码安装吧
git clone https://github.com/ceph/ceph-deploy.git
cd ceph-deploy
chmod +x setup.py 
python setup.py install

为了防止时钟不同步导致问题，建议安装NTP客户端，并保持和NTP服务器的同步。

# 在所有节点上执行
ansible k8s -m raw -a 'useradd -d /home/ceph-ops -m ceph-ops'
ansible k8s -m raw -a 'echo "ceph-ops ALL = (root) NOPASSWD:ALL" | sudo tee /etc/sudoers.d/ceph-ops'
ansible k8s -m raw -a 'chmod 0440 /etc/sudoers.d/ceph-ops'
ansible k8s -m raw -a 'echo "ceph-ops:password" | chpasswd'

# 在管理节点上执行
# 生成密钥对，默认生成~/.ssh下的id_rsa和id_rsa.pub
ssh-keygen
# 将公钥拷贝到被管理机，便于免密码登陆
ansible k8s -m raw -a "mkdir /home/ceph-ops/.ssh"
ansible k8s -m raw -a "scp -oStrictHostKeyChecking=no root@master-node:/root/.ssh/id_rsa.pub /home/ceph-ops/.ssh/authorized_keys"
ansible k8s -m raw -a "chown -R ceph-ops:ceph-ops /home/ceph-ops/.ssh"

在集群中的管理主机上，执行：

ceph-deploy install {hostname [hostname] ...} --release {code-name}
# 示例：
ceph-deploy --username ceph-ops install Carbon Radon Neon Boron Xenon --release jewel
ceph-deploy --username ceph-ops install Carbon Radon Neon Boron Xenon  --release luminous


# 如果网络速度太慢，ceph-deploy会提前退出。这种情况下手工、通过代理安装为好
export http_proxy=http://10.0.0.1:8087
export https_proxy=http://10.0.0.1:8087

# 实际上就是安装这些软件
apt install ceph ceph-osd ceph-mds ceph-mon radosgw

# 卸载软件
ceph-deploy uninstall {hostname [hostname] ...}
# 示例：
ceph-deploy --username ceph-ops uninstall  Carbon Radon Neon

# 下面的命令可以在Ubuntu上执行，清除配置文件
ceph-deploy purge {hostname [hostname] ...}
# 示例：
ceph-deploy --username ceph-ops purge  Carbon Radon Neon

# 在管理节点上执行：
# 创建一个目录，存放ceph-deploy生成的配置文件
mkdir /tmp/ceph
cd /tmp/ceph

# 创建一个新集群，host为mon节点
ceph-deploy --cluster {cluster-name} new {host [host], ...}

# 示例
ceph-deploy --username ceph-ops new Xenon

# 修改好当前目录的ceph.conf，执行下面的命令，分发到所有节点的/etc/ceph目录
# ceph.conf至少要提供网络配置
# public network = 10.0.0.0/16
# cluster network = 10.0.0.0/16

# 示例
ceph-deploy --username ceph-ops --overwrite-conf config push Carbon Radon Neon Boron Xenon

[client]
rbd_cache = true
rbd_cache_max_dirty = 25165824
rbd_cache_max_dirty_age = 5
rbd_cache_size = 268435456

[global]
fsid = 9b92d057-a4bc-473e-b6ab-462092fcf205
max_open_files = 131072
mon_initial_members = Carbon, Radon, Neon
mon_host = 10.0.0.100,10.0.1.1,10.0.2.1
osd pool default min size = 1
osd pool default pg num = 384
osd pool default pgp num = 384
osd pool default size = 2
mon_max_pg_per_osd = 256
auth_cluster_required = cephx
auth_service_required = cephx
auth_client_required = cephx

[mon]
mon_allow_pool_delete = true

[osd]
public network = 10.0.0.0/16
cluster network = 10.0.0.0/16
filestore max sync interval = 15
filestore min sync interval = 10
filestore op thread = 32
journal max write bytes = 1073714824
journal max write entries = 10000
journal queue max bytes = 10485760000
journal queue max ops = 50000
ms_bind_port_max = 7100
osd_client_message_size_cap = 2147483648
osd_crush_update_on_start = true
osd_deep_scrub_stride = 131072
osd_disk_threads = 4
osd_journal_size = 10240
osd_map_cache_bl_size = 128
osd_max_backfills = 4
osd_max_object_name_len = 256
osd_max_object_namespace_len = 64
osd_max_write_size = 512
osd_op_threads = 8
osd_recovery_op_priority = 4

执行下面的命令，部署初始mon节点，并收集key：

ceph-deploy --username ceph-ops mon create-initial

# 将在当前目录生成以下文件：
# ceph.client.admin.keyring
# ceph.bootstrap-mgr.keyring
# ceph.bootstrap-osd.keyring
# ceph.bootstrap-mds.keyring
# ceph.bootstrap-rgw.keyring
# ceph.bootstrap-rbd.keyring

# 目标主机的/etc/ceph/ceph.conf被创建，如果此文件已经存在，你必须用--overwrite-conf选项重新运行上述命令

# 增加
ceph-deploy mon create {host-name [host-name]...}
# 删除
ceph-deploy mon destroy {host-name [host-name]...}

# 示例：
ceph-deploy --username ceph-ops mon create Radon
ceph-deploy --username ceph-ops mon create Carbon

以ceph-deploy作为工具，将一台主机作为OSD或MDS时，需要收集MON、OSD、MDS的初始keyring：

ceph-deploy gatherkeys {monitor-host}

# 示例：
ceph-deploy --username ceph-ops gatherkeys Carbon Radon Neon Boron Xenon

不再使用ceph-deploy或者另外建立一个新集群时，需要删除管理主机、本地目录的密钥：

ceph-deploy forgetkeys

ceph-deploy disk list {node-name [node-name]...}
# 示例：
ceph-deploy --username ceph-ops disk list Carbon Radon Neon Boron Xenon

下面的命令可以擦净（删除分区表）磁盘，以供Ceph使用 ： 

ceph-deploy disk zap {osd-server-name} {disk-name}
# 示例（luminous）：
ceph-deploy --username ceph-ops disk zap xenial-100 /dev/vdb
ceph-deploy --username ceph-ops disk zap xenial-100 /dev/vdc
ceph-deploy --username ceph-ops disk zap Carbon     /dev/sdb
ceph-deploy --username ceph-ops disk zap Radon      /dev/sdb
ceph-deploy --username ceph-ops disk zap Neon       /dev/sdb
# 示例（jewel）：
ceph-deploy --username ceph-ops disk zap xenial-100:vdb
ceph-deploy --username ceph-ops disk zap xenial-100:vdc
ceph-deploy --username ceph-ops disk zap Carbon:sdb
ceph-deploy --username ceph-ops disk zap Radon:sdb
ceph-deploy --username ceph-ops disk zap Neon:sdb

警告：所有数据会被删除。

此命令在ceph-deploy 2.0.0中已经废除

使用prepare命令来准备磁盘，会自动创建分区。在大部分OS中，activate会随后自动执行

ceph-deploy osd prepare {node-name}:{data-disk}[:{journal-disk}]
# 示例：
ceph-deploy --username ceph-ops osd prepare --fs-type xfs xenial-100:vdb
ceph-deploy --username ceph-ops osd prepare --fs-type xfs xenial-100:vdc
ceph-deploy --username ceph-ops osd prepare --fs-type xfs Carbon:sdb
ceph-deploy --username ceph-ops osd prepare --fs-type xfs Radon:sdb

建议：将日志存储在独立磁盘中以最优化性能，如果将日志和数据存储在一起，会有损性能。

此命令在ceph-deploy 2.0.0中已经废除

很多操作系统上，不需要手工激活OSD。

ceph-deploy osd activate {node-name}:{data-disk-partition}[:{journal-disk-partition}]
# 示例
ceph-deploy --username ceph-ops osd activate xenial-100:vdb
ceph-deploy --username ceph-ops osd activate xenial-100:vdc
ceph-deploy --username ceph-ops osd activate Carbon:sdb
ceph-deploy --username ceph-ops osd activate Radon:sdb

激活之后，系统运行ceph-osd进程，OSD进入up+in状态。

即prepare + activate：

ceph-deploy osd create {node-name}:{disk}[:{path/to/journal}]
# 示例
ceph-deploy osd create osdserver1:sdb:/dev/ssd1

# 示例（luminous）：
ceph-deploy --username ceph-ops osd create --data /dev/vdb --bluestore xenial-100  
ceph-deploy --username ceph-ops osd create --data /dev/vdc --bluestore xenial-100  
ceph-deploy --username ceph-ops osd create --data /dev/sdb --bluestore Carbon
ceph-deploy --username ceph-ops osd create --data /dev/sdb --bluestore Radon
# 指定分区也可以
ceph-deploy --username ceph-ops osd create --data /dev/sda3 --bluestore Carbon

ceph-deploy --username ceph-ops mds create Carbon

仅仅luminous支持，否则报错Error EACCES: access denied could not create mgr

ceph-deploy --username ceph-ops mgr create Carbon

ceph-deploy --username ceph-ops rgw create Radon

默认情况下RGW监听7480端口，你可以验证RGW是否正常工作：

curl http://Carbon:7480

如果只想清除 /var/lib/ceph 下的数据、并保留 Ceph 安装包，可以：

ceph-deploy purgedata {hostname} [{hostname} ...]
# 示例：
ceph-deploy --username ceph-ops purgedata Carbon Radon

如果向同时清除数据、Ceph安装包：

ceph-deploy purge {hostname} [{hostname} ...]

要允许某些主机以管理员权限执行 Ceph 命令，可以：

ceph-deploy admin {host-name [host-name]...}

# 示例：
ceph-deploy --username ceph-ops admin Carbon Radon Neon Boron Xenon

上述命令执行后，当前目录中的ceph.client.admin.keyring被分发到所有指定的主机，在这些主机上可以执行ceph -s命令了。

要将修改过的、当前目录下的配置文件分发给集群内其它主机，可以：

ceph-deploy config push {host-name [host-name]...}

要获取某台主机的配置文件，可以：

ceph-deploy config pull {host-name [host-name]...} 

启动Ceph服务时，初始化进程会启动一系列守护进程，这些进程至少包含两类：

1. ceph-mon 监控进程
2. ceph-osd  Ceph OSD的守护进程

要使用Ceph文件系统功能，则需要额外运行：

1. ceph-mds Ceph元数据服务

要使用Ceph对象存储功能，则需要额外运行：

1. ceph-rgw RADOS网关守护进程 

要列出当前使用的所有配置值，可以访问守护进程的管理套接字。

在节点上执行下面的命令，获得管理套接字的位置：

ceph-conf --name mon.$(hostname -s) --show-config-value admin_socket
# /var/run/ceph/ceph-mon.a.asok

调用下面的命令列出所有配置：

ceph daemon /var/run/ceph/ceph-mon.a.asok config show 

对于osd或者其它守护进程，也可以使用上述方式获取运行时配置。

所有守护进程从同一个配置文件ceph.conf中检索自己感兴趣的信息。该配置文件中包含了集群身份、认证配置、集群成员、主机名、主机 IP 地址、Keyring路径、日志路径、数据路径，以及其它运行时选项。

按照以下顺序来搜索，后面的可以覆盖前面的：

1. 编译进二进制文件的默认值
2. ceph-mon的集群中心配置数据库
3. 本机上的配置文件：
   1. /etc/ceph/ceph.conf
   2. ~/.ceph/config
   3. ./ceph.conf
4. 环境变量：$CEPH_CONF 
5. 命令行参数：-c path/path
6. 管理员在运行时设置的选项

一个Ceph进程启动时，它会先从命令行、环境变量、本地配置文件收集配置项，然后连接ceph-mon读取集群中心配置信息，然后启动。

配置项的名称唯一，标准格式是小写字母 + 下划线

在命令行中指定配置项时，下划线_可以替换为短横线

在配置文件中指定配置项时，下划线可以替换为空格或短横线

配置文件是INI格式的，可以分为以下段落：

你还可以针对特定的实例配置段落：

1. [osd.1]，针对ID为1的OSD的配置
2. [mon.HOSTNAME]，针对名称为HOSTNAME的MON的配置

进程连接ceph-mon、进行身份验证、抓取集群中心配置信息时需要一些配置，这些配置必须存放在本地：

ceph-mon集群管理了配置配置选项的数据库，用于供整个集群来消费。为了简化管理，大部分的Ceph选项应该在此数据库中管理。

集群中心配置的分段情况，和上文的配置段落一致。

传入命令行选项

--no-mon-config

1. 希望所有配置信息在本地文件中管理
2. ceph-mon目前宕机，但是需要进行一些维护工作

集群中心配置的配置项，可以关联一个掩码，用于限定选项应用到哪种守护进程、哪种客户端。例如host:foo，限制foo选项仅仅应用到运行在host上的进程或客户端。

以下命令可以用于修改集群中心配置：

# 启用特定OSD的调试日志
ceph config set osd.123 debug_osd 20

在运行时，你可以使用

ceph osd pool set

Ubuntu系统下，基于ceph-deploy部署集群后，可以用这种方法来操控集群。

列出节点上所有Ceph进程：

initctl list | grep ceph

启动节点上所有Ceph进程：

start ceph-all

启动节点上特定类型的Ceph进程： 

sudo start ceph-osd-all
sudo start ceph-mon-all
sudo start ceph-mds-all

启动特定类型的Ceph进程的某个实例：

sudo start ceph-osd id={id}
sudo start ceph-mon id={hostname}
sudo start ceph-mds id={hostname}

停止特定类型的Ceph进程的某个实例：

sudo stop ceph-osd id={id}
sudo stop ceph-mon id={hostname}
sudo stop ceph-mds id={hostname}

在 CentOS 、 Redhat 、 Fedora 和 SLES 发行版上可以通过传统的 sysvinit 运行 Ceph ， Debian/Ubuntu 的较老的版本也可以用此方法。

命令格式：

# 启动、重启或停止
sudo /etc/init.d/ceph [options] [start|restart|stop] [daemonType|daemonID]

# 示例：

# -a 表示在所有节点执行
sudo /etc/init.d/ceph -a start
sudo /etc/init.d/ceph -a stop
sudo /etc/init.d/ceph start osd
sudo /etc/init.d/ceph -a stop osd
sudo /etc/init.d/ceph start osd.0
sudo /etc/init.d/ceph stop osd.0 

执行

ceph status

ceph -s

1. active+clean：说明集群健康运行
2. undersized+degraded：如果有OSD节点宕机，可能进入此状态。降级后还是可以正常读写数据
3. undersized+degraded+peered：如果超过min size要求的OSD宕机，则不可读写，显示为此状态。min size默认2，副本份数默认3。执行下面的命令可以修改min size：
   

   ceph osd pool set rbd min_size 1

   peered相当于已经配对（PG - OSDs），但是正在等待OSD上线

4. remapped+backfilling：默认情况下，OSD宕机5分钟后会被标记为out状态，Ceph认为它已经不属于集群了。Ceph会按照一定的规则，将已经out的OSD上的PG重映射到其它OSD，并且从现存的副本来回填（Backfilling）数据到新OSD

执行

ceph health

执行

ceph -w

执行命令

ceph df

GLOBAL:
                       # 已用存储空间总量（包括所有副本）
    SIZE     AVAIL     RAW USED     %RAW USED 
    323G      318G        4966M          1.50 

# 这一段显示的数值，不包含副本、克隆、快照的用量
POOLS:
                             # 大概使用率              # 大概对象数
    NAME     ID     USED      %USED     MAX AVAIL     OBJECTS 
    rbd      1      3539M      1.14          300G        1018

# 基本信息
ceph mon stat
# 详细信息
ceph mon dump
# 法定人数状态、monmap内容
ceph quorum_status -f json-pretty

ceph mds stat
ceph mds dump

通过PG这个中间层，Ceph确保了数据不会被绑死在某个特定的OSD。要追踪错误根源，你需要检查归置组、以及底层的OSD。

执行下面的命令，获取最简短的OSD状态：

ceph osd stat
# 输出
12 osds: 12 up, 12 in

执行

ceph osd dump

osd.0 up   out weight 0 up_from 70 up_thru 172 down_at 65 last_clean_interval [51,60) 10.5.39.13:6800/48 10.5.39.13:6801/48 10.5.39.13:6802/48 10.5.39.13:6803/48 exists,up 354a6547-3437-46d6-a928-f5633eb7f059
osd.1 up   in  weight 1 up_from 74 up_thru 327 down_at 63 last_clean_interval [55,60) 10.5.39.42:6800/48 10.5.39.42:6801/48 10.5.39.42:6802/48 10.5.39.42:6803/48 exists,up 0fb4bb77-7c84-45ac-919a-2cc350fc62b9

执行

ceph osd tree

# 仅仅包含out的OSD
ceph osd tree out
# ID CLASS WEIGHT  TYPE NAME               STATUS REWEIGHT PRI-AFF 
# -1       4.89999 root default                                    
# -2             0     host k8s-10-5-38-25                         
#  2   hdd       0         osd.2              DNE        0

执行命令

ceph pg stat

可以获取PG列表：

# 输出的第一列为PG ID
ceph pg dump
# 导出为JSON
ceph pg dump -o {filename} --format=json

执行下面的命令可以查看PG到OSD的映射关系：

# PG ID 格式为 存储池号.归置组ID，归置组ID为一个十六进制数字
ceph pg map 1.13d
# 输出
osdmap e790 pg 1.13d (1.13d) -> up [4,6,5] acting [4,6,5]

执行

ceph status

执行

ceph pg 1.13d query

MONID=Neon
MONADDR=10.0.3.1:6789

# 创建目录
mkdir /var/lib/ceph/mon/ceph-$MONID

# 获取密钥和monmap
ceph auth get mon. -o /tmp/keyring
ceph mon getmap -o /tmp/monmap

# 初始化Mon
sudo ceph-mon -i $MONID --mkfs --monmap /tmp/monmap --keyring /tmp/keyring

# 启动Mon
ceph-mon -i $MONID --public-addr $MONADDR

ceph mon rm Xenon 

导出monmap：

ceph mon getmap -o monmap

打印monmap的内容：

monmaptool --print monmap

从monmap中删除一个MON：

monmaptool  monmap --rm xenon

添加一个MON到monmap中：

monmaptool  monmap --add Xenon 10.0.5.1:6789

导入monmap到MON节点：

ceph-mon -i Xenon --inject-monmap monmap 

# 空间使用率达到 near full 比率后， OSD 失败可能导致集群空间占满。因此，你需要提前扩容
# 执行下面的命令创建一个新的OSD，其OSD号会输出到控制台：

# uuid、id可选，如果不指定则自动生成。不能和现有OSD的uuid、id重复。不建议手工指定id
ceph osd create [{uuid} [{id}]]


# 如果希望OSD使用独立磁盘或者分区，可以先创建好文件系统，再挂载到适当位置
sudo mkfs -t {fstype} /dev/{drive}
# 示例
mkfs -t xfs -f /dev/sda3
# 挂载点
mkdir /var/lib/ceph/osd/ceph-{osd-num}
# 挂载
mount /dev/sda3 /var/lib/ceph/osd/ceph-14

# 初始化OSD数据目录：
ceph-osd -i {osd-num} --mkfs --mkkey

# 注册OSD认证密钥：
ceph auth add osd.{osd-num} osd 'allow *' mon 'allow rwx' -i /var/lib/ceph/osd/${cluster-name}-{osd-num}/keyring
# 示例
ceph auth add osd.14 osd 'allow *' mon 'allow rwx' -i /var/lib/ceph/osd/ceph-14/keyring

# 你需要把OSD加入到CRUSH map，这样数据才会分配到此OSD上： 
# 把OSD加入到CRUSH树的适当位置（桶）
# 如果指定了不止一个桶，则将OSD加入到最靠近叶子节点的桶中，并把此桶移动到你指定的其它桶中
# 如果你指定了root桶，则此OSD直接挂在root下，则是不建议的，CRUSH规则期望OSD位于主机这种桶类型的下级节点
ceph osd crush add {id-or-name} {weight}  [{bucket-type}={bucket-name} ...]
# 示例
ceph osd crush add 14 0.11589
# 如果设置osd_crush_update_on_start=true，则可以OSD启动后自动加入到CRUSH树并更新权重
# 警告，如果上述参数设置为false，且你没有将osd添加到适当位置，则osd可能无法承载PG

ceph osd find 14
{
    "osd": 14,
    "ip": "10.0.1.1:6804/3146",
    "crush_location": {
        "host": "Carbon",
        "root": "default"
    }
} 

一旦启动了 OSD ，其状态就变成了 up+in ，此时可以通过ceph -w来观察数据迁移。归置组状态会变为active, some degraded objects，最终变回active+clean

# Debian/Ubuntu 上用 Upstart：
start ceph-osd id={osd-num}
# CentOS/RHEL 上用 sysvinit：
/etc/init.d/ceph start osd.{osd-num}
# 基于systemd的系统
systemctl start ceph-osd@14.service 

删除OSD之前，应该评估集群容量，保证操作之后，集群不会到达 near full 比率

# 首先从CRUSH map中移除
ceph osd crush remove {name}
# 删除其认证密钥
ceph auth del osd.{osd-num}
# 删除OSD
ceph osd rm {osd-num}

ceph osd down {osd-num}

踢出OSD后，Ceph会进行数据迁移，达到再平衡。归置组状态会变为active, some degraded objects，最终变回active+clean。

ceph osd out {osd-num}

对于某些小型测试集群，踢出一个OSD即导致CRUSH进入临界状态，某些归置组一直卡在active+remapped状态。如果遇到这种情况，你可以：

# 把被踢出的集群重新加进来
ceph osd in {osd-num}
# 将其权重标记为0，而非踢出
ceph osd crush reweight osd.{osd-num} 0 

等待数据迁移完毕后，再将OSD踢出。 

你可能需要更新CRUSH map才能让新进入的OSD接受数据：

ceph osd in {osd-num}

标记OSD为lost，可能导致数据丢失，谨慎：

ceph osd lost {id} [--yes-i-really-mean-it]

# 权重默认是以TB为单位
ceph osd reweight {osd-num} {weight} 

ceph osd scrub {osd-num}
# 清理所有
ceph osd scrub all

ceph osd deep-scrub all 

ceph osd repair N

ceph tell osd.N bench [TOTAL_DATA_BYTES] [BYTES_PER_WRITE]

Ceph不允许向满的 OSD 写入数据，以免丢失数据。在运营着的集群中，你应该能收到集群空间将满的警告。mon osd full ratio 默认为 0.95 ，也就是说达到 95% 时它将阻止客户端写入数据； mon osd backfillfull ratio 默认为 0.90 ，也就是说达到容量的 90% 时它会阻塞，防止回填启动； OSD 将满比率默认为 0.85 ，也就是说达到容量的 85% 时它会产生健康警告。

使用下面的命令临时修改设置，否则你可能没有机会清理不需要的RBD以腾出空间：

ceph osd set-nearfull-ratio 0.95
ceph osd set-full-ratio 0.99
ceph osd set-backfillfull-ratio 0.99

首先，在/var/lib/ceph/mds/mds.N创建一个数据挂载点。N是MDS的ID，通常就是主机名。

然后，修改Ceph配置，添加一个mds段。修改完毕后进行配置分发：

[mds.N]
host = {hostname}

 如果启用了CephX，需要创建认证密钥：

sudo ceph auth get-or-create mds.N mon 'profile mds' mgr 'profile mds' mds 'allow *' osd 'allow *' > \
    /var/lib/ceph/mds/ceph-N/keyring

执行下面的命令将目标mds标记为宕机：

ceph mds fail <mds name>

移除MDS的/var/lib/ceph/mds/ceph-NAME下对应目录，然后，删除/etc/systemd/system/ceph-mds.target.wants/下的对应项目：

systemctl stop ceph-mds@Neon.service
systemctl disable ceph-mds@Neon.service
rm -rf /var/lib/ceph/mds/ceph-Neon 

如果服务是通过/etc/init.d/ceph加载的，则：

service ceph stop
update-rc.d ceph disable

查看守护进程的简短状态：

ceph mds stat

service ceph start mds.NAME

你可以使用多种方式来引用一个MDS守护进程：

ceph mds fail 5446     # 基于GID
ceph mds fail myhost   # 基于名称
ceph mds fail 3:0      # 基于FSCID:rank
ceph mds fail myfs:0   # 基于文件系统名称:rank

和MDS进程的Standby行为相关的配置项包括：

# 如果设置为true则standby会持续的从Rank中读取元数据日志，从而维持一个有效的元数据缓存，这可以加速Failover
mds_standby_replay = true
# 仅仅作为具有指定名称的MDS的Standby
mds_standby_for_name = Carbon
# 仅仅作为指定Rank的Standby
mds_standby_for_rank
# 仅仅作为指定文件系统的Standby
mds_standby_for_fscid

如果不进行任何配置，没有持有Rank的那些MDS进程，可以作为任何Rank的Standby。

配置示例：

# a、b两个MDS互备，负责Rank 0
[mds.a]
mds standby replay = true
mds standby for rank = 0

[mds.b]
mds standby replay = true
mds standby for rank = 0

ceph tell mds.{mds-id} config set {setting} {value}
# 示例
ceph tell mds.0 config set debug_ms 1

ceph mds stat

标记当前活动MDS为失败，触发故障转移：

ceph mds fail 0 

要创建一个文件系统，你至少需要两个存储池，一个存放数据，另外一个存放元数据。注意：

1. 元数据池的副本份数要设置的高，因为任何元数据的丢失都会导致整个文件系统不可用
2. 元数据池应该使用高速存储，例如SSD，因为这对客户端操作的延迟有直接影响

示例：

# ceph fs new <fs_name> <metadata> <data>
# 示例，可以使用现有的存储池
ceph fs new cephfs rbd-ssd rbd-hdd

# Error EINVAL: pool 'rbd-ssd' already contains some objects. Use an empty pool instead.
# 出现上述错误，可以：
ceph fs new cephfs rbd-ssd rbd-hdd --force

创建了文件系统之后，在Luminous版本中，集群状态中显示：

mds: cephfs-1/1/1 up  {0=Carbon=up:active}

ceph fs ls

查看CephFS的详细状态，包括MDS列表、Rank列表等：

ceph fs status

ceph fs rm <filesystem name> [--yes-i-really-mean-it]

mds set <fs_name> down true

要获取某个文件系统的信息，可以：

ceph fs get cephfs

fs set <filesystem name> <var> <val>

# 示例
# 设置单个文件的大小，默认1TB
fs set cephfs max_file_size 1099511627776

fs add_data_pool <filesystem name> <pool name/id>
fs rm_data_pool <filesystem name> <pool name/id>

如果集群中有多个文件系统，而客户端在挂载时没有明确指定使用哪个，则使用默认文件系统：

ceph fs set-default cephfs

EC池可以作为Ceph的数据池，但是需要启用overwirte：

ceph osd pool set my_ec_pool allow_ec_overwrites true

注意：EC池不能用来存储元数据。

CephFS支持对任何一个子目录进行配额。但是，需要注意以下限制：

1. 需要客户端协作，因此被篡改过的客户端可以突破配额
2. 配额不是非常精确的
3. 内核客户端，仅仅在4.17+才支持配额。用户空间客户端fuse、libcephfs都支持配额

设置配额（设置为0则移除配额）：

setfattr -n ceph.quota.max_bytes -v 100000000 /some/dir     # 按字节数
setfattr -n ceph.quota.max_files -v 10000 /some/dir         # 按文件数

查看配额：

getfattr -n ceph.quota.max_bytes /some/dir
getfattr -n ceph.quota.max_files /some/dir 

你可以直接使用Linux内核提供的驱动来挂载CephFS：

mkdir /mnt/cephfs
mount -t ceph 10.0.1.1:6789:/ /mnt/cephfs

如何启用了CephX，需要指定访问密钥，否则会报22错误：

mount -t ceph 10.0.1.1:6789:/ /mnt/cephfs -o name=admin,secret=AQDRNBZbCp3WMBAAynSCCFPtILwHeI3RLDADKA==
# 或者指定包含密钥的文件
mount -t ceph 10.0.1.1:6789:/ /mnt/cephfs -o name=admin,secretfile=/etc/ceph/admin.secret

如果报can't read superblock，说明客户端内核不支持。

要实现自动挂载，你需要修改fstab：

{ipaddress}:{port}:/ {mountpoint} {fs-type} [name=username,secret=key|secretfile=file],[{mount.options}]

# 示例
10.0.1.1:6789:/ /mnt/cephfs  ceph name=admin,secretfile=/etc/ceph/cephfs.key,noatime,_netdev    0       2

要在用户空间挂载CephFS，你需要：

1. 将Ceph配置文件拷贝到客户端，命名为/etc/ceph/ceph.conf
2. 将Keyring拷贝到客户端，命名为/etc/ceph/ceph.keyring：
   

   sudo scp -i ~/Documents/puTTY/gmem.key root@xenon.gmem.cc:/etc/ceph/ceph.client.admin.keyring /etc/ceph/ceph.keyring 

3. 执行挂载：
   

   sudo ceph-fuse -m 10.0.1.1:6789 /mnt/cephfs
   # ceph-fuse[847]: starting ceph client                                                                                                                                                     
   # 2018-06-07 19:18:25.503086 7fa5c44e1000 -1 init, newargv = 0x7fa5cd643b40 newargc=9                                                                                                      
   # ceph-fuse[847]: starting fuse

如果有多个CephFS，你可以为ceph-fuse指定命令行选项--client_mds_namespace，或者在客户端的ceph.conf中添加client_mds_namespace配置。

要实现自动挂载，你需要修改fstab：

none    /mnt/ceph  fuse.ceph ceph.id={user-ID}[,ceph.conf={path/to/conf.conf}],_netdev,defaults  0 0

# 示例
none    /mnt/ceph  fuse.ceph ceph.id=admin,_netdev,defaults  0 0
none    /mnt/ceph  fuse.ceph ceph.id=admin,ceph.conf=/etc/ceph/ceph.conf,_netdev,defaults  0 0 

# 设置新建存储池时使用的默认参数
osd pool default pg num = 128
osd pool default pgp num = 128

ceph osd pool set {pool-name} option-name num
# 示例
ceph osd pool set  .rgw.root pg_num 128
ceph osd pool set  .rgw.root pgp_num 128 

# 创建存储池
# crush-ruleset-name：使用的默认CRUSH规则集名称
# 复制型的默认规则集由选项osd pool default crush replicated ruleset控制
# 
ceph osd pool create {pool-name} {pg-num} [{pgp-num}] [replicated] \
        [crush-ruleset-name] [expected-num-objects]
ceph osd pool create {pool-name} {pg-num}  {pgp-num}   erasure \
        [erasure-code-profile] [crush-ruleset-name] [expected_num_objects]


# 示例
ceph osd pool create rbd-ssd 384 replicated replicated_rule_ssd

创建存储池之后，在管理节点上，使用rbd工具来初始化池：

rbd pool init <pool-name>

# 修改存储池配置
ceph osd pool set {pool-name} {key} {value}
# 读取存储池配置
ceph osd pool get {pool-name} {key}

ceph osd lspools
# 输出
# 1 rbd,3 rbd-ssd,4 rbd-hdd,

# 列出存储池中的对象
rados -p rbd ls

# 显示所有存储池的使用情况
rados df

# 或者
ceph df

# 更多细节
ceph df detail
# USED       %USED       MAX AVAIL     OBJECTS     DIRTY     READ      WRITE      RAW USED 
# 用量       用量百分比                对象数量              读速度    写数量     用量x副本份数

# 设置最大对象数量、最大字节数
ceph osd pool set-quota {pool-name} [max_objects {obj-count}] [max_bytes {bytes}]
# 示例：
ceph osd pool set-quota data max_objects 10000

要取消配额，设置为0即可。 

# 制作存储池快照
ceph osd pool mksnap {pool-name} {snap-name}
# 删除存储池快照
ceph osd pool rmsnap {pool-name} {snap-name}

# 删除存储池
ceph osd pool delete {pool-name} [{pool-name} --yes-i-really-really-mean-it]

# 示例
ceph osd pool rm rbd-ssd rbd-ssd --yes-i-really-really-mean-it
ceph osd pool rm rbd-hdd rbd-hdd --yes-i-really-really-mean-it

# 列出池中对象，逐个删除
for i in `rados -p rbd-ssd ls`; do echo $i; rados -p rbd-ssd rm $i; done

镜像就是块设备，所谓块是一系列连续的字节序列（例如512KB）。基于块的存储接口，是磁盘、CD、软盘、甚至磁带都使用的，是存储对象最广泛使用的方式。

Ceph的块设备具有以下特点：thin-provisioned（精简配备）、可改变大小、跨越多OSD存储。

rbd ls {poolname}

如果不指定池名称，则列出默认池中的镜像。

下面的命令可以列出池中延迟删除的镜像：

rbd trash ls {poolname} 

rbd du --pool rbd-ssd

注意：rbd info输出的是thin provisioning的大小，不是实际磁盘空间占用。

除了上面的命令，还可以：

rbd diff k8s/kubernetes-dynamic-pvc | awk '{ SUM += $2 } END { print SUM/1024/1024 " MB" }' 

rbd info {pool-name}/{image-name}
rbd info {image-name}

# 输出示例：
rbd image 'kubernetes-dynamic-pvc-0783b011-6a04-11e8-a266-3e299ab03dc6':
        # 总大小（thin-provisioning的大小，不是实际占用磁盘大小），分布在多少个对象中
        size 2048 MB in 512 objects
        order 22 (4096 kB objects)
        block_name_prefix: rbd_data.7655b643c9869
        format: 2
        features: layering
        flags:
        create_timestamp: Thu Jun  7 11:36:58 2018

可以看到什么客户端在使用（watch）镜像：

rbd status k8s/kubernetes-dynamic-pvc-ca081cd3-01a0-11eb-99eb-ce0c4cdcd662
# Watchers:
#         watcher=192.168.106.18:0/756489925 client.254697953 cookie=18446462598732840981 

rbd create --size {megabytes} {pool-name}/{image-name}
# 示例
# 创建大小为1G的镜像
rbd create test --size 1G

如果不指定存储池，则在默认池中创建镜像。

# 修改镜像大小
rbd --image test resize --size 2G
# 不但可以扩大，还可以缩小
rbd --image test resize --size 1G --allow-shrink

# 将镜像映射为本地块设备，可以进行格式化、挂载
rbd map test
# 格式化
mkfs.xfs -f /dev/rbd0
# 挂载
mount /dev/rbd0 /test

# 显示映射到本地块设备的镜像
rbd showmapped

# 卸载
umount /dev/rbd0
# 解除映射
rbd unmap /dev/rbd0

rbd rm {pool-name}/{image-name}

rbd --image test rm

# 放入回收站
rbd trash mv {pool-name}/{image-name}
# 彻底删除
rbd trash rm {pool-name}/{image-id}
# 还原
rbd trash restore {image-id}

# 创建快照
rbd snap create --image test --snap test_snap
# 列出镜像的所有快照
rbd snap ls --image test

# 回滚到指定快照
rbd snap rollback --image test --snap test_snap
# 另一种写法
rbd snap rollback rbd/test@test_snap

# 删除快照，注意删除是异步进行的，空间不会立刻释放
rbd snap rm --image test --snap test_snap
rbd snap purge --image test

# 保护快照
rbd snap protect --image test --snap test_snap
# 取消保护
rbd snap unprotect --image test --snap test_snap

# 清除指定镜像的所有快照
rbd snap purge {pool-name}/{image-name}

# 克隆镜像，注意只有镜像格式2才支持克隆
# 从快照创建克隆
rbd clone --image test --snap test_snap test_clone
# 列出快照的所有克隆
rbd children --image test --snap test_snap
# 将父镜像（被克隆的镜像的快照）的数据扁平化到子镜像，从而解除父子关联
rbd flatten --image test_clone

从Jewel开始，RBD镜像可以异步的跨越两个集群进行镜像（Mirroring）。通过配置，你可以镜像池中的所有、或者一部分镜像。

rbd mirror pool enable {pool-name} {mode}

# 启用名为local的集群的镜像复制，默认为pool
rbd --cluster local mirror pool enable image-pool pool
rbd --cluster remote mirror pool enable image-pool pool

mode取值：

1. pool，池中所有启用了journaling特性的镜像都被复制
2. image，只有明确配置的镜像才进行复制 

rbd mirror pool disable {pool-name}

rbd --cluster local mirror pool disable image-pool
rbd --cluster remote mirror pool disable image-pool

# 在池中创建一个对象，其内容来自文件
echo "Hello World" > /tmp/file
rados -p rbd put helloworld /tmp/file

# 查看对象
rados -p rbd ls | grep helloworld

# 根据CRUSH Map，列出OSD树
ceph osd tree
#                 缩进显示树层次
# ID  CLASS WEIGHT  TYPE NAME               STATUS REWEIGHT PRI-AFF 
#  -1       5.73999 root default                                    
#  -2       0.84000     host k8s-10-5-38-25                         
#   0   hdd 0.84000         osd.0               up  1.00000 1.00000 
#  -5       0.45000     host k8s-10-5-38-70                         
#   1   hdd 0.45000         osd.1               up  1.00000 1.00000 

# 移动桶的位置
# 将rack01移动到{root=default} 
ceph osd crush move rack01 root=default

# 显示镜像和PG的关系
ceph osd map rbd  test
#                                                 此镜像存放在1.b5这个PG中
#                                                        此PG位于 osd.3 osd.1 osd.6中
#                                                                      主副本 位于osd.3中
# osdmap e26 pool 'rbd' (1) object 'test' -> pg 1.40e8aab5 (1.b5) -> up ([3,1,6], p3) acting ([3,1,6], p3)

# 显示PG和镜像的关系
ceph pg map 1.c0
# osdmap e1885 pg 1.c0 (1.c0) -> up [9,8] acting [9,8]

Dump出所有PG：

pg dump {all|summary|sum|delta|pools|osds|pgs|pgs_brief [all|summary|sum|delta|pools|osds|pgs|pgs_brief...]}
# 示例
ceph pg dump [--format {format}]  # format取值plain或json

Dump出卡在指定状态中的PG的统计信息：

# threshold默认30秒
ceph pg dump_stuck inactive|unclean|stale|undersized|degraded [--format {format}] [-t|--threshold {seconds}]

ceph pg repair 1.c0
# instructing pg 1.c0 on osd.9 to repair

ceph pg force-backfill <pgid> [<pgid>...]  
ceph pg force-recovery <pgid> [<pgid>...] 
# 取消
ceph pg cancel-force-backfill <pgid> [<pgid>...]
ceph pg cancel-force-recovery <pgid> [<pgid>...]

参考官网的算法进行计算。

执行调整之前，必须保证集群处于健康状态。

为避免调整PG数量导致业务性能受到严重影响，应该调整一些参数：

ceph tell osd.* injectargs '--osd-max-backfills 1'
ceph tell osd.* injectargs '--osd-recovery-max-active 1'

其它相关的参数还包括：

osd_backfill_scan_min = 4 
osd_backfill_scan_max = 32 
osd recovery threads = 1 
osd recovery op priority = 1

按照2的幂进行翻倍增长，例如原来32个，可以先调整为64个。

注意：不要一下子把PG设置为太大的值，这会导致大规模的rebalance，影响系统性能。

等到上一步操作后，集群变为Active+Clean状态后，再将pgp_num设置的和pg_num一致。 

# 在RGW节点安装软件
# yum install ceph-radosgw

RGW_HOST=$(hostname -s)

# 在RGW节点，配置ceph.conf
cat << EOF >> /etc/ceph/ceph.conf
[client.rgw.$RGW_HOST]
rgw_frontends = "civetweb port=7480"
EOF

# 拷贝配置到所有Ceph节点

# 在RGW节点，创建数据目录
mkdir -p /var/lib/ceph/radosgw/ceph-rgw.$RGW_HOST

# 在RGW节点，创建用户，输出Keyring
ceph auth get-or-create client.rgw.$RGW_HOST osd 'allow rwx' mon 'allow rw' \
    -o /var/lib/ceph/radosgw/ceph-rgw.$RGW_HOST/keyring
chown -R ceph:ceph /var/lib/ceph/radosgw

# 在RGW节点，启用Systemd服务
systemctl enable ceph-radosgw.target
systemctl enable ceph-radosgw@rgw.$RGW_HOST
systemctl start ceph-radosgw@rgw.$RGW_HOST

[client.rgw.Carbon]
rgw_frontends = "civetweb port=80"

推送修改后的配置文件后，重启RGW服务：

systemctl restart ceph-radosgw.service

[client.rgw.Carbon]
# 指定包含了私钥和证书的PEM
rgw_frontends = civetweb port=443s ssl_certificate=/etc/ceph/private/keyandcert.pem
# Luminous开始，可以同时绑定SSL和非SSL端口
rgw_frontends = civetweb port=80+443s ssl_certificate=/etc/ceph/private/keyandcert.pem

RGW在index_pool池中存放桶（Bucket）索引数据，此池默认名为.rgw.buckets.index。

从0.94版本开始，支持对桶索引进行分片，避免单个桶中对象数量过多时出现性能瓶颈：

# 每个桶的最大索引分片数，默认0，表示不支持分片
rgw_override_bucket_index_max_shards = 0

你可以在global段配置上面的选项。 

要使用RGW的RESTful接口，你需要：

1. 创建初始的S3接口的用户
2. 创建Swift接口的子用户
3. 验证用户可以访问网关

要创建S3接口用户，需要在网关机上执行：

radosgw-admin user create --uid="rgw" --display-name="rgw"

access_key、secret_key会打印在屏幕上，要访问网关，客户端必须提供这两个key：

{
    "user_id": "rgw",
    "display_name": "rgw",
    "email": "",
    "suspended": 0,
    "max_buckets": 1000,
    "auid": 0,
    "subusers": [],
    "keys": [
        {
            "user": "rgw",
            "access_key": "IN01UCU1M1996LK6OM88",
            "secret_key": "AuuAbroSUlWLykbQHCbFLVO6RU2ozUEjIFkYeoqc"
        }
    ],
    "swift_keys": [],
    "caps": [],
    "op_mask": "read, write, delete",
    "default_placement": "",
    "placement_tags": [],
    "bucket_quota": {
        "enabled": false,
        "check_on_raw": false,
        "max_size": -1,
        "max_size_kb": 0,
        "max_objects": -1
    },
    "user_quota": {
        "enabled": false,
        "check_on_raw": false,
        "max_size": -1,
        "max_size_kb": 0,
        "max_objects": -1
    },
    "temp_url_keys": [],
    "type": "rgw"
}

要创建Swift子用户，需要在网关机上执行：

radosgw-admin subuser create --uid=alex --subuser=alex:swift --access=full

你需要为Swift子用户创建secret key：

radosgw-admin key create --subuser=alex:swift --key-type=swift --gen-secret

现在，你可以用自己熟悉的语言的S3、Swift客户端来验证用户是否可用。 

radosgw-admin bucket list                # 列出桶
radosgw-admin bucket limit check         # 显示桶的分片情况
radosgw-admin bucket link                # 将桶链接到用户
radosgw-admin bucket unlink              # 取消桶到用户的链接
radosgw-admin bucket stats               # 显示桶的统计信息
radosgw-admin bucket rm                  # 删除桶
radosgw-admin bucket check               # 检查桶索引
radosgw-admin bucket reshard             # 对桶进行重分片
radosgw-admin bucket sync disable        # 禁止桶同步
radosgw-admin bucket sync enable         # 启用桶同步

要创建桶，你需要使用合法的User ID + AWS Access Key发起请求，Ceph没有提供对应的命令行。需要注意以下约束：

1. 桶名称必须唯一
2. 桶名称不能格式化为IP地址
3. 桶名称在3-63字符之间
4. 桶名称不得包含大写字母、下划线，但是可以包含短横线
5. 桶名称必须以小写字母或数字开头
6. 桶名称必须由一系列的标签组成，每个标签用点号.分隔

我们可以使用MinIO客户端创建桶：

# 添加配置
#                                               access_key           secret_key
mc config host add rgw https://rgw.gmem.cc:7480 IN01UCU1M1996LK6OM88 AuuAbroSUlWLykbQHCbFLVO6RU2ozUEjIFkYeoqc

# 创建桶
mc mb rgw/test

现在通过Rgw命令行可以看到这个桶：

radosgw-admin buckets list
# [
#     "test"
# ]

Ceph默认开启了cephx协议，加密认证需要消耗少量的资源。

启用cephx后，Cephe会自动在包括/etc/ceph/ceph.$name.keyring在内的位置寻找钥匙串，你可以指定keyring选项来修改默认路径，但是不推荐。

在禁用了cephx的集群上，启用它的步骤为：

1. 创建 client.admin 密钥：
   

   # 如果你使用的自动部署工具已经生成此文件，切勿执行此命令，会覆盖
   ceph auth get-or-create client.admin mon 'allow *' mds 'allow *' osd 'allow *' -o /etc/ceph/ceph.client.admin.keyring

2. 创建mon集群所需的钥匙串、密钥：
   

   ceph-authtool --create-keyring /tmp/ceph.mon.keyring --gen-key -n mon. --cap mon 'allow *'

3. 将上述钥匙串复制到所有mon的mon data目录，例如：
   

   cp /tmp/ceph.mon.keyring /var/lib/ceph/mon/ceph-a/keyring

4. 为每个OSD生成密钥：
   

   ceph auth get-or-create osd.{$id} mon 'allow rwx' osd 'allow *' -o /var/lib/ceph/osd/ceph-{$id}/keyring

5. 为每个 MDS 生成密钥：

   ceph auth get-or-create mds.{$id} mon 'allow rwx' osd 'allow *' mds 'allow *' -o /var/lib/ceph/mds/ceph-{$id}/keyring

6. 添加以下内容到配置文件的global段：

   auth cluster required = cephx
   auth service required = cephx
   auth client required = cephx

7. 启动或重启Ceph集群：  

   # 停止当前节点上的所有Ceph守护进程
   sudo stop ceph-all
   sudo start ceph-all

修改配置文件global段：

auth cluster required = none
auth service required = none
auth client required = none

然后重启Ceph集群。 

# 列出keyring
ceph auth ls
# 添加OSD的keyring
ceph auth add {osd} {--in-file|-i} {path-to-osd-keyring}

任何时后你都可以Dump、反编译、修改、编译、注入CURSH map。如果要完全基于手工方式管理，不使用自动生成的CRUSH map，可以设置：

osd crush update on start = false

执行命令

ceph osd crush dump

# 下面的输出时安装后最初的状态，没有任何OSD

{   
    # 设备列表，最初为空                                                                                                                                                                       
    "devices": [],   
    # 桶类型定义列表                                                                                                                                                               
    "types": [                                                                                                                                                                           
        {                                                                                                                                                                                
            "type_id": 0,                                                                                                                                                                
            "name": "osd"                                                                                                                                                                
        },                                                                                                                                                                               
        {                                                                                                                                                                                
            "type_id": 1,                                                                                                                                                                
            "name": "host"                                                                                                                                                               
        },                                                                                                                                                                               
        {                                                                                                                                                                                
            "type_id": 2,                                                                                                                                                                
            "name": "chassis"                                                                                                                                                            
        },                                                                                                                                                                               
        {                                                                                                                                                                                
            "type_id": 3,                                                                                                                                                                
            "name": "rack"                                                                                                                                                               
        },                                                                                                                                                                               
        {                                                                                                                                                                                
            "type_id": 4,                                                                                                                                                                
            "name": "row"                                                                                                                                                                
        },                                                                                                                                                                               
        {                                                                                                                                                                                
            "type_id": 5,                                                                                                                                                                
            "name": "pdu"                                                                                                                                                                
        },                                                                                                                                                                               
        {                                                                                                                                                                                
            "type_id": 6,                                                                                                                                                                
            "name": "pod"                                                                                                                                                                
        },                                                                                                                                                                               
        {                                                                                                                                                                                
            "type_id": 7,                                                                                                                                                                
            "name": "room"                                                                                                                                                               
        },
        {
            "type_id": 8,
            "name": "datacenter"
        },
        {
            "type_id": 9,
            "name": "region"
        },
        {
            "type_id": 10,
            "name": "root"
        }
    ],
    # 桶列表，可以形成树状结构
    "buckets": [
        {
            "id": -1,
            "name": "default",
            "type_id": 10,
            "type_name": "root",
            "weight": 0,
            "alg": "straw2",
            "hash": "rjenkins1",
            "items": []
        }
        # 加入一个OSD节点（基于目录），自动生成如下两个Bucket：
        {                                                                                                                                                                          
            "id": -2,                                                                                                                                                              
            "name": "k8s-10-5-38-25",                                                                                                                                              
            "type_id": 1,                                                                                                                                                          
            "type_name": "host",                                                                                                                                                   
            "weight": 55050,                                                                                                                                                       
            "alg": "straw2",                                                                                                                                                       
            "hash": "rjenkins1",                                                                                                                                                   
            "items": [                                                                                                                                                             
                {                                                                                                                                                                  
                    "id": 0,                                                                                                                                                       
                    "weight": 55050,                                                                                                                                               
                    "pos": 0                                                                                                                                                       
                }                                                                                                                                                                  
            ]                                                                                                                                                                      
        },                                                                                                                                                                         
        {                                                                                                                                                                          
            "id": -3,                                                                                                                                                              
            "name": "k8s-10-5-38-25~hdd",                                                                                                                                          
            "type_id": 1,                                                                                                                                                          
            "type_name": "host",                                                                                                                                                   
            "weight": 55050,                                                                                                                                                       
            "alg": "straw2",                                                                                                                                                       
            "hash": "rjenkins1",                                                                                                                                                   
            "items": [                                                                                                                                                             
                {
                    "id": 0,
                    "weight": 55050,
                    "pos": 0
                }
            ]
        },

    ],
    # 规则列表
    "rules": [
        {
            "rule_id": 0,
            "rule_name": "replicated_rule",
            # 所属规则集
            "ruleset": 0,
            # 此规则是否用于RAID，取值replicated 或 raid4
            "type": 1,
            # 如果Pool的副本份数不在此范围内，则CRUSH不会使用当前规则
            "min_size": 1,
            "max_size": 10,
            "steps": [
                {
                    # 选择一个桶，并迭代其子树
                    "op": "take",
                    "item": -1,
                    "item_name": "default"
                },
                {
                    # 在上一步的基础上，确定每个副本如何放置
                    "op": "chooseleaf_firstn",
                    # 取值0，此Step适用pool-num-replicas个副本（所有）
                    # 取值>0 & < pool-num-replicas，适用num个副本
                    # 取值<0，适用pool-num-replicas -num个副本
                    "num": 0,
                    "type": "host"
                },
                {
                    "op": "emit"
                }
            ]
        }
    ],
    # 可微调参数，以及一些状态信息
    "tunables": {                                                                                                                                                                        
        "choose_local_tries": 0,                                                                                                                                                         
        "choose_local_fallback_tries": 0,                                                                                                                                                
        "choose_total_tries": 50,                                                                                                                                                        
        "chooseleaf_descend_once": 1,                                                                                                                                                    
        "chooseleaf_vary_r": 1,                                                                                                                                                          
        "chooseleaf_stable": 1,                                                                                                                                                          
        "straw_calc_version": 1,                                                                                                                                                         
        "allowed_bucket_algs": 54,    
        # 使用的Profile，执行ceph osd crush tunables hammer后此字段改变，连带其它tunables字段自动改变                                                                                                                                                   
        "profile": "jewel",                                                                                                                                                              
        "optimal_tunables": 1,                                                                                                                                                           
        "legacy_tunables": 0,                                                                                                                                                            
        "minimum_required_version": "jewel",                                                                                                                                             
        "require_feature_tunables": 1,                                                                                                                                                   
        "require_feature_tunables2": 1,                                                                                                                                                  
        "has_v2_rules": 0,                                                                                                                                                               
        "require_feature_tunables3": 1,                                                                                                                                                  
        "has_v3_rules": 0,                                                                                                                                                               
        "has_v4_buckets": 1,                                                                                                                                                             
        "require_feature_tunables5": 1,
        "has_v5_rules": 0
    },
    "choose_args": {}
}

执行下面的命令，导出当前Map：

ceph osd getcrushmap -o curshmap

然后，需要反编译为文本：

crushtool -d curshmap -o curshmap.src

源文件内容示例：

# begin crush map
tunable choose_local_tries 0
tunable choose_local_fallback_tries 0
tunable choose_total_tries 50
tunable chooseleaf_descend_once 1
tunable chooseleaf_vary_r 1
tunable straw_calc_version 1
tunable allowed_bucket_algs 54

# devices

# types
type 0 osd
type 1 host
type 2 chassis
type 3 rack
type 4 row
type 5 pdu
type 6 pod
type 7 room
type 8 datacenter
type 9 region.Values.storageclass.fsType
type 10 root

# buckets
root default {
        id -1           # do not change unnecessarily
        # weight 0.000
        alg straw2           
        hash 0  # rjenkins1
}
# rules
rule replicated_rule {
        id 0
        type replicated
        min_size 1
        max_size 10
        step take default
        step chooseleaf firstn 0 type host
        step emit
}

# end crush map

我们可以根据实际需要，对源文件进行修改，例如将算法改为straw，解决CentOS 7上CEPH_FEATURE_CRUSH_V4 1000000000000特性不满足的问题：

sed -i 's/straw2/straw/g' curshmap.src

修改源文件完毕后，执行下面的命令编译：

crushtool -c curshmap.src -o curshmap

最后，注入最新编译的Map：

ceph osd setcrushmap -i curshmap
# 会输出修订版号 

默认情况下，Ceph自动根据硬件类型，设置OSD的设备类型为hdd, ssd或nvme。你可以手工进行设置：

# 你需要移除当前设置的设备类型，才能重新设置
ceph osd crush rm-device-class <osd-name> [...]
# 示例
ceph osd crush rm-device-class osd.3 osd.4 osd.5 osd.6 osd.7 osd.8 osd.0 osd.10 osd.1 osd.12 osd.2 osd.13 


ceph osd crush set-device-class <class> <osd-name> [...]
# 示例
ceph osd crush set-device-class ssd osd.3 osd.4 osd.5 osd.6 osd.7 osd.8 osd.0 osd.10 osd.1 osd.12 osd.2 osd.13

列出集群中的CRUSH rule：

ceph osd crush rule ls

Dump出规则的内容：

ceph osd crush rule dump

ceph osd crush rule rm replicated_rule_ssd

创建一个规则，仅仅使用指定类型的设备：

ceph osd crush rule create-replicated <rule-name> <root> <failure-domain> <class>
# 示例：仅仅使用ssd类型的设备，失败域为host，也就是数据副本必须位于不同的主机上
ceph osd crush rule create-replicated replicated_rule_ssd default host ssd
ceph osd crush rule create-replicated replicated_rule_hdd default host hdd

为存储池指定所使用的规则：

ceph osd pool set <pool-name> crush_rule <rule-name>
# 修改规则
ceph osd pool set rbd-ssd crush_rule replicated_rule_ssd
# 创建存储池时指定规则
ceph osd pool create rbd-ssd 384 replicated replicated_rule_ssd

CRUSH rule的语法如下：

rule <rulename> {
        ruleset <ruleset>
        type [ replicated | erasure ]
        min_size <min-size>
        max_size <max-size>
        # 根据桶名称来选取CRUSH子树，并迭代，可限定设备类型
        step take <bucket-name> [class <device-class>]
        # choose：选择指定数量、类型的桶
        # chooseleaf：选择指定数量、类型的桶，并选择每个这些桶的一个叶子节点
        step [choose|chooseleaf] [firstn|indep] <N> <bucket-type>
        step emit
}

示例一，将主副本存放在SSD中，第二副本存放在HDD中：

rule ssd-primary-affinity {
    ruleset 0
    type replicated
    min_size 2
    max_size 3
    # 选择名为SSD的桶
    step take ssd
    # 在上述桶中的host类型的子树中选择叶子节点，存储1个副本（第一个）
    step chooseleaf firstn 1 type host
    # 执行
    step emit
    # 选择名为HDD的桶
    step take hdd
    # 在上述桶中的host类型的子树中选择叶子节点，存储N-1个副本（所有其它副本）
    step chooseleaf firstn -1 type host
    step emit
}

 示意二，在第一个机架上存储两个副本，第二个机架上存储一个副本：

rule 3_rep_2_racks {
   ruleset 1
   type replicated
   min_size 2
   max_size 3
   step take default
   # 选择一个Rack，存储2个副本
   step choose firstn 2 type rack
   # 在上述选定的Rack中选择Host
   step chooseleaf firstn 2 type host
   step emit
}

如果要添加OSD到CRUSH map中，执行：

ceph osd crush set {name} {weight} root={root} [{bucket-type}={bucket-name} ...]
# 示例
ceph osd crush set osd.14 0 host=xenial-100
ceph osd crush set osd.0 1.0 root=default datacenter=dc1 room=room1 row=foo rack=bar host=foo-bar-1

ceph osd crush reweight {name} {weight}

ceph osd crush remove {name}

ceph osd crush add-bucket {bucket-name} {bucket-type}

ceph osd crush move {bucket-name} {bucket-type}={bucket-name}, [...]

ceph osd crush remove {bucket-name} 

# 自动优化
ceph osd crush tunables optimal
# 最大兼容性，存在老旧内核的cephfs/rbd客户端时
ceph osd crush tunables legacy


# 选择一个PROFILE，例如jewel
ceph osd crush tunables {PROFILE} 

# weight在0-1之间，默认1，值越小，CRUSH 越避免将目标OSD作为主
ceph osd primary-affinity <osd-id> <weight>

使用CRUSH rule，可以限定某个Pool仅仅使用一部分OSD：

# SSD主机
host ceph-osd-ssd-server-1 {
      id -1
      alg straw
      hash 0
      item osd.0 weight 1.00
      item osd.1 weight 1.00
}

# HDD主机
host ceph-osd-hdd-server-1 {
      id -3
      alg straw
      hash 0
      item osd.4 weight 1.00
      item osd.5 weight 1.00
}

# HDD的根桶
root hdd {
      id -5
      alg straw
      hash 0
      item ceph-osd-hdd-server-1 weight 2.00
}

# SSD的根桶
root ssd {
      id -6
      alg straw
      hash 0
      item ceph-osd-ssd-server-1 weight 2.00
}


# 仅仅使用HDD的规则
rule hdd {
      ruleset 3
      type replicated
      min_size 0
      max_size 10
      step take hdd
      # 选择
      step chooseleaf firstn 0 type host
      step emit
}

# 仅仅使用SSD的规则
rule ssd {
      ruleset 4
      type replicated
      min_size 0
      max_size 4
      step take ssd
      step chooseleaf firstn 0 type host
      step emit
}

# 在SSD上存储主副本，其它副本存放在HDD
rule ssd-primary {
      ruleset 5
      type replicated
      min_size 5
      max_size 10
      step take ssd
      step chooseleaf firstn 1 type host
      step emit
      step take hdd
      step chooseleaf firstn -1 type host
      step emit
}

前提条件：

1. 集群处于OK状态
2. 所有PG处于active+clean状态

步骤，针对每个需要改变尺寸的OSD，一个个的处理：

1. 修改Cephe配置，设置

   osd_journal_size = NEWSIZE

2. 禁止数据迁移（防止OSD进入out状态）：

   ceph osd set noout

3. 停止目标OSD实例
4. 刷出缓存：

   ceph-osd -i  OSDID --flush-journal

5. 删除日志：
   

   # 基于Helm部署时，需要到宿主机上的osd_directory下寻找对应目录
   cd /var/lib/ceph/osd/ceph-osd.OSDID
   rm journal 

6. 创建一个新的日志文件：

   ceph-osd --mkjournal -i OSDID

7. 启动OSD
8. 验证新的日志尺寸被使用：
   

   # Helm安装的情况下，需要在OSD容器中执行
   ceph --admin-daemon /var/run/ceph/ceph-osd.OSDID.asok config get osd_journal_size

9. 确保集群处于OK状态，所有PG处于active+clean状态 

处理完所有OSD后，执行： 

ceph osd unset noout

# 默认4K，可以--io-size定制
# 默认16线程，可以--io-threads定制

# 随机读
rbd bench -p rbd-hdd --image benchmark --io-total 128M --io-type read --io-pattern rand
# elapsed: 25 ops:  32768 ops/sec:  1284.01  bytes/sec: 5259316.53
# elapsed: 15 ops: 327680 ops/sec: 20891.46  bytes/sec: 85571410.91
# HDD差20倍

# 顺序读
rbd bench -p rbd-hdd --image benchmark --io-total 64M --io-type read --io-pattern seq
# elapsed: 46 ops:  163840 ops/sec:   3528.06  bytes/sec: 14450938.87
# elapsed: 45 ops: 1638400 ops/sec:   35672.87 bytes/sec: 146116057.32
# HDD差10倍

# 随机写
rbd bench -p rbd-hdd --image benchmark --io-total 128M --io-type write --io-pattern rand
# elapsed: 85  ops:  32768 ops/sec: 383.24  bytes/sec: 1569743.22
# elapsed: 111 ops: 327680 ops/sec: 2936.78 bytes/sec: 12029055.24
# HDD差7倍

# 顺序写
rbd bench -p rbd-hdd --image benchmark --io-total 128M --io-type write --io-pattern seq
# elapsed: 3  ops: 32768  ops/sec:  9382.16 bytes/sec: 38429334.91
# elapsed: 17 ops: 327680 ops/sec: 18374.69 bytes/sec: 75262749.05
# HDD差1倍

要动态、临时（重启后消失）的修改组件的参数，可以使用tell命令。

# 临时修改所有OSD和恢复相关的选项
ceph tell osd.* injectargs '--osd-max-backfills 1'             # 并发回填操作数
ceph tell osd.* injectargs '--osd-recovery-threads 1'          # 恢复线程数量
ceph tell osd.* injectargs '--osd-recovery-op-priority 1'      # 恢复线程优先级  
ceph tell osd.* injectargs '--osd-client-op-priority 63'       # 客户端线程优先级
ceph tell osd.* injectargs '--osd-recovery-max-active 1'       # 最大活跃的恢复请求数

可以将RBD上的Watcher加入黑名单，这样可以解除RBD的Watcher，再其它机器上挂载RBD：

rbd status  kubernetes-dynamic-pvc-22d9e659-6e31-11e8-92e5-c6b9f35768f0                                                                                                     
# Watchers:                                                                                                                                                                                
#         watcher=10.0.3.1:0/158685765 client.3524447 cookie=18446462598732840965

# 添加到黑名单
ceph osd blacklist add 10.0.3.1:0/158685765
# blacklisting 10.0.3.1:0/158685765 until 2018-08-21 18:04:31.855791 (3600 sec)

rbd status  kubernetes-dynamic-pvc-22d9e659-6e31-11e8-92e5-c6b9f35768f0
# Watchers: none

ceph osd blacklist ls
# listed 1 entries
# 10.0.3.1:0/158685765 2018-08-21 18:04:31.855791

ceph osd blacklist rm 10.0.3.1:0/158685765

ceph osd blacklist clear

# 列出池
rados lspools
.rgw.root
default.rgw.control
default.rgw.meta
default.rgw.log
rbd
rbd-ssd
rbd-hdd

# 创建池pool-name，使用auid 123，使用crush规则4
mkpool pool-name [123[ 4]] 

# 复制池的内容
cppool pool-name dest-pool

# 移除池
rmpool pool-name pool-name --yes-i-really-really-mean-it

# 清空池中对象
purge pool-name --yes-i-really-really-mean-it

# 显示每个池的对象数量、空间占用情况
rados df

# 列出池中对象
rados ls -p rbd

# 将池的所有者设置为auid 123
rados chown 123  -p rbd

# 列出池快照
rados lssnap -p rbd

# 创建池快照
rados mksnap snap-name -p rbd

# 删除池快照
rados rmsnap mksnap snap-name -p rbd

# 从快照中恢复对象
rados rollback <obj-name> <snap-name>

# 列出对象的快照
rados listsnaps <obj-name>

# 读对象
rados get object-name /tmp/obj -p rbd

# 使用指定的偏移量写对象
rados put object-name /tmp/obj --offset offset

# 附加内容到对象
rados append <obj-name> [infile

# 截断对象为指定的长度
rados truncate <obj-name> length

# 创建对象
rados create <obj-name>

# 移除对象
rados rm <obj-name> ...[--force-full]

# 复制对象
rados cp <obj-name> [target-obj]

# 列出扩展属性
rados listxattr <obj-name>
# 获取扩展属性
rados getxattr <obj-name> attr
# 设置扩展属性
rados setxattr <obj-name> attr val
# 移除扩展属性
rados rmxattr <obj-name> attr

# 显示属性
rados stat <obj-name>

rados list-inconsistent-pg pool-name

rados list-inconsistent-obj  40.14  --format=json-pretty

rados list-inconsistent-snapset 40.14 

ceph mgr module enable dashboard

# 使用自签名证书
ceph dashboard create-self-signed-cert

# 使用外部提供的证书
ceph dashboard set-ssl-certificate -i dashboard.crt
ceph dashboard set-ssl-certificate-key -i dashboard.key

# 禁用SSL
ceph config set mgr mgr/dashboard/ssl false

ceph dashboard ac-user-create admin  administrator -i - <<<"pswd"

# 创建用户
radosgw-admin user create --uid=rgw --display-name=rgw --system

# 设置access_key和secret_key
ceph dashboard set-rgw-api-access-key -i - <<< "$(radosgw-admin user info --uid=rgw | jq -r .keys[0].access_key)"
ceph dashboard set-rgw-api-secret-key -i - <<< "$(radosgw-admin user info --uid=rgw | jq -r .keys[0].secret_key)"

# 禁用SSL校验
ceph dashboard set-rgw-api-ssl-verify False

注意：详尽的日志每小时可能超过 1GB ，如果你的系统盘满了，这个节点就会停止工作。

# 通过中心化配置下发
ceph tell osd.0 config set debug_osd 0/5

# 到目标主机上，针对OSD进程设置
ceph daemon osd.0 config set debug_osd 0/5

可以为各子系统定制日志级别：

# debug {subsystem} = {log-level}/{memory-level}

[global]
        debug ms = 1/5
[mon]
        debug mon = 20
        debug paxos = 1/5
        debug auth = 2
[osd]
        debug osd = 1/5
        debug filestore = 1/5
        debug journal = 1
        debug monc = 5/20
[mds]
        debug mds = 1
        debug mds balancer = 1
        debug mds log = 1
        debug mds migrator = 1

子系统列表：

如果磁盘空间有限，可以配置/etc/logrotate.d/ceph，加快日志滚动：

rotate 7
weekly
size 500M
compress
sharedscripts

然后设置定时任务，定期检查并清理： 

30 * * * * /usr/sbin/logrotate /etc/logrotate.d/ceph >/dev/null 2>&1

为了将Ceph部署到K8S集群中，可以利用ceph-helm项目。 目前此项目存在一些限制：

1. public和cluster网络必须一样
2. 如果Storage的用户不是admin，你需要在Ceph集群中手工创建用户，并在K8S中创建对应的Secrets
3. ceph-mgr只能运行单副本

执行下面的命令把ceph-helm添加到本地Helm仓库：

# 此项目使用Helm本地仓库保存Chart，如果没有启动本地存储，请启动
nohup /usr/local/bin/helm serve  --address 0.0.0.0:8879 > /dev/null 2>&1 &

git clone https://github.com/ceph/ceph-helm
pushd ceph-helm/ceph
make
popd
# 构建成功后Chart归档文件位于 ./ceph-0.1.0.tgz

可用值的说明如下：

# 部署哪些组件
deployment:
  ceph: true
  storage_secrets: true
  client_secrets: true
  rbd_provisioner: true
  rgw_keystone_user_and_endpoints: false

# 修改这些值可以指定其它镜像
images:
  ks_user: docker.io/kolla/ubuntu-source-heat-engine:3.0.3
  ks_service: docker.io/kolla/ubuntu-source-heat-engine:3.0.3
  ks_endpoints: docker.io/kolla/ubuntu-source-heat-engine:3.0.3
  bootstrap: docker.io/ceph/daemon:tag-build-master-luminous-ubuntu-16.04
  dep_check: docker.io/kolla/ubuntu-source-kubernetes-entrypoint:4.0.0
  daemon: docker.io/ceph/daemon:tag-build-master-luminous-ubuntu-16.04
  ceph_config_helper: docker.io/port/ceph-config-helper:v1.7.5
  # 如果使用官方提供的StorageClass，你需要扩展kube-controller镜像，否则报executable file not found in $PATH
  rbd_provisioner: quay.io/external_storage/rbd-provisioner:v0.1.1
  minimal: docker.io/alpine:latest
  pull_policy: "IfNotPresent"

# 不同Ceph组件使用什么节点选择器
labels:
  jobs:
    node_selector_key: ceph-mon
    node_selector_value: enabled
  mon:
    node_selector_key: ceph-mon
    node_selector_value: enabled
  mds:
    node_selector_key: ceph-mds
    node_selector_value: enabled
  osd:
    node_selector_key: ceph-osd
    node_selector_value: enabled
  rgw:
    node_selector_key: ceph-rgw
    node_selector_value: enabled
  mgr:
    node_selector_key: ceph-mgr
    node_selector_value: enabled

pod:
  dns_policy: "ClusterFirstWithHostNet"
  replicas:
    rgw: 1
    mon_check: 1
    rbd_provisioner: 2
    mgr: 1
  affinity:
      anti:
        type:
          default: preferredDuringSchedulingIgnoredDuringExecution
        topologyKey:
          default: kubernetes.io/hostname
  # 如果集群资源匮乏，可以调整下面的资源请求
  resources:
    enabled: false
    osd:
      requests:
        memory: "256Mi"
        cpu: "100m"
      limits:
        memory: "1024Mi"
        cpu: "1000m"
    mds:
      requests:
        memory: "10Mi"
        cpu: "100m"
      limits:
        memory: "50Mi"
        cpu: "500m"
    mon:
      requests:
        memory: "50Mi"
        cpu: "100m"
      limits:
        memory: "100Mi"
        cpu: "500m"
    mon_check:
      requests:
        memory: "5Mi"
        cpu: "100m"
      limits:
        memory: "50Mi"
        cpu: "500m"
    rgw:
      requests:
        memory: "5Mi"
        cpu: "100m"
      limits:
        memory: "50Mi"
        cpu: "500m"
    rbd_provisioner:
      requests:
        memory: "5Mi"
        cpu: "100m"
      limits:
        memory: "50Mi"
        cpu: "500m"
    mgr:
      requests:
        memory: "5Mi"
        cpu: "100m"
      limits:
        memory: "50Mi"
        cpu: "500m"
    jobs:
      bootstrap:
        limits:
          memory: "1024Mi"
          cpu: "2000m"
        requests:
          memory: "128Mi"
          cpu: "100m"
      secret_provisioning:
        limits:
          memory: "1024Mi"
          cpu: "2000m"
        requests:
          memory: "128Mi"
          cpu: "100m"
      ks_endpoints:
        requests:
          memory: "128Mi"
          cpu: "100m"
        limits:
          memory: "1024Mi"
          cpu: "2000m"
      ks_service:
        requests:
          memory: "128Mi"
          cpu: "100m"
        limits:
          memory: "1024Mi"
          cpu: "2000m"
      ks_user:
        requests:
          memory: "128Mi"
          cpu: "100m"
        limits:
          memory: "1024Mi"
          cpu: "2000m"

secrets:
  keyrings:
    mon: ceph-mon-keyring
    mds: ceph-bootstrap-mds-keyring
    osd: ceph-bootstrap-osd-keyring
    rgw: ceph-bootstrap-rgw-keyring
    mgr: ceph-bootstrap-mgr-keyring
    admin: ceph-client-admin-keyring
  identity:
    admin: ceph-keystone-admin
    user: ceph-keystone-user
    user_rgw: ceph-keystone-user-rgw

# !! 根据实际情况网络配置
network:
  public:   10.0.0.0/16
  cluster:  10.0.0.0/16
  port:
    mon: 6789
    rgw: 8088

# !! 在此添加需要的Ceph配置项
conf:
  # 对象存储网关服务相关
  rgw_ks:
    config:
      rgw_keystone_api_version: 3
      rgw_keystone_accepted_roles: "admin, _member_"
      rgw_keystone_implicit_tenants: true
      rgw_s3_auth_use_keystone: true
  ceph:
    override:
    append:
    config:
      global:
        mon_host: null
      osd:
        ms_bind_port_max: 7100

ceph:
  rgw_keystone_auth: false
  enabled:
    mds: true
    rgw: true
    mgr: true
  storage:
    # 基于目录的OSD，在宿主机上存储的路径
    # /var/lib/ceph-helm/osd会挂载到容器的/var/lib/ceph/osd目录
    osd_directory: /var/lib/ceph-helm
    mon_directory: /var/lib/ceph-helm
    # 将日志收集到/var/log，便于fluentd来采集
    mon_log: /var/log/ceph/mon
    osd_log: /var/log/ceph/osd

# !! 是否启用基于目录的OSD，需要配合节点标签ceph-osd=enabled
# 存储的位置由上面的storage.osd_directory确定，沿用现有的文件系统
osd_directory:
  enabled: false

# 如果设置为1，则允许Ceph格式化磁盘，这会导致数据丢失
enable_zap_and_potentially_lose_data: true
# !! 基于块设备的OSD，需要配合节点标签ceph-osd-device-dev-***=enabled
osd_devices:
  - name: dev-vdb
    # 使用的块设备
    device: /dev/vdb
    # 日志可以存储到独立块设备上，提升性能，如果不指定，存放在device
    journal: /dev/vdc
    # 是否删除其分区表
    zap: "1"

bootstrap:
  enabled: false
  script: |
    ceph -s
    function ensure_pool () {
      ceph osd pool stats $1 || ceph osd pool create $1 $2
    }
    ensure_pool volumes 8

# 启用的mgr模块
ceph_mgr_enabled_modules:
  - restful
  - status

# 配置mgr模块
ceph_mgr_modules_config:
  dashboard:
    port: 7000
  localpool:
    failure_domain: host
    subtree: rack
    pg_num: "128"
    num_rep: "3"
    min_size: "2"

# 在部署/升级后，执行下面的命令
# 这些命令通过kubectl来执行
ceph_commands:
- ceph osd pool create  pg_num
- ceph osd crush tunables 

# Kubernetes 存储类配置
storageclass:
  provision_storage_class: true
  provisioner: ceph.com/rbd
  # 存储类名称
  name: ceph-rbd
  monitors: nullcurshmap.src
  # 使用的RBD存储池的名称
  pool: rbd
  admin_id: admin
  admin_secret_name: pvc-ceph-conf-combined-storageclass
  admin_secret_namespace: ceph
  user_id: admin
  user_secret_name: pvc-ceph-client-key
  # RBD设备的镜像格式和特性
  image_format: "2"
  image_features: layering

endpoints:
  # 集群域名后缀
  cluster_domain_suffix: k8s.gmem.cc
  identity:
    name: keystone
    namespace: null
    auth:
      admin:
        region_name: RegionOne
        username: admin
        password: password
        project_name: admin
        user_domain_name: default
        project_domain_name: default
      user:
        role: admin
        region_name: RegionOne
        username: swift
        password: password
        project_name: service
        user_domain_name: default
        project_domain_name: default
    hosts:
      default: keystone-api
      public: keystone
    host_fqdn_override:
      default: null
    path:
      default: /v3
    scheme:
      default: http
    port:
      admin:
        default: 35357
      api:
        default: 80
  object_store:
    name: swift
    namespace: null
    hosts:
      default: ceph-rgw
    host_fqdn_override:
      default: null
    path:
      default: /swift/v1
    scheme:
      default: http
    port:
      api:
        default: 8088
  ceph_mon:
    namespace: null
    hosts:
      default: ceph-mon
    host_fqdn_override:
      default: null
    port:
      mon:
        default: 6789

Ext4文件系统上基于目录的OSD配置，覆盖值示例：

network:
  public: 10.0.0.0/8
  cluster: 10.0.0.0/8

conf:
  ceph:
    config:
      global:
        # Ext4文件系统
        filestore_xattr_use_omap: true
      osd:
        ms_bind_port_max: 7100
        # Ext4文件系统
        osd_max_object_name_len: 256
        osd_max_object_namespace_len: 64
        osd_crush_update_on_start : false

ceph:
  storage:
    osd_directory: /var/lib/ceph-helm
    mon_directory: /var/lib/ceph-helm
    mon_log: /var/log/ceph/mon
    osd_log: /var/log/ceph/osd

# 和操作系统共享一个分区，基于目录的OSD
osd_directory:
  enabled: true

storageclass:
  name: ceph-rbd
  pool: rbd

为Ceph创建名字空间：

kubectl create namespace ceph

创建RBAC资源：

kubectl create -f ceph-helm/ceph/rbac.yaml

为了部署Ceph集群，需要为K8S集群中，不同角色（参与到Ceph集群中的角色）的节点添加标签： 

1. ceph-mon=enabled，部署mon的节点上添加
2. ceph-mgr=enabled，部署mgr的节点上添加
3. ceph-osd=enabled，部署基于设备、基于目录的OSD的节点上添加
4. ceph-osd-device-NAME=enabled。部署基于设备的OSD的节点上添加，其中NAME需要替换为上面 ceph-overrides.yaml中的OSD设备名，即：
   1. ceph-osd-device-dev-vdb=enabled
   2. ceph-osd-device-dev-vdc=enabled

对应的K8S命令：

# 部署Ceph Monitor的节点
kubectl label node xenial-100 ceph-mon=enabled ceph-mgr=enabled
# 对于每个OSD节点
kubectl label node xenial-100 ceph-osd=enabled ceph-osd-device-dev-vdb=enabled ceph-osd-device-dev-vdc=enabled
kubectl label node xenial-101 ceph-osd=enabled ceph-osd-device-dev-vdb=enabled ceph-osd-device-dev-vdc=enabled

helm install --name=ceph local/ceph --namespace=ceph -f ceph-overrides.yaml

确保所有Pod正常运行：

# kubectl -n ceph get pods
NAME                                    READY     STATUS    RESTARTS   AGE
ceph-mds-7cb7c647c7-7w6pc               0/1       Pending   0          18h
ceph-mgr-66cb85cbc6-hsm65               1/1       Running   3          1h
ceph-mon-check-758b88d88b-2r975         1/1       Running   1          1h
ceph-mon-gvtq6                          3/3       Running   3          1h
ceph-osd-dev-vdb-clj5f                  1/1       Running   15         1h
ceph-osd-dev-vdb-hldw5                  1/1       Running   15         1h
ceph-osd-dev-vdb-l4v6t                  1/1       Running   15         1h
ceph-osd-dev-vdb-v5jmd                  1/1       Running   15         1h
ceph-osd-dev-vdb-wm4v4                  1/1       Running   15         1h
ceph-osd-dev-vdb-zwr65                  1/1       Running   15         1h
ceph-osd-dev-vdc-27wfk                  1/1       Running   15         1h
ceph-osd-dev-vdc-4w4fn                  1/1       Running   15         1h
ceph-osd-dev-vdc-cpkxh                  1/1       Running   15         1h
ceph-osd-dev-vdc-twmwq                  1/1       Running   15         1h
ceph-osd-dev-vdc-x8tpb                  1/1       Running   15         1h
ceph-osd-dev-vdc-zfrll                  1/1       Running   15         1h
ceph-rbd-provisioner-5544dcbcf5-n846s   1/1       Running   4          18h
ceph-rbd-provisioner-5544dcbcf5-t84bz   1/1       Running   3          18h
ceph-rgw-7f97b5b85d-nc5fq               0/1       Pending   0          18h

其中MDS、RGW的Pod处于Pending状态，这是由于没有给任何节点添加标签：

# rgw即RADOS Gateway，是Ceph的对象存储网关服务，它是基于librados接口封装的FastCGI服务
# 提供存储和管理对象数据的REST API。对象存储适用于图片、视频等各类文件
# rgw兼容常见的对象存储API，例如绝大部分Amazon S3 API、OpenStack Swift API
ceph-rgw=enabled
# mds即Metadata Server，用于支持文件系统
ceph-mds=enabled

现在从监控节点，检查一下Ceph集群的状态：

# kubectl -n ceph exec -ti ceph-mon-gvtq6 -c ceph-mon -- ceph -s
  cluster:
    # 集群标识符
    id:     08adecc5-72b1-4c57-b5b7-a543cd8295e7
    health: HEALTH_OK
 
  services:
    # 监控节点
    mon: 1 daemons, quorum xenial-100
    # 管理节点
    mgr: xenial-100(active)
    # OSD（Ceph Data Storage Daemon）
    osd: 12 osds: 12 up, 12 in
  
  data:
    # 存储池、PG数量
    pools:   0 pools, 0 pgs
    # 对象数量
    objects: 0 objects, 0 bytes
    # 磁盘的用量，如果是基于文件系统的OSD，则操作系统用量也计算在其中
    usage:   1292 MB used, 322 GB / 323 GB avail

    # 所有PG都未激活，不可用
    pgs:     100.000% pgs not active
             # undersize是由于OSD数量不足（复制份数3，此时仅仅一个OSD），peerd表示128个PG配对到OSD
             128 undersized+peered
    # 将复制份数设置为1后，输出变为
    pgs:     100.000% pgs not active
             128 creating+peering
    # 过了一小段时间后，输出变为
    pgs: 128 active+clean
    # 到这里，PVC才能被提供，否则PVC状态显示 Provisioning，Provisioner日志中出现类似下面的：
    # attempting to acquire leader lease...
    # successfully acquired lease to provision for pvc ceph/ceph-pvc
    # stopped trying to renew lease to provision for pvc ceph/ceph-pvc, timeout reached

如果K8S集群没有默认StorageClass，可以设置：

kubectl patch storageclass ceph-rbd -p '{"metadata": {"annotations":{"storageclass.kubernetes.io/is-default-class":"true"}}}'

这样没有显式声明StorageClass的PVC将自动通过ceph-rbd进行卷提供。 

# 创建具有384个PG的名为rbd的复制存储池
ceph osd pool create rbd 384 replicated
ceph osd pool set rbd min_size 1

# 开发环境下，可以把Replica份数设置为1
ceph osd pool set rbd size 1
# min_size 会自动被设置的比size小
# 减小size后，可以立即看到ceph osd status的used变小

# 初始化池，最好在所有节点加入后，调整好CURSH Map后执行
rbd pool init rbd

# 可以创建额外的用户，例如下面的，配合Value storageclass.user_id=k8s使用
ceph auth get-or-create-key client.k8s mon 'allow r' osd 'allow rwx pool=rbd' | base64
# 如果使用默认用户admin，则不需要生成上面这步。admin权限也是足够的


# 其它命令
# 查看块设备使用情况（需要MGR）
ceph osd status
+----+------------+-------+-------+--------+---------+--------+---------+-----------+
| id |    host    |  used | avail | wr ops | wr data | rd ops | rd data |   state   |
+----+------------+-------+-------+--------+---------+--------+---------+-----------+
| 0  | xenial-100 |  231M | 26.7G |    0   |  3276   |    0   |     0   | exists,up |
| 1  | xenial-103 |  216M | 26.7G |    0   |   819   |    0   |     0   | exists,up |
| 2  | xenial-101 |  253M | 26.7G |    0   |     0   |    0   |     0   | exists,up |
| 3  | xenial-103 |  286M | 26.7G |    0   |     0   |    0   |     0   | exists,up |
| 4  | xenial-101 |  224M | 26.7G |    0   |  1638   |    0   |     0   | exists,up |
| 5  | xenial-105 |  211M | 26.7G |    0   |     0   |    0   |     0   | exists,up |
| 6  | xenial-100 |  243M | 26.7G |    0   |     0   |    0   |     0   | exists,up |
| 7  | xenial-102 |  224M | 26.7G |    0   |  2457   |    0   |     0   | exists,up |
| 8  | xenial-102 |  269M | 26.7G |    0   |  1638   |    0   |     0   | exists,up |
| 9  | xenial-104 |  252M | 26.7G |    0   |  2457   |    0   |     0   | exists,up |
| 10 | xenial-104 |  231M | 26.7G |    0   |     0   |    0   |     0   | exists,up |
| 11 | xenial-105 |  206M | 26.7G |    0   |     0   |    0   |     0   | exists,up |
+----+------------+-------+-------+--------+---------+--------+---------+-----------+

可以先使用ceph命令尝试创建RBD并挂载：

# 镜像格式默认2
# format 1 - 此格式兼容所有版本的 librbd 和内核模块，但是不支持较新的功能，像克隆。此格式目前已经废弃
# 2 - librbd 和 3.11 版以上内核模块才支持。此格式增加了克隆支持，未来扩展更容易
rbd create  test --size 1G --image-format 2 --image-feature layering

# 映射为本地块设备，如果卡住，可能有问题，一段时间后会有提示
rbd map test
# CentOS 7 下可能出现如下问题：
#   rbd: sysfs write failed
#   In some cases useful info is found in syslog - try "dmesg | tail".
#   rbd: map failed: (5) Input/output error
# dmesg | tail
#   [1180891.928386] libceph: mon0 10.5.39.41:6789 feature set mismatch, 
#     my 2b84a042a42 < server's 40102b84a042a42, missing 401000000000000                                            
#   [1180891.934804] libceph: mon0 10.5.39.41:6789 socket error on read
# 解决办法是把Bucket算法从straw2改为straw

# 挂载为目录
fdisk /dev/rbd0
mkfs.ext4 /dev/rbd0
mkdir /test
mount /dev/rbd0 /test

# 测试性能
# 1MB块写入
sync; dd if=/dev/zero of=/test/data bs=1M count=512; sync
# 512+0 records in
# 512+0 records out
# 536870912 bytes (537 MB) copied, 4.44723 s, 121 MB/s
# 16K随机写
fio -filename=/dev/rbd0 -direct=1 -iodepth 1 -thread -rw=randwrite -ioengine=psync -bs=16k -size=512M -numjobs=30 -runtime=60 -name=test
# WRITE: bw=35.7MiB/s (37.5MB/s), 35.7MiB/s-35.7MiB/s (37.5MB/s-37.5MB/s), io=2148MiB (2252MB), run=60111-60111msec 
# 16K随机读
fio -filename=/dev/rbd0 -direct=1 -iodepth 1 -thread -rw=randread -ioengine=psync -bs=16k -size=512M -numjobs=30 -runtime=60 -name=test
# READ: bw=110MiB/s (116MB/s), 110MiB/s-110MiB/s (116MB/s-116MB/s), io=6622MiB (6943MB), run=60037-60037msec

# 删除测试镜像
umount /test
rbd unmap test
rbd remove test

确认Ceph RBD可以挂载、读写后，创建一个PVC：

kind: PersistentVolumeClaim
apiVersion: v1
metadata:
  name: ceph-pvc
  namespace: ceph
spec:
  accessModes:
   - ReadWriteOnce
  resources:
    requests:
       storage: 1Gi
  storageClassName: ceph-rbd

查看PVC是否绑定到PV：

kubectl -n ceph create -f ceph-pvc.yaml

kubectl -n ceph get pvc

# NAME       STATUS    VOLUME                                     CAPACITY   ACCESS MODES   STORAGECLASS   AGE
# ceph-pvc   Bound     pvc-43caef06-46b4-11e8-bed8-deadbeef00a0   1Gi        RWO            ceph-rbd       3s

# 在Monitor节点上确认RBD设备已经创建
rbd ls
# kubernetes-dynamic-pvc-fbddb77d-46b5-11e8-9204-8a12961e4b47
rbd info kubernetes-dynamic-pvc-fbddb77d-46b5-11e8-9204-8a12961e4b47
# rbd image 'kubernetes-dynamic-pvc-fbddb77d-46b5-11e8-9204-8a12961e4b47':
#         size 128 MB in 32 objects
#         order 22 (4096 kB objects)
#         block_name_prefix: rbd_data.11412ae8944a
#         format: 2
#         features: layering
#         flags: 
#         create_timestamp: Mon Apr 23 05:20:07 2018

需要在其它命名空间中使用此存储池时，拷贝一下Secret：

kubectl -n ceph get secrets/pvc-ceph-client-key -o json --export | jq '.metadata.namespace = "default"' | kubectl create -f - 

helm delete ceph --purge
kubectl delete namespace ceph

此外，如果要重新安装，一定要把所有节点的一下目录清除掉：

rm -rf /var/lib/ceph-helm
rm -rf /var/lib/ceph

只需要安装相应的Provisioner，配置适当的StorageClass即可。示例：

1. Provisioner：https://git.gmem.cc/alex/helm-charts/src/branch/master/ceph-provisioners
2. 安装脚本：https://git.gmem.cc/alex/k8s-init/src/branch/master/4.infrastructure/0.ceph-external.sh

Kubernetes卷的动态Provisioning，目前需要依赖于external-storage项目，K8S没有提供内置的Provisioner。此项目存在不少问题，生产环境下可以考虑静态提供。

Provisioner会自动在Ceph集群的默认CephFS中创建“卷”，Ceph支持基于libcephfs+librados来实现一个基于CephFS目录的虚拟卷。

你可以在默认CephFS中看到volumes/kubernetes目录。kubernetes目录对应一个虚拟卷组。每个PV对应了它的一个子目录。

1. 监控节点对于集群的正确运行非常重要，应当为其分配独立的硬件资源。如果跨数据中心部署，监控节点应该分散在不同数据中心或者可用性区域
2. 日志可能会让集群的吞吐量减半。理想情况下，应该在不同磁盘上运行操作系统、OSD数据、OSD日志。对于高吞吐量工作负载，考虑使用SSD进行日志存储
3. 纠删编码（Erasure coding）可以用于存储大容量的一次性写、非频繁读、性能要求不高的数据。纠删编码存储消耗小，但是IOPS也降低
4. 目录项（Dentry）和inode缓存可以提升性能，特别是存在很多小对象的情况下
5. 使用缓存分层（Cache Tiering）可以大大提升集群性能。此技术可以在热、冷Tier之间自动的进行数据迁移。为了最大化性能，请使用SSD作为缓存池、并且在低延迟节点上部署缓存池
6. 部署奇数个数的监控节点，以便仲裁投票（Quorum Voting），建议使用3-5个节点。更多的节点可以增强集群的健壮性，但是mon之间需要保持数据同步，这会影响性能
7. 诊断性能问题的时候，总是从最底层（磁盘、网络）开始，然后再检查块设备、对象网关等高层接口
8. 在大型集群里用单独的集群网络（Cluster Newwork）可显著地提升性能和安全性

1. 限制最大文件大小，创建极大的文件会导致删除过程很缓慢
2. 避免在生产环境下使用试验特性。你应该使用单个活动MDS、不使用快照（默认如此）
3. 避免增大max_mds，可能导致大于1个的MDS处于Active
4. 客户端选择：
   1. FUSE，容易使用、容易升级和服务器集群保持一致
   2. 内核，性能好
   3. 不同客户端的功能并不完全一致，例如FUSE支持客户端配额，内核不支持
5. 对于Ceph 10.x，最好使用4.x内核。如果必须使用老内核，你应该使用FUSE作为客户端

OSD需要消耗CPU资源，可以将其绑定到一个核心上。如果使用纠删码，则需要更多的CPU资源。此外，集群处于Recovery状态时，OSD的CPU消耗显著增加

MON不怎么消耗CPU资源，几个G内存的单核心物理机即可。

MDS相当消耗CPU资源，考虑4核心或更多CPU。如果依赖于CephFS处理大量工作，应当分配专用物理机

MON/MDS需要不少于2G内存。OSD通常需要1G内存（和存储容量有关）。此外，集群处于Recovery状态时，OSD的内存消耗显著增加，因此配备2G内存更好

最好具有万兆网络，公共网络、集群网络需要物理隔离（双网卡连接到独立交换机）。对于数百TB规模的集群，千兆网络也能够正常工作

集群网络往往消耗更多的带宽，此外，高性能的集群网络对于Recovery的效率很重要。

如果交换机支持，应当启用Jumbo帧，可以提升网络吞吐量。

在生产环境下，最好让OSD使用独立的驱动器，如果和OS共享驱动，最好使用独立的分区。

通常使用SATA SSD作为日志存储，预算足够可以考虑PCIE SSD。Intel S3500的4K随机写 IOPS可达10K+

关于RAID：

1. 最好不要使用RAID
2. 如果有RAID卡，并且磁盘数量太多，而对应的内存数量不足（每个OSD大概需要2G内存），可以RAID0
3. 不要使用RAID5，因为随机IO的性能降低

关于filestore：

1. 建议使用SSD存储日志，以减少访问时间、读取延迟，实现吞吐量的显著提升
2. 可以为创建SSD分区，每个分区作为一个OSD的日志存储，但是最好不要超过4个

1. 启用超线程Hyper-Threading技术
2. 关闭节能
3. 关闭NUMA

# 修改pid max
# 执行命令
echo 4194303 > /proc/sys/kernel/pid_max
# 或者
sysctl -w kernel.pid_max=4194303

# read_ahead, 数据预读到内存，提升磁盘读操作能力
echo "8192" > /sys/block/sda/queue/read_ahead_kb

# 禁用交换文件
echo "vm.swappiness = 0" | tee -a /etc/sysctl.conf

# I/O Scheduler：SSD使用用noop，SATA/SAS使用deadline
echo "deadline" > /sys/block/sda/queue/scheduler
echo "noop" > /sys/block/sda/queue/scheduler

底层文件系统的稳定性和性能对于Ceph很重要。在开发、非关键部署时可以使用btrfs，这也是未来的方向。关键的生产环境下应该使用XFS。

在高可扩容性的存储环境下，XFS和btrfs相比起ext3/4有很大优势。XFS和btrfs都是日志式文件系统，更健壮，容易从崩溃、断电中恢复。日志文件系统会在执行写操作之前，把需要进行的变更记录到日志。

OSD依赖于底层文件系统的扩展属性（Extended Attributes，XATTRs），来存储各种内部对象状态和属性。XFS支持64KB的XATTRs，但是ext4就太小了，你应该为运行在ext4上的OSD配置：

# 新版本Ceph此配置项已经没了
filestore xattr use omap = true

关于文件系统的一些知识：

1. XFS 、 btrfs 和 ext4 都是日志文件系统
2. XFS很成熟
3. btrfs相对年轻，他是一个写时复制（COW）文件系统，因而支持可写文件系统快照。此外它还支持透明压缩、完整性校验

PG的数量应当总是和PGP相同。PGP是为了实现定位而创建的PG。再平衡仅仅再pgp_num被修改后才会触发，仅仅修改pg_num不会触发。

随着OSD数量的变化，选取适当的PG数量很重要。因为PG数量对集群行为、数据持久性（Durability，灾难性事件发生时保证数据堡丢失）有很大影响。此外，归置组很耗计算资源，所以很多存储池x很多归置组会导致性能下降。建议的取值：

1. 对于小于5个OSD的集群：设置为128
2. 5-10个OSD的集群：设置为512
3. 10-50个OSD的集群：设置为1024
4. 超过50个OSD的集群，需要自己权衡，利用pgcalc来计算适合的PG数量

《Ceph分布式存储学习指南》一书中建议的PG数量算法：

每个池的PG数量 = OSD总数 * 100 / 最大副本数 / 池数

计算结果需要向上舍入到2的N次幂。此外该书倾向于让所有池具有相同的PG数量。

1. 加入新的OSD后，考虑设置权重为0，然后逐渐增加权重，这样可以避免性能下降

DigitalOcean开源了Ceph的Exporter，本文使用gmemcc的fork版本。Ceph Exporter和MON节点通信，所有信息都通过rados_mon_command()调用获得。

此Exporter可以在任意Ceph客户端节点上运行，和任何形式的Ceph客户端一样，你需要提供ceph.conf、ceph.USER.keyring两个配置文件。

你可以直接使用预构建好的镜像：

digitalocean/ceph_exporter:2.0.1-luminous

或者，从源码构建：

sudo apt install librados-dev

git clone https://github.com/gmemcc/ceph_exporter.git
cd ceph_exporter
go install
make
docker build -t docker.gmem.cc/digitalocean/ceph_exporter .

对于Luminous12.2或者Mimic13.2版本，MGR已经内置了Prometheus模块，不再需要ceph_exporter了。

执行下面的命令启用Prometheus模块：

ceph mgr module enable prometheus

然后，你就可以访问任意MGR节点的http://MGR_HOST:9283/metrics，抓取指标了。Prometheus配置示例：

scrape_configs:               
- job_name: ceph                           
  static_configs:                          
  - targets:
    # 列出所有MGR节点，防止故障转移时数据丢失                      
    - 10.0.1.1:9283                        
    labels:                                
      cluster: ceph

Grafana仪表盘可以参考这个示例：https://grafana.com/dashboards/7056

R表示必须支持的特性，S表示该版本内核可以支持，-*-表示从这个版本开始支持。

1. Ceph From Scratch
2. CEPH CONTROL COMMANDS

1. 纠删码支持
2. 缓存分层
3. 键/值 OSD后端
4. 独立的RadosGW（使用civetweb）

1. LRC纠删码
2. CephFS日志恢复，诊断工具

1. RGW对象版本化
2. 对象桶分片
3. Crush straw2算法

1. 纠删码到达稳定，支持很多新特性
2. 支持Swift API新特性，例如对象过期设置

1. CephFS到达稳定
2. RGW多站点可达（支持主/主配置）
3. AWS4兼容
4. RBD镜像（mirroring）
5. 引入BlueStore

1. BlueStore到达稳定
2. AsyncMessenger
3. RGW：通过ES来索引元数据
4. S3桶生命周期API支持
5. RGW：支持导出为NFS v3接口
6. Rados支持在基于纠删码的池上进行overwrite操作
7. 基于纠删码池的RBD卷

1. 集成Web仪表盘Ceph Dashboard
2. 直接管理裸设备的BlueStore到达稳定并且作为默认选项
3. 纠删码池完全支持overwirte，可以和CephFS/RDB一起使用
4. 引入组件ceph-mgr，如果该组件停止，则指标不会更新，某些依赖于指标的请求，例如ceph df，无法工作
5. 可扩容能力提升，可部署10000OSD的集群
6. 每个OSD支持关联一个设备类（例如hdd/ssd），允许CRUSH规则将数据简单地映射到系统中的设备的子集。通常不需要手动编写CRUSH规则或手动编辑CRUSH
7. 支持优化CRUSH权重，以保持OSD之间数据的近乎完美的分布
8. OSD可以根据后端设备是HDD还是SSD来调整其默认配置
9. RGW引入了上传对象的服务器端加密，用于管理加密密钥的三个选项有：自动加密（仅推荐用于测试设置），客户提供的类似于Amazon SSE-C规范的密钥，以及通过使用外部密钥管理服务
10. RGW具有初步的类似AWS的存储桶策略API支持。现在，策略是一种表达一系列新授权概念的方式。未来，这将成为附加身份验证功能的基础，例如STS和组策略等
11. RGW通过使用rados命名空间合并了几个元数据索引池
12. 引入组件rbd-mirror，负责RBD卷的镜像复制
13. rbd trash命令支持延迟的镜像删除
14. 镜像可以通过rbd mirroringreplay delay配置选项支持可配置的复制延迟
15. 多Active MDS到达稳定状态

1. 引入一个新的、全功能和美观的仪表盘 Dashboard V2
2. RADOS：配置选项可被mon中心化存储和管理
3. RADOS：在恢复和再平衡时，mon使用的磁盘大大减小
4. RADOS：引入一个异步恢复特性，减少在OSD从错误恢复期间，请求的tail latency
5. RGW：支持将一个Zone（或者Buckets的子集）复制到外部云服务，例如S3
6. RGW：支持S3多因子身份验证
7. RGW：前端Beast到达stable
8. CephFS：使用多MDS时快照功能到达stable
9. RBD：镜像克隆不需要显式的protect/unprotect步骤
10. RBD：镜像支持深克隆（包含parent镜像、关联快照的数据的克隆）到新池，支持修改数据布局

1. 仪表盘：增加很多新功能，全方位的查看各种指标，对Ceph进行管理
2. RADOS：每个池的PG数量 ，现在可以随时减小了。集群可以根据用量和管理员的提示，自动优化PG数量
3. RADOS：v2 wire protocol支持传输加密
4. RADOS：mon/osd使用的物理设备的健康指标（例如SMART）可以得到跟踪，并且在预期出现磁盘失败前进行警告
5. RADOS：在recovery/backfill时，OSD更有效的优先恢复重要的PG、对象
6. RADOS：例如磁盘失败后的恢复，这样长期运行的后台操作的进度，在ceph status中报告
7. RGW：Beast替换civetweb作为默认Web前端
8. CephFS：MDS稳定性得到很大优化，特别是针对大缓存、长时间运行的具有大内存的客户端
9. CephFS：在Rook管理的环境下，CephFS可以通过NFS-Ganesha集群暴露出去
10. CephFS：支持查询进行中的针对MDS的scrub的进度
11. RBD：镜像可以在最小宕机时间内进行迁移，这可以支持在池之间迁移镜像、修改镜像布局
12. RBD：rbd perf image iotop 以及 rbd perf image iostat命令可以提供iostat风格的、针对所有RBD镜像的监控
13. RBD：ceph-mgr的Prometheus Exporter支持暴露所有RBD镜像的IO监控指标
14. RBD：在一个池中，可以使用命名空间来隔离RBD，实现多租户

1. 新的工具cephadm，用于支持容器化部署
2. Health警告可以被临时/永久的静默
3. Dashboard：UI增强、安全性增强
4. 管理功能的增强
5. RADOS：从N版引入的PG括缩，默认启用
6. RADOS：Bluestore包含了多项改进和性能增强
7. RBD：镜像支持一种新的，基于快照的模式，不再依赖于journaling特性
8. RBD：克隆操作保持源镜像的稀疏性（sparseness）
9. RBD：改进了rbd-nbd 工具，可以使用新的内核特性
10. RBD：缓存性能增强

创建新CephFS报错Error EINVAL: pool 'rbd-ssd' already contains some objects. Use an empty pool instead，解决办法：

ceph fs new cephfs rbd-ssd rbd-hdd --force

断电后出现此问题。MDS进程报错： Error recovering journal 0x200: (5) Input/output error。诊断过程：

# 健康状况
ceph health detail
# HEALTH_ERR mds rank 0 is damaged; mds cluster is degraded
# mds.0 is damaged

# 文件系统详细信息，可以看到唯一的MDS Boron启动不了
ceph fs status
# cephfs - 0 clients
# ======
# +------+--------+-----+----------+-----+------+
# | Rank | State  | MDS | Activity | dns | inos |
# +------+--------+-----+----------+-----+------+
# |  0   | failed |     |          |     |      |
# +------+--------+-----+----------+-----+------+
# +---------+----------+-------+-------+
# |   Pool  |   type   |  used | avail |
# +---------+----------+-------+-------+
# | rbd-ssd | metadata |  138k |  106G |
# | rbd-hdd |   data   | 4903M | 2192G |
# +---------+----------+-------+-------+

# +-------------+
# | Standby MDS |
# +-------------+
# |    Boron    |
# +-------------+

# 显示错误原因
ceph tell mds.0 damage
# terminate called after throwing an instance of 'std::out_of_range'
#   what():  map::at
# Aborted

# 尝试修复，无效
ceph mds repaired 0

# 尝试导出CephFS日志，无效
cephfs-journal-tool journal export backup.bin
# 2019-10-17 16:21:34.179043 7f0670f41fc0 -1 Header 200.00000000 is unreadable
# 2019-10-17 16:21:34.179062 7f0670f41fc0 -1 journal_export: Journal not readable, attempt object-by-object dump with `rados`Error ((5) Input/output error)

# 尝试重日志修复，无效
# 尝试将journal中所有可回收的 inodes/dentries 写到后端存储（如果版本比后端更高）
cephfs-journal-tool event recover_dentries summary
# Events by type:
# Errors: 0
# 2019-10-17 16:22:00.836521 7f2312a86fc0 -1 Header 200.00000000 is unreadable

# 尝试截断日志，无效
cephfs-journal-tool journal reset 
# got error -5from Journaler, failing
# 2019-10-17 16:22:14.263610 7fe6717b1700  0 client.6494353.journaler.resetter(ro) error getting journal off disk
# Error ((5) Input/output error)


# 删除重建，数据丢失
ceph fs rm cephfs  --yes-i-really-mean-it



## 又一次遇到此问题

# 深度清理，发现200.00000000存在数据不一致
ceph osd deep-scrub all
40.14 shard 14: soid 40:292cf221:::200.00000000:head data_digest
  0x6ebfd975 != data_digest 0x9e943993 from auth oi 40:292cf221:::200.00000000:head
  (22366'34 mds.0.902:1 dirty|data_digest|omap_digest s 90 uv 34 dd 9e943993 od ffffffff alloc_hint [0 0 0])                                                                                  
40.14 deep-scrub 0 missing, 1 inconsistent objects
40.14 deep-scrub 1 errors

# 查看RADOS不一致对象详细信息
rados list-inconsistent-obj  40.14  --format=json-pretty
{
    "epoch": 23060,
    "inconsistents": [
        {
            "object": {
                "name": "200.00000000",
            },
            "errors": [],
            "union_shard_errors": [
                # 错误原因，校验信息不一致
                "data_digest_mismatch_info"
            ],
            "selected_object_info": {
                "oid": {
                    "oid": "200.00000000",
                },
            },
            "shards": [
                {
                    "osd": 7,
                    "primary": true,
                    "errors": [],
                    "size": 90,
                    "omap_digest": "0xffffffff"
                },
                {
                    "osd": 14,
                    "primary": false,

# errors：分片之间存在不一致，而且无法确定哪个分片坏掉了，原因：
#    data_digest_mismatch 此副本的摘要信息和主副本不一样
#    size_mismatch 此副本的数据长度和主副本不一致
#    read_error 可能存在磁盘错误
                    "errors": [
                        # 这里的原因是两个副本的摘要不一致
                        "data_digest_mismatch_info"
                    ],
                    "size": 90,
                    "omap_digest": "0xffffffff",
                    "data_digest": "0x6ebfd975"
                }
            ]
        }
    ]
}
# 转为处理inconsistent问题，停止OSD.14，Flush 日志，启动OSD.14，执行PG修复
# 无效…… 执行PG修复后Ceph会自动以权威副本覆盖不一致的副本，但是并非总能生效，
# 例如，这里的情况，主副本的数据摘要信息丢失

# 删除故障对象
rados -p rbd-ssd  rm 200.00000000

通常可以认为属于Ceph的Bug。这些Bug可能因为数据状态引发，有些时候将崩溃OSD的权重清零，可以恢复：

# 尝试解决osd.17启动后立即宕机
ceph osd reweight 17 0

如果创建一个存储池后，其所有PG都卡在此状态，可能原因是CRUSH map不正常。你可以配置osd_crush_update_on_start为true让集群自动调整CRUSH map。

ceph -s显示如下状态，长期不恢复：

cluster:                 
    health: HEALTH_WARN                                                    
            Reduced data availability: 2 pgs inactive, 2 pgs peering
            19 slow requests are blocked > 32 sec
  data:
    pgs:     0.391% pgs not active
             510 active+clean
             2   peering

此案例中，使用此PG的Pod呈Known状态。

检查卡在inactive状态的PG：

ceph pg dump_stuck inactive

PG_STAT STATE   UP     UP_PRIMARY ACTING ACTING_PRIMARY  
17.68   peering [3,12]          3 [3,12]              3
16.32   peering [4,12]          4 [4,12]              4

输出其中一个PG的诊断信息，片断如下：

// ceph pg 17.68 query
{                                                   
    "info": {                                                
        "stats": {
            "state": "peering",
            "stat_sum": {
                "num_objects_dirty": 5
            },
            "up": [
                3,
                12
            ],
            "acting": [
                3,
                12
            ],
            // 因为哪个OSD而阻塞
            "blocked_by": [
                12
            ],
            "up_primary": 3,
            "acting_primary": 3
        }
    },
    "recovery_state": [
        // 如果顺利，第一个元素应该是 "name": "Started/Primary/Active"
        {
            "name": "Started/Primary/Peering/GetInfo",
            "enter_time": "2018-06-11 18:32:39.594296",
            // 但是，卡在向OSD 12 请求信息这一步上
            "requested_info_from": [
                {
                    "osd": "12"
                }
            ]
        },
        {
            "name": "Started/Primary/Peering",
        },
        {
            "name": "Started",
        }
    ]
}

没有获得osd-12阻塞Peering的明确原因。 

查看日志，osd-12位于10.0.0.104，osd-3位于10.0.0.100，后者为Primary OSD。

osd-3日志，在18:26开始出现，和所有其它OSD之间心跳检测失败。此时10.0.0.100负载很高，卡死。

osd-12日志，在18:26左右大量出现：

osd.12 466 heartbeat_check: no reply from 10.0.0.100:6803 osd.4 since back 2018-06-11 18:26:44.973982 ...

直到18:44分仍然无法进行心跳检测，重启osd-12后一切恢复正常。 

检查无法完成的PG：

ceph pg dump_stuck

# PG_STAT STATE      UP     UP_PRIMARY ACTING ACTING_PRIMARY
# 17.79   incomplete [9,17]          9 [9,17]              9
# 32.1c   incomplete [16,9]         16 [16,9]             16
# 17.30   incomplete [16,9]         16 [16,9]             16
# 31.35   incomplete [9,17]          9 [9,17]              9

查询PG 17.30的诊断信息：

// ceph pg  17.30 query
{
  "state": "incomplete",
  "info": {
    "pgid": "17.30",
    "stats": {
      // 被osd.11阻塞而无法完成，此osd已经不存在
      "blocked_by": [
        11
      ],
      "up_primary": 16,
      "acting_primary": 16
    }
  },
  // 恢复的历史记录
  "recovery_state": [
    {
      "name": "Started/Primary/Peering/Incomplete",
      "enter_time": "2018-06-17 04:48:45.185352",
      // 最终状态，此PG没有完整的副本
      "comment": "not enough complete instances of this PG"
    },
    {
      "name": "Started/Primary/Peering",
      "enter_time": "2018-06-17 04:48:45.131904",
      "probing_osds": [
        "9",
        "16",
        "17"
      ],
      // 期望检查已经不存在的OSD
      "down_osds_we_would_probe": [
        11
      ],
      "peering_blocked_by_detail": [
        {
          "detail": "peering_blocked_by_history_les_bound"
        }
      ]
    }
  ]
}

可以看到17.30期望到osd.11寻找权威数据，而osd.11已经永久丢失了。这种情况下，可以尝试强制标记PG为complete。

首先，停止PG的主OSD：

service ceph-osd@16 stop

然后，运行下面的工具：

ceph-objectstore-tool --data-path /var/lib/ceph/osd/ceph-16  --pgid 17.30 --op mark-complete
# Marking complete 
# Marking complete succeeded

最后，重启PG的主OSD：

service ceph-osd@16 start

不做副本的情况下，单个OSD宕机即导致数据不可用：

ceph health detail 
# 注意Acting Set仅仅有一个成员
# pg 2.21 is stuck stale for 688.372740, current state stale+active+clean, last acting [7]
# 但是其它PG的Acting Set则不是
# pg 3.4f is active+recovering+degraded, acting [9,1]

如果OSD的确出现硬件故障，则数据丢失。此外，你也无法对这种PG进行查询操作。

定位出问题PG的主OSD，停止它，刷出日志，然后修复PG：

ceph health detail
# HEALTH_ERR 2 scrub errors; Possible data damage: 2 pgs inconsistent
# OSD_SCRUB_ERRORS 2 scrub errors
# PG_DAMAGED Possible data damage: 2 pgs inconsistent
#     pg 15.33 is active+clean+inconsistent, acting [8,9]
#     pg 15.61 is active+clean+inconsistent, acting [8,16]

# 查找OSD所在机器
ceph osd find 8
 
# 登陆到osd.8所在机器
systemctl stop ceph-osd@8.service
ceph-osd -i 8 --flush-journal
systemctl start ceph-osd@8.service
ceph pg repair 15.61

持有对象权威副本的OSD宕机或被剔除，会导致该问题出现。例如两个配对的OSD（共同处理某个PG）：

1. osd.1宕机
2. osd.2独自处理了一些写操作
3. osd1开机
4. osd.1+osd2配对，由于osd.2独自的写操作，缺失的对象排队等候在osd.1上恢复
5. 恢复完成之前，osd.2宕机，或者被移除

在上面这个事件序列中，osd.1知道权威副本存在，但是却找不到，这种情况下针对目标对象的请求会被阻塞，直到权威副本的持有者osd上线。

执行下面的命令，定位存在问题的PG：

ceph health detail | grep unfound
# OBJECT_UNFOUND 1/90055 objects unfound (0.001%)
#     pg 33.3e has 1 unfound objects
#    pg 33.3e is active+recovery_wait+degraded, acting [17,6], 1 unfound

进一步，定位存在问题的对象：

// ceph pg 33.3e list_missing
{
    "offset": {
        "oid": "",
        "key": "",
        "snapid": 0,
        "hash": 0,
        "max": 0,
        "pool": -9223372036854775808,
        "namespace": ""
    },
    "num_missing": 1,
    "num_unfound": 1,
    "objects": [
        {
            "oid": {
                // 丢失的对象
                "oid": "obj_delete_at_hint.0000000066",
                "key": "",
                "snapid": -2,
                "hash": 2846662078,
                "max": 0,
                "pool": 33,
                "namespace": ""
            },
            "need": "1723'1412",
            "have": "0'0",
            "flags": "none",
            "locations": []
        }
    ],
    "more": false
}

如果丢失的对象太多，more会显示为true。

执行下面的命令，可以查看PG的诊断信息：

// ceph pg 33.3e query
{
  "state": "active+recovery_wait+degraded",
  "recovery_state": [
    {
      "name": "Started/Primary/Active",
      "enter_time": "2018-06-16 15:03:32.873855",
      // 丢失的对象所在的OSD
      "might_have_unfound": [
        {
          "osd": "6",
          "status": "already probed"
        },
        {
          "osd": "11",
          "status": "osd is down"
        }
      ],
    } 
  ]
}

上面输出中的osd.11，先前已经出现硬件故障，被移除了。这意味着unfound的对象已经不可恢复。你可以标记：

# 回滚到前一个版本，如果是新创建对象则忘记其存在。不支持EC池
ceph pg 33.3e mark_unfound_lost revert
# 让Ceph忘记unfound对象的存在
ceph pg 33.3e mark_unfound_lost delete 

/usr/lib/python2.7/dist-packages/ceph_deploy/osd.py第376行，替换为：

LOG.info(line.decode('utf-8')) 

应该安装ceph-deploy的1.5.39版本，2.0.0版本仅仅支持luminous：

apt remove ceph-deploy
apt install ceph-deploy=1.5.39 -y

在我的环境下，是因为MON节点识别的public addr为LVS的虚拟网卡的IP地址导致。修改配置，显式指定MON的IP地址即可：

[mon.master01-10-5-38-24]
public addr = 10.5.38.24 
cluster addr = 10.5.38.24

[mon.master02-10-5-38-39]
public addr = 10.5.38.39
cluster addr = 10.5.38.39

[mon.master03-10-5-39-41]
public addr = 10.5.39.41
cluster addr = 10.5.39.41

在我的环境下部署，出现一系列和权限有关的问题，如果你遇到相同问题且不关心安全性，可以修改配置：

# kubectl -n ceph edit configmap ceph-etc
apiVersion: v1
data:
  ceph.conf: |
    [global]
    fsid = 08adecc5-72b1-4c57-b5b7-a543cd8295e7
    mon_host = ceph-mon.ceph.svc.k8s.gmem.cc
    # 添加以下三行
    auth client required = none
    auth cluster required = none
    auth service required = none
    [osd]
    # 在大型集群里用单独的“集群”网可显著地提升性能
    cluster_network = 10.0.0.0/16
    ms_bind_port_max = 7100
    public_network = 10.0.0.0/16
kind: ConfigMap

如果需要保证集群安全，请参考下面几个案例。

问题现象：

此Pod一直无法启动，查看容器日志，发现：

timeout 10 ceph --cluster ceph auth get-or-create mgr.xenial-100 mon 'allow profile mgr' osd 'allow *' mds 'allow *' -o /var/lib/ceph/mgr/ceph-xenial-100/keyring

0 librados: client.admin authentication error (1) Operation not permitted

问题分析：

连接到可以访问的ceph-mon，执行命令：

kubectl -n ceph exec -it ceph-mon-nhx52 -c ceph-mon -- ceph

发现报同样的错误。这说明client.admin的Keyring有问题。登陆到ceph-mon，获取Keyring列表：

# kubectl -n ceph exec -it ceph-mon-nhx52 -c ceph-mon bash
# ceph --cluster=ceph  --name mon. --keyring=/var/lib/ceph/mon/ceph-xenial-100/keyring auth list   
 
installed auth entries:

client.admin
        key: AQAXPdtaAAAAABAA6wd1kCog/XtV9bSaiDHNhw==
        auid: 0
        caps: [mds] allow
        caps: [mgr] allow *
        caps: [mon] allow *
        caps: [osd] allow *

client.bootstrap-mds
        key: AQAgPdtaAAAAABAAFPgqn4/zM5mh8NhccPWKcw==
        caps: [mon] allow profile bootstrap-mds
client.bootstrap-osd
        key: AQAUPdtaAAAAABAASbfGQ/B/PY4Imoa4Gxsa2Q==
        caps: [mon] allow profile bootstrap-osd
client.bootstrap-rgw
        key: AQAJPdtaAAAAABAAswtFjgQWahHsuy08Egygrw==
        caps: [mon] allow profile bootstrap-rgw

而当前使用的client.admin的Keyring内容为：

[client.admin]
  key = AQAda9taAAAAABAAgWIsgbEiEsFRJQq28hFgTQ==
  auid = 0
  caps mds = "allow"
  caps mon = "allow *"
  caps osd = "allow *"
  caps mgr = "allow *"

内容不一致。使用auth list获得的client.admin的Keyring，可以发现是有效的：

ceph --cluster=ceph --name mon. --keyring=/var/lib/ceph/mon/ceph-xenial-100/keyring auth get client.admin > client.admin.keyyring
ceph --name client.admin --keyring client.admin.keyyring # OKskydns_skydns_dns_cachemiss_count_total{instance="172.27.100.134:10055"}

检查一下各Pod的/etc/ceph/ceph.client.admin.keyring，可以发现都是从Secret ceph-client-admin-keyring挂载的。那么这个Secret是如何生成的呢？执行命令：

kubectl -n ceph get job --output=yaml --export | grep ceph-client-admin-keyring -B 50

可以发现Job ceph-storage-keys-generator负责生成该Secret。 查看其Pod日志可以生成Keyring、创建Secret的记录。进一步查看Pod的资源定义，可以看到负责创建的脚本/opt/ceph/ceph-storage-key.sh挂载自ConfigMap ceph-bin中的ceph-storage-key.sh。

解决此问题最简单的办法就是修改Secret，将其修改为集群中实际有效的Keyring：

# 导出Secret定义
kubectl -n ceph get  secret ceph-client-admin-keyring --output=yaml --export > ceph-client-admin-keyring
# 获得有效Keyring的Base64编码
cat client.admin.keyyring | base64
# 将Secret中的编码替换为上述Base64，然后重新创建Secret
kubectl -n ceph apply -f ceph-client-admin-keyring

此外Secret pvc-ceph-client-key中存放的也是admin用户的Key，其内容也需要替换到有效的：

kubectl -n ceph edit secret  pvc-ceph-client-key

原因和上一个问题类似，还是权限问题。

查看无法绑定的PVC日志：

# kubectl -n ceph describe pvc
 Normal   Provisioning        53s   ceph.com/rbd ceph-rbd-provisioner-5544dcbcf5-n846s 708edb2c-4619-11e8-abf2-e672650d97a2  External provisioner is provisioning volume for claim
"ceph/ceph-pvc"
  Warning  ProvisioningFailed  53s   ceph.com/rbd ceph-rbd-provisioner-5544dcbcf5-n846s 708edb2c-4619-11e8-abf2-e672650d97a2  Failed to provision volume with StorageClass "general"
: failed to create rbd image: exit status 1, command output: 2018-04-22 13:44:35.269967 7fb3e3e3ad80 -1 did not load config file, using default settings.
2018-04-22 13:44:35.297828 7fb3e3e3ad80 -1 auth: unable to find a keyring on /etc/ceph/ceph.client.admin.keyring,/etc/ceph/ceph.keyring,/etc/ceph/keyring,/etc/ceph/keyring.bin: (2)
 No such file or directoryConnection to localhost closed by remote host.
Connection to localhost closed.e3e3ad80  0 librados: client.admin authentication error (1) Operation not permitted

rbd-provisioner需要读取StorageClass定义，获取需要的凭证信息：

# kubectl -n ceph get storageclass --output=yaml
apiVersion: v1                                                                                                                                                                      
items:                                                                                                                                                                              
- apiVersion: storage.k8s.io/v1                                                                                                                                                     
  kind: StorageClass                                                                                                                                                                
  metadata:                                                                                                                                 
    name: general
  parameters:
    adminId: admin
    adminSecretName: pvc-ceph-conf-combined-storageclass
    adminSecretNamespace: ceph
    imageFeatures: layering
    imageFormat: "2"
    monitors: ceph-mon.ceph.svc.k8s.gmem.cc:6789
    pool: rbd
    userId: admin
    userSecretName: pvc-ceph-client-key
  provisioner: ceph.com/rbd
  reclaimPolicy: Delete

可以看到牵涉到两个Secret：pvc-ceph-conf-combined-storageclass、pvc-ceph-client-key，你需要把正确的Keyring内容写入其中。

症状：PVC可以Provision，RBD可以通过Ceph命令挂载，但是Pod无法启动，Describe之显示：

auth: unable to find a keyring on /etc/ceph/keyring: (2) No such file or directory
monclient(hunting): authenticate NOTE: no keyring found; disabled cephx authentication
librados: client.admin authentication error (95) Operation not supported

解决办法：把ceph.client.admin.keyring拷贝一份为 /etc/ceph/keyring即可。

原因和上一个问题一样。查看无法启动的容器日志：

kubectl -n ceph logs ceph-osd-dev-vdb-bjnbm -c osd-prepare-pod
# ceph --cluster ceph --name client.bootstrap-osd --keyring /var/lib/ceph/bootstrap-osd/ceph.keyring health                                                             
# 0 librados: client.bootstrap-osd authentication error (1) Operation not permitted                                                         
# [errno 1] error connecting to the cluster

进一步查看，可以发现/var/lib/ceph/bootstrap-osd/ceph.keyring挂载自ceph-bootstrap-osd-keyring下的ceph.keyring：

# kubectl -n ceph get secret ceph-bootstrap-osd-keyring --output=yaml --export
apiVersion: v1
data:
  ceph.keyring: W2NsaWVudC5ib290c3RyYXAtb3NkXQogIGtleSA9IEFRQVlhOXRhQUFBQUFCQUFSQ2l1bVY1NFpOU2JGVWwwSDZnYlJ3PT0KICBjYXBzIG1vbiA9ICJhbGxvdyBwcm9maWxlIGJvb3RzdHJhcC1vc2QiCgo=
kind: Secret
metadata:
  creationTimestamp: null
  name: ceph-bootstrap-osd-keyring
  selfLink: /api/v1/namespaces/ceph/secrets/ceph-bootstrap-osd-keyring
type: Opaque

# BASE64解码后：
[client.bootstrap-osd]
  key = AQAYa9taAAAAABAARCiumV54ZNSbFUl0H6gbRw==
  caps mon = "allow profile bootstrap-osd"

获得实际有效的Keyring：

kubectl -n ceph exec -it ceph-mon-nhx52 -c ceph-mon -- ceph --cluster=ceph --name mon. --keyring=/var/lib/ceph/mon/ceph-xenial-100/keyring auth get client.bootstrap-osd
# 注意上述命令的输出的第一行exported keyring for client.bootstrap-osd不属于Keyring
[client.bootstrap-osd]
        key = AQAUPdtaAAAAABAASbfGQ/B/PY4Imoa4Gxsa2Q==
        caps mon = "allow profile bootstrap-osd"

修改Secret：

kubectl -n ceph edit secret ceph-bootstrap-osd-keyring

报错信息：

# kubectl -n ceph logs  ceph-osd-dev-vdc-cpkxh -c osd-activate-pod
ceph_disk.main.Error: Error: No cluster conf found in /etc/ceph with fsid 08adecc5-72b1-4c57-b5b7-a543cd8295e7
# 每个OSD都包同样的错误

对应的配置文件内容： 

kubectl -n ceph get configmap ceph-etc --output=yaml
apiVersion: v1
data:
  ceph.conf: |
    [global]
    fsid = a4426e8a-c46d-4407-95f1-911a23a0dd6e
    mon_host = ceph-mon.ceph.svc.k8s.gmem.cc
    [osd]
    cluster_network = 10.0.0.0/16
    ms_bind_port_max = 7100
    public_network = 10.0.0.0/16
kind: ConfigMap
metadata:
  name: ceph-etc
  namespace: ceph

可以看到，fsid不一致。修改一下ConfigMap中的fsid即可解决此问题。  

报错信息：

describe pod报错：timeout expired waiting for volumes to attach/mount for pod
kubelet报错：executable file not found in $PATH, rbd output

原因分析：动态提供的持久卷，包含两个阶段：

1. 卷提供，原本由控制平面负责，controller-manager中需要包含rbd命令，才能在Ceph集群中创建供K8S使用的镜像。目前这个职责由external_storage项目的rbd-provisioner完成
2. 卷依附/分离，由使用卷的Pod所在的Node的kubelet负责完成。这些Node需要安装rbd命令，并提供有效的配置文件

解决方案：

# 安装软件
apt install -y ceph-common
# 从ceph-mon拷贝以下文件：
# /etc/ceph/ceph.client.admin.keyring
# /etc/ceph/ceph.conf

应用上述方案后，如果继续报错：rbd: map failed exit status 110, rbd output: rbd: sysfs write failed In some cases useful info is found in syslog。则查看一下系统日志：

dmesg | tail

# [ 3004.833252] libceph: mon0 10.0.0.100:6789 feature set mismatch, my 106b84a842a42 
#     < server's 40106b84a842a42, missing 400000000000000
# [ 3004.840980] libceph: mon0 10.0.0.100:6789 missing required protocol features

对照本文前面的特性表，可以发现内核版本必须4.5+才可以（CEPH_FEATURE_NEW_OSDOPREPLY_ENCODING）。 

最简单的办法就是升级一下内核：

# Desktop
apt install --install-recommends linux-generic-hwe-16.04 xserver-xorg-hwe-16.04 -y
# Server
apt install --install-recommends linux-generic-hwe-16.04 -y

sudo apt-get remove linux-headers-4.4.* -y && \
sudo apt-get remove linux-image-4.4.* -y && \
sudo apt-get autoremove -y && \
sudo update-grub

或者，将tunables profile调整到hammer版本的Ceph：

ceph osd crush tunables hammer
# adjusted tunables profile to hammer

报错信息：ERROR: osd init failed: (36) File name too long

报错原因：使用的文件系统为EXT4，存储的xattrs大小有限制，有条件的话最好使用XFS

解决办法：修改配置文件，如下：

osd_max_object_name_len = 256
osd_max_object_namespace_len = 64

报错信息：Fail to open '/proc/0/cmdline' error No such file or directory

报错原因：在CentOS 7上，将ceph-mon和ceph-osd（基于目录）部署在同一节点（基于Helm）报此错误，分离后问题消失。此外部署mon的那些节点还设置了虚IP，其子网和Ceph的Cluster/Public网络相同，这导致了某些OSD监听的地址不正确。

再次遇到此问题，原因是一个虚拟网卡lo:ngress使用和eth0相同的网段，导致OSD使用了错误的网络。

解决办法是写死OSD监听地址：

[osd.2]                                                                                                                                                                                    
public addr = 10.0.4.1                                                                                                                                                                     
cluster addr = 10.0.4.1

报错信息：Input/output error，结合dmesg | tail可以看到更细节的报错

报错原因，可能情况：

1. CentOS7下报错，提示客户端不满足特性CEPH_FEATURE_CRUSH_V4（1000000000000）。解决办法，将Bucket算法改为straw。注意，之后加入的OSD仍然默认使用straw2，使用的镜像的标签为tag-build-master-luminous-ubuntu-16.04。

external storage中的CephFS可以正常Provisioning，但是尝试读写数据时报此错误。原因是文件路径过长，和底层文件系统有关，为了兼容部分Ext文件系统的机器，我们限制了osd_max_object_name_len。

解决办法，不使用UUID，而使用namespace + pvcname来命名目录。修改cephfs-provisioner.go，118行：

// create random share name
share := fmt.Sprintf("%s-%s", options.PVC.Namespace,options.PVC.Name)
// create random user id
user := fmt.Sprintf("%s-%s", options.PVC.Namespace,options.PVC.Name)

重新编译即可。 

describe pod发现：

rbd image rbd-unsafe/kubernetes-dynamic-pvc-c0ac2cff-84ef-11e8-9a2a-566b651a72d6 is still being used

说明有其它客户端正在占用此镜像。如果尝试删除镜像，你会发现无法成功：

rbd rm rbd-unsafe/kubernetes-dynamic-pvc-c0ac2cff-84ef-11e8-9a2a-566b651a72d6 

librbd::image::RemoveRequest: 0x560e39df9af0 check_image_watchers: image has watchers - not removing
Removing image: 0% complete...failed.
rbd: error: image still has watchers
This means the image is still open or the client using it crashed. Try again after closing/unmapping it or waiting 30s for the crashed client to timeout. 

要知道watcher是谁，可以执行：

rbd status rbd-unsafe/kubernetes-dynamic-pvc-c0ac2cff-84ef-11e8-9a2a-566b651a72d6 
Watchers:
        watcher=10.5.39.12:0/1652752791 client.94563 cookie=18446462598732840961

可以发现10.5.39.12正在占用镜像。

另一种获取watcher的方法是，使用rbd的header对象。执行下面的命令获取rbd的诊断信息：

rbd info rbd-unsafe/kubernetes-dynamic-pvc-c0ac2cff-84ef-11e8-9a2a-566b651a72d6 

rbd image 'kubernetes-dynamic-pvc-c0ac2cff-84ef-11e8-9a2a-566b651a72d6':
        size 8192 MB in 2048 objects
        order 22 (4096 kB objects)
        block_name_prefix: rbd_data.134474b0dc51
        format: 2
        features: layering
        flags: 
        create_timestamp: Wed Jul 11 17:49:51 2018

字段block_name_prefix的值rbd_data.134474b0dc51，将data换为header即为header对象。然后使用命令：

rados listwatchers -p rbd-unsafe rbd_header.134474b0dc51

watcher=10.5.39.12:0/1652752791 client.94563 cookie=18446462598732840961

既然知道10.5.39.12占用镜像，断开连接即可。 在此机器上执行下面的命令，显示当前映射的rbd镜像列表：

rbd showmapped

id pool       image                                                       snap device    
0  rbd-unsafe kubernetes-dynamic-pvc-c0ac2cff-84ef-11e8-9a2a-566b651a72d6 -    /dev/rbd0 
1  rbd-unsafe kubernetes-dynamic-pvc-0729f9a6-84f0-11e8-9b75-5a3f858854b1 -    /dev/rbd1

此机器上的rbd0虽然映射，但是没有挂载。解除映射：

rbd unmap /dev/rbd0

再次检查rbd镜像状态，发现没有watcher了：

rbd status rbd-unsafe/kubernetes-dynamic-pvc-c0ac2cff-84ef-11e8-9a2a-566b651a72d6 

Watchers: none

kubectl describe报错Unable to mount volumes for pod... timeout expired waiting for volumes to attach or mount for pod...

检查发现目标rbd没有Watcher，Pod所在机器的Kubectl报错rbd: map failed signal: aborted (core dumped)。此前曾经在该机器上执行过rbd unmap操作。

手工 rbd map后问题消失。

报错信息：journal do_read_entry(156389376): bad header magic......FAILED assert(interval.last > last)

这是12.2版本已知的BUG，断电后可能出现OSD无法启动，可能导致数据丢失。

RGW实例无法启动，通过journalctl看到上述信息。

要查看更多信息，需要查看RGW日志：

2020-10-22 16:51:55.771035 7fb1b0f20e80  0 ceph version 12.2.5 (cad919881333ac92274171586c827e01f554a70a) luminous (stable), process (unknown), pid 2546439
2020-10-22 16:51:55.792872 7fb1b0f20e80  0 librados: client.rgw.ceph02 authentication error (22) Invalid argument
2020-10-22 16:51:55.793450 7fb1b0f20e80 -1 Couldn't init storage provider (RADOS)

可以发现是和身份验证有关的问题。

通过

systemctl status ceph-radosgw@rgw.$RGW_HOST

radosgw -f --cluster ceph  --name client.rgw.ceph02 --setuser ceph --setgroup ceph -d --debug_ms 1

发现报错和上面一样。尝试增加--keyring参数，问题解决：

radosgw -f --cluster ceph  --name client.rgw.ceph02        \
  --setuser ceph --setgroup ceph -d --debug_ms 1           \
  --keyring=/var/lib/ceph/radosgw/ceph-rgw.ceph02/keyring

看来是Systemd服务没有找到keyring导致。 

报错信息：Unhandled exception from module 'prometheus' while running on mgr.master01-10-5-38-24: error('No socket could
be created',)  

解决办法：

ceph config-key set mgr/prometheus/server_addr 0.0.0.0

原因是时钟不同步警告阈值太低，在global段增加配置并重启MON：

mon clock drift allowed = 2
mon clock drift warn backoff = 30

或者执行下面的命令即时生效：

ceph tell mon.* injectargs '--mon_clock_drift_allowed=2'
ceph tell mon.* injectargs '--mon_clock_drift_warn_backoff=30'

或者检查ntp相关配置，保证时钟同步精度。

深度清理很消耗IO，如果长时间无法完成，可以禁用：

ceph osd set noscrub
ceph osd set nodeep-scrub

问题解决后，可以再启用： 

ceph osd unset noscrub
ceph osd unset nodeep-scrub 

使用CFQ作为IO调度器时，可以调整OSD IO线程的优先级：

# 设置调度器
echo cfq > /sys/block/sda/queue/scheduler

# 检查当前某个OSD的磁盘线程优先级类型
ceph daemon osd.4 config get osd_disk_thread_ioprio_class

# 修改IO优先级
ceph tell osd.* injectargs '--osd_disk_thread_ioprio_priority 7'
# IOPRIO_CLASS_RT最高 IOPRIO_CLASS_IDLE最低
ceph tell osd.* injectargs '--osd_disk_thread_ioprio_class idle'

如果上述措施没有问题时，可以考虑配置以下参数：

osd_deep_scrub_stride = 131072                                                                                                                                                           
# 每次Scrub的块数量范围
osd_scrub_chunk_min = 1                                                                                                                                                                  
osd_scrub_chunk_max = 5                                                                                                                                                                  
osd scrub during recovery = false                                                                                                                                                        
osd deep scrub interval = 2592000                                                                                                                                                        
osd scrub max interval = 2592000                                                                                                                                                         
# 单个OSD并发进行的Scrub个数
osd max scrubs = 1       
# Scrub起止时间                                                                                                                                                                
osd max begin hour = 2                                                                                                                                                                   
osd max end hour = 6                                                                                                                                                                     
# 系统负载超过多少则禁止Scrub
osd scrub load threshold = 4                                                                                                                                                             
# 每次Scrub后强制休眠0.1秒
osd scrub sleep = 0.1                                                                                                                                                                      
# 线程优先级
osd disk thread ioprio priority = 7
osd disk thread ioprio class = idle

如果Watcher被黑名单，则尝试Unmap镜像时会报错：rbd: sysfs write failed rbd: unmap failed: (16) Device or resource busy

可以使用下面的命令强制unmap：

rbd unmap -o force ...

部分PG状态卡死，可能原因是OSD允许的PG数量受限，修改全局配置项mon_max_pg_per_osd并重启MON即可。

此外注意：调整PG数量后，一定要进入A+C状态后，再进行下一次调整。

下面第二个镜像对应的K8S PV已经删除：

rbd ls
# kubernetes-dynamic-pvc-35350b13-46b8-11e8-bde0-a2c14c93573f
# kubernetes-dynamic-pvc-78740b26-46eb-11e8-8349-e6e3339859d4

但是对应的RBD没有删除，手工删除：

rbd remove kubernetes-dynamic-pvc-78740b26-46eb-11e8-8349-e6e3339859d4

报错：

2018-04-23 13:37:25.559444 7f919affd700 -1 librbd::image::RemoveRequest: 0x5598e77831d0 check_image_watchers: image has watchers - not removing
Removing image: 0% complete...failed.
rbd: error: image still has watchers
This means the image is still open or the client using it crashed. Try again after closing/unmapping it or waiting 30s for the crashed client to timeout.

查看RBD状态：

# rbd info kubernetes-dynamic-pvc-78740b26-46eb-11e8-8349-e6e3339859d4
rbd image 'kubernetes-dynamic-pvc-78740b26-46eb-11e8-8349-e6e3339859d4':
        size 8192 MB in 2048 objects
        order 22 (4096 kB objects)
        block_name_prefix: rbd_data.1003e238e1f29
        format: 2
        features: layering
        flags: 
        create_timestamp: Mon Apr 23 11:42:59 2018

#rbd status kubernetes-dynamic-pvc-78740b26-46eb-11e8-8349-e6e3339859d4
Watchers:
        watcher=10.0.0.101:0/4275384344 client.65597 cookie=18446462598732840963

到10.0.0.101这台机器上查看：

# df | grep e6e3339859d4
/dev/rbd2        8125880  251560   7438508   4% /var/lib/kubelet/plugins/kubernetes.io/rbd/rbd/rbd-image-kubernetes-dynamic-pvc-78740b26-46eb-11e8-8349-e6e3339859d4

重启Kubelet后可以删除RBD。

# 删除密钥
ceph auth del osd.9
# 重新收集目标主机的密钥
ceph-deploy --username ceph-ops gatherkeys Carbon

pgs:     12.413% pgs unknown                                                                                                                                                         
             20.920% pgs not active                                                                                                                                                      
             768 active+clean                                                                                                                                                            
             241 creating+activating                                                                                                                                                     
             143 unknown

可能是由于PG总数太大导致，降低PG数量后很快Active+Clean 

报错信息：Orphaned pod "a9621c0e-41ee-11e8-9407-deadbeef00a0" found, but volume paths are still present on disk : There were a total of 1 errors similar to this. Turn up verbosity to see them

临时解决办法：

rm -rf /var/lib/kubelet/pods/a9621c0e-41ee-11e8-9407-deadbeef00a0/volumes/rook.io~rook/

可能原因是OSD使用的keyring和MON不一致。对于ID为14的OSD，将宿主机/var/lib/ceph/osd/ceph-14/keyring的内容替换为

ceph auth get osd.14

在没有停止OSD的情况下执行ceph-objectstore-tool命令，会出现此错误。

通过ceph-deploy添加MON节点时出现此错误，将public_network配置添加到配置文件的global段即可。

可能原因：

1. 对应的PVC没有删除，还在引用此PV。先删除PV即可

OSD无法启动，报上面的错误，可以配置：

ceph:
  storage:
    osd_log: /var/log 

#池 # 功能
ceph osd pool application enable rbd block-devices

The post Ceph学习笔记 appeared first on 绿色记忆.

OpenStack是一个开源的IaaS解决方案，使用它，你可以通过仪表盘或者利用OpenStack API控制/Provision大规模的计算、存储、网络资源池。

通过“驱动”，OpenStack支持大量商业、开源的计算、存储、网络相关技术框架，从而能够管理各种各样的基础设施。不管是裸金属机器、虚拟机、还是容器，都可以基于OpenStack进行管理，并共享网络、存储等底层资源：

Kubernetes、CloudFoundry等PaaS平台可以构建在OpenStack之上。

OpenStack由若干子项目组成，它们围绕着计算、存储、网络这三个核心概念组织：

1. 计算：提供并管理网络中大量的虚拟机，主要由Nova子项目负责
2. 存储：供服务器、应用程序使用的对象存储、块存储，分别由Swift、Cinder子项目负责
3. 网络：可拔插、可扩容、API驱动的网络和IP管理

这三类子项目还具有一些共享的服务：identity、镜像管理（image management）、一个基于Web的UI接口。

OpenStack项目的总览图如下，其中粗体标出了它的核心子项目，包括Horizon、Heat、Nova、Neutron、Swift、Cinder等：

以Bigdata as Service场景为例，各子项目的交互关系如下图：

简单的说明一下：

1. Keystone提供身份验证服务
2. Ceilometer提供监控服务
3. Horizon提供一个管理UI
4. Nova负责分配虚拟机
5. Glance提供镜像服务，镜像文件存放在Swift中
6. Cinder为虚拟机提供块存储卷
7. Cinder将卷备份到Swift中
8. Neuron为虚拟机提供网络连接

每个子项目，或者叫OpenStack服务，都通过公共的Identity Service进行身份验证，服务之间通过公共API进行交互。每个服务至少包含一个API进程，此进程监听API请求，进行预处理然后转交给服务的其它部分进行处理。

每个服务可以有多个进程，这些进程之间的通信方式通常是AMQP。服务的状态持久化在数据库中。多种消息代理、RDBMS被支持，例如RabbitMQ、MySQL、MariaDB。

用户访问OpenStack的方式有几种：

1. 通过Horizon提供的Web仪表盘
2. 提供CLI客户端
3. 提供SDK进行编程

不管是何种方式，在底层都会向不同的OpenStack服务发送REST请求。

Nova是OpenStack云中的计算组织控制器。支持OpenStack云中实例（instances）生命周期的所有活动都由Nova处理。这样使得Nova成为一个负责管理计算资源、网络、认证、所需可扩展性的平台。

Neutron是openstack核心项目之一，提供云计算环境下的虚拟网络功能。OpenStack网络（neutron）管理OpenStack环境中所有虚拟网络基础设施（VNI），物理网络基础设施（PNI）的接入层。

Cinder接口提供了一些标准功能，允许创建和附加块设备到虚拟机，如“创建卷”，“删除卷”和“附加卷”。还有更多高级的功能，支持扩展容量的能力，快照和创建虚拟机镜像克隆。

Octavia 是 openstack lbaas的支持的一种后台程序，提供为虚拟机流量的负载均衡。实质是类似于trove，调用 nova 以及neutron的api生成一台安装好haproxy和keepalived软件的虚拟机，并连接到目标网路。

Swift 不是文件系统或者实时的数据存储系统，而是对象存储，用于长期存储永久类型的静态数据。这些数据可以检索、调整和必要时进行更新。Swift最适合虚拟机镜像、图片、邮件和存档备份这类数据的存储。

Glance（OpenStack Image Service）是一个提供发现，注册，和下载镜像的服务。Glance提供了虚拟机镜像的集中存储。通过 Glance 的 RESTful API，可以查询镜像元数据、下载镜像。虚拟机的镜像可以很方便的存储在各种地方，从简单的文件系统到对象存储系统（比如 OpenStack Swift）。

Horizon 为 Openstack 提供一个 WEB 前端的管理界面 (UI 服务 )通过 Horizon 所提供的 DashBoard 服务 , 管理员可以使用通过 WEB UI 对 Openstack 整体云环境进行管理 , 并可直观看到各种操作结果与运行状态。

Ironic包含一个API和多个插件，用于安全性和容错性地提供物理服务器。它可以和nova结合被使用为hypervisor驱动，或者用bifrost使用为独立服务。默认情况下，它会使用PXE和IPMI去与裸金属机器去交互。Ironic也支持使用供应商的插件而实现额外的功能。

Cyborg（以前称为Nomad）旨在为加速资源（即FPGA,GPU,SoC, NVMe SSD,DPDK/SPDK,eBPF/XDP …）提供通用管理框架。

kolla 的使命是为 openstack 云平台提供生产级别的、开箱即用的交付能力。kolla 的基本思想是一切皆容器，将所有服务基于 Docker 运行，并且保证一个容器只跑一个服务（进程），做到最小粒度的运行 docker。

Kubernetes Kuryr是 OpenStack Neutron 的子项目，其主要目标是通过该项目来整合 OpenStack 与Kubernetes 的网络。该项目在 Kubernetes 中实现了原生 Neutron-based 的网络，因此使用 Kuryr-Kubernetes 可以让你的 OpenStack VM 与 Kubernetes Pods 能够选择在同一个子网上运作，并且能够使用 Neutron 的 L3 与 Security Group 来对网络进行路由，以及阻挡特定来源 Port。

Manila项目全称是File Share Service，文件共享即服务，用来提供云上的文件共享，支持CIFS协议和NFS协议。

Tacker是一个在OpenStack内部孵化的项目, 他的作用是NVF管理器，用于管理NVF的生命周期。Tacker的重点是配置VNF, 并监视他们。如果需要，还可重启和/或扩展（自动修复）NVF。整个进程贯穿ETSIMANO所描述的整个生命周期。

显示详细配置信息：

# --unmask表示明文显示密码
openstack configuration show [--mask | --unmask]

一个Domain，是用户、组、项目的集合。任何组、项目仅仅属于单个Domain。

openstack domain create
    [--description <description>]
    [--enable | --disable]
    [--or-show]
    # 禁止删除或修改，除非去掉此标记
    [--immutable | --no-immutable]
    <domain-name>

openstack domain delete <domain> [<domain> ...]

openstack domain list
    [--sort-column SORT_COLUMN]
    [--name <name>]
    [--enabled]

openstack domain set
    [--name <name>]
    [--description <description>]
    [--enable | --disable]
    [--immutable | --no-immutable]
    <domain>

openstack domain show <domain>

管理项目

openstack project create
    [--domain <domain>]
    [--parent <project>]
    [--description <description>]
    [--enable | --disable]
    [--property <key=value>]
    [--or-show]
    [--immutable | --no-immutable]
    [--tag <tag>]
    <project-name>

openstack project delete [--domain <domain>] <project> [<project> ...]

openstack project list
    [--sort-column SORT_COLUMN]
    [--domain <domain>]
    [--parent <parent>]
    [--user <user>]
    [--my-projects]
    [--long]
    [--sort <key>[:<direction>]]
    [--tags <tag>[,<tag>,...]]
    [--tags-any <tag>[,<tag>,...]]
    [--not-tags <tag>[,<tag>,...]]
    [--not-tags-any <tag>[,<tag>,...]]

openstack project set
    [--name <name>]
    [--domain <domain>]
    [--description <description>]
    [--enable | --disable]
    [--property <key=value>]
    [--immutable | --no-immutable]
    [--tag <tag>]
    [--clear-tags]
    [--remove-tag <tag>]
    <project>

openstack project show
    [--domain <domain>]
    [--parents]
    [--children]
    <project> 

清除和指定项目关联的资源

openstack project purge
    [--dry-run]
    [--keep-project]
    (--auth-project | --project <project>)
    [--project-domain <project-domain>]

用户的组。

# 添加用户到组
openstack group add user
    [--group-domain <group-domain>]
    [--user-domain <user-domain>]
    <group>
    <user>
    [<user> ...]
openstack group remove user
    [--group-domain <group-domain>]
    [--user-domain <user-domain>]
    <group>
    <user>
    [<user> ...]

# 检查组是否包含用户
openstack group contains user
    [--group-domain <group-domain>]
    [--user-domain <user-domain>]
    <group>
    <user>

# 创建组
openstack group create
    [--domain <domain>]
    [--description <description>]
    [--or-show]
    <group-name>


openstack group delete [--domain <domain>] <group> [<group> ...]

openstack group list
    [--sort-column SORT_COLUMN]
    [--domain <domain>]
    [--user <user>]
    [--user-domain <user-domain>]
    [--long]
openstack group show [--domain <domain>] <group>

openstack group set
    [--domain <domain>]
    [--name <name>]
    [--description <description>]
    <group> 

用户管理

openstack user create
    # 用户的默认domain
    [--domain <domain>]
    # 用户的默认project
    [--project <project>]
    [--project-domain <project-domain>]
    # 指定密码
    [--password <password>]
    # 交互的输入密码
    [--password-prompt]
    [--email <email-address>]
    [--description <description>]
    # 禁止连续身份验证失败后，锁定用户
    [--ignore-lockout-failure-attempts]
    [--no-ignore-lockout-failure-attempts]
    # 禁止密码过期
    [--ignore-password-expiry]
    [--no-ignore-password-expiry]
    # 禁止首次使用必须修改密码
    [--ignore-change-password-upon-first-use]
    [--no-ignore-change-password-upon-first-use]
    # 锁定密码，不给修改
    [--enable-lock-password]
    [--disable-lock-password]
    # 启用多因子身份验证
    [--enable-multi-factor-auth]
    [--disable-multi-factor-auth]
    [--multi-factor-auth-rule <rule>]
    # 启用/禁用
    [--enable | --disable]
    # 显示已有的用户
    [--or-show]
    <name>
openstack user delete [--domain <domain>] <user> [<user> ...]

openstack user list
    [--sort-column SORT_COLUMN]
    [--domain <domain>]
    [--group <group> | --project <project>]
    [--long]
openstack user show [--domain <domain>] <user>

# 修改密码
openstack user password set
    [--password <new-password>]
    [--original-password <original-password>]


openstack user set
    [--name <name>]
    [--domain <domain>]
    [--project <project>]
    [--project-domain <project-domain>]
    [--password <password>]
    [--password-prompt]
    [--email <email-address>]
    [--description <description>]
    [--ignore-lockout-failure-attempts]
    [--no-ignore-lockout-failure-attempts]
    [--ignore-password-expiry]
    [--no-ignore-password-expiry]
    [--ignore-change-password-upon-first-use]
    [--no-ignore-change-password-upon-first-use]
    [--enable-lock-password]
    [--disable-lock-password]
    [--enable-multi-factor-auth]
    [--disable-multi-factor-auth]
    [--multi-factor-auth-rule <rule>]
    [--enable | --disable]
    <user> 

可以创建角色，将角色映射给用户或组。

# 将角色赋予组或用户
openstack role add
    [--system <system> | --domain <domain> | --project <project>]
    [--user <user> | --group <group>]
    [--group-domain <group-domain>]
    [--project-domain <project-domain>]
    [--user-domain <user-domain>]
    [--inherited]
    [--role-domain <role-domain>]
    <role>
openstack role remove
    [--system <system> | --domain <domain> | --project <project>]
    [--user <user> | --group <group>]
    [--group-domain <group-domain>]
    [--project-domain <project-domain>]
    [--user-domain <user-domain>]
    [--inherited]
    [--role-domain <role-domain>]
    <role>

# 创建角色
openstack role create
    [--description <description>]
    [--domain <domain>]
    [--or-show]
    [--immutable | --no-immutable]
    <role-name>

openstack role delete [--domain <domain>] <role> [<role> ...]

openstack role list [--sort-column SORT_COLUMN] [--domain <domain>]

openstack role set
    [--description <description>]
    [--domain <domain>]
    [--name <name>]
    [--immutable | --no-immutable]
    <role>

openstack role show [--domain <domain>] <role> 

角色和用户的映射关系。

openstack role assignment list
    [--role <role>]
    [--role-domain <role-domain>]
    [--user <user>]
    [--user-domain <user-domain>]
    [--group <group>]
    [--group-domain <group-domain>]
    [--domain <domain>]
    [--project <project>]
    [--project-domain <project-domain>]
    [--effective]
    [--inherited]
    [--names] 

指定角色之间的包含关系。

#                             被隐含的角色           目标角色
openstack implied role create --implied-role <role> <role>

openstack implied role delete --implied-role <role> <role>

openstack implied role list [--sort-column SORT_COLUMN] 

提供特定项目中，用户之间的角色代理，支持可选的替身机制（impersonation）。需要 OS-TRUST扩展。

在Identity服务的OS-OAUTH1扩展中使用，用于创建request token 、access token，仅仅支持Identity v3。

openstack consumer create [--description <description>]
openstack consumer delete <consumer> [<consumer> ...]
openstack consumer list [--sort-column SORT_COLUMN]
openstack consumer set [--description <description>] <consumer>
openstack consumer show <consumer>

管理凭证：

openstack credential create
    [--type <type>]
    [--project <project>]
    <user>
    <data>

openstack credential delete <credential-id> [<credential-id> ...]

openstack credential list
    [--sort-column SORT_COLUMN]
    [--user <user>]
    [--user-domain <user-domain>]
    [--type <type>]

openstack credential set
    --user <user>
    --type <type>
    --data <data>
    [--project <project>]
    <credential-id>

openstack credential show <credential-id> 

使用应用凭证，用户可以给自己的应用程序授予对云资源的有限访问权限。

# 创建新的凭证
openstack application credential create
    [--secret <secret>]
    [--role <role>]
    [--expiration <expiration>]
    [--description <description>]
    [--unrestricted]
    [--restricted]
    [--access-rules <access-rules>]
    <name>

openstack application credential delete
    <application-credential>
    [<application-credential> ...]

openstack application credential list
    [--sort-column SORT_COLUMN]
    [--user <user>]
    [--user-domain <user-domain>]

openstack application credential show <application-credential>

对应用程序凭证的权限进行细粒度控制。每个访问规则包含一下要素：

服务类型 + 请求路径 + 请求方法

openstack access rule delete <access-rule> [<access-rule> ...]

openstack access rule list
    [--user <user>]
    [--user-domain <user-domain>]

openstack access rule show <access-rule>

创建或吊销一个令牌

openstack token issue

openstack token revoke <token> 

Identity服务的OS-OAUTH1扩展使用访问令牌。consumer可以代表被授权用户来获得新的Identity API token。

openstack access token create
    # consumer的键/密钥
    --consumer-key <consumer-key>
    --consumer-secret <consumer-secret>
    --request-key <request-key>
    --request-secret <request-secret>
    --verifier <verifier>

Identity服务的OS-OAUTH1扩展使用请求令牌。consumer使用此令牌来请求access token

# 验证请求令牌
openstack request token authorize
    --request-key <request-key>
    --role <role>

# 创建请求令牌
openstack request token create
    --consumer-key <consumer-key>
    --consumer-secret <consumer-secret>
    --project <project>
    [--domain <domain>]

策略是一组规则，可以被远程服务消费。

openstack policy create [--type <type>] <filename>

openstack policy delete <policy> [<policy> ...]

openstack policy list [--sort-column SORT_COLUMN] [--long]

openstack policy set [--type <type>] [--rules <filename>] <policy>

openstack policy show <policy> 

基于RBAC的、针对网络资源的授权控制策略。让用户获得某个项目的网络资源的访问权限

openstack network rbac create
    --type <type>
    --action <action>
    (--target-project <target-project> | --target-all-projects)
    [--target-project-domain <target-project-domain>]
    [--project <project>]
    [--project-domain <project-domain>]
    <rbac-object>

openstack network rbac delete <rbac-policy> [<rbac-policy> ...]

openstack network rbac list
    [--sort-column SORT_COLUMN]
    [--type <type>]
    [--action <action>]
    [--long]

openstack network rbac set
    [--target-project <target-project>]
    [--target-project-domain <target-project-domain>]
    <rbac-policy>

openstack network rbac show <rbac-policy> 

很多API都支持资源配额

openstack quota set
    # 为指定的class设置配额
    [--class]
    # 核心数配额
    [--cores <cores>]
    # 固定IP数量配额
    [--fixed-ips <fixed-ips>]
    [--injected-file-size <injected-file-size>]
    [--injected-path-size <injected-path-size>]
    [--injected-files <injected-files>]
    [--instances <instances>]
    [--key-pairs <key-pairs>]
    [--properties <properties>]
    [--ram <ram>]
    [--server-groups <server-groups>]
    [--server-group-members <server-group-members>]
    [--backups <backups>]
    [--backup-gigabytes <backup-gigabytes>]
    [--gigabytes <gigabytes>]
    [--per-volume-gigabytes <per-volume-gigabytes>]
    [--snapshots <snapshots>]
    [--volumes <volumes>]
    [--floating-ips <floating-ips>]
    [--secgroup-rules <secgroup-rules>]
    [--secgroups <secgroups>]
    [--networks <networks>]
    [--subnets <subnets>]
    [--ports <ports>]
    [--routers <routers>]
    [--rbac-policies <rbac-policies>]
    [--subnetpools <subnetpools>]
    [--volume-type <volume-type>]
    [--force]
    # 此配额针对的项目或者class
    <project/class>

openstack quota list
    [--sort-column SORT_COLUMN]
    [--project <project>]
    [--detail]
    (--compute | --volume | --network)

openstack quota show [--class | --default] [<project/class>]

# 显示针对所有项目的默认配额
openstack quota show --default

# 增大默认安装下admin项目的资源配额
openstack quota set --cores 32 admin
openstack quota set --ram 131072 admin
openstack quota set --gigabytes 8192 admin
openstack quota set --volumes 32 admin
openstack quota set --snapshots 32 admin
openstack quota set --instances 16 admin

用于在项目级别进行资源配额。

# 创建一个配额
openstack limit create
    [--description <description>]
    # 此配额影响的区域
    [--region <region>]
    # 此配额针对的项目
    --project <project>
    # 负责资源的服务
    --service <service>
    # 资源额度
    --resource-limit <resource-limit>
    <resource-name>

openstack limit delete <limit-id> [<limit-id> ...]

openstack limit list
    [--sort-column SORT_COLUMN]
    [--service <service>]
    [--resource-name <resource-name>]
    [--region <region>]
    [--project <project>]

openstack limit set
    [--description <description>]
    [--resource-limit <resource-limit>]
    <limit-id>

openstack limit show <limit-id>

用于定义OpenStack部署中的默认资源限制

openstack registered limit create
    [--description <description>]
    [--region <region>]
    --service <service>
    --default-limit <default-limit>
    <resource-name>

openstack registered limit delete
    <registered-limit-id>
    [<registered-limit-id> ...]

openstack registered limit list
    [--sort-column SORT_COLUMN]
    [--service <service>]
    [--resource-name <resource-name>]
    [--region <region>]

openstack registered limit set
    [--service <service>]
    [--resource-name <resource-name>]
    [--default-limit <default-limit>]
    [--description <description>]
    [--region <region>]
    <registered-limit-id>

openstack registered limit show <registered-limit-id> 

显示计算、存储资源用量的限制

openstack limits show
    [--sort-column SORT_COLUMN]
    (--absolute | --rate)
    [--reserved]
    [--project <project>]
    [--domain <domain>]

显示项目的资源用量

openstack usage list
    [--sort-column SORT_COLUMN]
    # 用量统计的起始时间，默认4周前
    [--start <start>]
    # 用量统计的结束日期，默认明天
    [--end <end>]

openstack usage show
    [--project <project>]
    [--start <start>]
    [--end <end>] 

区域是OpenStack部署中的最大的分区。你可以配置多个sub-region，甚至形成树形结构。

openstack region create
    [--parent-region <region-id>]
    [--description <description>]
    <region-id>

openstack region delete <region-id> [<region-id> ...]

openstack region list
    [--sort-column SORT_COLUMN]
    [--parent-region <region-id>]

openstack region set
    [--parent-region <region-id>]
    [--description <description>]
    <region-id>

openstack region show <region-id> 

可用区是云存储、计算、网络服务的逻辑分区。对等的AZ具有构成HA的效果，这和Region不同。

# 列出可用区
openstack availability zone list
    [--sort-column SORT_COLUMN]
    [--compute]
    [--network]
    [--volume]
    [--long] 

聚合是一组分组host的机制：

# 添加/删除主机到聚合中
openstack aggregate add host <aggregate> <host>
openstack aggregate remove host <aggregate> <host>

# 为聚合请求缓存镜像
openstack aggregate cache image <aggregate> <image> [<image> ...]

# 创建一个聚合，可以看到聚合是在某个AZ内部的
openstack aggregate create
    [--zone <availability-zone>]
    [--property <key=value>]
    <name>

openstack aggregate delete <aggregate> [<aggregate> ...]

# 为聚合设置元数据（键值对），然后为Flavor设置scope为aggregate_instance_extra_specs的
# 额外规格，规格键值和元数据一致，可以将Flavor映射到聚合。从Flavor创建的实例将位于聚合的主机中
openstack aggregate set
    [--name <name>]
    [--zone <availability-zone>]
    [--property <key=value>]
    [--no-property]
    <aggregate>
openstack aggregate unset [--property <key>] <aggregate>

openstack aggregate show <aggregate>
openstack aggregate list [--sort-column SORT_COLUMN] [--long]

运行Hypervisor的物理机器。

openstack host list [--sort-column SORT_COLUMN] [--zone <zone>]

openstack host set
    [--enable | --disable]
    [--enable-maintenance | --disable-maintenance]
    <host>

openstack host show [--sort-column SORT_COLUMN] <host>

openstack hypervisor list
    [--sort-column SORT_COLUMN]
    [--matching <hostname>]
    [--long]

openstack hypervisor show <hypervisor>

openstack hypervisor stats show 

OpenSSH公钥管理，用于访问创建的server（虚拟机）。

# 创建公钥
# 如果什么参数都不指定，则生成新的公钥
openstack keypair create
    [--public-key <file> | --private-key <file>]
    [--type <type>]
    [--user <user>]
    [--user-domain <user-domain>]
    <name>

openstack keypair delete
    [--user <user>]
    [--user-domain <user-domain>]
    <key>
    [<key> ...]

openstack keypair list
    [--sort-column SORT_COLUMN]
    [--user <user>]
    [--user-domain <user-domain>]
    [--project <project>]
    [--project-domain <project-domain>]

openstack keypair show
    [--public-key]
    [--user <user>]
    [--user-domain <user-domain>]
    <key>

显示所有服务的版本、端点、是否弃用之类的信息

openstack versions show 

显示服务的类型、名称、端点列表：

openstack catalog list [--sort-column SORT_COLUMN]
openstack catalog show <service>

openstack catalog list
# +-----------+-----------+-----------------------------------------+
# | Name      | Type      | Endpoints                               |
# +-----------+-----------+-----------------------------------------+
# | glance    | image     | zircon                                  |
# |           |           |   public: http://os.gmem.cc:9292        |
# |           |           |                                         |
# | keystone  | identity  | zircon                                  |
# |           |           |   internal: http://os.gmem.cc:5000/v3/  |
# |           |           | zircon                                  |
# |           |           |   public: http://os.gmem.cc:5000/v3/    |
# |           |           | zircon                                  |
# |           |           |   admin: http://os.gmem.cc:5000/v3/     |
# |           |           |                                         |
# | nova      | compute   | zircon                                  |
# |           |           |   internal: http://os.gmem.cc:8774/v2.1 |
# |           |           | zircon                                  |
# |           |           |   public: http://os.gmem.cc:8774/v2.1   |
# |           |           | zircon                                  |
# |           |           |   admin: http://os.gmem.cc:8774/v2.1    |
# |           |           |                                         |
# | placement | placement | zircon                                  |
# |           |           |   public: http://os.gmem.cc:8778        |
# |           |           | zircon                                  |
# |           |           |   admin: http://os.gmem.cc:8778         |
# |           |           | zircon                                  |
# |           |           |   internal: http://os.gmem.cc:8778      |
# |           |           |                                         |
# +-----------+-----------+-----------------------------------------+

很多OpenStack API包含API扩展，这些扩展提供额外的功能。

# 列出API扩展
openstack extension list
    [--sort-column SORT_COLUMN]
    [--compute]
    [--identity]
    [--network]
    [--volume]
    [--long]

# 显示API扩展
openstack extension show <extension>

管理服务的API端点

# 关联项目到端点
openstack endpoint add project
    [--project-domain <project-domain>]
    <endpoint>
    <project>
openstack endpoint remove project
    [--project-domain <project-domain>]
    <endpoint>
    <project>

# 创建新的端点
openstack endpoint create
    # 所属的区域
    [--region <region-id>]
    [--enable | --disable]
    # 端点所属的服务
    <service>
    # admin, public 还是 internal
    <interface>
    <url>

openstack endpoint delete <endpoint-id> [<endpoint-id> ...]

openstack endpoint list
    [--sort-column SORT_COLUMN]
    [--service <service>]
    [--interface <interface>]
    [--region <region-id>]
    [--endpoint <endpoint-group> | --project <project>]
    [--project-domain <project-domain>]

openstack endpoint set
    [--region <region-id>]
    [--interface <interface>]
    [--url <url>]
    [--service <service>]
    [--enable | --disable]
    <endpoint-id>

openstack endpoint show <endpoint>

一组端点，可以一起关联到项目。

# 关联端点组到项目
openstack endpoint group add project
    [--project-domain <project-domain>]
    <endpoint-group>
    <project>
openstack endpoint group remove project
    [--project-domain <project-domain>]
    <endpoint-group>
    <project>


# 创建端点组
openstack endpoint group create
    [--description DESCRIPTION]
    <name>
    <filename>
openstack endpoint group delete <endpoint-group> [<endpoint-group> ...]
openstack endpoint group set
    [--name <name>]
    [--filters <filename>]
    [--description <description>]
    <endpoint-group>
openstack endpoint group list
    [--sort-column SORT_COLUMN]
    [--endpointgroup <endpoint-group> | --project <project>]
    [--domain <domain>]
openstack endpoint group show <endpointgroup> 

表示一种虚拟机的规格。

openstack flavor create
    [--id <id>]
    # 内存大小，MB
    [--ram <size-mb>]
    # 磁盘大小，GB
    [--disk <size-gb>]
    # 临时磁盘大小
    [--ephemeral <size-gb>]
    # 交换分区大小
    [--swap <size-mb>]
    # VCPU数量，默认1
    [--vcpus <vcpus>]
    # RX/TX 因子，默认1.0
    [--rxtx-factor <factor>]
    # 是否可以被其它项目使用
    [--public | --private]
    [--property <key=value>]
    # 所属项目
    [--project <project>]
    [--description <description>]
    [--project-domain <project-domain>]
    # 传统的名字是  XX.SIZE_NAME 格式，现在已经没有要求。不排除某些工具依赖于这种名称格式
    <flavor-name>

openstack flavor list
    [--sort-column SORT_COLUMN]
    [--public | --private | --all]
    [--long]
    [--marker <flavor-id>]
    [--limit <num-flavors>]

openstack flavor set
    [--no-property]
    [--property <key=value>]
    [--project <project>]
    [--description <description>]
    [--project-domain <project-domain>]
    <flavor>
openstack flavor unset
    [--property <key>]
    [--project <project>]
    [--project-domain <project-domain>]
    <flavor>

openstack flavor show <flavor>


# 创建一个Flavor
openstack flavor create FLAVOR_NAME --id FLAVOR_ID \
    --ram RAM_IN_MB --disk ROOT_DISK_IN_GB --vcpus NUMBER_OF_VCPUS

# 创建Flavor并分配给一个租户
openstack flavor create --public m1.extra_tiny --id auto \
    --ram 256 --disk 0 --vcpus 1
openstack flavor set --project PROJECT_ID m1.extra_tiny



# 列出所有flavor
openstack flavor create --id 0 --vcpus 1 --ram 64 --disk 1 m1.nano
openstack flavor create --id 1 --vcpus 1 --ram 512 --disk 8 m1.tiny
openstack flavor create --id 2 --vcpus 1 --ram 2048 --disk 32 m1.small
openstack flavor create --id 3 --vcpus 2 --ram 4096 --disk 64 m1.medium
openstack flavor create --id 4 --vcpus 4 --ram 8192 --disk 128 m1.large
openstack flavor create --id 5 --vcpus 8 --ram 16384 --disk 256 m1.xlarge

openstack flavor list
# +----+-----------+-------+------+-----------+-------+-----------+
# | ID | Name      |   RAM | Disk | Ephemeral | VCPUs | Is Public |
# +----+-----------+-------+------+-----------+-------+-----------+
# | 0  | m1.nano   |    64 |    1 |         0 |     1 | True      |
# | 1  | m1.tiny   |   512 |    8 |         0 |     1 | True      |
# | 2  | m1.small  |  2048 |   32 |         0 |     1 | True      |
# | 3  | m1.medium |  4096 |   64 |         0 |     2 | True      |
# | 4  | m1.large  |  8192 |  128 |         0 |     4 | True      |
# | 5  | m1.xlarge | 16384 |  256 |         0 |     8 | True      |
# +----+-----------+-------+------+-----------+-------+-----------+

管理镜像。

# 允许项目访问镜像
openstack image add project
    [--project-domain <project-domain>]
    <image>
    <project>
openstack image remove project
    [--project-domain <project-domain>]
    <image>
    <project>

# 创建镜像
openstack image create
    [--id <id>]
    # 镜像容器格式：ami, ari, aki, bare, docker, ova, ovf。默认bare
    [--container-format <container-format>]
    # 镜像磁盘格式：ami, ari, aki, vhd, vmdk, raw, qcow2, vhdx, vdi, iso, ploop。默认raw
    [--disk-format <disk-format>]
    # 启动镜像需要的最小磁盘尺寸
    [--min-disk <disk-gb>]
    # 启动镜像需要的最小内存
    [--min-ram <ram-mb>]
    # 镜像文件       从卷生成镜像
    [--file <file> | --volume <volume>]
    # 从卷生成镜像时，即便卷正在使用，也强制生成镜像
    [--force]
    # 使用本地私钥签名镜像
    [--sign-key-path <sign-key-path>]
    # 用于镜像签名校验的，位于key manager中的certificate的UUID
    [--sign-cert-id <sign-cert-id>]
    # 保护镜像防止被删除
    [--protected | --unprotected]
    # 公共      项目私有    可被社区使用    共享
    [--public | --private | --community | --shared]
    [--property <key=value>]
    [--tag <tag>]
    [--project <project>]
    [--import]
    [--project-domain <project-domain>]
    <image-name>

# 设置镜像属性
openstack image set
    [--name <name>]
    [--min-disk <disk-gb>]
    [--min-ram <ram-mb>]
    [--container-format <container-format>]
    [--disk-format <disk-format>]
    [--protected | --unprotected]
    [--public | --private | --community | --shared]
    [--property <key=value>]
    [--tag <tag>]
    [--architecture <architecture>]
    [--instance-id <instance-id>]
    [--kernel-id <kernel-id>]
    [--os-distro <os-distro>]
    [--os-version <os-version>]
    [--ramdisk-id <ramdisk-id>]
    [--deactivate | --activate]
    [--project <project>]
    [--project-domain <project-domain>]
    [--accept | --reject | --pending]
    <image>
openstack image unset [--tag <tag>] [--property <property-key>] <image>

# 删除镜像
openstack image delete <image> [<image> ...]

# 将镜像保存到本地
openstack image save [--file <filename>] <image>

# 列出镜像
openstack image member list
    [--sort-column SORT_COLUMN]
    [--project-domain <project-domain>]
    <image>

# 显示镜像信息
openstack image show [--human-readable] <image>


# 示例
# 上传镜像
openstack image create --public --disk-format qcow2 --container-format bare \
  --file cirros-0.5.1-x86_64-disk.img cirros-0.5.1-amd64
# 将卷上传为镜像，上传的QCOW2镜像，会自动shrink
# 注意，默认情况下只有Available状态的卷能够上传为镜像，In-use的用--force也不行
# Force upload to image is disabled, Force option will be ignored.
openstack image create --volume 840e9e25-192c-401b-83f5-898fd82839c4 --force centos8-amd64-prepared

计算代理是和Hypervisor相关的，且仅仅被 XenAPI hypervisor driver支持。

Nova相关的服务。

openstack compute service delete <service> [<service> ...]

openstack compute service list
    [--sort-column SORT_COLUMN]
    [--host <host>]
    [--service <service>]
    [--long]

openstack compute service set
    [--enable | --disable]
    [--disable-reason <reason>]
    [--up | --down]
    <host>
    <service>

显示虚拟机的控制台日志：

openstack console log show [--lines <num-lines>] <server>

打印各种类型的控制台URL：

openstack console url show
    [--novnc | --xvpvnc | --spice | --rdp | --serial | --mks]
    <server> 

基于某种策略对服务器进行分组。

openstack server group create [--policy <policy>] <name>

openstack server group delete <server-group> [<server-group> ...]

openstack server group list
    [--sort-column SORT_COLUMN]
    [--all-projects]
    [--long]

openstack server group show <server-group>

创建一个实例（虚拟机，也叫服务器server） 

openstack server create
    # --image 从镜像创建服务器的启动磁盘
    # --volume 将卷作为服务器的启动磁盘，会自动创建一个块设备，映射boot index为0
    #          在很多Hypervisor（例如libvirt/kvm）这个磁盘将是vda
    #          不要使用 –block-device-mapping  选项来为此磁盘创建重复的映射
    (--image <image> | --image-property <key=value> | --volume <volume>)
    # 服务器的密码
    [--password <password>]
    # 服务器的风格
    --flavor <flavor>
    # 加入安全组，可以指定多个
    [--security-group <security-group>]
    # 注入到此服务器的OpenSSH公钥
    [--key-name <key-name>]
    # 设置属性
    [--property <key=value>]
    # 在启动之前，注入到镜像中的文件。可以指定多个
    [--file <dest-filename=source-filename>]
    # 从metadata服务器来serve的用户数据文件。用于配置新实例
    [--user-data <user-data>]
    [--description <description>]
    # 在哪个AZ中创建此服务器，可以指定：
    #   <zone-name>:<host-name>:<node-name>
    #   <zone-name>::<node-name>
    #   <zone-name>:<host-name>
    #   <zone-name>
    [--availability-zone <zone-name>]
    # 指定在某个宿主机上创建实例
    [--host <host>]
    [--hypervisor-hostname <hypervisor-hostname>]
    # 和 --image 或 --image-property 一起使用时，该选项自动创建boot index 为0的块设备
    # 并且告知计算服务，从镜像创建卷+卷的大小（GB）。此卷在实例销毁后不会删除
    # 不能和 --volume 联用
    [--boot-from-volume <volume-size>]
    # 在服务器上创建额外的块设备，格式：
    #   <dev-name>=<id>:<type>:<size(GB)>:<delete-on-terminate>
    #     dev-name 为块设备名称，例如vdb xvdc
    #     id 为卷、卷快照、镜像的名字或ID
    #     type：volume, snapshot 或 image。默认volume
    #     size：卷的大小
    #     delete-on-terminate：true或false
    [--block-device-mapping <dev-name=mapping>]
    # 在服务器上创建NIC。要创建多个NIC，则指定多次
    #     net-id和port-id互斥，不能同时指定
    #     v4-fixed-ip 此NIC的IPv4固定IP地址
    #     v6-fixed-ip 此NIC的IPv6固定IP地址
    #     auto 由计算服务自动分配一个网络。不能和其它参数一起使用
    #     none 不连接到网络。不能和其它参数一起使用
    [--nic <net-id=net-uuid,v4-fixed-ip=ip-addr,v6-fixed-ip=ip-addr,port-id=port-uuid,auto,none>]
    # 创建一个NIC，并且连接到该网络。可以指定多次，以创建多个NIC并连接到多个网络
    [--network <network>]
    # 创建一个NIC，并且连接到该端口。可以指定多次，以创建多个NIC并连接到多个端口
    [--port <port>]
    # 提供给nova-scheduler的提示信息
    [--hint <key=value>]
    # 启用config drive
    [--use-config-drive | --no-config-drive | --config-drive <config-drive-volume>|True]
    # 启动的实例数量
    [--min <count>]
    [--max <count>]
    # 等待实例构建完成
    [--wait]
    [--tag <tag>]
    # 实例的名字
    <server-name>


# 从镜像启动虚拟机，并挂载一个非启动磁盘
## 创建非启动磁盘
openstack volume create --size 8 my-volume
## 创建虚拟机         从镜像创建
nova boot --flavor 2 --image 98901246-af91-43d8-b5e6-a4506aa8f369 \
# 添加块设备      源是卷        卷的ID                                   挂载为卷    虚拟机删除后保留卷  
  --block-device source=volume,id=d620d971-b160-4c4e-8652-2513d74e2080,dest=volume,shutdown=preserve \
  myInstanceWithVolume


# 从SOURCE创建启动卷，并从该卷启动虚拟机
# SOURCE： volume, snapshot, image, 或者 blank
# DEST：volume或local
nova boot --flavor FLAVOR --block-device \
  source=SOURCE,id=ID,dest=DEST,size=SIZE,shutdown=PRESERVE,bootindex=INDEX  NAME

# 从镜像创建一个可启动卷。如果指定--image参数，则Cinder自动将卷标记为可启动的
openstack volume create --image IMAGE_ID --size SIZE_IN_GB bootable_volume


# 挂载Swap或者临时磁盘到虚拟机
nova boot --flavor FLAVOR --image IMAGE_ID --swap 512  --ephemeral size=2 NAME

为服务器添加固定IP地址：

openstack server add fixed ip
    # 请求的固定IP地址
    [--fixed-ip-address <ip-address>]
    [--tag <tag>]
    <server>
    <network>

openstack server remove fixed ip <server> <ip-address>

为服务器添加浮动IP地址：

openstack server add floating ip
    # 和此浮动IP地址关联的固定IP地址，使用第一个具有此固定IP地址的、此服务器上的port
    [--fixed-ip-address <ip-address>]
    <server>
    # 分配给上述第一个服务器port的浮动IP地址
    <ip-address>

openstack server remove floating ip <server> <ip-address>

将服务器连接到某个网络 

openstack server add network [--tag <tag>] <server> <network>

openstack server remove network <server> <network>

将某个端口连接到服务器

openstack server add port [--tag <tag>] <server> <port>

openstack server remove port <server> <port>

将服务器添加到安全组

openstack server add security group <server> <group>

openstack server remove security group <server> <group>

挂载（Attach）一个卷给服务器

openstack server add volume
    # 服务器上的内部设备名
    [--device <device>]
    [--tag <tag>]
    # 如果服务器被销毁，此卷是否被删除
    [--enable-delete-on-termination | --disable-delete-on-termination]
    <server>
    <volume>

openstack server remove volume <server> <volume>

# 示例
openstack server add volume cirros-amd64 cirros-amd64-diskb

服务器迁移，就是将一台宿主机上的实例，转移到另外一台上运行。

OpenStack支持四种迁移模式：热迁移、冷迁移、升降配（resize）、重建（evacuation）

# 显示迁移历史的列表
openstack server migration list
    [--sort-column SORT_COLUMN]
    [--server <server>]
    [--host <host>]
    [--status <status>]
    [--type <type>]
    [--marker <marker>]
    [--limit <limit>]
    [--changes-since <changes-since>]
    [--changes-before <changes-before>]
    [--project <project>]
    [--user <user>]

扩/缩容服务器为新的flavor。实现方式是：

1. 创就一个新的服务器
2. 复制文件到新服务器

扩/缩容操作分为两步完成：第一步迁移，第二步确认

openstack server resize
    [--flavor <flavor> | --confirm | --revert]
    [--wait]
    <server>

openstack server resize confirm <server>

openstack server resize revert <server>

将服务器迁移到另外一个宿主机上。

迁移操作是基于resize操作实现的：

1. 创建一个新的实例，使用相同的flavor
2. 从原始磁盘上拷贝内容到新磁盘

和resize一样，迁移操作是分两步完成的：

1. 执行上述两步的迁移操作
2. 让用户确认，迁移是否成功并移除酒实例，还是执行revert操作 —— 删除新实例并重启老的

openstack server migrate
    # 不宕机迁移
    [--live-migration]
    # 目标主机 
    [ --host <hostname>]
    [--shared-migration | --block-migration]
    [--disk-overcommit | --no-disk-overcommit]
    [--wait]
    <server>

确认迁移

openstack server migrate confirm <server>

撤销迁移 

openstack server migrate revert <server>

将服务器在另外一个宿主机上重建。这个命令的使用场景是：实例已经运行，但是后来它所在的宿主机宕掉了。 也就是说，仅当管理此实例的compute service宕机了，才可以使用此命令。

如果服务器实例使用临时的（ephemeral）root磁盘，此磁盘位于非共享存储上，则使用原始的glance镜像重建服务器。连接到原实例的port、挂载的卷被保留。

如果服务器实例从volume启动，或者跟磁盘位于共享存储上，则新建实例会重用此启动盘。

暂停服务器，状态保存在内存中

openstack server pause <server> [<server> ...]

取消暂停服务器

openstack server unpause <server> [<server> ...]

暂停服务器，状态保存在磁盘中

openstack server suspend <server> [<server> ...]

从暂停中恢复

openstack server resume <server> [<server> ...]

回退状态为软删除的服务器

openstack server restore <server> [<server> ...] 

重启服务器

#                       强行立即重启
openstack server reboot [--hard | --soft] [--wait] <server>

启动服务器

openstack server start <server> [<server> ...]

停止服务器

openstack server stop <server> [<server> ...]

重建服务器

openstack server rebuild
    [--image <image>]
    [--password <password>]
    [--property <key=value>]
    [--description <description>]
    [--key-name <key-name> | --key-unset]
    [--wait]
    <server> 

让服务器进入rescue模式

openstack server rescue
    [--image <image>]
    [--password <password>]
    <server> 

从rescue模式恢复：

openstack server unrescue <server>

将服务器实例作为镜像，保存在glance中，然后在宿主机上删除此服务器 

openstack server shelve <server> [<server> ...] 

将shelve的实例恢复

openstack server unshelve
    [--availability-zone AVAILABILITY_ZONE]
    <server>
    [<server> ...] 

通过SSH连接到服务器

openstack server ssh
    [--login <login-name>]
    [--port <port>]
    [--identity <keyfile>]
    [--option <config-options>]
    [-4 | -6]
    [--public | --private | --address-type <address-type>]
    <server>


# 自动使用当前用户的SSH key
openstack server ssh --private -4 --login cirros cirros-amd64-0

创建服务器的Dump文件。这会触发一个crash dump（例如Linux的kdump） 

openstack server dump create <server> [<server> ...]

（软）删除服务器

openstack server delete [--wait] <server> [<server> ...]

设置服务器属性

openstack server set
    [--name <new-name>]
    [--root-password]
    [--property <key=value>]
    [--state <state>]
    [--description <description>]
    [--tag <tag>]
    <server>

openstack server unset
    [--property <key>]
    [--description]
    [--tag <tag>]
    <server>

锁定实例，这样非admin用户就不能对它进行任何操作。

openstack server lock [--reason <reason>] <server> [<server> ...]

解锁服务器

openstack server unpause <server> [<server> ...] 

openstack server list
    [--sort-column SORT_COLUMN]
    [--availability-zone <availability-zone>]
    [--reservation-id <reservation-id>]
    [--ip <ip-address-regex>]
    [--ip6 <ip-address-regex>]
    [--name <name-regex>]
    [--instance-name <server-name>]
    [--status <status>]
    [--flavor <flavor>]
    [--image <image>]
    [--host <hostname>]
    [--all-projects]
    [--project <project>]
    [--project-domain <project-domain>]
    [--user <user>]
    [--user-domain <user-domain>]
    [--long]
    [-n | --name-lookup-one-by-one]
    [--marker <server>]
    [--limit <num-servers>]
    [--deleted]
    [--changes-before <changes-before>]
    [--changes-since <changes-since>]
    [--locked | --unlocked]
    [--tags <tag>]
    [--not-tags <tag>]

#                     显示诊断信息
openstack server show [--diagnostics] <server>

备份一个运行中的服务器实例，将其磁盘保存为镜像，存放在Glance中。

# 创建备份
openstack server backup create
    # 备份镜像的名字，默认为服务器名
    [--name <image-name>]
    # 填充镜像的backup_type字段
    [--type <backup-type>]
    # 保存的备份数量
    [--rotate <count>]
    [--wait]
    <server>

从运行中的实例创建磁盘镜像，并存放到Glance中。

openstack server image create [--name <image-name>] [--wait] <server> 

服务器事件，记录了针对服务器的各种操作。事件由操作类型（create, delete, reboot ...）+ 操作结果（success, error） + 开始/结束时间组成。

# 事件列表
openstack server event list
    [--sort-column SORT_COLUMN]
    [--long]
    <server>

# 显示事件
openstack server event show <server> <request-id>

一个网络服务提供者，表示一个特定的、实现了网络服务的驱动：

openstack network service provider list [--sort-column SORT_COLUMN]

所谓网络，是指一个独立的（isolated）的L2网段。OpenStack具有两种类型的网络：

1. project：完全隔离的、不和其它项目共享的网络。自服务网络
2. provider：映射到现有的、数据中心中的物理网络，为server或其它资源提供外部网络访问

仅仅管理员可以创建provider网络

openstack network create
    # 是否允许跨项目共享
    [--share | --no-share]
    # 是否启用网络
    [--enable | --disable]
    # 所属项目
    [--project <project>]
    [--description <description>]
    # MTU设置
    [--mtu <mtu>]
    [--project-domain <project-domain>]
    # 在什么AZ中创建此网络。需要Network Availability Zone扩展
    # 此选项可以指定多次，表示网络跨越多个AZ
    [--availability-zone-hint <availability-zone>]
    # 是否启用端口安全，如果指定，则此网络上创建的端口自动应用安全设置
    [--enable-port-security | --disable-port-security]
    # 是否外部网络，如果是，则需要external-net扩展
    [--external | --internal]
    # 是否作为默认外部网络
    [--default | --no-default]
    # 应用到此网络的QoS策略
    [--qos-policy <qos-policy>]
    # 指定此网络是VLAN透明的
    [--transparent-vlan | --no-transparent-vlan]
    # 此虚拟网络所基于其实现的物理机制（physical mechanism）
    #   例如  flat, geneve, gre, local, vlan, vxlan
    [--provider-network-type <provider-network-type>]
    # 此虚拟网络所基于的物理网络的名字
    [--provider-physical-network <provider-physical-network>]
    # 对于VLAN网络，指定VLAN ID
    # 对于GENEVE/GRE/VXLAN，指定Tunnel ID
    [--provider-segment <provider-segment>]
    # 此网络的DNS domain，需要DNS integration扩展
    [--dns-domain <dns-domain>]
    [--tag <tag> | --no-tag]
    # IPv4的CIDR
    --subnet <subnet>
    <name>

openstack network delete <network> [<network> ...]

openstack network list
    [--sort-column SORT_COLUMN]
    [--external | --internal]
    [--long]
    [--name <name>]
    [--enable | --disable]
    [--project <project>]
    [--project-domain <project-domain>]
    [--share | --no-share]
    [--status <status>]
    [--provider-network-type <provider-network-type>]
    [--provider-physical-network <provider-physical-network>]
    [--provider-segment <provider-segment>]
    [--agent <agent-id>]
    [--tags <tag>[,<tag>,...]]
    [--any-tags <tag>[,<tag>,...]]
    [--not-tags <tag>[,<tag>,...]]
    [--not-any-tags <tag>[,<tag>,...]]

openstack network set
    [--name <name>]
    [--enable | --disable]
    [--share | --no-share]
    [--description <description]
    [--mtu <mtu]
    [--enable-port-security | --disable-port-security]
    [--external | --internal]
    [--default | --no-default]
    [--qos-policy <qos-policy> | --no-qos-policy]
    [--tag <tag>]
    [--no-tag]
    [--provider-network-type <provider-network-type>]
    [--provider-physical-network <provider-physical-network>]
    [--provider-segment <provider-segment>]
    [--dns-domain <dns-domain>]
    <network>
openstack network unset [--tag <tag> | --all-tag] <network>

openstack network show <network>

子网是一段IP地址以及关联的配置状态。当新的Port接入到网络中时，子网用于向Port分配IP地址。

openstack subnet create
    [--project <project>]
    [--project-domain <project-domain>]
    # --subnet-pool 该子网从此池中获得自己的CIDR
    # --use-default-subnet-pool 使用默认的子网池
    [--subnet-pool <subnet-pool> | --use-prefix-delegation USE_PREFIX_DELEGATION | --use-default-subnet-pool]
    # 从子网池中分配子网时，前缀的长度
    [--prefix-length <prefix-length>]
    # CIDR格式的子网IP地址范围
    [--subnet-range <subnet-range>]
    # 是否启用DHCP
    [--dhcp | --no-dhcp]
    # 是否在DNS中发布固定IP
    [--dns-publish-fixed-ip | --no-dns-publish-fixed-ip]
    # 指定子网的网关。三种形式：
    #   <ip-address> 将指定的IP地址作为网关
    #   auto 自动在子网内部选择网关地址，默认
    #   none 不使用网关
    [--gateway <gateway>]
    # 子网的IP版本，如果使用了subnet pool，则IP版本取决于子网池，该选项被忽略
    [--ip-version {4,6}]
    # IPv6 RA（Router Advertisement）模式
    [--ipv6-ra-mode {dhcpv6-stateful,dhcpv6-stateless,slaac}]
    # IPv6地址模式
    [--ipv6-address-mode {dhcpv6-stateful,dhcpv6-stateless,slaac}]
    # 关联到此子网的网段，网段属于某个网络
    [--network-segment <network-segment>]
    # 此子网所属的网络
    --network <network>
    [--description <description>]
    # 此子网的DHCP自动分配IP地址的范围。可以指定多个
    [--allocation-pool start=<ip-address>,end=<ip-address>]
    # 此子网使用的DNS服务器
    [--dns-nameserver <dns-nameserver>]
    # 为子网添加额外的路由，示例 destination=10.10.0.0/16,gateway=192.168.71.254 网关为下一跳地址
    [--host-route destination=<subnet>,gateway=<ip-address>]
    # 子网的服务类型，必须指定为有效的、某个网络端口的device owner，例如network:floatingip_agent_gateway
    # 可以指定多个，以支持多个服务类型
    [--service-type <service-type>]
    [--tag <tag> | --no-tag]
    <name>

openstack subnet delete <subnet> [<subnet> ...]

openstack subnet list
    [--sort-column SORT_COLUMN]
    [--long]
    [--ip-version <ip-version>]
    [--dhcp | --no-dhcp]
    [--service-type <service-type>]
    [--project <project>]
    [--project-domain <project-domain>]
    [--network <network>]
    [--gateway <gateway>]
    [--name <name>]
    [--subnet-range <subnet-range>]
    [--tags <tag>[,<tag>,...]]
    [--any-tags <tag>[,<tag>,...]]
    [--not-tags <tag>[,<tag>,...]]
    [--not-any-tags <tag>[,<tag>,...]]
openstack subnet show <subnet>

openstack subnet set
    [--name <name>]
    [--dhcp | --no-dhcp]
    [--dns-publish-fixed-ip | --no-dns-publish-fixed-ip]
    [--gateway <gateway>]
    [--network-segment <network-segment>]
    [--description <description>]
    [--tag <tag>]
    [--no-tag]
    [--allocation-pool start=<ip-address>,end=<ip-address>]
    [--no-allocation-pool]
    [--dns-nameserver <dns-nameserver>]
    [--no-dns-nameservers]
    [--host-route destination=<subnet>,gateway=<ip-address>]
    [--no-host-route]
    [--service-type <service-type>]
    <subnet>
openstack subnet unset
    [--allocation-pool start=<ip-address>,end=<ip-address>]
    [--dns-nameserver <dns-nameserver>]
    [--host-route destination=<subnet>,gateway=<ip-address>]
    [--service-type <service-type>]
    [--tag <tag> | --all-tag]
    <subnet>

子网池中包含若干CIDR格式的子网前缀，这些前缀用于分配给子网。

# 创建一个子网池
openstack subnet pool create
    # 子网池的前缀
    --pool-prefix <pool-prefix>
    # 子网池默认前缀长度
    [--default-prefix-length <default-prefix-length>]
    # 最小/最大前缀长度
    [--min-prefix-length <min-prefix-length>]
    [--max-prefix-length <max-prefix-length>]
    [--project <project>]
    [--project-domain <project-domain>]
    # 关联到此池的address scope对象的名字或ID
    [--address-scope <address-scope>]
    # 是否作为默认子网池
    [--default | --no-default]
    [--share | --no-share]
    [--description <description>]
    # 默认的，每个项目的配额 —— 可以从池中分配的IP数量
    [--default-quota <num-ip-addresses>]
    [--tag <tag> | --no-tag]
    <name>

openstack subnet pool delete <subnet-pool> [<subnet-pool> ...]

openstack subnet pool list
    [--sort-column SORT_COLUMN]
    [--long]
    [--share | --no-share]
    [--default | --no-default]
    [--project <project>]
    [--project-domain <project-domain>]
    [--name <name>]
    [--address-scope <address-scope>]
    [--tags <tag>[,<tag>,...]]
    [--any-tags <tag>[,<tag>,...]]
    [--not-tags <tag>[,<tag>,...]]
    [--not-any-tags <tag>[,<tag>,...]]
openstack subnet pool show <subnet-pool>

openstack subnet pool set
    [--name <name>]
    [--pool-prefix <pool-prefix>]
    [--default-prefix-length <default-prefix-length>]
    [--min-prefix-length <min-prefix-length>]
    [--max-prefix-length <max-prefix-length>]
    [--address-scope <address-scope> | --no-address-scope]
    [--default | --no-default]
    [--description <description>]
    [--default-quota <num-ip-addresses>]
    [--tag <tag>]
    [--no-tag]
    <subnet-pool>
openstack subnet pool unset [--tag <tag> | --all-tag] <subnet-pool>

表示IPv4或IPv6的地址范围，属于某个特定项目，可以被多个项目共享。

# 创建地址范围
openstack address scope create
    [--ip-version {4,6}]
    [--project <project>]
    [--project-domain <project-domain>]
    # 是否可以在项目之间共享
    [--share | --no-share]
    <name>

openstack address scope delete <address-scope> [<address-scope> ...]

openstack address scope list
    [--sort-column SORT_COLUMN]
    [--name <name>]
    [--ip-version <ip-version>]
    [--project <project>]
    [--project-domain <project-domain>]
    [--share | --no-share]

openstack address scope set
    [--name <name>]
    [--share | --no-share]
    <address-scope>

openstack address scope show <address-scope> 

虚拟路由器是一个逻辑组件，能够在不同网络之间分发数据包。虚拟路由器也提供L3和NAT转发功能，让虚拟网络中的服务器能够访问外部流量。

# 将端口添加到路由器
openstack router add port <router> <port>
openstack router remove port <router> <port>

# 将子网连接到路由器
openstack router add subnet <router> <subnet>
openstack router remove subnet <router> <subnet>

# 在路由器的路由表中添加一个静态路由
openstack router add route
    [--route destination=<subnet>,gateway=<ip-address>]
    <router>
openstack router remove route
    [--route destination=<subnet>,gateway=<ip-address>]
    <router>

# 创建路由器
openstack router create
    [--enable | --disable]
    # 集中还是分布式的
    [--distributed | --centralized]
    # 是否高可用
    [--ha | --no-ha]
    [--description <description>]
    [--project <project>]
    [--project-domain <project-domain>]
    [--availability-zone-hint <availability-zone>]
    [--tag <tag> | --no-tag]
    <name>

# 删除路由器
openstack router delete <router> [<router> ...]

# 列出路由器
openstack router list
    [--sort-column SORT_COLUMN]
    [--name <name>]
    [--enable | --disable]
    [--long]
    [--project <project>]
    [--project-domain <project-domain>]
    [--agent <agent-id>]
    [--tags <tag>[,<tag>,...]]
    [--any-tags <tag>[,<tag>,...]]
    [--not-tags <tag>[,<tag>,...]]
    [--not-any-tags <tag>[,<tag>,...]]

# 设置属性
openstack router set
    [--name <name>]
    [--description <description>]
    [--enable | --disable]
    [--distributed | --centralized]
    [--route destination=<subnet>,gateway=<ip-address>]
    [--no-route]
    [--ha | --no-ha]
    [--external-gateway <network>]
    [--fixed-ip subnet=<subnet>,ip-address=<ip-address>]
    [--enable-snat | --disable-snat]
    [--qos-policy <qos-policy> | --no-qos-policy]
    [--tag <tag>]
    [--no-tag]
    <router>
openstack router unset
    [--route destination=<subnet>,gateway=<ip-address>]
    [--external-gateway]
    [--qos-policy]
    [--tag <tag> | --all-tag]
    <router>

# 显示路由器信息
openstack router show <router> 

端口是网络上的接入点，它可以将单个设备（例如server上的NIC）连接到网络。端口也描述了其关联的网络配置，例如MAC地址、IP地址

openstack port create
    # 端口所属的网络
    --network <network>
    [--description <description>]
    # 端口的设备ID
    [--device <device-id>]
    # 端口的MAC地址
    [--mac-address <mac-address>]
    # 使用端口的实体，例如network:dhcp
    [--device-owner <device-owner>]
    # 端口的VNIC类型。默认normal
    # direct | direct-physical | macvtap | normal | baremetal | virtio-forwarder
    [--vnic-type <vnic-type>]
    # 在宿主机上分配端口
    [--host <host-id>]
    # 此端口所属的DNS域
    [--dns-domain dns-domain]
    # 此端口的DNS名称
    [--dns-name <dns-name>]
    # 调度此端口所需的NUMA亲和性策略
    [--numa-policy-required | --numa-policy-preferred | --numa-policy-legacy]
    # 此端口期望的IP和/或子网。可以指定多次
    [--fixed-ip subnet=<subnet>,ip-address=<ip-address> | --no-fixed-ip]
    [--binding-profile <binding-profile>]
    # 启用/禁用端口
    [--enable | --disable]
    # 启用uplink状态传播
    [--enable-uplink-status-propagation | --disable-uplink-status-propagation]
    [--project <project>]
    [--project-domain <project-domain>]
    # 额外分配给此端口的DHCP选项
    [--extra-dhcp-option name=<name>[,value=<value>,ip-version={4,6}]]
    # 关联到此端口的安全组
    [--security-group <security-group> | --no-security-group]
    # 关联到此端口的QoS策略
    [--qos-policy <qos-policy>]
    # 是否启用端口安全
    [--enable-port-security | --disable-port-security]
    # 添加允许的IP/MAC地址。可以指定多次
    # 不被允许的IP地址，不能作为发往此端口的IP目的地址
    [--allowed-address ip-address=<ip-address>[,mac-address=<mac-address>]]
    [--tag <tag> | --no-tag]
    <name>

openstack port delete <port> [<port> ...]

openstack port list
    [--sort-column SORT_COLUMN]
    [--device-owner <device-owner>]
    [--host <host-id>]
    [--network <network>]
    [--router <router> | --server <server> | --device-id <device-id>]
    [--mac-address <mac-address>]
    [--long]
    [--project <project>]
    [--project-domain <project-domain>]
    [--fixed-ip subnet=<subnet>,ip-address=<ip-address>,ip-substring=<ip-substring>]
    [--tags <tag>[,<tag>,...]]
    [--any-tags <tag>[,<tag>,...]]
    [--not-tags <tag>[,<tag>,...]]
    [--not-any-tags <tag>[,<tag>,...]]

openstack port set
    [--description <description>]
    [--device <device-id>]
    [--mac-address <mac-address>]
    [--device-owner <device-owner>]
    [--vnic-type <vnic-type>]
    [--host <host-id>]
    [--dns-domain dns-domain]
    [--dns-name <dns-name>]
    [--numa-policy-required | --numa-policy-preferred | --numa-policy-legacy]
    [--enable | --disable]
    [--name <name>]
    [--fixed-ip subnet=<subnet>,ip-address=<ip-address>]
    [--no-fixed-ip]
    [--binding-profile <binding-profile>]
    [--no-binding-profile]
    [--qos-policy <qos-policy>]
    [--security-group <security-group>]
    [--no-security-group]
    [--enable-port-security | --disable-port-security]
    [--allowed-address ip-address=<ip-address>[,mac-address=<mac-address>]]
    [--no-allowed-address]
    [--data-plane-status <status>]
    [--tag <tag>]
    [--no-tag]
    <port>
openstack port unset
    [--fixed-ip subnet=<subnet>,ip-address=<ip-address>]
    [--binding-profile <binding-profile-key>]
    [--security-group <security-group>]
    [--allowed-address ip-address=<ip-address>[,mac-address=<mac-address>]]
    [--qos-policy]
    [--data-plane-status]
    [--numa-policy]
    [--tag <tag> | --all-tag]
    <port>

openstack port show <port> 

安全组是虚拟的网络防火墙，网络中的服务器、端口等资源可以受其影响。

安全组是安全组规则的容器。

# 创建安全组
openstack security group create
    [--description <description>]
    [--project <project>]
    # 是否五状态
    [--stateful | --stateless]
    [--project-domain <project-domain>]
    [--tag <tag> | --no-tag]
    <name>

openstack security group delete <group> [<group> ...]

openstack security group list
    [--sort-column SORT_COLUMN]
    [--project <project>]
    [--project-domain <project-domain>]
    [--tags <tag>[,<tag>,...]]
    [--any-tags <tag>[,<tag>,...]]
    [--not-tags <tag>[,<tag>,...]]
    [--not-any-tags <tag>[,<tag>,...]]
    [--all-projects]

openstack security group set
    [--name <new-name>]
    [--description <description>]
    [--stateful | --stateless]
    [--tag <tag>]
    [--no-tag]
    <group>
openstack security group unset [--tag <tag> | --all-tag] <group>

openstack security group show <group>

安全组中的一条规则。

# 创建一条规则
openstack security group rule create
    # 此规则针对的远程IP，可以使用CIDR
    #   0.0.0.0/0 表示默认IPv4规则
    #   ::/0 表示默认IPv6规则
    [--remote-ip <ip-address> | --remote-group <group>]
    # 目标（远程）端口。可以使用端口范围，例如  137:139
    # 对于TCP/UDP必须，对于ICMP忽略此字段
    [--dst-port <port-range>]
    # 协议： 默认any表示任何协议
    #   ah, dccp, egp, esp, gre, icmp, igmp, ipv6-encap, ipv6-frag, ipv6-icmp, ipv6-nonxt, 
    #   ipv6-opts, ipv6-route, ospf, pgm, rsvp, sctp, tcp, udp, udplite, vrrp 
    [--protocol <protocol>]
    [--description <description>]
    # 针对特定的ICMP类型
    [--icmp-type <icmp-type>]
    [--icmp-code <icmp-code>]
    # 此规则针对入站还是出站流量，默认ingress
    [--ingress | --egress]
    # 以太网上的流量类型  IPv4, IPv6
    [--ethertype <ethertype>]
    [--project <project>]
    [--project-domain <project-domain>]
    # 所属的组
    <group>

openstack security group rule delete <rule> [<rule> ...]

openstack security group rule list
    [--sort-column SORT_COLUMN]
    [--protocol <protocol>]
    [--ethertype <ethertype>]
    [--ingress | --egress]
    [--long]
    [--all-projects]
    [<group>]

openstack security group rule show <rule>


# 完全开放默认安全组
openstack security group rule create --remote-ip 0.0.0.0/0  --protocol any --ingress --ethertype IPv4 default
openstack security group rule create --remote-ip ::/0  --protocol any --ingress --ethertype IPv6 default
openstack security group rule create --remote-ip 0.0.0.0/0  --protocol any --egress --ethertype IPv4 default
openstack security group rule create --remote-ip ::/0  --protocol any --egress --ethertype IPv6 default

可以让管理员快速的设置某个项目的外部连接性。每个项目只能有一个此对象。

openstack network auto allocated topology create
    [--project <project>]
    [--project-domain <project-domain>]
    [--check-resources]
    [--or-show]

openstack network auto allocated topology delete
    [--project <project>]
    [--project-domain <project-domain>]

扩展network flavor允许用户在创建资源时，选择管理员配置的“网络风格”

# 添加一个service profile到network flavor
openstack network flavor add profile <flavor> <service-profile>
openstack network flavor remove profile <flavor> <service-profile>

# 创建network flavor
openstack network flavor create
    # 此flavor应用到的网络服务类型，例如VPN
    # 执行 openstack network service provider list  获得网络服务类型列表
    --service-type <service-type>
    [--description DESCRIPTION]
    [--project <project>]
    [--project-domain <project-domain>]
    [--enable | --disable]
    <name>

openstack network flavor delete <flavor> [<flavor> ...]

openstack network flavor list [--sort-column SORT_COLUMN]

openstack network flavor set
    [--description DESCRIPTION]
    [--disable | --enable]
    [--name <name>]
    <flavor>

openstack network flavor show <flavor>

用于管理员创建/删除/列出/显示网络服务的profile。

openstack network flavor profile create
    [--project <project>]
    [--project-domain <project-domain>]
    [--description <description>]
    [--enable | --disable]
    [--driver DRIVER]
    [--metainfo METAINFO]

openstack network flavor profile delete
    <flavor-profile>
    [<flavor-profile> ...]

openstack network flavor profile list [--sort-column SORT_COLUMN]

openstack network flavor profile set
    [--project-domain <project-domain>]
    [--description <description>]
    [--enable | --disable]
    [--driver DRIVER]
    [--metainfo METAINFO]
    <flavor-profile>

openstack network flavor profile show <flavor-profile>

允许管理员来度量某个IP范围的流量。需要L3 metering extension

openstack network meter create
    [--description <description>]
    [--project <project>]
    [--project-domain <project-domain>]
    [--share | --no-share]
    <name>

openstack network meter delete <meter> [<meter> ...]

openstack network meter list [--sort-column SORT_COLUMN]

openstack network meter show <meter>

为某个meter设置度量网络流量的规则。需要L3 metering extension

openstack network meter rule create
    [--project <project>]
    [--project-domain <project-domain>]
    [--exclude | --include]
    [--ingress | --egress]
    [--remote-ip-prefix <remote-ip-prefix>]
    [--source-ip-prefix <remote-ip-prefix>]
    [--destination-ip-prefix <remote-ip-prefix>]
    <meter>

openstack network meter rule delete
    <meter-rule-id>
    [<meter-rule-id> ...]

openstack network meter rule list [--sort-column SORT_COLUMN]

openstack network meter rule show <meter-rule-id>

将一组网络QoS规则组合到一起，可以应用到一个网络或端口。

openstack network qos policy create
    [--description <description>]
    [--share | --no-share]
    [--project <project>]
    [--project-domain <project-domain>]
    [--default | --no-default]
    <name>

openstack network qos policy delete <qos-policy> [<qos-policy> ...]

openstack network qos policy list
    [--sort-column SORT_COLUMN]
    [--project <project>]
    [--project-domain <project-domain>]
    [--share | --no-share]

openstack network qos policy set
    [--name <name>]
    [--description <description>]
    [--share | --no-share]
    [--default | --no-default]
    <qos-policy>

openstack network qos policy show <qos-policy>

上述policy中的一个规则

openstack network qos rule create
    # QoS规则类型
    # minimum-bandwidth, dscp-marking, bandwidth-limit
    [--type <type>]
    # 最大带宽
    [--max-kbps <max-kbps>]
    # 最大突发带宽。如果不指定或者设置为0表示自动，为80%的最大带宽，适合于典型的TCP流量
    [--max-burst-kbits <max-burst-kbits>]
    # DSCP标记，可以是0，或者8-56之间的偶数（42 44 50 52 54不可以）
    [--dscp-mark <dscp-mark>]
    # 最小保障的带宽
    [--min-kbps <min-kbps>]
    # 此规则是用于入站还是出站的流量（从当前项目的角度）
    [--ingress | --egress]
    # 此规则加到哪个策略中
    <qos-policy>

openstack network qos rule delete <qos-policy> <rule-id>

openstack network qos rule list
    [--sort-column SORT_COLUMN]
    <qos-policy>

openstack network qos rule set
    [--max-kbps <max-kbps>]
    [--max-burst-kbits <max-burst-kbits>]
    [--dscp-mark <dscp-mark>]
    [--min-kbps <min-kbps>]
    [--ingress | --egress]
    <qos-policy>
    <rule-id>

openstack network qos rule show <qos-policy> <rule-id>

表示一个网络中的隔离的L2的段。一个（虚拟）网络可以包含多个段，同一个网络中的段的L2通信不被保证。

# 创建一个网络段
openstack network segment create
    [--description <description>]
    # 物理网络的名字
    [--physical-network <physical-network>]
    # 段的名字
    [--segment <segment>]
    # 此段属于的虚拟网络的名字
    --network <network>
    # 此段的网络类型：flat, geneve, gre, local, vlan, vxlan
    --network-type <network-type>
    <name>

openstack network segment delete
    <network-segment>
    [<network-segment> ...]

openstack network segment list
    [--sort-column SORT_COLUMN]
    [--long]
    [--network <network>]

openstack network segment set
    [--description <description>]
    [--name <name>]
    <network-segment>

openstack network segment show <network-segment>

用于多租户下的网络段分配。可以让管理员全局的，或者基于用户的，来控制网络段范围。

openstack network segment range create
    [--private | --shared]
    [--project <project>]
    [--project-domain <project-domain>]
    --network-type <network-type>
    [--physical-network <physical-network-name>]
    --minimum <minimum-segmentation-id>
    --maximum <maximum-segmentation-id>
    <name>

openstack network segment range delete
    <network-segment-range>
    [<network-segment-range> ...]

openstack network segment range list
    [--sort-column SORT_COLUMN]
    [--long]
    [--used | --unused]
    [--available | --unavailable]

openstack network segment range set
    [--name <name>]
    [--minimum <minimum-segmentation-id>]
    [--maximum <maximum-segmentation-id>]
    <network-segment-range>

openstack network segment range show <network-segment-range> 

所谓网络代理，负责（在节点上）处理各种任务，以实现虚拟网络。网络代理包括：

1. neutron-dhcp-agent，负责提供DHCP服务给虚拟机
2. neutron-l3-agent，负责在自服务网络中提供路由
3. neutron-metering-agent
4. neutron-lbaas-agent

# 添加网络到代理
openstack network agent add network [--dhcp] <agent-id> <network>
openstack network agent remove network [--dhcp] <agent-id> <network>

# 添加路由器到代理
openstack network agent add router [--l3] <agent-id> <router>
openstack network agent remove router [--l3] <agent-id> <router>

# 删除代理
openstack network agent delete <network-agent> [<network-agent> ...]

# 设置代理属性
openstack network agent set
    [--description <description>]
    [--enable | --disable]
    <network-agent>

# 列出代理
openstack network agent list
    [--sort-column SORT_COLUMN]
    [--agent-type <agent-type>]
    [--host <host>]
    [--network <network> | --router <router>]
    [--long]

# 显示代理详细信息
openstack network agent show <network-agent> 

显示网络可用的IP地址

# IP可用数量
openstack ip availability list

# 显示详细信息
openstack ip availability show <network>

管理浮动IP

# 创建一个浮动IP
openstack floating ip create
    # 在哪个子网上创建浮动IP
    [--subnet <subnet>]
    # 浮动IP授予哪个端口
    [--port <port>]
    # 浮动IP的值
    [--floating-ip-address <ip-address>]
    # 映射到浮动IP的固定IP
    [--fixed-ip-address <ip-address>]
    # 浮动IP的QoS策略
    [--qos-policy <qos-policy>]
    [--description <description>]
    [--project <project>]
    # 浮动IP的DNS名
    [--dns-domain <dns-domain>]
    [--dns-name <dns-name>]
    [--project-domain <project-domain>]
    # 添加标记
    [--tag <tag> | --no-tag]
    # 从什么网络来分配浮动IP
    <network>
openstack floating ip unset
    [--port]
    [--qos-policy]
    [--tag <tag> | --all-tag]
    <floating-ip>

openstack floating ip delete <floating-ip> [<floating-ip> ...]
openstack floating ip set
    [--port <port>]
    [--fixed-ip-address <ip-address>]
    [--description <description>]
    [--qos-policy <qos-policy> | --no-qos-policy]
    [--tag <tag>]
    [--no-tag]
    <floating-ip>

openstack floating ip show <floating-ip>
openstack floating ip list
    [--sort-column SORT_COLUMN]
    [--network <network>]
    [--port <port>]
    [--fixed-ip-address <ip-address>]
    [--floating-ip-address <ip-address>]
    [--long]
    [--status <status>]
    [--project <project>]
    [--project-domain <project-domain>]
    [--router <router>]
    [--tags <tag>[,<tag>,...]]
    [--any-tags <tag>[,<tag>,...]]
    [--not-tags <tag>[,<tag>,...]]
    [--not-any-tags <tag>[,<tag>,...]]

浮动IP池管理

openstack floating ip pool list [--sort-column SORT_COLUMN]

创建浮动IP端口转发规则

openstack floating ip port forwarding create
    # 端口上的固定IPv4地址，浮动IP将其作为转发目标
    --internal-ip-address <internal-ip-address>
    # 转发到的端口
    --port <port>
    # 固定地址上的端口
    --internal-protocol-port <port-number>
    # 浮动IP上的端口
    --external-protocol-port <port-number>
    # 协议
    --protocol <protocol>
    [--description <description>]
    # 此转发规则针对的浮动IP（的IP或ID）
    <floating-ip>

管理卷服务

openstack volume service list
    [--host <host>]
    [--service <service>]
    [--long]

openstack volume service set
    [--enable | --disable]
    [--disable-reason <reason>]
    <host>
    <service>

管理卷

# 创建卷
openstack volume create
    # 卷的大小，单位GB
    [--size <size>]
    # 卷的类型
    [--type <volume-type>]
    # 将镜像、快照或者另外一个卷，作为新卷的数据来源
    [--image <image> | --snapshot <snapshot> | --source <volume> ]
    [--description <description>]
    # 指定一个alternate用户、项目
    [--user <user>]
    [--project <project>]
    # 在指定可用区中创建卷
    [--availability-zone <availability-zone>]
    # 将卷加入到一致性组
    [--consistency-group <consistency-group>]
    [--property <key=value> [...] ]
    # 提供给卷调度器的提示信息
    [--hint <key=value> [...] ]
    # 卷是否需要支持多重挂载
    [--multi-attach]
    # 是否将卷标记为可启动磁盘
    [--bootable | --non-bootable]
    # 是否只读卷
    [--read-only | --read-write]
    <name>
# 删除卷
openstack volume delete
    [--force | --purge]
    <volume> [<volume> ...]

# 列出卷
openstack volume list
    [--project <project> [--project-domain <project-domain>]]
    [--user <user> [--user-domain <user-domain>]]
    [--name <name>]
    [--status <status>]
    [--all-projects]
    [--long]
    [--limit <num-volumes>]
    [--marker <volume>]
# 显示卷的详细信息
openstack volume show
    <volume>

# 设置卷属性
openstack volume set
    [--name <name>]
    [--size <size>]
    [--description <description>]
    [--no-property]
    [--property <key=value> [...] ]
    [--image-property <key=value> [...] ]
    [--state <state>]
    [--attached | --detached ]
    [--type <volume-type>]
    [--retype-policy <retype-policy>]
    [--bootable | --non-bootable]
    [--read-only | --read-write]
    <volume>
openstack volume unset
    [--property <key>]
    [--image-property <key>]
    <volume>

管理卷类型

openstack volume type create
    [--description <description>]
    [--public | --private]
    [--property <key=value> [...] ]
    [--project <project>]
    [--project-domain <project-domain>]
    [--encryption-provider <provider>]
    [--encryption-cipher <cipher>]
    [--encryption-key-size <key-size>]
    [--encryption-control-location <control-location>]
    <name>
openstack volume type delete
    <volume-type> [<volume-type> ...]

openstack volume type list
    [--long]
    [--default | --public | --private]
    [--encryption-type]
openstack volume type show
    [--encryption-type]
    <volume-type>


openstack volume type set
    [--name <name>]
    [--description <description>]
    [--property <key=value> [...] ]
    [--project <project>]
    [--project-domain <project-domain>]
    [--encryption-provider <provider>]
    [--encryption-cipher <cipher>]
    [--encryption-key-size <key-size>]
    [--encryption-control-location <control-location>]
    <volume-type>
openstack volume type unset
    [--property <key> [...] ]
    [--project <project>]
    [--project-domain <project-domain>]
    [--encryption-type]
    <volume-type>

# 显示卷后端特性
openstack volume backend capability show
    [--sort-column SORT_COLUMN]
    <host>

# 列出后端池
openstack volume backend pool list [--sort-column SORT_COLUMN] [--long] 

将卷迁移到一个新的宿主机 

openstack volume migrate
    # 目标主机
    --host <host>
    # 使用一般性的，基于复制的迁移。跳过存储驱动可能的优化
    [--force-host-copy]
    # 锁定卷，防止迁移被其它操作中止
    [--lock-volume]
    <volume>

管理卷的快照

# 创建一个卷快照
openstack volume snapshot create
    # 目标卷
    [--volume <volume>]
    [--description <description>]
    # 即使在使用中，也创建快照
    [--force]
    [--property <key=value> [...] ]
    [--remote-source <key=value> [...]]
    <snapshot-name>
openstack volume snapshot delete
    [--force]
    <snapshot> [<snapshot> ...]


# 列出和显示
openstack volume snapshot list
    [--all-projects]
    [--project <project> [--project-domain <project-domain>]]
    [--long]
    [--limit <num-snapshots>]
    [--marker <snapshot>]
    [--name <name>]
    [--status <status>]
    [--volume <volume>]
openstack volume snapshot show
    <snapshot>

# 设置属性
openstack volume snapshot set
    [--name <name>]
    [--description <description>]
    [--no-property]
    [--property <key=value> [...] ]
    [--state <state>]
    <snapshot>
openstack volume snapshot unset
    [--property <key>]
    <snapshot>

管理卷备份

# 创建卷备份
openstack volume backup create
    [--name <name>]
    [--description <description>]
    # 保存到哪个对象容器
    [--container <container>]
    # 备份快照
    [--snapshot <snapshot>]
    # 允许备份使用中的卷
    [--force]
    # 进行增量备份
    [--incremental]
    <volume>

# 删除卷备份
openstack volume backup delete [--force] <backup> [<backup> ...]

# 列出卷备份
openstack volume backup list
    [--sort-column SORT_COLUMN]
    [--long]
    [--name <name>]
    [--status <status>]
    [--volume <volume>]
    [--marker <volume-backup>]
    [--limit <num-backups>]
    [--all-projects]

# 显示备份详细信息
openstack volume backup show <backup>

# 导出卷备份详细信息
openstack volume backup record export <backup>

# 导入卷备份详细信息
openstack volume backup record import
    <backup_service>
    <backup_metadata>

# 设置属性
openstack volume backup set
    [--name <name>]
    [--description <description>]
    [--state <state>]
    <backup>

从备份中恢复卷

openstack volume backup restore <backup> <volume>

管理卷关联的QoS规格，将QoS规格关联到卷类型

# 关联QoS规格到一个卷类型
openstack volume qos associate
    <qos-spec>
    <volume-type>
volume qos disassociate

# 创建一个QoS规格
openstack volume qos create
    [--consumer <consumer>]
    [--property <key=value> [...] ]
    <name>

# 删除一个QoS规格
volume qos delete

# 列出和显示
volume qos list
openstack volume qos show
    <qos-spec>

# 设置属性
openstack volume qos set
    [--property <key=value> [...] ]
    <qos-spec>
openstack volume qos unset
    [--property <key> [...] ]
    <qos-spec> 

可以让一组卷同时进行快照，以保证数据一致性

# 将卷加入/移除一致性组
openstack consistency group add volume
    <consistency-group>
    <volume> [<volume> ...]
openstack consistency group remove volume
    <consistency-group>
    <volume> [<volume> ...]


# 创建一致性组
openstack consistency group create
    --volume-type <volume-type> | --consistency-group-source <consistency-group> | --consistency-group-snapshot <consistency-group-snapshot>
    [--description <description>]
    [--availability-zone <availability-zone>]
    [<name>]

# 删除一致性组
openstack consistency group delete
    # 即使出错也强制删除
    [--force]
    <consistency-group> [<consistency-group> ...]



openstack consistency group list
    [--all-projects]
    [--long]
openstack consistency group set
    [--name <name>]
    [--description <description>]
    <consistency-group>
openstack consistency group show
    <consistency-group>

定义Object Storage V1中的一个命名空间。

管理对象存储中的对象。

# 上传对象到container
openstack object create
    [--sort-column SORT_COLUMN]
    [--name <name>]
    <container>
    <filename>
    [<filename> ...]

# 删除对象
openstack object delete <container> <object> [<object> ...]

# 列出对象
openstack object list
    [--sort-column SORT_COLUMN]
    [--delimiter <delimiter>]
    [--marker <marker>]
    [--end-marker <end-marker>]
    [--limit <num-objects>]
    [--long]
    [--all]
    <container>

# 下载对象到本地
openstack object save [--file <filename>] <container> <object>

# 设置对象属性
openstack object set --property <key =value> <container> <object>
openstack object unset --property <key> <container> <object>

# 显示对象信息
openstack object show <container> <object>

账户是container - objects树结构的最根部。

openstack object store account set --property <key =value>
openstack object store account unset --property <key>

openstack object store account show 

很多功能和openstack命令重复，建议使用openstack命令，仅仅在使用某些高级特性时，才需要底层的nova命令。

OS_USERNAME
OS_PASSWORD
OS_PROJECT_NAME
OS_PROJECT_ID
OS_PROJECT_DOMAIN_NAME
OS_PROJECT_DOMAIN_ID
OS_USER_DOMAIN_NAME
OS_USER_DOMAIN_ID
# Keystone端点URL
OS_AUTH_URL
OS_COMPUTE_API_VERSION
OS_REGION_NAME
# 逗号分隔的，受信任的镜像证书ID
OS_TRUSTED_IMAGE_CERTIFICATE_IDS

为虚拟机添加安全组

列出指定虚拟机的安全组

将虚拟机从安全组移除

创建agent build， 类似的agent-delete、agent-list、agent-modify命令完成相关CRUD操作

管理服务器聚合， 类似的aggregate-delete、aggregate-list、aggregate-update、aggregate-show命令完成相关CRUD操作

添加虚拟机到聚合中。类似的aggregate-remove-host用于移除虚拟机

缓存镜像到聚合的所有虚拟机中

更新和聚合关联的元数据

创建（基于策略的）虚拟机分组。 类似的server-group-delete、server-group-list、server-group-get命令完成相关CRUD操作

列出可用区

列出虚拟机

修改虚拟机的名字或描述

显示单个虚拟机的详细信息

SSH到虚拟机

启动虚拟机

停止虚拟机

通过创建backup类型的快照，来备份一个虚拟机

启动一个新的虚拟机

从元数据服务器上清除某个虚拟机的管理密码，不会改变实例的密码

获取虚拟机的管理密码，调用元数据服务器，而不是虚拟机自身

设置虚拟机密码

获取虚拟机控制台日志

重置虚拟机状态

锁定虚拟机，非管理员将无法对虚拟机进行操作

解锁虚拟机

在内存中暂停虚拟机

解除内存中暂停的虚拟机

暂停虚拟机到磁盘

恢复暂停到磁盘的虚拟机

重启虚拟机

重启虚拟机进入救援模式 —— 从虚拟机的初始镜像或另外一个特定镜像启动虚拟机，将当前book disk挂载为非boot disk

重启虚拟机，进入正常模式

触发虚拟机crash dump

立即关机，同时删除实例

恢复一个软删除的实例

强制删除一个虚拟机

重建（关机、re-image、启动）虚拟机

保存虚拟机为镜像

将镜像化的虚拟机恢复

将shelved的虚拟机从宿主机上删除

设置/删除虚拟机的元数据

获取虚拟机诊断信息

重建失败宿主机上的某个虚拟机

迁移虚拟机

修改虚拟机规格，即flavor

确认修改规格操作

撤销尚未确认的resize操作，虚拟机恢复原状

对指定的虚拟机进行在线迁移

中止正在进行的在线迁移。需要Nova API版本2.24+

强制结束正在进行的在线迁移

显示某次虚拟机迁移的详细信息

列出指定虚拟机的迁移

列出所有迁移

添加一个或多个tag到虚拟机，类似的server-tag-delete、server-tag-delete-all、server-tag-list、server-tag-set完成相应CRUD操作

为某个租户增加某个flavor的权限。类似的flavor-access-remove移除某个租户访问某个flavor的权限

查看某个flavor的访问权限列表

创建一个flavor。类似的 flavor-delete、flavor-list、flavor-update、flavor-show命令完成相关CRUD操作。

为某个flavor设置或清除extra_spec。

达到虚拟机的RDP控制台

得到寻机的串口控制台

得到虚拟机的Spice控制台

得到虚拟机的VNC控制台

重建失败宿主机上的所有实例

对指定宿主机上所有虚拟机执行在线迁移操作

对指定宿主机上所有虚拟机执行迁移操作

设置/删除宿主机上所有的虚拟机的元数据

列出可用的Hypervisor

列出基于指定Hypervisor的虚拟机

查看Hypervisor的详细信息

显示所有Hypervisor的总和统计信息

显示指定Hypervisor的已启动时间

通过获取虚拟机快照，来创建新的镜像

列出针对指定虚拟机的操作历史

为虚拟机添加一个网络接口（Port）

列出连接到虚拟机的Port

刷新虚拟机的网络信息

重置虚拟机的网络

添加一个卷给虚拟机

将某个卷从虚拟机移除

列出所有添加到虚拟机的卷

将指定的、已经添加到虚拟机的卷的数据，拷贝到另外一个可用（没有被其它虚拟机使用）的卷上，然后将当前挂载的卷换成新的（接收数据拷贝的哪个）

添加访问虚拟机的密钥。类似的 keypair-delete、keypair-list、keypair-show命令完成相关CRUD操作。

显示一个quota class的配额信息

更新quota class的配额值

列出租户的默认配额

为一个用户/租户删除配额，配额值恢复为默认

显示指定用户/租户的配额

为指定用户/租户更新配额

显示单个租户的用量信息

列出所有租户的用量信息

列出所有API 版本

删除服务

禁用服务

启用服务

强制停止服务

列出运行中的服务

用于bash自动补全。脚本文件位于：/etc/bash_completion.d/nova，可以直接拷贝到其它机器使用

列出针对某个用户的，存储（总计、备份、快照、卷等）用量的硬限制

创建一个卷的备份

删除一个卷备份

导出备份元数据

导入备份元数据

列出所有备份

显式的更新备份状态

从一个备份恢复

显示备份详细信息

更新一个备份

创建一个卷

删除一个或多个卷

尝试扩展一个卷的尺寸

进行故障转移，要求卷是replicated

强制删除卷，不管其状态如何

冻结并且禁用指定的卷主机

显示卷的后端的统计信息、属性

显示卷的池信息：

cinder get-pools 

+----------+---------------------+
| Property | Value               |
+----------+---------------------+
| name     | openstack-3@lvm#LVM |
+----------+---------------------+
+----------+---------------------+
| Property | Value               |
+----------+---------------------+
| name     | openstack-4@lvm#LVM |
+----------+---------------------+
+----------+---------------------+
| Property | Value               |
+----------+---------------------+
| name     | openstack-2@lvm#LVM |
+----------+---------------------+
+----------+---------------------+
| Property | Value               |
+----------+---------------------+
| name     | openstack-2@nfs#nfs |
+----------+---------------------+

 每个主机上的lvm后端，独立作为一个池。但是在各主机上都配置了的、指向同一NFS export的，只显示了一个池

列出所有卷

将卷迁移到一个新的主机上

为指定的卷类型设置QoS规格

创建一个QoS规格

删除一个QoS规格

解除一个QoS规格和一个卷类型的关联

解除一个QoS规格的所有关联

列出QoS规格的关联

设置/删除QoS规格的某个属性

列出所有的QoS规格

列出一个配额类（quota class）的所有配额属性

更新配额类的属性

列出租户的默认配额

为一个租户删除配额

显示某个租户的当前配额

更新一个租户的配额

列出一个租户的配额使用情况

列出一个租户的速率限制

重命名卷

在Cinder数据库中显式的重置卷的状态

修改卷的类型

将某个卷回退到某个快照

禁用一个卷服务：

cinder service-disable  openstack-4@nfs  cinder-volume

要删除卷服务，需要：

cinder-manage service remove  cinder-volume openstack-4@nfs 

创建卷快照

删除卷快照

列出卷快照

管理卷快照

设置或删除快照元数据

查看快照元数据

重命名快照

显式的重置快照状态

显示卷快照的信息

停止管理卷快照

接受一个卷转移（volume transfer）

创建一个卷转移

撤销一个卷转移

列出所有卷转移

显示卷转移的信息

授予指定项目（租户）访问某个卷类型的权限

列出卷类型的访问权限

移除卷类型的访问权限

配置好一个卷后端后，需要使用该命令，创建对应的卷类型，并且将类型关联到后端：

cinder type-create nfs-fast
cinder type-key nfs-fast set volume_backend_name=nfs-fast

cinder type-create nfs-slow
cinder type-key nfs-slow set volume_backend_name=nfs-slow

显示默认使用的卷类型：

cinder type-default
+--------------------------------------+-------------+---------------------+-----------+
| ID                                   | Name        | Description         | Is_Public |
+--------------------------------------+-------------+---------------------+-----------+
| 464dc192-cc63-4aab-8466-6d4f41cd0fb4 | __DEFAULT__ | Default Volume Type | True      |
+--------------------------------------+-------------+---------------------+-----------+

通过type-update修改默认卷类型的名字，会导致出错。你必须同步修改控制节点的cinder.conf：

default_volume_type = lvm

删除卷类型

设置/删除卷类型的额外规格（extra_spec）

列出所有卷类型

显示一个卷类型的详细信息

根据ID来更新一个卷类型的名字、描述、是否公开：

cinder type-update --name __DEFAULT__ 464dc192-cc63-4aab-8466-6d4f41cd0fb4

停止管理卷

将卷上传到镜像服务，作为镜像使用

本章按照官网的样例架构，搭建最小化的OpenStack集群。此集群和生产环境架构的不同之处是：

1. 网络代理（networking agents）部署在控制器节点上，而非专用的网络节点
2. 自服务网络（self-service networks）的隧道（Overlay）流量，通过管理网络（management network）而非专用网络传递

此集群包含如下角色的节点：

1. Controller：要求2张NIC
   1. 部署Identity Service、Image Service、计算服务的管理部分、网络服务的管理部分、Web仪表盘，以及多种网络代理
   2. 部署支持性服务，包括SQL数据库、消息代理、NTP
   3. 可选的，部署块存储服务、对象存储服务、编排服务、遥测服务的部分组件
2. Compute：要求2张NIC
   1. 部署计算服务的Hypervisor部分，能够操控Instance。默认Hypervisor是KVM
   2. 部署一个网络代理，用于将Instance连接到虚拟网络，并通过安全组为Instance提供防火墙服务
3. Block Storage：可选的，为Instance提供块存储、共享文件系统服务。在本示例环境中，计算节点和块存储节点之间的流量通过管理网络传输，生产环境下应该有独立的存储网络
4. Object Storage：可选的，用于对象存储的服务

推荐使用两套物理网络：

1. 管理网络（management network，10.1.0.0/16）：通过NAT连接到互联网。绝大部分情况下，节点需要连接到外网（例如安装软件包）时，都应该通过管理网
2. 提供者网络（provider network，10.0.0.0/16）：这是虚拟机的工作负载流量所使用的网络，在：
   1. 网络选项一（提供者网络）下，虚拟机直接连接到此网络
   2. 网络选项二（自服务网络）下，虚拟机连接到自服务网络，然后NAT到此网络以获得外部连接

此集群可以选用两种虚拟网络之一。

Provider networks，也就是外部网络。以最简单的方式部署OpenStack网络服务，通常基于L2（桥接/交换）服务和网络VLAN分段实现。这种选项将虚拟网络桥接到物理网络，依赖于物理网络基础设施完成L3服务。

此外，一个DHCP服务用于为Instance提供IP地址。

这种选项不支持一些高级特性，例如LBaaS、FWaaS。

所谓自服务，是指非特权账户在不需要管理员介入的情况下，管理虚拟化基础设施 —— 例如网络的能力。

这种选项通过提供L3（路由）服务来增强提供者网络，使用的是类似VXLAN之类的overlay segmentation技术。虚拟网络到物理网络的路由通过NAT实现。

OpenStack用户可以在不了解数据网络（data network）底层基础设施的情况下，创建虚拟网络。包括VLAN网络（如果L2插件被相应的配置）。 

安装软件：

sudo -H pip install python-openstackclient  --ignore-installed PyYAML
# placement插件
sudo -H pip install osc-placement

# 修复错误，将下面两个文件开头的import queue 改为 import Queue as queue
sudo vim /usr/local/lib/python2.7/dist-packages/openstack/utils.py
sudo vim /usr/local/lib/python2.7/dist-packages/openstack/cloud/openstackcloud.py

配置Shell自动完成： 

openstack complete | sudo tee /etc/bash_completion.d/osc.bash_completion > /dev/null

OpenStack由一系列独立安装的、相互协作的组件构成。

dnf -y install centos-release-openstack-ussuri
yum config-manager --set-enabled powertools
dnf install https://dl.fedoraproject.org/pub/epel/epel-release-latest-8.noarch.rpm
dnf -y upgrade

dnf -y install telnet htop bridge-utils xterm

略，参考Ubuntu的时钟同步

Keystone为OpenStack提供身份（Identity）服务。Keystone可以提供四种Token（代表请求者身份），样例环境使用Fernet Token，同时基于Apache HTTP Server来处理请求。

首先，你需要安装一个数据库： 

# 安装mariadb模块
dnf -y install mariadb mariadb-server python2-PyMySQL

创建并修改配置文件：

[mysqld]
bind-address = 10.1.0.10

default-storage-engine = innodb
innodb_file_per_table = on
max_connections = 4096
collation-server = utf8_general_ci
character-set-server = utf8

启用服务：

systemctl enable mariadb.service
systemctl start mariadb.service

启用安全配置：

mysql_secure_installation 

安装RabbitMQ：

dnf -y install rabbitmq-server

systemctl enable rabbitmq-server.service
systemctl start rabbitmq-server.service

创建一个RabbitMQ用户：

rabbitmqctl add_user openstack openstack

为用户openstack授予配置、读写权限：

rabbitmqctl set_permissions openstack ".*" ".*" ".*"

Identity Service使用Memcached来缓存Tokens。

安装软件：

dnf -y install memcached python3-memcached

 修改配置：

OPTIONS="-l 0.0.0.0"

启动服务：

systemctl enable memcached.service
systemctl start memcached.service

OpenStack组件可能需要使用Etcd来实现分布式键锁定、配置存储、跟踪服务是否存活。

安装软件：

dnf -y install etcd

修改配置文件：

#[Member]
ETCD_DATA_DIR="/var/lib/etcd/default.etcd"
ETCD_LISTEN_PEER_URLS="http://10.1.0.10:2380"
ETCD_LISTEN_CLIENT_URLS="http://10.1.0.10:2379"
ETCD_NAME="openstack"
#[Clustering]
ETCD_INITIAL_ADVERTISE_PEER_URLS="http://10.1.0.10:2380"
ETCD_ADVERTISE_CLIENT_URLS="http://10.1.0.10:2379"
ETCD_INITIAL_CLUSTER="openstack=http://10.1.0.10:2380"
ETCD_INITIAL_CLUSTER_TOKEN="etcd-cluster-01"
ETCD_INITIAL_CLUSTER_STATE="new"

启动服务：

systemctl enable etcd
systemctl start etcd

为Keystone创建数据库和用户：

CREATE DATABASE IF NOT EXISTS keystone;

GRANT ALL PRIVILEGES ON keystone.* TO 'keystone'@'localhost' IDENTIFIED BY 'keystone';

GRANT ALL PRIVILEGES ON keystone.* TO 'keystone'@'%' IDENTIFIED BY 'keystone';

然后，安装以下包： 

dnf -y install openstack-keystone httpd
dnf -y install python3-mod_wsgi

编辑Keystone配置文件：

[database]
# ...
connection = mysql+pymysql://keystone:keystone@os.gmem.cc/keystone


[token]
provider = fernet

初始化数据库：

su -s /bin/sh -c "keystone-manage db_sync" keystone

初始化Fernet密钥存储库：

#                            运行keystone的操作系统用户和组
keystone-manage fernet_setup --keystone-user keystone --keystone-group keystone
keystone-manage credential_setup --keystone-user keystone --keystone-group keystone

启动Identity服务：

keystone-manage bootstrap --bootstrap-password keystone \
  --bootstrap-admin-url http://os.gmem.cc:5000/v3/ \
  --bootstrap-internal-url http://os.gmem.cc:5000/v3/ \
  --bootstrap-public-url http://os.gmem.cc:5000/v3/ \
  --bootstrap-region-id china

编辑Apache配置文件： 

ServerName os.gmem.cc

将Keystone的配置文件链接到Apache配置目录：

ln -s /usr/share/keystone/wsgi-keystone.conf /etc/httpd/conf.d/

启动Apache服务：

systemctl enable httpd.service
systemctl start httpd.service

为了后续使用OpenStack工具时进行身份验证，你需要设置环境变量（密码来自上面的 keystone-manage bootstrap 步骤）：

export OS_USERNAME=admin
export OS_PASSWORD=keystone
export OS_PROJECT_NAME=admin
export OS_USER_DOMAIN_NAME=Default
export OS_PROJECT_DOMAIN_NAME=Default
export OS_AUTH_URL=http://os.gmem.cc:5000/v3
export OS_IDENTITY_API_VERSION=3 

现在，我们需要需要创建一些OpenStack对象：

# 创建一个域
# openstack domain create --description "An Example Domain" example

# 创建一个项目
# 示例环境为每个服务创建一个用户，这些用户在此项目中获得授权
openstack project create --domain default --description "Service Project" service


# 常规操作（非管理）应该使用非特权的项目和用户进行
openstack project create --domain default --description "Gmem Project" gmem
openstack user create --domain default --password gmem gmem
openstack role create gmem
openstack role add --project gmem --user gmem gmem 

Glance为OpenStack提供（虚拟机）镜像服务，Glance支持多种后端存储，本样例环境下我们直接存放在文件系统中。

首先，需要为Glance创建数据库：

CREATE DATABASE IF NOT EXISTS glance;

GRANT ALL PRIVILEGES ON glance.* TO 'glance'@'localhost' IDENTIFIED BY 'glance';
GRANT ALL PRIVILEGES ON glance.* TO 'glance'@'%' IDENTIFIED BY 'glance';

使用OpenStack命令行来创建Glance的凭证信息，注意需要进行上述环境变量设置： 

openstack user create --domain default --password glance glance

为service项目中的glance用户添加admin角色：

openstack role add --project service --user glance admin

创建Glance服务： 

# 服务的类型
openstack service create --name glance --description "OpenStack Image" image

为Glance服务添加一个端点：

openstack endpoint create --region china image public http://os.gmem.cc:9292

下面，需要安装和配置Glance组件。安装软件包：

dnf -y install openstack-glance

修改配置文件：

[database]
connection = mysql+pymysql://glance:glance@os.gmem.cc/glance


[keystone_authtoken]
www_authenticate_uri  = http://os.gmem.cc:5000
auth_url = http://os.gmem.cc:5000
memcached_servers = os.gmem.cc:11211
auth_type = password
project_domain_name = Default
user_domain_name = Default
project_name = service
username = glance
password = glance


[paste_deploy]
flavor = keystone


[glance_store]
stores = file,http
default_store = file
filesystem_store_datadir = /var/lib/glance/images/

初始化Glance数据库：

su -s /bin/sh -c "glance-manage db_sync" glance

启动服务：

systemctl enable openstack-glance-api.service
systemctl start openstack-glance-api.service

为了测试OpenStack，建议使用CirrOS镜像。

wget http://download.cirros-cloud.net/0.4.0/cirros-0.4.0-x86_64-disk.img

openstack image create --public --disk-format qcow2 --container-format bare \
  --file cirros-0.4.0-x86_64-disk.img cirros-0.4.0-amd64 

在Stein版本之前，placement 的代码在Nova中，服务在compute REST API（nova-api）中。

Placement提供了WSGI脚本placement-api，可以在Apache/Nginx之类的WSGI-capable服务器中使用。取决于你的安装方式，该脚本可能位于/usr/bin或/usr/local/bin下面。

为Placement创建数据库：

CREATE DATABASE IF NOT EXISTS placement;
GRANT ALL PRIVILEGES ON placement.* TO 'placement'@'localhost' IDENTIFIED BY 'placement';
GRANT ALL PRIVILEGES ON placement.* TO 'placement'@'%' IDENTIFIED BY 'placement';

创建用户和端点：

openstack user create --domain default --password placement placement

openstack role add --project service --user placement admin

openstack service create --name placement --description "Placement API" placement

openstack endpoint create --region china placement public  http://os.gmem.cc:8778
openstack endpoint create --region china placement internal http://os.gmem.cc:8778
openstack endpoint create --region china placement admin http://os.gmem.cc:8778

安装和配置Placement组件：

dnf -y install openstack-placement-api

修改配置文件：

[placement_database]
connection = mysql+pymysql://placement:placement@os.gmem.cc/placement


[api]
auth_strategy = keystone


[keystone_authtoken]
auth_url = http://os.gmem.cc:5000/v3
memcached_servers = os.gmem.cc:11211
auth_type = password
project_domain_name = Default
user_domain_name = Default
project_name = service
username = placement
password = placement

初始化数据库：

su -s /bin/sh -c "placement-manage db sync" placement

修改Apache配置文件（否则可能计算节点nova报 You don't have permission to access this resource）：

<Directory /usr/bin>
  Require all granted
</Directory>

重启Apache服务：

systemctl restart httpd

创建数据库：

CREATE DATABASE IF NOT EXISTS nova_api;
CREATE DATABASE IF NOT EXISTS nova;
CREATE DATABASE IF NOT EXISTS nova_cell0;

GRANT ALL PRIVILEGES ON nova_api.* TO 'nova'@'localhost' IDENTIFIED BY 'nova';
GRANT ALL PRIVILEGES ON nova_api.* TO 'nova'@'%' IDENTIFIED BY 'nova';

GRANT ALL PRIVILEGES ON nova.* TO 'nova'@'localhost' IDENTIFIED BY 'nova';
GRANT ALL PRIVILEGES ON nova.* TO 'nova'@'%' IDENTIFIED BY 'nova';

GRANT ALL PRIVILEGES ON nova_cell0.* TO 'nova'@'localhost' IDENTIFIED BY 'nova';
GRANT ALL PRIVILEGES ON nova_cell0.* TO 'nova'@'%' IDENTIFIED BY 'nova';

创建用户和端点：

openstack user create --domain default --password nova nova
openstack role add --project service --user nova admin
openstack service create --name nova  --description "OpenStack Compute" compute

openstack endpoint create --region china compute public   http://os.gmem.cc:8774/v2.1
openstack endpoint create --region china compute internal http://os.gmem.cc:8774/v2.1
openstack endpoint create --region china compute admin    http://os.gmem.cc:8774/v2.1

安装组件：

dnf -y install openstack-nova-api openstack-nova-conductor openstack-nova-novncproxy openstack-nova-scheduler

修改配置文件： 

[DEFAULT]
enabled_apis = osapi_compute,metadata
transport_url = rabbit://openstack:openstack@os.gmem.cc:5672/
; 管理网络的IP地址
my_ip = 10.1.0.10

[api_database]
connection = mysql+pymysql://nova:nova@os.gmem.cc/nova_api

[database]
connection = mysql+pymysql://nova:nova@os.gmem.cc/nova

[api]
auth_strategy = keystone

[keystone_authtoken]
www_authenticate_uri = http://os.gmem.cc:5000/
auth_url = http://os.gmem.cc:5000/
memcached_servers = os.gmem.cc:11211
auth_type = password
project_domain_name = Default
user_domain_name = Default
project_name = service
username = nova
password = nova

[vnc]
enabled = true
server_listen = $my_ip
server_proxyclient_address = $my_ip

[glance]
api_servers = http://os.gmem.cc:9292

[oslo_concurrency]
lock_path = /var/lib/nova/tmp

[placement]
region_name = china
project_domain_name = Default
project_name = service
auth_type = password
user_domain_name = Default
auth_url = http://os.gmem.cc:5000/v3
username = placement
password = placement

[neutron]
; 参考：安装Neutron

[cinder]
; 参考：安装Cinder

初始化数据库：

su -s /bin/sh -c "nova-manage api_db sync" nova

su -s /bin/sh -c "nova-manage cell_v2 map_cell0" nova

su -s /bin/sh -c "nova-manage cell_v2 create_cell --name=cell1 --verbose" nova

su -s /bin/sh -c "nova-manage db sync" nova

校验一下，确保cell0和cell1正确的注册了： 

su -s /bin/sh -c "nova-manage cell_v2 list_cells" nova

启动服务：

systemctl enable \
    openstack-nova-api.service \
    openstack-nova-scheduler.service \
    openstack-nova-conductor.service \
    openstack-nova-novncproxy.service

systemctl start \
    openstack-nova-api.service \
    openstack-nova-scheduler.service \
    openstack-nova-conductor.service \
    openstack-nova-novncproxy.service

安装软件：

dnf -y install openstack-nova-compute

修改配置文件：

[DEFAULT]
enabled_apis = osapi_compute,metadata
; 替换为该计算节点上，管理网络的IP
my_ip = 10.1.0.10

[DEFAULT]
transport_url = rabbit://openstack:openstack@os.gmem.cc

[api]
auth_strategy = keystone

[keystone_authtoken]
www_authenticate_uri = http://os.gmem.cc:5000/
auth_url = http://os.gmem.cc:5000/
memcached_servers = os.gmem.cc:11211
auth_type = password
project_domain_name = Default
user_domain_name = Default
project_name = service
username = nova
password = nova

[vnc]
enabled = true
server_listen = 0.0.0.0
server_proxyclient_address = $my_ip
novncproxy_base_url = http://os.gmem.cc:6080/vnc_auto.html

[glance]
api_servers = http://os.gmem.cc:9292

[oslo_concurrency]
lock_path = /var/lib/nova/tmp

[placement]
region_name = china
project_domain_name = Default
project_name = service
auth_type = password
user_domain_name = Default
auth_url = http://os.gmem.cc:5000/v3
username = placement
password = placement

[libvirt]
virt_type = kvm

[neutron]
; 参考：安装Neutron

[cinder]
; 参考：安装Cinder

启动服务：

systemctl enable libvirtd.service openstack-nova-compute.service
systemctl start libvirtd.service openstack-nova-compute.service

如果nova-compute启动失败，检查日志： /var/log/nova/nova-compute.log。

最后，将该节点加入到cell数据库中：

# 检查计算服务列表
openstack compute service list --service nova-compute

# 发现计算服务主机
# 需要在控制节点上执行
su -s /bin/sh -c "nova-manage cell_v2 discover_hosts --verbose" nova

# 如果希望自动发现新的主机，可以配置控制节点的/etc/nova/nova.conf：
# [scheduler]
# discover_hosts_in_cells_interval = 300

创建数据库：

CREATE DATABASE IF NOT EXISTS neutron;

GRANT ALL PRIVILEGES ON neutron.* TO 'neutron'@'localhost'  IDENTIFIED BY 'neutron';
GRANT ALL PRIVILEGES ON neutron.* TO 'neutron'@'%' IDENTIFIED BY 'neutron';

创建用户和端点：

openstack user create --domain default --password neutron neutron

openstack role add --project service --user neutron admin

openstack service create --name neutron --description "OpenStack Networking" network

openstack endpoint create --region china network public   http://os.gmem.cc:9696
openstack endpoint create --region china network internal http://os.gmem.cc:9696
openstack endpoint create --region china network admin    http://os.gmem.cc:9696

如果使用提供者网络，也就是直接将VM添加到外部网络，不提供自服务网络（以及路由器、浮动IP等），则需要使用admin或其它特权账户。步骤如下：

1. 安装软件：
   

   dnf -y install openstack-neutron openstack-neutron-ml2 openstack-neutron-linuxbridge ebtables 

2. 配置Neutron：
   

   [database]
   connection = mysql+pymysql://neutron:neutron@os.gmem.cc/neutron
   
   [DEFAULT]
   core_plugin = ml2
   service_plugins =
   
   transport_url = rabbit://openstack:openstack@os.gmem.cc
   
   auth_strategy = keystone
   
   notify_nova_on_port_status_changes = true
   notify_nova_on_port_data_changes = true
   
   [keystone_authtoken]
   www_authenticate_uri = http://os.gmem.cc:5000
   auth_url = http://os.gmem.cc:5000
   memcached_servers = os.gmem.cc:11211
   auth_type = password
   project_domain_name = default
   user_domain_name = default
   project_name = service
   username = neutron
   password = neutron
   
   [nova]
   auth_url = http://os.gmem.cc:5000
   auth_type = password
   project_domain_name = default
   user_domain_name = default
   region_name = china
   project_name = service
   username = nova
   password = nova
   
   [oslo_concurrency]
   lock_path = /var/lib/neutron/tmp

3. 配置Modular Layer2（ML2）插件。此插件使用Linux bridge来为虚拟机构建L2 VNI：

   [ml2]
   ; 启用Flat/VLAN网络
   type_drivers = flat,vlan
   ; 禁用自服务网络
   tenant_network_types =
   ; 启用 Linux bridge mechanism 
   mechanism_drivers = linuxbridge
   ; 启用端口安全扩展驱动
   extension_drivers = port_security
   
   [ml2_type_flat]
   ; 配置提供者虚拟网络为Flat网络
   flat_networks = provider
   
   [securitygroup]
   ; 增强安全组规则的性能
   enable_ipset = true 

4.  配置Linux Bridge agent，此Agent为VM构建L2 VNI，并处理安全组：

   [linux_bridge]
   ; 这里填写底层的提供者网络的设备名
   physical_interface_mappings = provider:eth0
   
   [vxlan]
   ; 禁用VXLAN
   enable_vxlan = false
   
   [securitygroup]
   ; 启用安全组，配置基于iptables的防火墙驱动
   enable_security_group = true
   firewall_driver = neutron.agent.linux.iptables_firewall.IptablesFirewallDriver

5. 确保宿主机内核支持Network bridge filters：

   # 二层的网桥在转发包时也会被iptables的FORWARD规则所过滤
   net.bridge.bridge-nf-call-iptables  1
   net.bridge.bridge-nf-call-ip6tables 1

   此外，为了支持网桥，需要加载内核模块

   br_netfilter

6.  配置DHCP代理，此代理为虚拟网络提供DHCP服务：

   [DEFAULT]
   interface_driver = linuxbridge
   dhcp_driver = neutron.agent.linux.dhcp.Dnsmasq
   enable_isolated_metadata = true

如果使用自服务网络，不需要特权用户就可以管理网络（包括路由）并在自服务网络和提供者网络之间创建连接，也可以为VM提供浮动IP，以便从外部访问VM。步骤如下：

1. 安装软件，同上
2. 配置Neutron，基本同上：
   

   [database]
   connection = mysql+pymysql://neutron:neutron@os.gmem.cc/neutron
   
   [DEFAULT]
   ; 同样使用ML2插件
   core_plugin = ml2
   ; 启用路由服务，允许IP重叠
   service_plugins = router
   allow_overlapping_ips = true
   
   transport_url = rabbit://openstack:openstack@os.gmem.cc
   
   auth_strategy = keystone
   
   notify_nova_on_port_status_changes = true
   notify_nova_on_port_data_changes = true
   
   [keystone_authtoken]
   www_authenticate_uri = http://os.gmem.cc:5000
   auth_url = http://os.gmem.cc:5000
   memcached_servers = os.gmem.cc:11211
   auth_type = password
   project_domain_name = default
   user_domain_name = default
   project_name = service
   username = neutron
   password = neutron
   
   [nova]
   auth_url = http://os.gmem.cc:5000
   auth_type = password
   project_domain_name = default
   user_domain_name = default
   region_name = china
   project_name = service
   username = nova
   password = nova
   
   [oslo_concurrency]
   lock_path = /var/lib/neutron/tmp

3.  配置Modular Layer2（ML2）插件：

   [ml2]
   ; 启用Flat/VLAN/VXLAN
   type_drivers = flat,vlan,vxlan
   ; 启用自服务网络，基于VXLAN
   tenant_network_types = vxlan
   ; 启用Linux网桥，以及Layer-2 Population
   mechanism_drivers = linuxbridge,l2population
   ; 启用端口安全扩展驱动
   extension_drivers = port_security
   
   [ml2_type_flat]
   ; 配置提供者虚拟网络为Flat网络
   flat_networks = provider
   
   [ml2_type_vxlan]
   ; 设置VXLAN网络标识符的范围
   vni_ranges = 1:1000
   
   [securitygroup]
   ; 增强安全组规则的性能
   enable_ipset = true

4. 配置Linux Bridge agent：
   

   [linux_bridge]
   ; 这里填写底层的提供者网络的设备名
   physical_interface_mappings = provider:eth0
   
   [vxlan]
   ; 启用VXLAN
   enable_vxlan = true
   ; 用于处理Overlay网络的底层网络的本机IP地址
   local_ip = 10.1.0.10
   l2_population = true
   
   [securitygroup]
   ; 启用安全组，配置基于iptables的防火墙驱动
   enable_security_group = true
   firewall_driver = neutron.agent.linux.iptables_firewall.IptablesFirewallDriver 

5. 确保宿主机内核支持Network bridge filters，同上

6.  配置DHCP，同上

7. 配置L3代理，此代理为自服务VNI提供路由、NAT：
   

   [DEFAULT]
   interface_driver = linuxbridge

自服务网络是overlay网络，使用VXLAN之类的协议，这些协议具有额外的头，导致实际可能负载减小，如果VM不知道此VNI的特征，会自动设置过大的MTU 1500。Neutron提供的DHCP能自动给VM提供正确的MTU。但是，某些云镜像不使用DHCP，或者忽略DHCP的MTU选项，需要注意。

执行完上述两种网络选项之一后，继续配置元数据代理（metadata agent） ，元数据代理代替虚拟机（附加Instance ID、Tenant ID等请求头）访问Nova metadata API，获取虚拟机镜像的配置信息：

[DEFAULT]
nova_metadata_host = os.gmem.cc
; 设置适当的共享密钥
metadata_proxy_shared_secret = openstack

 配置计算服务（Nova）来使用网络服务：

[neutron]
auth_url = http://os.gmem.cc:5000
auth_type = password
project_domain_name = default
user_domain_name = default
region_name = china
project_name = service
username = neutron
password = neutron
service_metadata_proxy = true
metadata_proxy_shared_secret = openstack

将ML2配置链接为Neutron插件主配置文件：

ln -s /etc/neutron/plugins/ml2/ml2_conf.ini /etc/neutron/plugin.ini

初始化数据库： 

su -s /bin/sh -c "neutron-db-manage --config-file /etc/neutron/neutron.conf \
  --config-file /etc/neutron/plugins/ml2/ml2_conf.ini upgrade head" neutron

重启Nova： 

systemctl restart openstack-nova-api.service

启动Neutron：  

systemctl enable neutron-server.service \
  neutron-linuxbridge-agent.service neutron-dhcp-agent.service \
  neutron-metadata-agent.service
systemctl start neutron-server.service \
  neutron-linuxbridge-agent.service neutron-dhcp-agent.service \
  neutron-metadata-agent.service

如果使用自服务网络选项，还需要启用L3服务： 

systemctl enable neutron-l3-agent.service
systemctl start neutron-l3-agent.service

安装软件： 

dnf -y install openstack-neutron-linuxbridge ebtables ipset

配置身份验证、消息队列： 

[DEFAULT]
transport_url = rabbit://openstack:openstack@os.gmem.cc

auth_strategy = keystone


[keystone_authtoken]
www_authenticate_uri = http://os.gmem.cc:5000
auth_url = http://os.gmem.cc:5000
memcached_servers = os.gmem.cc:11211
auth_type = password
project_domain_name = default
user_domain_name = default
project_name = service
username = neutron
password = neutron

[oslo_concurrency]
lock_path = /var/lib/neutron/tmp

配置网络选项。如果使用提供者网络：

1.  配置Linux bridge Agent：
   

   [linux_bridge]
   physical_interface_mappings = provider:eth0
   
   [vxlan]
   enable_vxlan = false
   
   [securitygroup]
   enable_security_group = true
   firewall_driver = neutron.agent.linux.iptables_firewall.IptablesFirewallDriver

2. 确保内核参数（通常需要保证内核模块br_netfilter已加载 ）：

   net.bridge.bridge-nf-call-iptables 1
   net.bridge.bridge-nf-call-ip6tables 1

如果使用自服务网络：

1.  配置Linux bridge Agent：
   

   [linux_bridge]
   physical_interface_mappings = provider:eth0
   
   [vxlan]
   enable_vxlan = true
   local_ip = 10.1.0.11
   l2_population = true
   
   [securitygroup]
   enable_security_group = true
   firewall_driver = neutron.agent.linux.iptables_firewall.IptablesFirewallDriver

2. 同上 

配置计算服务，让它使用网络服务：

[neutron]
auth_url = http://os.gmem.cc:5000
auth_type = password
project_domain_name = default
user_domain_name = default
region_name = china
project_name = service
username = neutron
password = neutron

重启Nova：

systemctl restart openstack-nova-compute.service

启动Linux bridge Agent：

systemctl enable neutron-linuxbridge-agent.service
systemctl start neutron-linuxbridge-agent.service

列出已加载的扩展列表，确保Neutron相关进程启动：

openstack extension list --network

校验Neutron代理都已经启动： 

openstack network agent list

应该启动的代理包括：

1. 控制节点的元数据代理、DHCP代理、Linux bridge代理
2. 计算节点的Linux bridge代理
3. 如果使用自服务网络，控制节点还有L3代理

样例环境中，使用存储节点上的空白磁盘/dev/sdb ，基于LVM划分初逻辑卷，然后通过iSCSI协议暴露给虚拟机。

CREATE DATABASE IF NOT EXISTS cinder;

GRANT ALL PRIVILEGES ON cinder.* TO 'cinder'@'localhost' IDENTIFIED BY 'cinder';
GRANT ALL PRIVILEGES ON cinder.* TO 'cinder'@'%' IDENTIFIED BY 'cinder';

创建用户和端点：

openstack user create --domain default --password cinder cinder

openstack role add --project service --user cinder admin

openstack service create --name cinderv2 --description "OpenStack Block Storage" volumev2
openstack service create --name cinderv3 --description "OpenStack Block Storage" volumev3

openstack endpoint create --region china volumev2 public http://os.gmem.cc:8776/v2/%\(project_id\)s
openstack endpoint create --region china volumev2 internal http://os.gmem.cc:8776/v2/%\(project_id\)s
openstack endpoint create --region china volumev2 admin http://os.gmem.cc:8776/v2/%\(project_id\)s

openstack endpoint create --region china volumev3 public http://os.gmem.cc:8776/v3/%\(project_id\)s
openstack endpoint create --region china volumev3 internal http://os.gmem.cc:8776/v3/%\(project_id\)s
openstack endpoint create --region china volumev3 admin http://os.gmem.cc:8776/v3/%\(project_id\)s

安装组件：

dnf -y install openstack-cinder

修改配置文件：

[DEFAULT]
transport_url = rabbit://openstack:openstack@os.gmem.cc
auth_strategy = keystone
; 管理网络接口的IP地址
my_ip = 10.1.0.10

[database]
connection = mysql+pymysql://cinder:cinder@os.gmem.cc/cinder

[keystone_authtoken]
www_authenticate_uri = http://os.gmem.cc:5000
auth_url = http://os.gmem.cc:5000
memcached_servers = os.gmem.cc:11211
auth_type = password
project_domain_name = default
user_domain_name = default
project_name = service
username = cinder
password = cinder

[oslo_concurrency]
lock_path = /var/lib/cinder/tmp

初始化数据库：

su -s /bin/sh -c "cinder-manage db sync" cinder

配置Nova来使用存储服务： 

[cinder]
os_region_name = china

重新启动Nova：

systemctl restart openstack-nova-api.service

启动Cinder服务： 

systemctl enable openstack-cinder-api.service openstack-cinder-scheduler.service
systemctl start openstack-cinder-api.service openstack-cinder-scheduler.service

在本样例环境下，需要LVM支持：

yum install lvm2 device-mapper-persistent-data

systemctl enable lvm2-lvmetad.service
systemctl start lvm2-lvmetad.service

在/dev/sdb上创建LVM物理卷，并创建名为cinder-volumes的卷组：

pvcreate /dev/sdb

vgcreate cinder-volumes /dev/sdb

只有虚拟机实例能够访问块设备卷。但是，存储节点的底层OS负责管理卷关联的块设备。默认情况下，LVM卷扫描工具会扫描/dev/目录来寻找包含卷的块设备。如果某个OpenStack项目使用基于LVM的卷，扫描工具会扫描卷并缓存结果，这可能导致很多问题。因此，你必须重新配置LVM，让它仅仅扫描包含cinder-volumes卷组的设备：

devices {
# a表示允许允许使用的卷，r表示拒绝使用的卷     
#                       拒绝所有其它的卷    
filter = [ "a/sdb/", "r/.*/"]

安装组件： 

dnf -y install openstack-cinder targetcli python3-keystone

修改配置文件： 

[DEFAULT]
transport_url = rabbit://openstack:openstack@os.gmem.cc
auth_strategy = keystone
; 此节点启用的存储后端
enabled_backends = lvm
; 配置镜像服务的API地址
glance_api_servers = http://os.gmem.cc:9292
; 管理网络接口的IP地址
my_ip = 10.1.0.11

[database]
connection = mysql+pymysql://cinder:cinder@os.gmem.cc/cinder

[keystone_authtoken]
www_authenticate_uri = http://os.gmem.cc:5000
auth_url = http://os.gmem.cc:5000
memcached_servers = os.gmem.cc:11211
auth_type = password
project_domain_name = default
user_domain_name = default
project_name = service
username = cinder
password = cinder

[oslo_concurrency]
lock_path = /var/lib/cinder/tmp

[lvm]
volume_driver = cinder.volume.drivers.lvm.LVMVolumeDriver
volume_group = cinder-volumes
target_protocol = iscsi
target_helper = lioadm

启动服务：

systemctl enable openstack-cinder-volume.service target.service
systemctl start openstack-cinder-volume.service target.service

OpenStack Dashboard组件，即Horizon，此组件仅仅依赖于Identity。

安装软件：

dnf -y install openstack-dashboard

修改配置文件：

OPENSTACK_HOST = "os.gmem.cc"

WEBROOT = '/dashboard/'

# 允许哪些主机访问仪表盘
ALLOWED_HOSTS = ['os.gmem.cc']


# 配置基于Memcache的分布式会话存储
SESSION_ENGINE = 'django.contrib.sessions.backends.cache'
CACHES = {
    'default': {
         'BACKEND': 'django.core.cache.backends.memcached.MemcachedCache',
         'LOCATION': 'os.gmem.cc:11211',
    }
}

# 启用Identity API v3
OPENSTACK_KEYSTONE_URL = "http://%s/identity/v3" % OPENSTACK_HOST

# 确保Domain支持
OPENSTACK_KEYSTONE_MULTIDOMAIN_SUPPORT = True

# 配置API版本
OPENSTACK_API_VERSIONS = {
    "identity": 3,
    "image": 2,
    "volume": 3,
}

# 默认访问的Domain
OPENSTACK_KEYSTONE_DEFAULT_DOMAIN = "Default"

# 通过仪表盘创建的用户的默认角色
OPENSTACK_KEYSTONE_DEFAULT_ROLE = "user"

# 配置网络
OPENSTACK_NEUTRON_NETWORK = {
    # 如果使用提供者网络，需要禁用router
    'enable_router': False,
    'enable_quotas': False,
    'enable_distributed_router': False,
    'enable_ha_router': False,
    'enable_lb': False,
    'enable_firewall': False,
    'enable_vpn': False,
    'enable_fip_topology_check': False,
}

TIME_ZONE = "Asia/Shanghai"

修改配置文件：

WSGIDaemonProcess dashboard
WSGIProcessGroup dashboard
WSGISocketPrefix run/wsgi

WSGIApplicationGroup %{GLOBAL}

WSGIScriptAlias /dashboard /usr/share/openstack-dashboard/openstack_dashboard/wsgi/django.wsgi
Alias /dashboard/static /usr/share/openstack-dashboard/static

<Directory /usr/share/openstack-dashboard/openstack_dashboard/wsgi>
  Options All
  AllowOverride All
  Require all granted
</Directory>

<Directory /usr/share/openstack-dashboard/static>
  Options All
  AllowOverride All
  Require all granted
</Directory>

重启服务：

systemctl restart httpd.service memcached.service

此后你应该可以通过：http://os.gmem.cc访问仪表盘。

修改horizon主配置文件：

# 添加以下配置
USE_SSL = True
CSRF_COOKIE_SECURE = True
SESSION_COOKIE_SECURE = True
SESSION_COOKIE_HTTPONLY = True

修改Dashboard的httpd配置：

WSGISocketPrefix run/wsgi

<VirtualHost *:443>
  ServerName os.gmem.cc

  SSLEngine On
  SSLCertificateFile /etc/httpd/ssl/os.gmem.cc.crt
  SSLCACertificateFile /etc/httpd/ssl/os.gmem.cc.crt
  SSLCertificateKeyFile /etc/httpd/ssl/os.gmem.cc.key
  SetEnvIf User-Agent ".*MSIE.*" nokeepalive ssl-unclean-shutdown

  Header add Strict-Transport-Security "max-age=15768000"

  WSGIDaemonProcess dashboard
  WSGIProcessGroup dashboard

  WSGIApplicationGroup %{GLOBAL}

  WSGIScriptAlias /dashboard /usr/share/openstack-dashboard/openstack_dashboard/wsgi/django.wsgi
  Alias /dashboard/static /usr/share/openstack-dashboard/static

  <Directory /usr/share/openstack-dashboard/openstack_dashboard/wsgi>
    Options All
    AllowOverride All
    Require all granted
  </Directory>

  <Directory /usr/share/openstack-dashboard/static>
    Options All
    AllowOverride All
    Require all granted
  </Directory>
</VirtualHost>

安装必要的httpd模块：

dnf -y install mod_ssl 

在启动实例之前，你需要创建必要的VNI。如果使用网络选项一，则虚拟机通过Provider（External）网络连接到PNI（基于bridging/switching）。

网络架构如下图：

使用下面的命令在OpenStack中创建一个名为provider的网络：

# share 表示允许所有project使用此虚拟网络
# external 表示网络是外部的，默认值internal
openstack network create  --share --external \
# 此虚拟网络所基于的物理网络
# 此名字对应的物理网络接口在linuxbridge_agent.ini中定义
#   physical_interface_mappings = provider:eth0
  --provider-physical-network provider \
# 此虚拟网络的物理实现机制（physical mechanism）
  --provider-network-type flat \
# 网络的名字
  provider

为上述网络创建一个子网：

openstack subnet create --network provider \
# 子网中，用于分配给虚拟机实例的IP地址范围，此IP地址范围由DHCP agent管理
  --allocation-pool start=10.0.100.1,end=10.0.1.255 \
# DNS服务器地址              底层物理网络的网关地址
  --dns-nameserver 10.0.0.1 --gateway 10.0.0.1 \
# 底层物理网络的CIDR
  --subnet-range 10.0.0.0/16 provider

前面我们提到过两个网络选项，如果使用选项1，则参考上一小节的内容创建虚拟网络。如果使用选项2，则在创建上述provider网络之后，还需要参考本节内容。

网络架构如下：

使用选项2时，需要创建一个自服务（私有）的虚拟网络，并通过NAT连接到物理网络。此虚拟网络提供DHCP服务器，并且分配IP地址给实例。在这种私有网络中的实例可以直接访问外部网络（NAT），但是外部网络不能直接访问这些实例，除非给实例分配浮动IP。

修改环境变量，使用用户gmem来操作。

创建名为gmem的自服务网络：

openstack network create gmem-net

非特权用户通常无法为上述命令指定额外的参数。OpenStack会依据下面的配置文件来自动选择参数：

[ml2]
tenant_network_types = vxlan

[ml2_type_vxlan]
vni_ranges = 1:1000

创建子网： 

openstack subnet create --network gmem-net \
#                           子网的网关地址，不是物理网络上的网关地址
  --dns-nameserver 10.1.0.1 --gateway 192.168.100.1 \
# 子网的CIDR
  --subnet-range 192.168.100.0/24 gmem-subnet

自服务网络通过一个虚拟路由器，连接到提供者网络：

openstack router create gmem-router

将上述子网添加为此虚拟路由器的一个接口（interface）： 

openstack router add subnet gmem-router gmem-subnet

将在提供者网络上的生成一个“网关“，连接到路由器：

openstack router set gmem-router --external-gateway provider

到控制节点上进行校验，确保虚拟网络正常工作：

# 检查网络命名空间，应该至少看到：
#   一个qrouter开头的
#   二个qdhcp开头的
ip netns


# 列出路由器的端口，确定提供者网络上的网关地址
openstack port list --router router


# 确认可以从控制节点，或者物理网络上任何节点来访问上述网关地址  

所谓Flavor就是虚拟机的规格，例如内存多大，CPU几个，磁盘几个，等等。最小的默认Flavor消耗512MB内存，这里我们创建一个仅消耗64MB内存的Flavor：

openstack flavor create --id 0 --vcpus 1 --ram 64 --disk 1 m1.nano

大部分的云镜像支持基于PKI的身份验证，而不是密码。在启动实例之前，我们需要为计算服务创建密钥： 

openstack keypair create --public-key /home/alex/Documents/puTTY/gmem.crt default

openstack keypair list

默认的安全组应用到所有的实例， 此安全组禁止对实例的所有远程访问。对于Linux镜像例如CirrOS，我们至少应该允许ICMP（ping）以及SSH：

openstack security group rule create --proto icmp default

openstack security group rule create --proto tcp --dst-port 22 default

列出可用的基础资源：

openstack flavor list
# +----+---------+-----+------+-----------+-------+-----------+
# | ID | Name    | RAM | Disk | Ephemeral | VCPUs | Is Public |
# +----+---------+-----+------+-----------+-------+-----------+
# | 0  | m1.nano |  64 |    1 |         0 |     1 | True      |
# +----+---------+-----+------+-----------+-------+-----------+

openstack image list
# +--------------------------------------+--------------------+--------+
# | ID                                   | Name               | Status |
# +--------------------------------------+--------------------+--------+
# | 5b337b93-96c6-4803-b0e2-bc0bce0afde9 | cirros-0.5.1-amd64 | active |
# +--------------------------------------+--------------------+--------+

openstack network list
# +--------------------------------------+----------+--------------------------------------+
# | ID                                   | Name     | Subnets                              |
# +--------------------------------------+----------+--------------------------------------+
# | 500cd78a-a05c-4b93-b399-06b26cc108de | provider | 9be1305c-a641-40f0-bd1b-6617e96025e6 |
# +--------------------------------------+----------+--------------------------------------+

openstack security group list
# +--------------------------------------+---------+------------------------+----------------------------------+------+
# | ID                                   | Name    | Description            | Project                          | Tags |
# +--------------------------------------+---------+------------------------+----------------------------------+------+
# | f5b0e967-5903-4b6b-9b9d-8e39a07b52da | default | Default security group | e1c4a3403e1b46cd969e4d626b5cf799 | []   |
# +--------------------------------------+---------+------------------------+----------------------------------+------+

openstack server create --flavor m1.nano --image cirros-0.5.1-amd64 \
  --nic net-id=500cd78a-a05c-4b93-b399-06b26cc108de --security-group default \
  --key-name default cirros-amd64-0

当虚拟机构建完毕后，其状态会从BUILD变为ACTIVE：

openstack server list 

CirrOS的默认用户密码是cirros / gocubsgo，确认可以登陆。

在虚拟机的宿主机上，可以看到OpenStack创建了一个网桥，连接了提供者物理网络和虚拟机（的tap设备）：

brctl show
# bridge name     bridge id               STP enabled     interfaces
# brq1305444e-cf          8000.100000000012       no              eth0
#                                                         tapa87f2880-fc 

Keystone是OpenStack的Identity服务，它负责身份验证、授权，以及一系列其它服务。Keystone可以集成到外部的用户管理系统，例如LDAP。

Keystone通常是用户首先与之交互的服务，随后用户使用他的Identity来访问其它OpenStack服务。OpenStack组件也需要访问Keystone来验证用户声明的Identity是否合法。

用户或者服务，可以利用服务目录来得到其它服务（Openstack组件）的位置，服务目录（Service catalog）也是Keystone提供的服务之一。

每个服务可以提供1-N个端点，每个端点可以是admin/internal（可能仅限于OpenStack所在主机访问）/public（可能允许Internet访问）三种类型之一。在生产环境中，这些不同类型的端点可能出于安全方面的考虑，存放在不同的网络中，供不同类型的用户访问。

代表单个API消费者：

1. 用户就是一个有身份验证信息的API消费实体
2. 用户可以属于多个项目/角色

代表一组User的集合。

代表OpenStack中基本的所有权单元 —— OpenStack中各种计算资源都是归属于某个特定项目的。而Project则是归属于某个Domain的。

租户（Tenant）在OpenStack中，就是项目，其目的就是隔离计算资源。

是Project、User、Role、Group的高层次容器，后面三者仅仅属于唯一一个domain。Keystone默认提供一个名为Defulat的domain。

Keystone由三类组件构成。

中心化的HTTP服务器，对外提供鉴权的RESTful接口

集成在Server里面，用于访问存放在OpenStack外部（例如LDAP或MySQL数据库）的身份信息。

运行在使用Identity service的那些OpenStack组件中，负责拦截针对这些组件的请求，抽取用户凭证信息，发送到上述Server执行鉴权。

这些Modules基于Python Web Server Gateway Interface和OpenStack组件集成。

K版本之后，通常选择Fernet Token。

Nova，即OpenStack Compute组件，负责host和管理云主机，是IaaS系统的核心组成部分。可以管理的云主机类型包括虚拟机、物理机（依赖ironic），并对容器提供有限的支持。

Nova和Keystone交互进行身份验证。Placement负责计算资源的跟踪和选择（作为实例的宿主），Glance提供虚拟机镜像，这些组件配合就能让实例运行起来。

OpenStack自身不提供虚拟化软件，而是通过“驱动”和底层的Hypervisor进行交互。交互工作主要由Nova完成。

Nova由一系列分布式的组件构成，每种组件具有自己的职责。面向用户的是一个REST API。内部组件主要通过RPC消息传递机制通信。

API组件监听到请求后，通常会进行数据库读写操作，可选的，会将RPC消息发送给其它Nova组件，然后将REST响应发给客户端。RPC消息是通过 oslo.messaging 库完成的，这个库是基于消息队列的抽象。

大部分组件可以运行在多台宿主机上，并且其中具有一个manager负责监听RPC消息、执行一些周期性工作。一个主要的例外是nova-compute，此组件和它管理的Hypervisor（除了VMware或Ironic驱动）对应，每个Hypervisor对应一个nova-compute。

Nova具有一个逻辑的、中心化的、被所有组件共享的数据库。为了辅助OpenStack升级，对数据库的访问基于一个对象层，此对象层确保一个升级后的控制平面，仍然能和低版本的nova-compute进行交互。具体实现上，nova-compute通过中心化的nova-conductor间接的访问数据库，后者提供基于RPC的接口。

安装在控制节点上。提供OpenStack Compute API，负责确保一些策略，发起大部分编排活动（例如运行实例）。

安装在控制节点上。处理处理获取实例元数据的请求。

安装在计算节点上。Worker守护进程，负责调用Hypervisor API，在计算节点上创建、终结虚拟机实例。支持的Hypervisor API包括：

1. XenAPI for XenServer/XCP
2. libvirt for KVM or QEMU
3. VMwareAPI for VMware

该组件的大概工作流程是：

1. 从消息队列里接受Action
2. 调用一系列的系统命令，启动虚拟机
3. 在数据库中更新实例状态

从队列中取出虚拟机实例的请求，然后决定将其调度在哪台计算节点上。

协调nova-compute s服务和数据库之间的交互。避免nova-compute直接访问数据库。该模块支持水平扩容，避免将其部署在nova-compute运行的节点。

提供一个代理，用于通过VNC协议连接到运行中的实例。

提供一个代理，用于通过SPICE协议连接到运行中的实例，支持HTML5客户端。

这个服务目前已经独立出去，它负责跟踪资源库存、使用情况。

这是一个中心化的Hub，用于在不同组件之间传递消息。通常使用RabbitMQ。

存储云基础设施的构建时、运行时状态，包括：

1. 可用的实例类型
2. 使用着哦个的实例
3. 可用的网络
4. 项目
5. ……

任何SQLAlchemy支持的RDBMS都可以。

为了支持Nova部署的水平扩展，Nova引入了分片机制，每个分片叫Cell。利用Cell：

1. 可以在单个Region中将计算节点的数量扩容到成千上万。每个Cell具有自己的数据库、消息队列，这是可扩容的关键
2. 实现故障隔离的特性（一个Cell故障，其它Cell还可以正常工作）
3. 作为一种分组机制，可以将类似的硬件放在同一Cell中

Cell V1的特性：

1. 捕获并中继消息给Cell
2. 处理竞态条件
3. 两级调度架构

Cell V1的缺点：

1. 不支持安全组、主机聚合、可用区等特性
2. 顶级调度功能很弱

当Nova API接收到针对实例的前请求后，实例的信息将从数据库读取，其中包含实例的宿主机名字。如果需要针对实例进行其它操作（通常都需要），那么宿主机名字将用来计算出消息队列的名字，RPC消息随后被写入消息队列，可以到达正确的计算节点。

引入Cell后，上述逻辑将变成：

1. 查找实例的三元组：宿主机名称、数据库连接信息、消息队列连接信息
2. 连接到数据库，获取实例记录
3. 连接到消息队列，并根据宿主机名称，选额消息队列，发送RPC消息

引入Cell V2后，不存在没有Cell的部署架构。Cell V2的优势包括：

1. 数据库、消息队列的分片，成为Nova的一等特性
2. 不需要在顶级复制Cell数据库，Nova API需要自己的数据库，存放例如实例索引的信息
3. 在gloabl和local数据元素之间划分好了界限。Flavor、Keypair之类的全局性质对象，仅仅需要存储在顶级。这样计算节点更加无状态化，不会被全局数据的修改所干扰

所有Nova部署中，都需要一个名为API的数据库，一个特殊的Cell数据库cell0，1-N个cell的数据库。高层次的跟踪信息存放在API数据库中，哪些从未调度成功的实例，存放在cell0。所有成功调度的/运行的实例，都放在其它cell数据库中。

你需要将API数据库的信息配置在nova.conf：

[api_database]
connection = mysql+pymysql://nova:nova@os.gmem.cc/nova_api?charset=utf8

由于cell数据库数量不定，此外任何部署都至少有cell0和cell1（唯一的Cell使用），因此这些Cell的连接信息，是写在API数据库中（而不是静态编写在文件）的。

# 后续命令需要读写API数据库，因此首先执行api_db sync子命令来初始化schema
su -s /bin/sh -c "nova-manage api_db sync" nova

# 为cell0的数据库创建记录
nova-manage cell_v2 map_cell0 --database_connection \
  mysql+pymysql://nova:nova@os.gmem.cc/nova_cell0
# 如果不指定--database_connection，就像样例环境那样，则自动使用[database]/connection字段
# 中的连接串，但是在结尾添加_cell0后缀

由于cell0中不会存在任何宿主机，不需要对它进行进一步配置。

现在，你需要创建第一个常规cell： 

# 如果不指定 --database_connection、--transport-url，就像样例环境那样，
# 则自动使用 [database]/connection 和 [DEFAULT]/transport_url
su -s /bin/sh -c "nova-manage cell_v2 create_cell --name=cell1 --verbose" nova

nova-manage cell_v2 create_cell --verbose --name cell1 \
  --database_connection mysql+pymysql://nova:nova@os.gmem.cc/nova
  --transport-url rabbit://openstack:openstack@os.gmem.cc

如果为cell1准备的数据库是空白的，你需要同步数据库schema：

su -s /bin/sh -c "nova-manage db sync" nova

现在，cell1中没有任何宿主机，因此nova-scheduler不会把实例调度到此cell中。

使用下面的命令，可以扫描数据库中计算节点的记录，并将其添加到刚刚创建的cell中。执行命令之前，至少需要安装一个计算节点并添加到cell。

nova-manage cell_v2 discover_hosts

上述命令会连接到所有cell数据库，扫描将自己注册到cell的宿主机，然后在API数据库中映射这些宿主机，这样nova-scheduler就可以进行调度了。

任何时候，你加入新的宿主机到cell，都需要调用此命令（或者启用自动发现）。

我们知道计算节点通过消息队列和控制平面通信，也不会直接访问数据库。实际上，计算节点属于哪个cell，就看它通过哪个消息队列连接。你只需要配置计算节点的nova.conf：

[DEFAULT]
; 设置为某个cell的--transport-url 
transport_url = rabbit://openstack:openstack@os.gmem.cc

然后再启动nova-compute服务，最后验证、确保节点在下面命令的输出中： 

nova service-list --binary nova-compute

就将计算节点添加到cell中了。 

要实现自动发现添加到cell的计算节点，并通过到API数据库，可以配置所有nova-scheduler节点的nova.conf：

[scheduler]
; 300秒执行一次发现
discover_hosts_in_cells_interval = 300 

到目前为止（V版），还不支持跨Cell迁移实例。影响的操作包括resize/evacuate/migrate等。

如果Cell不可达，那么针对租户的用量统计信息可能不准确。

从T版开始，可以配置在Placement服务+API数据库上进行Quota统计，这样宕掉/性能很差的Cell不会导致用量统计不准确。

多Cell环境下，列出实例的结果可能没有排序、分页可能不正确。

从S版开始，元数据服务可以运行为两种模式之一：全局/PerCell。使用api.local_metadata_per_cell配置项

Nova将它启动的实例的配置信息呈现为元数据。cloud-init之类的助手会在虚拟机初始化时，利用元数据进行配置工作，例如设置虚拟机root密码。

通过元数据服务、或者config drive，元数据变的可（被实例使）用。你还可以通过nova api的user data特性来定制实例的元数据。

控制节点上的Neutron元数据代理服务，负责代替虚拟机Nova metadata API。并自动设置正确的Instance ID、Tenant ID等请求头。

元数据服务为实例提供了一种获取自身元数据的REST API。实例可以通过169.254.169.254或者fe80::a9fe:a9fe访问此REST API，如此奇怪的地址是兼容Amazon EC2的考虑。在Openstack里面，这两个IP通过iptables映射到控制节点。

所有上述三类元数据，都可以通过此REST API访问：

# OpenStack metadata API
curl http://169.254.169.254/openstack
# EC2-compatible API
curl http://169.254.169.254
# 都会显示若干目录（版本信息）
# 2012-08-10
# 2013-04-04
# 2013-10-17
# 2015-10-15
# 2016-06-30
# 2016-10-06
# 2017-02-22
# 2018-08-27
# latest

Config drive是一种特殊的drive，在实例boot时添加。实例可以挂载此drive，读取其中的文件，从而获取（通常应该从metadata service获取的）信息。

下面的命令示意了如何使用在创建实例时使用config drive：

#                       使用config drive
openstack server create --config-drive true --image my-image-name \
#                               传递一个user data文件
    --flavor 1 --key-name mykey --user-data ./my-user-data.txt \
#   传递两个元数据键值对
    --property role=webservers --property essential=false MYINSTANCE

如果客户机操作系统支持udev，则可以这样挂载config drive： 

mkdir -p /mnt/config
mount /dev/disk/by-label/config-2 /mnt/config

否则，这样识别config drive对应的块设备：

blkid -t LABEL="config-2" -odevice
# /dev/vdb

config drive中的文件目录结构，和metadata service的URL结构对应：

cd /mnt/config
find . -maxdepth 2
# .
# EC2兼容的元数据放在这里
# ./ec2
# ./ec2/2009-04-04
# ./ec2/latest
# OpenStack元数据放在这里
# ./openstack
# ./openstack/2012-08-10
# ./openstack/2013-04-04
# ./openstack/2013-10-17
# ./openstack/2015-10-15
# ./openstack/2016-06-30
# ./openstack/2016-10-06
# ./openstack/2017-02-22
# ./openstack/latest

OpenStack元数据基于JSON格式分发： 

1. meta_data.json：提供Nova相关的信息
2.  network_data.json：提供从Neutron获取的，网络相关信息

示例：

// curl http://169.254.169.254/openstack/2018-08-27/meta_data.json
{
   "random_seed": "yu5ZnkqF2CqnDZVAfZgarG...",
   "availability_zone": "nova",
   "keys": [
       {
         "data": "ssh-rsa AAAAB3NzaC1y...== Generated by Nova\n",
         "type": "ssh",
         "name": "mykey"
       }
   ],
   "hostname": "test.novalocal",
   "launch_index": 0,
   "meta": {
      "priority": "low",
      "role": "webserver"
   },
   "devices": [
       {
         "type": "nic",
         "bus": "pci",
         "address": "0000:00:02.0",
         "mac": "00:11:22:33:44:55",
         "tags": ["trusted"]
       },
       {
         "type": "disk",
         "bus": "ide",
         "address": "0:0",
         "serial": "disk-vol-2352423",
         "path": "/dev/sda",
         "tags": ["baz"]
       }
   ],
   "project_id": "f7ac731cc11f40efbc03a9f9e1d1d21f",
   "public_keys": {
       "mykey": "ssh-rsa AAAAB3NzaC1y...== Generated by Nova\n"
   },
   "name": "test"
}


// curl http://169.254.169.254/openstack/2018-08-27/network_data.json
{
    "links": [
        {
            "ethernet_mac_address": "fa:16:3e:9c:bf:3d",
            "id": "tapcd9f6d46-4a",
            "mtu": null,
            "type": "bridge",
            "vif_id": "cd9f6d46-4a3a-43ab-a466-994af9db96fc"
        }
    ],
    "networks": [
        {
            "id": "network0",
            "link": "tapcd9f6d46-4a",
            "network_id": "99e88329-f20d-4741-9593-25bf07847b16",
            "type": "ipv4_dhcp"
        }
    ],
    "services": [
        {
            "address": "8.8.8.8",
            "type": "dns"
        }
    ]
}

兼容Amazon EC2 metadata service 2009-04-04版本。这意味着，为EC2设计的虚拟机镜像，可以和OpenStack一起工作。

EC2 API为每个元数据暴露了独立的URL：

# curl http://169.254.169.254/2009-04-04/meta-data/
ami-id
ami-launch-index
ami-manifest-path
block-device-mapping/
hostname
instance-action
instance-id
instance-type
kernel-id
local-hostname
local-ipv4
placement/
public-hostname
public-ipv4
public-keys/
ramdisk-id
reservation-id
security-groups

# curl http://169.254.169.254/2009-04-04/meta-data/block-device-mapping/
ami

# curl http://169.254.169.254/2009-04-04/meta-data/placement/
availability-zone

# curl http://169.254.169.254/2009-04-04/meta-data/public-keys/
0=mykey

# curl http://169.254.169.254/2009-04-04/meta-data/public-keys/0/openssh-key
ssh-rsa AAAAB3NzaC1yc2EAAAADAQABAAAAgQDYVEprvtYJXVOBN0XNKVVRNCRX6BlnNbI+US\
LGais1sUWPwtSg7z9K9vhbYAPUZcq8c/s5S9dg5vTHbsiyPCIDOKyeHba4MUJq8Oh5b2i71/3B\
ISpyxTBH/uZDHdslW2a+SrPDCeuMMoss9NFhBdKtDkdG9zyi0ibmCP6yMdEX8Q== Generated\
by Nova

就是一小段blob，OpenStack不知道它内容的意义。传递user data： 

openstack server create --image ubuntu-cloudimage --flavor 1 \
    --user-data mydata.file TEST

在客户机里面访问user data： 

# OpenStack
http://169.254.169.254/openstack/{version}/user_data
# EC2
http://169.254.169.254/{version}/user-data

支持cloud-init的镜像，可以利用user data，定制实例的初始化过程。

这类数据可以通过metadata service或config drive读取。对于前者： 

// curl http://169.254.169.254/openstack/2018-08-27/vendor_data2.json
{
    "testing": {
        "value1": 1
    }
}

cloud-init是一个在主要Linux发行版中都支持的包，用于在云环境（例如OpenStack）中初始化虚拟机实例。cloud-init在虚拟机第一次运行时执行。

cloud-init集成到系统启动的五个Stage，以发挥作用：

cloud-init需要判断实例是否第一次启动。在第一次启动时，会运行

per-instance

per-boot

在运行的时候，cloud-init会将内部状态缓存起来，共后续boot读取。缓存存在，意味着两种情况之一：

1. 实例不是第一次启动
2. 文件系统被挂载给一个新实例，该实例是第一次启动。将一个OpenStack卷上传为镜像，然后从此镜像启动新实例，就会导致这种情况

默认情况下，cloud-init检查缓存中的实例ID，和运行时获取的实例ID，来判断是上述两种情况的哪一种。

使用命令

cloud-init clean

cloud-init的主配置文件位于

/etc/cloud/cloud.cfg

/etc/cloud/cloud.cfg.d

# 需要添加到系统中的用户，特殊值default特指system_info.default_user
users:
 - default

# 禁止root登陆
disable_root: 1
# 禁用密码登陆
ssh_pwauth:   0

mount_default_fields: [~, ~, 'auto', 'defaults,nofail,x-systemd.requires=cloud-init.service', '0', '2']
resize_rootfs_tmp: /dev
ssh_deletekeys:   1
ssh_genkeytypes:  ~
syslog_fix_perms: ~
disable_vmware_customization: false

# 每个Stage都包含一系列的模块，可以启用/禁用
cloud_init_modules:
 - disk_setup
 - migrator
 - bootcmd
 - write-files
 - growpart
 - resizefs
 - set_hostname
 - update_hostname
 - update_etc_hosts
 - rsyslog
 - users-groups
 - ssh

cloud_config_modules:
 - mounts
 - locale
 - set-passwords
 - rh_subscription
 - yum-add-repo
 - package-update-upgrade-install
 - timezone
 - puppet
 - chef
 - salt-minion
 - mcollective
 - disable-ec2-metadata
 - runcmd

cloud_final_modules:
 - rightscale_userdata
 - scripts-per-once
 - scripts-per-boot
 - scripts-per-instance
 - scripts-user
 - ssh-authkey-fingerprints
 - keys-to-console
 - phone-home
 - final-message
 - power-state-change

system_info:
  # 默认用户信息
  default_user:
    name: centos
    lock_passwd: true
    gecos: Cloud User
    groups: [adm, systemd-journal]
    sudo: ["ALL=(ALL) NOPASSWD:ALL"]
    shell: /bin/bash
  distro: rhel
  paths:
    cloud_dir: /var/lib/cloud
    templates_dir: /etc/cloud/templates
  ssh_svcname: sshd

# vim:syntax=yaml

用户数据支持多种形式：

# cloud-init devel make-mime --list-types
cloud-boothook
cloud-config
cloud-config-archive
cloud-config-jsonp
jinja2
part-handler
upstart-job
x-include-once-url
x-include-url
x-shellscript

cloud-init devel make-mime -a config.yaml:cloud-config \
                           -a script.sh:x-shellscript > user-data

#!

#include

#cloud-config

#cloud-config
# Add groups to the system
# The following example adds the ubuntu group with members 'root' and 'sys'
# and the empty group cloud-users.
groups:
  - ubuntu: [root,sys]
  - cloud-users

# Add users to the system. Users are added after groups are added.
# Note: Most of these configuration options will not be honored if the user
#       already exists. Following options are the exceptions and they are
#       applicable on already-existing users:
#       - 'plain_text_passwd', 'hashed_passwd', 'lock_passwd', 'sudo',
#         'ssh_authorized_keys', 'ssh_redirect_user'.
users:
  - default
  - name: foobar
    gecos: Foo B. Bar
    primary_group: foobar
    groups: users
    selinux_user: staff_u
    expiredate: '2012-09-01'
    ssh_import_id: foobar
    lock_passwd: false
    passwd: $6$j212wezy$7H/1LT4f9/N3wpgNunhsIqtMj62OKiS3nyNwuizouQc3u7MbYCarYeAHWYPYb2FT.lbioDm2RrkJPb9BZMN1O/
  - name: barfoo
    gecos: Bar B. Foo
    sudo: ALL=(ALL) NOPASSWD:ALL
    groups: users, admin
    ssh_import_id: None
    lock_passwd: true
    ssh_authorized_keys:
      - <ssh pub key 1>
      - <ssh pub key 2>
  - name: cloudy
    gecos: Magic Cloud App Daemon User
    inactive: '5'
    system: true
  - name: fizzbuzz
    sudo: False
    ssh_authorized_keys:
      - <ssh pub key 1>
      - <ssh pub key 2>
  - snapuser: joe@joeuser.io
  - name: nosshlogins
    ssh_redirect_user: true

# Valid Values:
#   name: The user's login name
#   expiredate: Date on which the user's account will be disabled.
#   gecos: The user name's real name, i.e. "Bob B. Smith"
#   homedir: Optional. Set to the local path you want to use. Defaults to
#           /home/<username>
#   primary_group: define the primary group. Defaults to a new group created
#           named after the user.
#   groups:  Optional. Additional groups to add the user to. Defaults to none
#   selinux_user:  Optional. The SELinux user for the user's login, such as
#           "staff_u". When this is omitted the system will select the default
#           SELinux user.
#   lock_passwd: Defaults to true. Lock the password to disable password login
#   inactive: Number of days after password expires until account is disabled
#   passwd: The hash -- not the password itself -- of the password you want
#           to use for this user. You can generate a safe hash via:
#               mkpasswd --method=SHA-512 --rounds=4096
#           (the above command would create from stdin an SHA-512 password hash
#           with 4096 salt rounds)
#
#           Please note: while the use of a hashed password is better than
#               plain text, the use of this feature is not ideal. Also,
#               using a high number of salting rounds will help, but it should
#               not be relied upon.
#
#               To highlight this risk, running John the Ripper against the
#               example hash above, with a readily available wordlist, revealed
#               the true password in 12 seconds on a i7-2620QM.
#
#               In other words, this feature is a potential security risk and is
#               provided for your convenience only. If you do not fully trust the
#               medium over which your cloud-config will be transmitted, then you
#               should use SSH authentication only.
#
#               You have thus been warned.
#   no_create_home: When set to true, do not create home directory.
#   no_user_group: When set to true, do not create a group named after the user.
#   no_log_init: When set to true, do not initialize lastlog and faillog database.
#   ssh_import_id: Optional. Import SSH ids
#   ssh_authorized_keys: Optional. [list] Add keys to user's authorized keys file
#   ssh_redirect_user: Optional. [bool] Set true to block ssh logins for cloud
#       ssh public keys and emit a message redirecting logins to
#       use <default_username> instead. This option only disables cloud
#       provided public-keys. An error will be raised if ssh_authorized_keys
#       or ssh_import_id is provided for the same user.
#
#       ssh_authorized_keys.
#   sudo: Defaults to none. Accepts a sudo rule string, a list of sudo rule
#         strings or False to explicitly deny sudo usage. Examples:
#
#         Allow a user unrestricted sudo access.
#             sudo:  ALL=(ALL) NOPASSWD:ALL
#
#         Adding multiple sudo rule strings.
#             sudo:
#               - ALL=(ALL) NOPASSWD:/bin/mysql
#               - ALL=(ALL) ALL
#
#         Prevent sudo access for a user.
#             sudo: False
#
#         Note: Please double check your syntax and make sure it is valid.
#               cloud-init does not parse/check the syntax of the sudo
#               directive.
#   system: Create the user as a system user. This means no home directory.
#   snapuser: Create a Snappy (Ubuntu-Core) user via the snap create-user
#             command available on Ubuntu systems.  If the user has an account
#             on the Ubuntu SSO, specifying the email will allow snap to
#             request a username and any public ssh keys and will import
#             these into the system with username specifed by SSO account.
#             If 'username' is not set in SSO, then username will be the
#             shortname before the email domain.
#

# Default user creation:
#
# Unless you define users, you will get a 'ubuntu' user on ubuntu systems with the
# legacy permission (no password sudo, locked user, etc). If however, you want
# to have the 'ubuntu' user in addition to other users, you need to instruct
# cloud-init that you also want the default user. To do this use the following
# syntax:
#   users:
#     - default
#     - bob
#     - ....
#  foobar: ...
#
# users[0] (the first user in users) overrides the user directive.
#
# The 'default' user above references the distro's config:
# system_info:
#   default_user:
#     name: Ubuntu
#     plain_text_passwd: 'ubuntu'
#     home: /home/ubuntu
#     shell: /bin/bash
#     lock_passwd: True
#     gecos: Ubuntu
#     groups: [adm, audio, cdrom, dialout, floppy, video, plugdev, dip, netdev]

#cloud-config
# vim: syntax=yaml
#
# This is the configuration syntax that the write_files module
# will know how to understand. encoding can be given b64 or gzip or (gz+b64).
# The content will be decoded accordingly and then written to the path that is
# provided. 
#
# Note: Content strings here are truncated for example purposes.
write_files:
- encoding: b64
  content: CiMgVGhpcyBmaWxlIGNvbnRyb2xzIHRoZSBzdGF0ZSBvZiBTRUxpbnV4...
  owner: root:root
  path: /etc/sysconfig/selinux
  permissions: '0644'
- content: |
    # My new /etc/sysconfig/samba file

    SMBDOPTIONS="-D"
  path: /etc/sysconfig/samba
- content: !!binary |
    f0VMRgIBAQAAAAAAAAAAAAIAPgABAAAAwARAAAAAAABAAAAAAAAAAJAVAAAAAAAAAAAAAEAAOAAI
    AEAAHgAdAAYAAAAFAAAAQAAAAAAAAABAAEAAAAAAAEAAQAAAAAAAwAEAAAAAAADAAQAAAAAAAAgA
    AAAAAAAAAwAAAAQAAAAAAgAAAAAAAAACQAAAAAAAAAJAAAAAAAAcAAAAAAAAABwAAAAAAAAAAQAA
    ....
  path: /bin/arch
  permissions: '0555'
- encoding: gzip
  content: !!binary |
    H4sIAIDb/U8C/1NW1E/KzNMvzuBKTc7IV8hIzcnJVyjPL8pJ4QIA6N+MVxsAAAA=
  path: /usr/bin/hello
  permissions: '0755'

#cloud-config
# vim: syntax=yaml
#
# Add yum repository configuration to the system
#
# The following example adds the file /etc/yum.repos.d/epel_testing.repo
# which can then subsequently be used by yum for later operations.
yum_repos:
  # The name of the repository
  epel-testing:
    # Any repository configuration options
    # See: man yum.conf
    #
    # This one is required!
    baseurl: http://download.fedoraproject.org/pub/epel/testing/5/$basearch
    enabled: false
    failovermethod: priority
    gpgcheck: true
    gpgkey: file:///etc/pki/rpm-gpg/RPM-GPG-KEY-EPEL
    name: Extra Packages for Enterprise Linux 5 - Testing

#cloud-config

# Add primary apt repositories
#
# To add 3rd party repositories, see cloud-config-apt.txt or the
# Additional apt configuration and repositories section.
#
#
# Default: auto select based on cloud metadata
#  in ec2, the default is <region>.archive.ubuntu.com
# apt:
#   primary:
#     - arches [default]
#       uri:
#     use the provided mirror
#       search:
#     search the list for the first mirror.
#     this is currently very limited, only verifying that
#     the mirror is dns resolvable or an IP address
#
# if neither mirror is set (the default)
# then use the mirror provided by the DataSource found.
# In EC2, that means using <region>.ec2.archive.ubuntu.com
#
# if no mirror is provided by the DataSource, but 'search_dns' is
# true, then search for dns names '<distro>-mirror' in each of
# - fqdn of this host per cloud metadata
# - localdomain
# - no domain (which would search domains listed in /etc/resolv.conf)
# If there is a dns entry for <distro>-mirror, then it is assumed that there
# is a distro mirror at http://<distro>-mirror.<domain>/<distro>
#
# That gives the cloud provider the opportunity to set mirrors of a distro
# up and expose them only by creating dns entries.
#
# if none of that is found, then the default distro mirror is used
apt:
  primary:
    - arches: [default]
      uri: http://us.archive.ubuntu.com/ubuntu/
# or
apt:
  primary:
    - arches: [default]
      search:
        - http://local-mirror.mydomain
        - http://archive.ubuntu.com
# or
apt:
  primary:
    - arches: [default]
      search_dns: True

#cloud-config
# Update apt database on first boot (run 'apt-get update').
# Note, if packages are given, or package_upgrade is true, then
# update will be done independent of this setting.
#
# Default: false
# Aliases: apt_update
package_update: true

#cloud-config

# Upgrade the instance on first boot
# (ie run apt-get upgrade)
#
# Default: false
# Aliases: apt_upgrade
package_upgrade: true

#cloud-config
#
# This is an example file to configure an instance's trusted CA certificates
# system-wide for SSL/TLS trust establishment when the instance boots for the
# first time.
#
# Make sure that this file is valid yaml before starting instances.
# It should be passed as user-data when starting the instance.

ca-certs:
  # If present and set to True, the 'remove-defaults' parameter will remove
  # all the default trusted CA certificates that are normally shipped with
  # Ubuntu.
  # This is mainly for paranoid admins - most users will not need this
  # functionality.
  remove-defaults: true

  # If present, the 'trusted' parameter should contain a certificate (or list
  # of certificates) to add to the system as trusted CA certificates.
  # Pay close attention to the YAML multiline list syntax.  The example shown
  # here is for a list of multiline certificates.
  trusted: 
  - |
   -----BEGIN CERTIFICATE-----
   YOUR-ORGS-TRUSTED-CA-CERT-HERE
   -----END CERTIFICATE-----
  - |
   -----BEGIN CERTIFICATE-----
   YOUR-ORGS-TRUSTED-CA-CERT-HERE
   -----END CERTIFICATE-----

#cloud-config
#
# This is an example file to automatically configure resolv.conf when the
# instance boots for the first time.
#
# Ensure that your yaml is valid and pass this as user-data when starting
# the instance. Also be sure that your cloud.cfg file includes this
# configuration module in the appropriate section.
#
manage_resolv_conf: true

resolv_conf:
  nameservers: ['8.8.4.4', '8.8.8.8']
  searchdomains:
    - foo.example.com
    - bar.example.com
  domain: example.com
  options:
    rotate: true
    timeout: 1

#cloud-config

# boot commands
# default: none
# this is very similar to runcmd, but commands run very early
# in the boot process, only slightly after a 'boothook' would run.
# bootcmd should really only be used for things that could not be
# done later in the boot process.  bootcmd is very much like
# boothook, but possibly with more friendly.
# - bootcmd will run on every boot
# - the INSTANCE_ID variable will be set to the current instance id.
# - you can use 'cloud-init-per' command to help only run once
bootcmd:
  - echo 192.168.1.130 us.archive.ubuntu.com >> /etc/hosts
  - [ cloud-init-per, once, mymkfs, mkfs, /dev/vdb ]

#cloud-config

# run commands
# default: none
# runcmd contains a list of either lists or a string
# each item will be executed in order at rc.local like level with
# output to the console
# - runcmd only runs during the first boot
# - if the item is a list, the items will be properly executed as if
#   passed to execve(3) (with the first arg as the command).
# - if the item is a string, it will be simply written to the file and
#   will be interpreted by 'sh'
#
# Note, that the list has to be proper yaml, so you have to quote
# any characters yaml would eat (':' can be problematic)
runcmd:
 - [ ls, -l, / ]
 - [ sh, -xc, "echo $(date) ': hello world!'" ]
 - [ sh, -c, echo "=========hello world'=========" ]
 - ls -l /root
 # Note: Don't write files to /tmp from cloud-init use /run/somedir instead.
 # Early boot environments can race systemd-tmpfiles-clean LP: #1707222.
 - mkdir /run/mydir
 - [ wget, "http://slashdot.org", -O, /run/mydir/index.html ]

#cloud-config

# Install additional packages on first boot
#
# Default: none
#
# if packages are specified, this apt_update will be set to true
#
# packages may be supplied as a single package name or as a list
# with the format [<package>, <version>] wherein the specifc
# package version will be installed.
packages:
 - pwgen
 - pastebinit
 - [libpython2.7, 2.7.3-0ubuntu3.1]

#cloud-config

# set up mount points
# 'mounts' contains a list of lists
#  the inner list are entries for an /etc/fstab line
#  ie : [ fs_spec, fs_file, fs_vfstype, fs_mntops, fs-freq, fs_passno ]
#
# default:
# mounts:
#  - [ ephemeral0, /mnt ]
#  - [ swap, none, swap, sw, 0, 0 ]
#
# in order to remove a previously listed mount (ie, one from defaults)
# list only the fs_spec.  For example, to override the default, of
# mounting swap:
# - [ swap ]
# or
# - [ swap, null ]
#
# - if a device does not exist at the time, an entry will still be
#   written to /etc/fstab.
# - '/dev' can be ommitted for device names that begin with: xvd, sd, hd, vd
# - if an entry does not have all 6 fields, they will be filled in
#   with values from 'mount_default_fields' below.
#
# Note, that you should set 'nofail' (see man fstab) for volumes that may not
# be attached at instance boot (or reboot).
#
mounts:
 - [ ephemeral0, /mnt, auto, "defaults,noexec" ]
 - [ sdc, /opt/data ]
 - [ xvdh, /opt/data, "auto", "defaults,nofail", "0", "0" ]
 - [ dd, /dev/zero ]

# mount_default_fields
# These values are used to fill in any entries in 'mounts' that are not
# complete.  This must be an array, and must have 6 fields.
mount_default_fields: [ None, None, "auto", "defaults,nofail", "0", "2" ]


# swap can also be set up by the 'mounts' module
# default is to not create any swap files, because 'size' is set to 0
swap:
  filename: /swap.img
  size: "auto" # or size in bytes
  maxsize: size in bytes

#cloud-config

## poweroff or reboot system after finished
# default: none
#
# power_state can be used to make the system shutdown, reboot or
# halt after boot is finished.  This same thing can be acheived by
# user-data scripts or by runcmd by simply invoking 'shutdown'.
# 
# Doing it this way ensures that cloud-init is entirely finished with
# modules that would be executed, and avoids any error/log messages
# that may go to the console as a result of system services like
# syslog being taken down while cloud-init is running.
#
# If you delay '+5' (5 minutes) and have a timeout of
# 120 (2 minutes), then the max time until shutdown will be 7 minutes.
# cloud-init will invoke 'shutdown +5' after the process finishes, or
# when 'timeout' seconds have elapsed.
#
# delay: form accepted by shutdown.  default is 'now'. other format
#        accepted is '+m' (m in minutes)
# mode: required. must be one of 'poweroff', 'halt', 'reboot'
# message: provided as the message argument to 'shutdown'. default is none.
# timeout: the amount of time to give the cloud-init process to finish
#          before executing shutdown.
# condition: apply state change only if condition is met.
#            May be boolean True (always met), or False (never met),
#            or a command string or list to be executed.
#            command's exit code indicates:
#               0: condition met
#               1: condition not met
#            other exit codes will result in 'not met', but are reserved
#            for future use.
#
power_state:
  delay: "+30"
  mode: poweroff
  message: Bye Bye
  timeout: 30
  condition: True

#cloud-config

# add each entry to ~/.ssh/authorized_keys for the configured user or the
# first user defined in the user definition directive.
ssh_authorized_keys:
  - ssh-rsa AAAAB3NzaC1yc2EAAAABIwAAAGEA3FSyQwBI6Z+nCSjUUk8EEAnnkhXlukKoUPND/RRClWz2s5TCzIkd3Ou5+Cyz71X0XmazM3l5WgeErvtIwQMyT1KjNoMhoJMrJnWqQPOt5Q8zWd9qG7PBl9+eiH5qV7NZ mykey@host
  - ssh-rsa AAAAB3NzaC1yc2EAAAABIwAAAQEA3I7VUf2l5gSn5uavROsc5HRDpZdQueUq5ozemNSj8T7enqKHOEaFoU2VoPgGEWC9RyzSQVeyD6s7APMcE82EtmW4skVEgEGSbDc1pvxzxtchBj78hJP6Cf5TCMFSXw+Fz5rF1dR23QDbN1mkHs7adr8GW4kSWqU7Q7NDwfIrJJtO7Hi42GyXtvEONHbiRPOe8stqUly7MvUoN+5kfjBM8Qqpfl2+FNhTYWpMfYdPUnE7u536WqzFmsaqJctz3gBxH9Ex7dFtrxR4qiqEr9Qtlu3xGn7Bw07/+i1D+ey3ONkZLN+LQ714cgj8fRS4Hj29SCmXp5Kt5/82cD/VN3NtHw== smoser@brickies

# Send pre-generated SSH private keys to the server
# If these are present, they will be written to /etc/ssh and
# new random keys will not be generated
#  in addition to 'rsa' and 'dsa' as shown below, 'ecdsa' is also supported
ssh_keys:
  rsa_private: |
    -----BEGIN RSA PRIVATE KEY-----
    MIIBxwIBAAJhAKD0YSHy73nUgysO13XsJmd4fHiFyQ+00R7VVu2iV9Qcon2LZS/x
    1cydPZ4pQpfjEha6WxZ6o8ci/Ea/w0n+0HGPwaxlEG2Z9inNtj3pgFrYcRztfECb
    1j6HCibZbAzYtwIBIwJgO8h72WjcmvcpZ8OvHSvTwAguO2TkR6mPgHsgSaKy6GJo
    PUJnaZRWuba/HX0KGyhz19nPzLpzG5f0fYahlMJAyc13FV7K6kMBPXTRR6FxgHEg
    L0MPC7cdqAwOVNcPY6A7AjEA1bNaIjOzFN2sfZX0j7OMhQuc4zP7r80zaGc5oy6W
    p58hRAncFKEvnEq2CeL3vtuZAjEAwNBHpbNsBYTRPCHM7rZuG/iBtwp8Rxhc9I5w
    ixvzMgi+HpGLWzUIBS+P/XhekIjPAjA285rVmEP+DR255Ls65QbgYhJmTzIXQ2T9
    luLvcmFBC6l35Uc4gTgg4ALsmXLn71MCMGMpSWspEvuGInayTCL+vEjmNBT+FAdO
    W7D4zCpI43jRS9U06JVOeSc9CDk2lwiA3wIwCTB/6uc8Cq85D9YqpM10FuHjKpnP
    REPPOyrAspdeOAV+6VKRavstea7+2DZmSUgE
    -----END RSA PRIVATE KEY-----

  rsa_public: ssh-rsa AAAAB3NzaC1yc2EAAAABIwAAAGEAoPRhIfLvedSDKw7XdewmZ3h8eIXJD7TRHtVW7aJX1ByifYtlL/HVzJ09nilCl+MSFrpbFnqjxyL8Rr/DSf7QcY/BrGUQbZn2Kc22PemAWthxHO18QJvWPocKJtlsDNi3 smoser@localhost

  dsa_private: |
    -----BEGIN DSA PRIVATE KEY-----
    MIIBuwIBAAKBgQDP2HLu7pTExL89USyM0264RCyWX/CMLmukxX0Jdbm29ax8FBJT
    pLrO8TIXVY5rPAJm1dTHnpuyJhOvU9G7M8tPUABtzSJh4GVSHlwaCfycwcpLv9TX
    DgWIpSj+6EiHCyaRlB1/CBp9RiaB+10QcFbm+lapuET+/Au6vSDp9IRtlQIVAIMR
    8KucvUYbOEI+yv+5LW9u3z/BAoGBAI0q6JP+JvJmwZFaeCMMVxXUbqiSko/P1lsa
    LNNBHZ5/8MOUIm8rB2FC6ziidfueJpqTMqeQmSAlEBCwnwreUnGfRrKoJpyPNENY
    d15MG6N5J+z81sEcHFeprryZ+D3Ge9VjPq3Tf3NhKKwCDQ0240aPezbnjPeFm4mH
    bYxxcZ9GAoGAXmLIFSQgiAPu459rCKxT46tHJtM0QfnNiEnQLbFluefZ/yiI4DI3
    8UzTCOXLhUA7ybmZha+D/csj15Y9/BNFuO7unzVhikCQV9DTeXX46pG4s1o23JKC
    /QaYWNMZ7kTRv+wWow9MhGiVdML4ZN4XnifuO5krqAybngIy66PMEoQCFEIsKKWv
    99iziAH0KBMVbxy03Trz
    -----END DSA PRIVATE KEY-----

  dsa_public: ssh-dss AAAAB3NzaC1kc3MAAACBAM/Ycu7ulMTEvz1RLIzTbrhELJZf8Iwua6TFfQl1ubb1rHwUElOkus7xMhdVjms8AmbV1Meem7ImE69T0bszy09QAG3NImHgZVIeXBoJ/JzByku/1NcOBYilKP7oSIcLJpGUHX8IGn1GJoH7XRBwVub6Vqm4RP78C7q9IOn0hG2VAAAAFQCDEfCrnL1GGzhCPsr/uS1vbt8/wQAAAIEAjSrok/4m8mbBkVp4IwxXFdRuqJKSj8/WWxos00Ednn/ww5QibysHYULrOKJ1+54mmpMyp5CZICUQELCfCt5ScZ9GsqgmnI80Q1h3Xkwbo3kn7PzWwRwcV6muvJn4PcZ71WM+rdN/c2EorAINDTbjRo97NueM94WbiYdtjHFxn0YAAACAXmLIFSQgiAPu459rCKxT46tHJtM0QfnNiEnQLbFluefZ/yiI4DI38UzTCOXLhUA7ybmZha+D/csj15Y9/BNFuO7unzVhikCQV9DTeXX46pG4s1o23JKC/QaYWNMZ7kTRv+wWow9MhGiVdML4ZN4XnifuO5krqAybngIy66PMEoQ= smoser@localhost

# By default, the fingerprints of the authorized keys for the users
# cloud-init adds are printed to the console. Setting
# no_ssh_fingerprints to true suppresses this output.
no_ssh_fingerprints: false

# By default, (most) ssh host keys are printed to the console. Setting
# emit_keys_to_console to false suppresses this output.
ssh:
  emit_keys_to_console: false

#cloud-config
# Cloud-init supports the creation of simple partition tables and file systems
# on devices.

# Default disk definitions for AWS
# --------------------------------
# (Not implemented yet, but provided for future documentation)

disk_setup:
  ephmeral0:
    table_type: 'mbr'
    layout: True
    overwrite: False

fs_setup:
  - label: None,
    filesystem: ext3
    device: ephemeral0
    partition: auto

# Default disk definitions for Microsoft Azure
# ------------------------------------------

device_aliases: {'ephemeral0': '/dev/sdb'}
disk_setup:
  ephemeral0:
    table_type: mbr
    layout: True
    overwrite: False

fs_setup:
  - label: ephemeral0
    filesystem: ext4
    device: ephemeral0.1
    replace_fs: ntfs


# Data disks definitions for Microsoft Azure
# ------------------------------------------

disk_setup:
  /dev/disk/azure/scsi1/lun0:
    table_type: gpt
    layout: True
    overwrite: True

fs_setup:
  - device: /dev/disk/azure/scsi1/lun0
    partition: 1
    filesystem: ext4


# Default disk definitions for SmartOS
# ------------------------------------

device_aliases: {'ephemeral0': '/dev/vdb'}
disk_setup:
  ephemeral0:
    table_type: mbr
    layout: False
    overwrite: False

fs_setup:
  - label: ephemeral0
    filesystem: ext4
    device: ephemeral0.0

# Caveat for SmartOS: if ephemeral disk is not defined, then the disk will
#    not be automatically added to the mounts.


# The default definition is used to make sure that the ephemeral storage is
# setup properly.

# "disk_setup": disk partitioning
# --------------------------------

# The disk_setup directive instructs Cloud-init to partition a disk. The format is:

disk_setup:
  ephmeral0:
    table_type: 'mbr'
    layout: 'auto'
  /dev/xvdh:
    table_type: 'mbr'
    layout:
      - 33
      - [33, 82]
      - 33
    overwrite: True

# The format is a list of dicts of dicts. The first value is the name of the
# device and the subsequent values define how to create and layout the
# partition.
# The general format is:
#   disk_setup:
#     <DEVICE>:
#       table_type: 'mbr'
#       layout: <LAYOUT|BOOL>
#       overwrite: <BOOL>
#
# Where:
#   <DEVICE>: The name of the device. 'ephemeralX' and 'swap' are special
#               values which are specific to the cloud. For these devices
#               Cloud-init will look up what the real devices is and then
#               use it.
#
#               For other devices, the kernel device name is used. At this
#               time only simply kernel devices are supported, meaning
#               that device mapper and other targets may not work.
#
#               Note: At this time, there is no handling or setup of
#               device mapper targets.
#
#   table_type=<TYPE>: Currently the following are supported:
#                   'mbr': default and setups a MS-DOS partition table
#                   'gpt': setups a GPT partition table
#
#               Note: At this time only 'mbr' and 'gpt' partition tables
#                   are allowed. It is anticipated in the future that
#                   we'll also have "RAID" to create a mdadm RAID.
#
#   layout={...}: The device layout. This is a list of values, with the
#               percentage of disk that partition will take.
#               Valid options are:
#                   [<SIZE>, [<SIZE>, <PART_TYPE]]
#
#               Where <SIZE> is the _percentage_ of the disk to use, while
#               <PART_TYPE> is the numerical value of the partition type.
#
#               The following setups two partitions, with the first
#               partition having a swap label, taking 1/3 of the disk space
#               and the remainder being used as the second partition.
#                 /dev/xvdh':
#                   table_type: 'mbr'
#                   layout:
#                     - [33,82]
#                     - 66
#                   overwrite: True
#
#               When layout is "true" it means single partition the entire
#               device.
#
#               When layout is "false" it means don't partition or ignore
#               existing partitioning.
#
#               If layout is set to "true" and overwrite is set to "false",
#               it will skip partitioning the device without a failure.
#
#   overwrite=<BOOL>: This describes whether to ride with saftey's on and
#               everything holstered.
#
#               'false' is the default, which means that:
#                   1. The device will be checked for a partition table
#                   2. The device will be checked for a file system
#                   3. If either a partition of file system is found, then
#                       the operation will be _skipped_.
#
#               'true' is cowboy mode. There are no checks and things are
#                   done blindly. USE with caution, you can do things you
#                   really, really don't want to do.
#
#
# fs_setup: Setup the file system
# -------------------------------
#
# fs_setup describes the how the file systems are supposed to look.

fs_setup:
  - label: ephemeral0
    filesystem: 'ext3'
    device: 'ephemeral0'
    partition: 'auto'
  - label: mylabl2
    filesystem: 'ext4'
    device: '/dev/xvda1'
  - cmd: mkfs -t %(filesystem)s -L %(label)s %(device)s
    label: mylabl3
    filesystem: 'btrfs'
    device: '/dev/xvdh'

# The general format is:
#   fs_setup:
#     - label: <LABEL>
#       filesystem: <FS_TYPE>
#       device: <DEVICE>
#       partition: <PART_VALUE>
#       overwrite: <OVERWRITE>
#       replace_fs: <FS_TYPE>
#
# Where:
#   <LABEL>: The file system label to be used. If set to None, no label is
#     used.
#
#   <FS_TYPE>: The file system type. It is assumed that the there
#     will be a "mkfs.<FS_TYPE>" that behaves likes "mkfs". On a standard
#     Ubuntu Cloud Image, this means that you have the option of ext{2,3,4},
#     and vfat by default.
#
#   <DEVICE>: The device name. Special names of 'ephemeralX' or 'swap'
#     are allowed and the actual device is acquired from the cloud datasource.
#     When using 'ephemeralX' (i.e. ephemeral0), make sure to leave the
#     label as 'ephemeralX' otherwise there may be issues with the mounting
#     of the ephemeral storage layer.
#
#     If you define the device as 'ephemeralX.Y' then Y will be interpetted
#     as a partition value. However, ephermalX.0 is the _same_ as ephemeralX.
#
#   <PART_VALUE>:
#     Partition definitions are overwriten if you use the '<DEVICE>.Y' notation.
#
#     The valid options are:
#     "auto|any": tell cloud-init not to care whether there is a partition
#       or not. Auto will use the first partition that does not contain a
#       file system already. In the absence of a partition table, it will
#       put it directly on the disk.
#
#       "auto": If a file system that matches the specification in terms of
#       label, type and device, then cloud-init will skip the creation of
#       the file system.
#
#       "any": If a file system that matches the file system type and device,
#       then cloud-init will skip the creation of the file system.
#
#       Devices are selected based on first-detected, starting with partitions
#       and then the raw disk. Consider the following:
#           NAME     FSTYPE LABEL
#           xvdb
#           |-xvdb1  ext4
#           |-xvdb2
#           |-xvdb3  btrfs  test
#           \-xvdb4  ext4   test
#
#         If you ask for 'auto', label of 'test, and file system of 'ext4'
#         then cloud-init will select the 2nd partition, even though there
#         is a partition match at the 4th partition.
#
#         If you ask for 'any' and a label of 'test', then cloud-init will
#         select the 1st partition.
#
#         If you ask for 'auto' and don't define label, then cloud-init will
#         select the 1st partition.
#
#         In general, if you have a specific partition configuration in mind,
#         you should define either the device or the partition number. 'auto'
#         and 'any' are specifically intended for formating ephemeral storage or
#         for simple schemes.
#
#       "none": Put the file system directly on the device.
#
#       <NUM>: where NUM is the actual partition number.
#
#   <OVERWRITE>: Defines whether or not to overwrite any existing
#     filesystem.
#
#     "true": Indiscriminately destroy any pre-existing file system. Use at
#         your own peril.
#
#     "false": If an existing file system exists, skip the creation.
#
#   <REPLACE_FS>: This is a special directive, used for Microsoft Azure that
#     instructs cloud-init to replace a file system of <FS_TYPE>. NOTE:
#     unless you define a label, this requires the use of the 'any' partition
#     directive.
#
# Behavior Caveat: The default behavior is to _check_ if the file system exists.
#   If a file system matches the specification, then the operation is a no-op.

#cloud-config
#
# growpart entry is a dict, if it is not present at all
# in config, then the default is used ({'mode': 'auto', 'devices': ['/']})
#
#  mode:
#    values:
#     * auto: use any option possible (any available)
#             if none are available, do not warn, but debug.
#     * growpart: use growpart to grow partitions
#             if growpart is not available, this is an error.
#     * off, false
#
# devices:
#   a list of things to resize.
#   items can be filesystem paths or devices (in /dev)
#   examples:
#     devices: [/, /dev/vdb1]
#
# ignore_growroot_disabled:
#   a boolean, default is false.
#   if the file /etc/growroot-disabled exists, then cloud-init will not grow
#   the root partition.  This is to allow a single file to disable both
#   cloud-initramfs-growroot and cloud-init's growroot support.
#
#   true indicates that /etc/growroot-disabled should be ignored
#
growpart:
  mode: auto
  devices: ['/']
  ignore_growroot_disabled: false

#upstart-job

#cloud-boothook

#part-handler

def list_types():
    # return a list of mime-types that are handled by this module
    return(["text/plain", "text/go-cubs-go"])

def handle_part(data,ctype,filename,payload):
    # data: the cloudinit object
    # ctype: '__begin__', '__end__', or the specific mime-type of the part
    # filename: the filename for the part, or dynamically generated part if
    #           no filename is given attribute is present
    # payload: the content of the part (empty for begin or end)
    if ctype == "__begin__":
       print "my handler is beginning"
       return
    if ctype == "__end__":
       print "my handler is ending"
       return

    print "==== received ctype=%s filename=%s ====" % (ctype,filename)
    print payload
    print "==== end ctype=%s filename=%s" % (ctype, filename)

#part-handler

所谓实例数据，是指cloud-init用来配置实例的所有数据的集合。数据来源包括：

1. 云环境的元数据服务（metadata）
2. 用户定制的，提供给实例的config-drive
3. 镜像中的cloud-config seed files
4. 提供文件/元数据服务提供的vendor-data
5. 创建实例时提供的user-data

也就是说，上节的user-data是instance-data的一部分。

在OpenStack中，Flavor定义了实例的规格 —— 计算、内存、存储资源的硬件规格。Flavor也可以用来定义实例可以在哪些宿主机上启动。

# 确保虚拟机只能消耗50%的物理CPU能力
openstack flavor set FLAVOR-NAME \
    --property quota:cpu_quota=10000 \
    --property quota:cpu_period=20000

# 限制每秒最多写入10MB到磁盘
openstack flavor set FLAVOR-NAME \
    --property quota:disk_write_bytes_sec=10485760

允许使用的资源的配额可以针对项目（租户）或者用户进行设置。

使用下面的命令查看默认配额值：

openstack quota show --default

要查看某个用户的配额，执行：

nova quota-show --user USER --tenant PROJECT

主机聚合是一种对宿主机进行分区的机制，聚合中的主机常常具有类似的硬件/性能特征。一个主机可以属于多个聚合。

引入主机聚合最初是为了使用Xen资源池，但是现在作为一种机制，允许管理员将一系列键值对（属性）同时分配到多台主机。

主机聚合不直接对用户暴露，管理员可以将Flavor映射到主机聚合 —— 只需要为聚合设置匹配Flavor的额外规格说明的元数据，即可完成映射。

管理员也可以将一组主机划分为AZ，与主机聚合不同，AZ是面向用户的概念，而且主机仅能属于一个AZ。

要让Nova调度器支持主机聚合，需要配置：

[filter_scheduler]
enabled_filters=...,AggregateInstanceExtraSpecsFilter

# 在nova可用区中创建一个SSD磁盘的主机的聚合（后面假设聚合的ID为1）
openstack aggregate create --zone nova fast-io

# 为聚合设置元数据
openstack aggregate set --property ssd=true 1

# 添加主机到聚合
openstack aggregate add host 1 node1
openstack aggregate add host 1 node2


# 创建一个Flavor
openstack flavor create --id 6 --ram 8192 --disk 80 --vcpus 4 ssd.large

# 映射Flavor到聚合
openstack flavor set \
# 设置scope为aggregate_instance_extra_specs的额外规格，
#                                             键值和聚合元数据一致
    --property aggregate_instance_extra_specs:ssd=true ssd.large

在Placement中，Aggregate表示相关的资源提供者（resource provider）的分组。在Placement中，Nova的计算节点就是资源提供者。因此，节点在Placement中也可以被加入到聚合。

使用下面的命令，可以查询计算节点的UUID，并将其加入到Placement聚合中：

openstack --os-compute-api-version=2.53 hypervisor list
# +--------------------------------------+---------------------+-----------------+-----------------+-------+
# | ID                                   | Hypervisor Hostname | Hypervisor Type | Host IP         | State |
# +--------------------------------------+---------------------+-----------------+-----------------+-------+
# | 815a5634-86fb-4e1e-8824-8a631fee3e06 | node1               | QEMU            | 192.168.1.123   | up    |
# +--------------------------------------+---------------------+-----------------+-----------------+-------+

openstack --os-placement-api-version=1.2 resource provider aggregate set \
    --aggregate df4c74f3-d2c4-4991-b461-f1a678e1d161 \
    815a5634-86fb-4e1e-8824-8a631fee3e06

从Nova 18.0.0开始，添加主机到Host Aggregate中后，会自动修改对应的Placement聚合。不需要手工操作。删除时类似。

为了使用Placement来进行租户隔离，必须存在和Host Aggregate在UUID+成员关系上匹配的Placement Aggregate。调度过滤器AggregateMultiTenancyIsolation会使用聚合元数据。

需要设置 scheduler.limit_tenants_to_placement_aggregate  = True才能启用此特性。

配置示例：

# 创建主机聚合
openstack --os-compute-api-version=2.53 aggregate create myagg
# +-------------------+--------------------------------------+
# | Field             | Value                                |
# +-------------------+--------------------------------------+
# | availability_zone | None                                 |
# | created_at        | 2018-03-29T16:22:23.175884           |
# | deleted           | False                                |
# | deleted_at        | None                                 |
# | id                | 4                                    |
# | name              | myagg                                |
# | updated_at        | None                                 |
# | uuid              | 019e2189-31b3-49e1-aff2-b220ebd91c24 |
# +-------------------+--------------------------------------+

# 添加节点到主机聚合
openstack --os-compute-api-version=2.53 aggregate add host myagg node1

# 获取租户ID
openstack project list -f value | grep 'demo'
9691591f913949818a514f95286a6b90 demo

# 设置此聚合仅仅给租户使用
openstack aggregate set --property filter_tenant_id=9691591f913949818a514f95286a6b90 myagg

# 将主机加入到聚合
openstack --os-placement-api-version=1.2 resource provider aggregate set \
    --aggregate 019e2189-31b3-49e1-aff2-b220ebd91c24 \
    815a5634-86fb-4e1e-8824-8a631fee3e06

nova aggregate-cache-images my-aggregate image1 image2

Nova组件nova-scheduler负责决定在哪台计算节点上创建虚拟机。 在调度的场景下，术语host表示运行了nova-compute服务的哪些节点。

调度器的基本配置项是：

[scheduler]
driver = filter_scheduler

[filter_scheduler]
available_filters = nova.scheduler.filters.all_filters
enabled_filters = AvailabilityZoneFilter, ComputeFilter, ComputeCapabilitiesFilter, ImagePropertiesFilter, ServerGroupAntiAffinityFilter, ServerGroupAffinityFilter

默认的调度器驱动是 filter_scheduler，在默认配置下，该调度器选择满足以下所有条件的宿主机：

1. AvailabilityZoneFilter：位于请求的AZ中
2. ComputeFilter：能够服务请求
3. ComputeCapabilitiesFilter：满足实例类型的extra_specs（来自Flavor）
4. ImagePropertiesFilter：满足实例镜像属性中的架构、Hypervisor类型、虚拟机模式属性
5. ServerGroupAntiAffinityFilter：满足服务器组的反亲和设置——和组中的其它虚拟机不再同一宿主机上
6. ServerGroupAffinityFilter：满足服务器组亲和设置

当执行nova evacuate命令重建虚拟机时，调度器服务遵循管理员给出的目标宿主机，如果管理员没有指定目标宿主机，则由调度器来选择适当的宿主机。

从R版开始，调度器包含一个前置的过滤步骤，其目的时提升效率，减少候选的主机。

下面是一些常用的预过滤器：

前面我们提到过，nova.scheduler.filter_scheduler.FilterScheduler是默认的调度器（驱动）。它使用过滤器、权重来选择宿主机。

配置项 [filter_scheduler]/available_filters 列出调度器可以使用的过滤器集合，此配置项可以指定多次：

[filter_scheduler]
; 所有自带过滤器
available_filters = nova.scheduler.filters.all_filters
; 加上这个自己编写的过滤器
available_filters = myfilter.MyFilter

配置项 [filter_scheduler]/filter_scheduler.enabled_filters 列出当前nova-scheduler启用的过滤器。