深入理解 cloud-init：配置、流程与数据源

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12

# meta-data 示例
instance-id: i-87018aed              # 必需：实例唯一标识
local-hostname: web-server-01        # 建议：主机名
public-keys:                         # 建议：SSH 公钥
  - ssh-rsa AAAAB3NzaC1yc2EAAAADAQABAAABAQ...
placement:
  availability-zone: us-east-1a     # 可用区
local-ipv4: 10.223.26.178           # 内网 IP
public-ipv4: 184.72.174.120         # 公网 IP
instance-type: m1.large             # 实例类型
ami-id: ami-fd4aa494                # 镜像 ID
security-groups: default            # 安全组

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42

#cloud-config

# 用户管理
users:
  - name: deploy
    sudo: ALL=(ALL) NOPASSWD:ALL
    shell: /bin/bash
    ssh_authorized_keys:
      - ssh-rsa AAAAB3NzaC1yc2EAAAADAQABAAABAQ...

# 软件包安装
packages:
  - nginx
  - docker.io
  - python3-pip

# 写文件
write_files:
  - path: /etc/nginx/sites-available/app
    content: |
      server {
          listen 80;
          server_name _;
          location / {
              proxy_pass http://127.0.0.1:8000;
          }
      }
    permissions: '0644'

# 运行命令
runcmd:
  - [ systemctl, enable, nginx ]
  - [ systemctl, start, nginx ]
  - docker run -d -p 8000:8000 myapp:latest

# 挂载点
mounts:
  - [ /dev/sdb, /data, ext4, defaults, 0, 2 ]

# SSH 配置
ssh_authorized_keys:
  - ssh-rsa AAAAB3NzaC1yc2EAAAADAQABAAABAQ...

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11

#!/bin/bash
set -euo pipefail

echo "=== 开始初始化 ==="
apt-get update
apt-get install -y nginx docker.io

systemctl enable nginx docker
systemctl start nginx docker

echo "=== 初始化完成 ==="

1
2
3

#cloud-boothook
# 这个脚本在 Local 阶段执行，早于网络配置
echo "Boothook executed at $(date)" > /tmp/boothook.log

1
2
3
4
5

# ds-identify 检测逻辑
1. 检查 DMI 信息（制造商、产品名）
2. 检查 /sys/class/dmi/id/product_uuid
3. 检查内核命令行参数
4. 匹配已知云平台特征

1
2
3

# systemd 依赖关系
Before=network-pre.target
After=hv_kvp_daemon.service

1
2
3
4
5
6
7

class DataSource:
    network_config_sources = (
        NetworkConfigSource.CMD_LINE,      # 1. 内核命令行
        NetworkConfigSource.INITRAMFS,      # 2. Initramfs
        NetworkConfigSource.SYSTEM_CFG,     # 3. 系统配置
        NetworkConfigSource.DS,             # 4. 数据源
    )

1
2
3
4
5

# systemd 依赖关系
After=cloud-init-local.service
After=NetworkManager.service
Before=network-online.target
Before=sshd.service

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19

def process_user_data(raw_data):
    # 1. Gzip 解压
    if raw_data.startswith(b'\x1f\x8b'):
        raw_data = gzip.decompress(raw_data)
    
    # 2. Mime Multi Part 处理
    if is_mime_multipart(raw_data):
        for part in parse_mime(raw_data):
            process_user_data(part)  # 递归处理
    
    # 3. 根据开头标识分发处理
    if raw_data.startswith('#!'):
        handle_shell_script(raw_data)
    elif raw_data.startswith('#cloud-config'):
        handle_cloud_config(raw_data)
    elif raw_data.startswith('#cloud-boothook'):
        handle_boothook(raw_data)
    elif raw_data.startswith('#include'):
        handle_include(raw_data)

1

After=network-online.target

1
2
3
4
5
6
7
8
9

cloud_config_modules:
  - ssh_import_id
  - keyboard
  - locale
  - set_passwords
  - rsyslog
  - ca-certs
  - ntp
  - timezone

1
2

# 在大多数服务之后运行
Before=rc-local.service

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14

def check_if_new_instance_id(self):
    # 从缓存读取上次的 instance-id
    previous_id = self.get_previous_instance_id()
    
    # 从数据源获取当前 instance-id
    current_id = self.datasource.get_instance_id()
    
    # 比较
    if previous_id == NO_PREVIOUS_INSTANCE_ID:
        return True  # 首次启动
    elif previous_id != current_id:
        return True  # 新实例（从镜像创建）
    else:
        return False  # 后续启动

1
2
3

