kcli-plan-authoring

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

kcli Plan Authoring

kcli计划文件编写

Plan File Structure

计划文件结构

Plans are YAML files with Jinja2 templating. Resources are defined as top-level keys with a

type

field.

yaml

parameters:
  param1: value1
  param2: value2

resourcename:
  type: resourcetype
  key1: value1
  key2: {{ param1 }}

计划文件是带有Jinja2模板的YAML文件。资源以顶级键的形式定义，并包含

type

字段。

yaml

parameters:
  param1: value1
  param2: value2

resourcename:
  type: resourcetype
  key1: value1
  key2: {{ param1 }}

Resource Types

资源类型

VM (default if no type specified)

VM（未指定type时的默认类型）

yaml

myvm:
  image: fedora40
  memory: 4096
  numcpus: 2
  disks:
    - size: 20
    - size: 10
      pool: otherpool
  nets:
    - name: default
    - name: mynet
      ip: 192.168.1.10
      netmask: 255.255.255.0
      gateway: 192.168.1.1
  cmds:
    - echo hello > /tmp/test
  files:
    - path: /etc/myconfig
      content: |
        key=value

yaml

myvm:
  image: fedora40
  memory: 4096
  numcpus: 2
  disks:
    - size: 20
    - size: 10
      pool: otherpool
  nets:
    - name: default
    - name: mynet
      ip: 192.168.1.10
      netmask: 255.255.255.0
      gateway: 192.168.1.1
  cmds:
    - echo hello > /tmp/test
  files:
    - path: /etc/myconfig
      content: |
        key=value

Profile

yaml

myprofile:
  type: profile
  image: centos9stream
  memory: 2048
  numcpus: 2
  disks:
    - 10
  nets:
    - default

yaml

myprofile:
  type: profile
  image: centos9stream
  memory: 2048
  numcpus: 2
  disks:
    - 10
  nets:
    - default

Network

yaml

mynetwork:
  type: network
  cidr: 192.168.100.0/24
  dhcp: true
  nat: true
  domain: mylab.local

yaml

mynetwork:
  type: network
  cidr: 192.168.100.0/24
  dhcp: true
  nat: true
  domain: mylab.local

Image

yaml

myimage:
  type: image
  url: https://example.com/image.qcow2
  pool: default

yaml

myimage:
  type: image
  url: https://example.com/image.qcow2
  pool: default

Container

yaml

mycontainer:
  type: container
  image: nginx:latest
  ports:
    - 8080:80

yaml

mycontainer:
  type: container
  image: nginx:latest
  ports:
    - 8080:80

Jinja2 Templating

Jinja2模板使用

Parameter Substitution

参数替换

yaml

parameters:
  cluster_name: mycluster
  worker_count: 3

{{ cluster_name }}-master:
  image: rhcos
  
{% for i in range(worker_count) %}
{{ cluster_name }}-worker-{{ i }}:
  image: rhcos
{% endfor %}

yaml

parameters:
  cluster_name: mycluster
  worker_count: 3

{{ cluster_name }}-master:
  image: rhcos
  
{% for i in range(worker_count) %}
{{ cluster_name }}-worker-{{ i }}:
  image: rhcos
{% endfor %}

Conditionals

条件判断

yaml

parameters:
  enable_storage: true

myvm:
  image: fedora40
{% if enable_storage %}
  disks:
    - size: 100
{% endif %}

yaml

parameters:
  enable_storage: true

myvm:
  image: fedora40
{% if enable_storage %}
  disks:
    - size: 100
{% endif %}

Custom Filters

自定义过滤器

kcli provides custom Jinja2 filters in

kvirt/jinjafilters/jinjafilters.py

Path/File Filters:

```
basename
```
- Get filename from path
```
dirname
```
- Get directory from path
```
diskpath
```
- Convert to /dev/ path if needed
```
exists
```
- Check if file/path exists
```
pwd_path
```
- Handle workdir paths in containers
```
real_path
```
- Get real/absolute path
```
read_file
```
- Read file contents

String/Data Filters:

```
none
```
- Return empty string if None
```
type
```
- Return type name (string, int, dict, list)
```
base64
```
- Base64 encode value
```
certificate
```
- Wrap in BEGIN/END CERTIFICATE if needed
```
count
```
- Count occurrences of character

Kubernetes/Cluster Filters:

```
kubenodes
```
- Generate node names for cluster
```
defaultnodes
```
- Generate default node list
```
has_ctlplane
```
- Check if list has ctlplane/master entries

Version/Release Filters:

```
github_version
```
- Get latest version from GitHub releases
```
min_ocp_version
```
- Compare OpenShift versions (minimum)
```
max_ocp_version
```
- Compare OpenShift versions (maximum)

Network Filters:

```
local_ip
```
- Get local IP for network interface
```
network_ip
```
- Get IP from network CIDR
```
ipv6_wrap
```
- Wrap IPv6 addresses in brackets

Utility Filters:

```
kcli_info
```
- Get VM info via kcli command
```
find_manifests
```
- Find YAML manifests in directory
```
wait_crd
```
- Generate wait script for CRD creation
```
wait_csv
```
- Generate wait script for CSV readiness
```
filter_bgp_peers
```
- Filter BGP peer list

Standard Jinja2 filters (default, join, upper, lower, etc.) also work

kcli在

kvirt/jinjafilters/jinjafilters.py

中提供了自定义Jinja2过滤器：

路径/文件过滤器：

