Rancher通过基础设施中的Metadata服务为服务和容器提供数据。这些数据用来管理运行中的docker实例。这些数据可以通过调用基于HTTP的API来访问。这些数据包括创建容器,服务时的静态数据,也包括运行时数据,例如:在同一个服务里的其他容器的相关信息。

通过Rancher的Metadata服务,你可以进到任何使用Rancher托管网络的容器的命令行中,并查看运行在Rancher中的容器的信息。通过Metadata服务你可以获取容器,服务,容器所在的应用,容器所在的主机。Metadata是JSON格式的。

有多种方式可以将容器运行在Rancher托管网络中。Rancher网络的原理详见网络相关文档

如何获取Metadata

通过Rancher UI,你可以通过容器的下拉菜单的执行命令行进入运行命令界面。在鼠标悬停在容器上时,会显示容器名和右侧的下拉菜单。

你可以通过curl命令获取metadata信息。

# If curl is not installed, install it
$ apt-get install curl
# Basic curl command to obtain a plaintext response
$ curl http://rancher-metadata/<version>/<path>

curl请求的路径取决于你想要获取的metadata信息和格式。

Metadata 路径 描述
容器 self/container 提供运行命令的容器的metadata信息
容器所在服务 self/service 提供运行命令的容器对应服务的metadata信息
容器所在应用 self/stack 提供运行命令的容器对应应用的metadata信息
容器所在主机 self/host 提供运行命令的容器对应主机的metadata信息
其他容器 containers 提供所有容器的metadata信息。在纯文本格式时,提供了带上索引序号的所有容器。在JSON格式,提供了所有容器的所有metadata信息。使用序号或者名字。都可以获取指定容器的metadata信息。
其他服务 services 提供了所有服务的metadata信息。在纯文本格式时,提供了带上索引序号的所有服务。在JSON格式,提供了所有服务的所有metadata信息。在路径中使用序号或者名字,都可以获取指定服务的metadata信息。当访问容器详细信息时,在V1 (2015-07-25)只返回容器名称,但是在V2 (2015-12-19),容器实例也会返回。
其他应用 stacks/<stack-name> 提供了所有应用的metadata信息。在纯文本格式,提供了带上索引序号的所有应用。在JSON格式,提供了所有应用的所有metadata信息。使用序号或者名字。都可以获取指定容器的metadata信息。在路径中使用序号或者名字,都可以获取指定应用的metadata信息。当访问container详细信息时,在V1 (2015-07-25)只返回容器名称,但是在V2 (2015-12-19),容器实例也会返回。

Metadata的版本

curl命令中,我们强烈建议使用确定的版本号,但是你也可以选者latest

注意: 因为latest版本会包含最新的代码变动,各个版本的返回的数据可能不同,需要确认是否和你之前的代码能够兼容。

metadata的版本是基于日期的。

Version Reference Version
V2 2015-12-19
V1 2015-07-25

版本变化

V1 vs. V2

当通过http请求访问路径 /services/<service-name>/containers或者/stacks/<stack-name>/services/<service-name>/containers时, V1 返回容器名称,V2返回容器实例。更多详细信息在V2 metadata服务中提供。

范例

在Rancher中,名为foostack的应用包含一个有三个容器的服务 barservice

# 在V1只返回service的container names
$ curl --header 'Accept: application/json' 'http://rancher-metadata/2015-07-25/services/barservice/containers'
["foostack_barservice_1", "foostack_barservice_2", "foostack_barservice_1"]

# 在V2中返回service的container objects
$ curl --header 'Accept: application/json' 'http://rancher-metadata/2015-12-19/services/barservice/containers'
[{"create_index":1, "health_state":null,"host_uuid":...
...
# 获取service中所有容器的metadata信息
...
...}]

# 在V2,可以获取指定的container object
$ curl --header 'Accept: application/json' 'http://rancher-metadata/2015-12-19/services/barservice/containers/foostack_barservice_1'
[{"create_index":1, "health_state":null,"host_uuid":...
...
# 获取service中所有容器的metadata信息
...
...}]

# 通过路径 /stacks/<service-name>,可以访问services和containers

# 使用V1只返回service的container names
$ curl --header 'Accept: application/json' 'http://rancher-metadata/2015-07-25/stacks/foostack/services/barservice/containers'
["foostack_barservice_1", "foostack_barservice_2", "foostack_barservice_1"]

# 使用V2返回service的container objects
$ curl --header 'Accept: application/json' 'http://rancher-metadata/2015-12-19/stacks/foostack/services/barservice/containers'
[{"create_index":1, "health_state":null,"host_uuid":...
...
# 获取service中所有容器的metadata信息
...
...}]

纯文本 vs JSON

Metadata返回有纯文本和JSON两种格式,根据需要选择相应格式.

纯文本

通过curl命令,会获得请求路径的纯文本格式返回。你可以通过从第一层路径开始,层层推进,找到你需要的信息。

$ curl 'http://rancher-metadata/2015-12-19/self/container'
create_index
dns/
dns_search/
external_id
health_check_hosts/
health_state
host_uuid
hostname
ips/
labels/
memory_reservation
milli_cpu_reservation
name
network_from_container_uuid
network_uuid
ports/
primary_ip
primary_mac_address
service_index
service_name
stack_name
stack_uuid
start_count
state
system
uuid
$ curl 'http://rancher-metadata/2015-12-19/self/container/name'
# Note: Curl 不会返回新的行,只有一个数据时返回会输出在同一行
Default_Example_1$root@<container_id>
$ curl 'http://rancher-metadata/2015-12-19/self/container/label/io.rancher.stack.name'
Default$root@<container_id>
# Arrays可以通过序号或者名字访问
$ curl 'http://rancher-metadata/2015-12-19/services'
0=Example
# 使用序号或者名字
$ curl 'http://rancher-metadata/2015-12-19/services/0'
$ curl 'http://rancher-metadata/2015-12-19/services/Example'