/var/lib/cloud/instance/obj.pkl           # Pickled 对象缓存
/var/lib/cloud/data/previous-instance-id  # 上次 instance ID
/var/lib/cloud/data/instance-id           # 当前 instance ID

1
2
3
4
5

/var/lib/cloud/instance/sem/
├── config-ssh          # 已执行标记
├── config-users_groups
├── config-runcmd
└── scripts-per-instance/

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20

def run_module(module_name, freq):
    sem_file = f"/var/lib/cloud/instance/sem/{module_name}"
    
    if freq == PER_ALWAYS:
        return True  # 总是执行
    
    if freq == PER_INSTANCE:
        if os.path.exists(sem_file):
            return False  # 已执行，跳过
        else:
            touch(sem_file)
            return True
    
    if freq == PER_ONCE:
        global_sem = f"/var/lib/cloud/sem/{module_name}"
        if os.path.exists(global_sem):
            return False
        else:
            touch(global_sem)
            return True

1
2

# /etc/cloud/cloud.cfg
manual_cache_clean: true

1
2
3
4
5

# 手动清理缓存（重置实例）
cloud-init clean

# 或手动删除
rm -rf /var/lib/cloud/instance/*

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27

class DataSource(metaclass=abc.ABCMeta):
    # 基本属性
    dsname = "_undef"           # 数据源名称
    dsmode = DSMODE_NETWORK    # 运行模式
    
    # 必须实现的方法
    @abc.abstractmethod
    def _get_data(self):
        """获取数据，返回 True/False 表示是否成功"""
        pass
    
    # 可选重写的方法
    def get_userdata(self):
        """返回 user-data"""
        return self.userdata
    
    def get_instance_id(self):
        """返回 instance-id"""
        return self.metadata.get('instance-id')
    
    def get_public_ssh_keys(self):
        """返回 SSH 公钥列表"""
        return self.metadata.get('public-keys', [])
    
    def get_network_config(self):
        """返回网络配置"""
        return self._network_config

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12

def _get_data(self):
    sources = [
        self._get_data_from_dmi(),        # 1. DMI 序列号
        self._get_data_from_cmdline(),    # 2. 内核命令行
        self._get_data_from_seed_dir(),   # 3. 种子目录
        self._get_data_from_iso(),        # 4. ISO 镜像
    ]
    
    for source in sources:
        if source:
            return True
    return False

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22

# 1. 创建种子目录
sudo mkdir -p /var/lib/cloud/seed/nocloud

# 2. 写入 meta-data
cat <<EOF | sudo tee /var/lib/cloud/seed/nocloud/meta-data
instance-id: my-test-instance
local-hostname: test-vm
EOF

# 3. 写入 user-data
cat <<EOF | sudo tee /var/lib/cloud/seed/nocloud/user-data
#cloud-config
packages:
  - nginx
runcmd:
  - systemctl enable nginx
  - systemctl start nginx
EOF

# 4. 重置并重新运行
sudo cloud-init clean
sudo cloud-init init

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37

/var/lib/cloud/
├── instance -> instances/i-87018aed/     # 当前实例符号链接
├── instances/
│   └── i-87018aed/
│       ├── boot-finished                 # 启动完成标记
│       ├── cloud-config.txt              # 合并后的完整配置
│       ├── user-data.txt                 # 原始 user-data
│       ├── user-data.txt.i               # 处理后的 user-data
│       ├── obj.pkl                       # Pickled 对象缓存
│       ├── datasource                    # 数据源信息
│       ├── sem/                          # 信号量目录（执行标记）
│       │   ├── config-ssh
│       │   ├── config-users_groups
│       │   ├── scripts-per-instance
│       │   └── ...
│       ├── scripts/                      # 脚本目录
│       │   ├── per-instance/            # 每实例执行一次
│       │   ├── per-boot/               # 每次启动执行
│       │   ├── per-once/                # 永远执行一次
│       │   └── user/                    # 用户脚本
│       ├── data/                         # 实例数据
│       └── handlers/                     # 处理器状态
├── scripts/
│   ├── per-instance/                     # 全局 per-instance 脚本
│   ├── per-boot/                         # 全局 per-boot 脚本
│   └── per-once/                         # 全局 per-once 脚本
├── seed/
│   └── nocloud/                          # NoCloud 种子目录
│       ├── meta-data
│       └── user-data
├── sem/                                  # 全局信号量
│   └── scripts.once
├── data/                                 # 全局数据
│   ├── previous-datasource
│   ├── previous-instance-id
│   └── previous-hostname
└── handlers/                             # 全局处理器

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26

{
  "v1": {
    "init-local": {
      "errors": [],
      "start": 1712345678.123,
      "end": 1712345679.456
    },
    "init": {
      "errors": [],
      "start": 1712345680.789,
      "end": 1712345685.012
    },
    "modules-config": {
      "errors": [],
      "start": 1712345686.345,
      "end": 1712345690.678
    },
    "modules-final": {
      "errors": [],
      "start": 1712345691.901,
      "end": 1712345695.234
    },
    "datasource": "DataSourceEc2",
    "stage": null
  }
}

1
2
3
4
5
6

{
  "v1": {
    "datasource": "DataSourceEc2",
    "errors": []
  }
}

1
2
3
4
5
6
7

# /etc/cloud/cloud.cfg
cloud_config_modules:
  - mounts               # 默认 PER_INSTANCE
  - ssh                  # 默认 PER_INSTANCE
  - [apt_update_upgrade, always]  # 强制 PER_ALWAYS
  - runcmd
  - puppet

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89

#cloud-config

# 1. 系统设置
hostname: web-server-01
fqdn: web-server-01.example.com
manage_etc_hosts: true
timezone: Asia/Shanghai
locale: en_US.UTF-8

# 2. 用户管理
users:
  - name: deploy
    primary_group: deploy
    sudo: ALL=(ALL) NOPASSWD:ALL
    shell: /bin/bash
    groups: [docker, sudo]
    ssh_authorized_keys:
      - ssh-rsa AAAAB3NzaC1yc2EAAAADAQABAAABAQC7...

  - name: app
    system: true
    shell: /usr/sbin/nologin
    home: /opt/app

# 3. 软件包
package_update: true
package_upgrade: false
packages:
  - nginx
  - docker.io
  - docker-compose
  - python3-pip
  - git

# 4. 写文件
write_files:
  - path: /etc/nginx/sites-available/app
    content: |
      upstream backend {
          server 127.0.0.1:8000;
      }
      server {
          listen 80;
          server_name _;
          location / {
              proxy_pass http://backend;
              proxy_set_header Host $host;
              proxy_set_header X-Real-IP $remote_addr;
          }
      }
    permissions: '0644'

  - path: /opt/app/docker-compose.yml
    content: |
      version: '3'
      services:
        web:
          image: myapp:latest
          ports:
            - "8000:8000"
          restart: always
    permissions: '0644'
    owner: app:app

# 5. 挂载点
mounts:
  - [ /dev/sdb, /data, ext4, "defaults,noatime", 0, 2 ]
  - [ /dev/sdc, /logs, ext4, "defaults,noatime", 0, 2 ]

# 6. 运行命令
runcmd:
  # 启用服务
  - systemctl enable nginx docker
  - systemctl start nginx docker
  
  # 配置 Nginx
  - ln -sf /etc/nginx/sites-available/app /etc/nginx/sites-enabled/
  - rm -f /etc/nginx/sites-enabled/default
  - systemctl reload nginx
  
  # 启动应用
  - cd /opt/app && docker-compose up -d

# 7. SSH 配置
ssh_authorized_keys:
  - ssh-rsa AAAAB3NzaC1yc2EAAAADAQABAAABAQC7...

# 8. 最终消息
final_message: "云实例初始化完成！运行时间: $UPTIME 秒"

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26

# 1. 创建种子目录
sudo mkdir -p /var/lib/cloud/seed/nocloud

# 2. 写入配置
cat <<EOF | sudo tee /var/lib/cloud/seed/nocloud/meta-data
instance-id: test-vm-001
local-hostname: test-vm
EOF

cat <<EOF | sudo tee /var/lib/cloud/seed/nocloud/user-data
#cloud-config
packages:
  - nginx
runcmd:
  - systemctl enable nginx
  - systemctl start nginx
EOF

# 3. 清理并重新初始化
sudo cloud-init clean --logs
sudo cloud-init init --local
sudo cloud-init init

# 4. 检查状态
cloud-init status --wait
cloud-init query -f '{{ instance_data }}'

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20

# 查看执行日志
journalctl -u cloud-init-local.service
journalctl -u cloud-init-network.service
journalctl -u cloud-config.service
journalctl -u cloud-final.service

# 查看 cloud-init 日志
cat /var/log/cloud-init-output.log
cat /var/log/cloud-init.log

# 分析执行时间
cloud-init analyze show
cloud-init analyze dump

# 查询实例数据
cloud-init query instance-id
cloud-init query ds.meta_data

# 验证配置语法
cloud-init schema --config-file user-data