```
basename
```
- 从路径中获取文件名
```
dirname
```
- 从路径中获取目录名
```
diskpath
```
- 按需转换为/dev/路径
```
exists
```
- 检查文件/路径是否存在
```
pwd_path
```
- 处理容器中的工作目录路径
```
real_path
```
- 获取真实/绝对路径
```
read_file
```
- 读取文件内容

字符串/数据过滤器：

```
none
```
- 如果值为None则返回空字符串
```
type
```
- 返回类型名称（string、int、dict、list）
```
base64
```
- Base64编码值
```
certificate
```
- 按需包裹BEGIN/END CERTIFICATE
```
count
```
- 统计字符出现次数

Kubernetes/集群过滤器：

```
kubenodes
```
- 生成集群节点名称
```
defaultnodes
```
- 生成默认节点列表
```
has_ctlplane
```
- 检查列表中是否包含ctlplane/master条目

版本/发布过滤器：

```
github_version
```
- 从GitHub发布中获取最新版本
```
min_ocp_version
```
- 比较OpenShift版本（最小值）
```
max_ocp_version
```
- 比较OpenShift版本（最大值）

网络过滤器：

```
local_ip
```
- 获取网络接口的本地IP
```
network_ip
```
- 从网络CIDR中获取IP
```
ipv6_wrap
```
- 用方括号包裹IPv6地址

实用工具过滤器：

```
kcli_info
```
- 通过kcli命令获取VM信息
```
find_manifests
```
- 在目录中查找YAML清单
```
wait_crd
```
- 生成CRD创建的等待脚本
```
wait_csv
```
- 生成CSV就绪的等待脚本
```
filter_bgp_peers
```
- 过滤BGP对等体列表

标准Jinja2过滤器（default、join、upper、lower等）同样适用

Parameter Files

参数文件

Create

kcli_parameters.yml

alongside your plan:

yaml

cluster_name: prod
worker_count: 5
memory: 8192

Override at runtime:

bash

kcli create plan -f myplan.yml -P worker_count=10 myplan

在计划文件旁创建

kcli_parameters.yml

：

yaml

cluster_name: prod
worker_count: 5
memory: 8192

在运行时覆盖参数：

bash

kcli create plan -f myplan.yml -P worker_count=10 myplan

Common VM Parameters

常见VM参数

Parameter	Default	Description
`numcpus`	2	Number of CPUs
`memory`	512	Memory in MB
`pool`	default	Storage pool
`image`	None	Base image name
`nets`	[default]	Network list
`disks`	[{size:10}]	Disk list
`cmds`	[]	Post-boot commands
`files`	[]	Files to inject
`keys`	[]	SSH public keys
`start`	true	Auto-start VM
`cloudinit`	true	Enable cloud-init

参数	默认值	说明
`numcpus`	2	CPU数量
`memory`	512	内存（MB）
`pool`	default	存储池
`image`	None	基础镜像名称
`nets`	[default]	网络列表
`disks`	[{size:10}]	磁盘列表
`cmds`	[]	开机后执行的命令
`files`	[]	要注入的文件
`keys`	[]	SSH公钥
`start`	true	自动启动VM
`cloudinit`	true	启用cloud-init

Plan Execution

计划执行

bash

undefined

bash

undefined

Create plan

创建计划

kcli create plan -f myplan.yml myplanname

Create with parameter overrides

覆盖参数创建计划

kcli create plan -f myplan.yml -P memory=4096 -P image=fedora40 myplanname

List plans

列出计划

kcli list plan

Get plan info

获取计划信息

kcli info plan myplanname

Delete plan (and all its resources)

删除计划（及其所有资源）

kcli delete plan myplanname

Update existing plan

更新现有计划

kcli update plan -f myplan.yml myplanname

undefined

kcli update plan -f myplan.yml myplanname

undefined

Debugging Plans

计划调试

Validate YAML syntax - Use

python -c "import yaml; yaml.safe_load(open('plan.yml'))"

Check Jinja2 rendering - Look for unbalanced
```
{{
```
```
}}
```
or
```
{% %}
```
Run with debug -
```
kcli -d create plan -f plan.yml test
```
Check dependencies - Ensure images/networks exist before VMs reference them

验证YAML语法 - 使用

python -c "import yaml; yaml.safe_load(open('plan.yml'))"

检查Jinja2渲染 - 查找未匹配的
```
{{
```
```
}}
```
或
```
{% %}
```
启用调试模式运行 -
```
kcli -d create plan -f plan.yml test
```
检查依赖项 - 确保VM引用的镜像/网络已存在

Example: Multi-VM Plan

示例：多VM计划

yaml

parameters:
  domain: lab.local
  base_image: centos9stream

labnetwork:
  type: network
  cidr: 10.0.0.0/24
  dhcp: true
  domain: {{ domain }}

webserver:
  image: {{ base_image }}
  memory: 2048
  nets:
    - labnetwork
  cmds:
    - dnf -y install nginx
    - systemctl enable --now nginx

database:
  image: {{ base_image }}
  memory: 4096
  disks:
    - size: 20
    - size: 50
  nets:
    - labnetwork
  cmds:
    - dnf -y install postgresql-server
    - postgresql-setup --initdb

yaml

parameters:
  domain: lab.local
  base_image: centos9stream

labnetwork:
  type: network
  cidr: 10.0.0.0/24
  dhcp: true
  domain: {{ domain }}

webserver:
  image: {{ base_image }}
  memory: 2048
  nets:
    - labnetwork
  cmds:
    - dnf -y install nginx
    - systemctl enable --now nginx

database:
  image: {{ base_image }}
  memory: 4096
  disks:
    - size: 20
    - size: 50
  nets:
    - labnetwork
  cmds:
    - dnf -y install postgresql-server
    - postgresql-setup --initdb