JSON

JSON格式的返回可以通过在curl命令中增加header Accept: application/json

$ curl --header 'Accept: application/json' 'http://rancher-metadata/2015-12-19/self/container'
$ curl --header 'Accept: application/json' 'http://rancher-metadata/2015-12-19/self/stack'
# 获取stack中另一个service的信息
$ curl --header 'Accept: application/json' 'http://rancher-metadata/2015-12-19/services/<service-name>'

Metadata属性

容器

属性 描述
create_index 容器启动的序号 例如 2 代表的是服务中启动的第二个容器。注意: Create_index不会被重用。 如果你的服务包含两个容器,删除了第二个容器,下一个启动的容器的create_index会是3,即使服务中只包含2个容器
dns 容器的DNS服务器。
dns_search 容器的搜索域。
external_id 在主机上的Docker容器ID。
health_check_hosts 列出运行健康检查的主机的的UUIDs。
health_state 开启健康检查的容器的健康状态 健康检查
host_uuid Rancher Server分配给主机的唯一标识。
hostname 容器的hostname。
ips 支持多NIC时的IP列表
labels 容器标签列表。格式为key:value
memory_reservation 容器可以使用内存的软限制。
milli_cpu_reservation 容器可以使用CPU的软限制,值为正整数,1代表1/1000CPU。所以,1000 代表1个CPU,500代表半个CPU。
name 容器的名字。
network_from_container_uuid 容器网络来源的容器UUID。
network_uuid Rancher分配的网络唯一标识
ports 列出容器使用的端口。格式为: hostIP:publicIP:privateIP[/protocol].
primary_ip 容器IP
primary_mac_address 容器的MAC地址
service_index 服务中容器名称的最后一个数字
service_name 服务名称(如果存在)
stack_name 服务所在的应用的名称(如果存在)
stack_uuid Rancher分配的应用的唯一标识
start_count 容器启动的次数
state 容器状态
system 容器是否是Rancher基础设施服务
uuid Rancher分配容器唯一标识

服务

属性 描述
containers 列出服务中的容器名称
create_index 服务中最后启动的容器的序号 例如 2代表的是服务中启动的第二个容器。注意: Create_index不会被重用。 如果你的服务包含2个容器,删除了第二个容器,下一个启动的容器的create_index会是3,即使服务中只包含2个容器
expose 对主机暴露,但是不对外暴露的端口
external_ips 内部服务的IP列表
fqdn 服务的全称域名
health_check 服务的健康检查配置
hostname 内部服务的CNAME
kind Rancher的服务类型
labels 服务标签列表,格式为 key:value.
lb_config 负载均衡的配置
links 列出服务的链接,格式为stack_name/service∂_name:service_alias. links(例如 stack_name/service_name 获取所有链接)根据返回的service_alias,获取进一步的详细信息。
metadata 用户添加的metadata
name 服务名称
ports 服务使用的端口。格式hostIP:publicIP:privateIP[/protocol].
primary_service_name 主服务名,如果有从服务
scale 服务中容器的规模数量
sidekicks 从容器服务的名称列表
stack_name 服务所在的应用的名称
stack_uuid Rancher分配的应用的唯一标识
system 是否是基础设施服务
uuid Rancher分配的服务的唯一标识

应用

属性 描述
environment_name 应用所在的环境的名字
environment_uuid Rancher分配的环境的唯一标识
name 应用名称
services 应用中的服务列表
system 应用是否为基础设施服务
uuid Rancher分配的应用的唯一标识

主机

属性 描述
agent_ip Rancher Agent的IP,例如 CATTLE_AGENT_IP环境变量值。
hostname 主机的名称
labels 主机标签列表。格式为key:value.
local_storage_mb 主机的存储大小,单位为MB
memory 主机的内存大小,单位为MB
milli_cpu 主机的CPU。数值为整数,1代表1/1000的cpu。所以,1000代表1 CPU.
name 主机的名称
uuid Rancher分配的主机的唯一标识

为服务添加用户自定义Metadata

Rancher支持为服务添加用户metadata。现在只支持通过Rancher Compose添加,metadata是rancher-compose.yml的一部分。metadatakey对应的部分,yaml会被转化成在metadata-service中使用的JSON格式

Example rancher-compose.yml

service:
  # Scale of service
  scale: 3
  # User added metadata
  metadata:
    example:
      name: hello
      value: world
    example2:
      foo: bar

服务启动后,可以使用metadata服务在.../self/service/metadata或者.../services/<service_id>/metadata看到metadata数据

按照JSON格式查询

$ curl --header 'Accept: application/json' 'http://rancher-metadata/latest/self/service/metadata'
{"example":{"name":"hello","value":"world"},"example2":{"foo":"bar"}}

按照纯文本格式查询

$ curl 'http://rancher-metadata/latest/self/service/metadata'
example/
$ curl 'http://rancher-metadata/latest/self/service/metadata/example'
name
value
$ curl 'http://rancher-metadata/latest/self/service/metadata/example/name'
# # Note: Curl 不会返回新的行,只有一个数据时返回会输出在同一行
hello$root@<container_id>