1.2. ClusterInstance API

1.2.1. 概述

本文档介绍了与 Red Hat Advanced Cluster Management for Kubernetes 的 ClusterInstance 资源相关的 API 信息。ClusterInstance 资源有 4 个可用的请求：create、query、delete 和 update。

1.2.1.1. 版本信息

版本 : 2.12.0

1.2.1.2. URI scheme

BasePath : /kubernetes/apis
Schemes : HTTPS

1.2.1.3. Tags

SiteConfig.open-cluster-management.io : 创建和管理集群

1.2.2. 路径

1.2.2.1. 查询所有集群

GET /siteconfig.open-cluster-management.io/v1alpha1/{clusterinstance_namespace}/{clusterinstance_name}

1.2.2.1.1. 描述

查询集群以获取更多详细信息。

1.2.2.1.2. 参数

类型	Name	描述	模式
标头	COOKIE 必需	身份验证：Bearer {ACCESS_TOKEN} ; ACCESS_TOKEN 是用户访问令牌。	字符串
路径	clusterinstance_namespace required	要查询的 ClusterInstance 的命名空间。	字符串
路径	clusterinstance_name required	要查询的 ClusterInstance 的名称。	字符串

1.2.2.1.3. 响应

HTTP 代码	描述	模式
200	成功	无内容
403	禁止访问	无内容
404	未找到资源	无内容
500	内部服务错误	无内容
503	服务不可用	无内容

1.2.2.1.4. 使用

clusterinstance/json

1.2.2.1.5. Tags

siteconfig.open-cluster-management.io

1.2.2.2. 创建安装清单

POST /siteconfig.open-cluster-management.io/v1alpha1/<clusterinstance_namespace>/<clusterinstance_name>

1.2.2.2.1. 描述

使用 SiteConfig operator 创建安装清单，供您选择安装方法。

1.2.2.2.2. 参数

类型	Name	描述	模式
标头	COOKIE 必需	身份验证：Bearer {ACCESS_TOKEN} ; ACCESS_TOKEN 是用户访问令牌。	字符串
Body	body 必需	描述要创建的安装清单的参数。	ClusterInstance
路径	clusterinstance_namespace required	要使用的 ClusterInstance 的命名空间。	字符串
路径	clusterinstance_name required	要使用的 ClusterInstance 的名称。	字符串

1.2.2.2.3. 响应

HTTP 代码	描述	模式
200	成功	无内容
403	禁止访问	无内容
404	未找到资源	无内容
500	内部服务错误	无内容
503	服务不可用	无内容

1.2.2.2.4. 使用

clusterinstance/json

1.2.2.2.5. Tags

siteconfig.open-cluster-management.io

1.2.2.2.6. HTTP 请求示例

1.2.2.2.6.1. 请求正文

{
    "apiVersion": "siteconfig.open-cluster-management.io/v1alpha1",
    "kind": "ClusterInstance",
    "metadata": {
        "name": "site-sno-du-1",
        "namespace": "site-sno-du-1"
    },
    "spec": {
        "baseDomain": "example.com",
        "pullSecretRef": {
            "name": "pullSecretName"
        },
        "sshPublicKey": "ssh-rsa ",
        "clusterName": "site-sno-du-1",
        "proxy": {
            "noProxys": "foobar"
        },
        "caBundleRef": {
            "name": "my-bundle-ref"
        },
        "extraManifestsRefs": [
            {
                "name": "foobar1"
            },
            {
                "name": "foobar2"
            }
        ],
        "networkType": "OVNKubernetes",
        "installConfigOverrides": "{\"capabilities\":{\"baselineCapabilitySet\": \"None\", \"additionalEnabledCapabilities\": [ \"marketplace\", \"NodeTuning\" ] }}",
        "extraLabels": {
            "ManagedCluster": {
                "group-du-sno": "test",
                "common": "true",
                "sites": "site-sno-du-1"
            }
        },
        "clusterNetwork": [
            {
                "cidr": "203.0.113.0/24",
                "hostPrefix": 23
            }
        ],
        "machineNetwork": [
            {
                "cidr": "203.0.113.0/24"
            }
        ],
        "serviceNetwork": [
            {
                "cidr": "203.0.113.0/24"
            }
        ],
        "additionalNTPSources": [
            "NTP.server1",
            "198.51.100.100"
        ],
        "ignitionConfigOverride": "{\"ignition\": {\"version\": \"3.1.0\"}, \"storage\": {\"files\": [{\"path\": \"/etc/containers/registries.conf\", \"overwrite\": true, \"contents\": {\"source\": \"data:text/plain;base64,foobar==\"}}]}}",
        "diskEncryption": {
            "type": "nbde",
            "tang": [
                {
                    "url": "http://192.0.2.5:7500",
                    "thumbprint": "1234567890"
                }
            ]
        },
        "clusterType": "SNO",
        "templateRefs": [
            {
                "name": "ai-cluster-templates-v1",
                "namespace": "rhacm"
            }
        ],
        "nodes": [
            {
                "hostName": "node1",
                "role": "master",
                "templateRefs": [
                    {
                        "name": "ai-node-templates-v1",
                        "namespace": "rhacm"
                    }
                ],
                "ironicInspect": "",
                "bmcAddress": "idrac-virtualmedia+https://203.0.113.100/redfish/v1/Systems/System.Embedded.1",
                "bmcCredentialsName": {
                    "name": "<bmcCredentials_secre_name>"
                },
                "bootMACAddress": "00:00:5E:00:53:00",
                "bootMode": "UEFI",
                "installerArgs": "[\"--append-karg\", \"nameserver=8.8.8.8\", \"-n\"]",
                "ignitionConfigOverride": "{\"ignition\": {\"version\": \"3.1.0\"}, \"storage\": {\"files\": [{\"path\": \"/etc/containers/registries.conf\", \"overwrite\": true, \"contents\": {\"source\": \"data:text/plain;base64,foobar==\"}}]}}",
                "nodeNetwork": {
                    "interfaces": [
                        {
                            "name": "eno1",
                            "macAddress": "00:00:5E:00:53:01"
                        }
                    ],
                    "config": {
                        "interfaces": [
                            {
                                "name": "eno1",
                                "type": "ethernet",
                                "ipv4": {
                                    "enabled": true,
                                    "dhcp": false,
                                    "address": [
                                        {
                                            "ip": "192.0.2.1",
                                            "prefix-length": 24
                                        }
                                    ]
                                },
                                "ipv6": {
                                    "enabled": true,
                                    "dhcp": false,
                                    "address": [
                                        {
                                            "ip": "2001:0DB8:0:0:0:0:0:1",
                                            "prefix-length": 32
                                        }
                                    ]
                                }
                            }
                        ],
                        "dns-resolver": {
                            "config": {
                                "server": [
                                    "198.51.100.1"
                                ]
                            }
                        },
                        "routes": {
                            "config": [
                                {
                                    "destination": "0.0.0.0/0",
                                    "next-hop-address": "203.0.113.255",
                                    "next-hop-interface": "eno1",
                                    "table-id": 254
                                }
                            ]
                        }
                    }
                }
            }
        ]
    }
}

1.2.2.3. 查询单个集群

GET /siteconfig.open-cluster-management.io/v1alpha1/<clusterinstance_namespace>/<clusterinstance_name>

1.2.2.3.1. 描述

查询单个集群以获取更多详细信息。

1.2.2.3.2. 参数

类型	Name	描述	模式
标头	COOKIE 必需	身份验证：Bearer {ACCESS_TOKEN} ; ACCESS_TOKEN 是用户访问令牌。	字符串
路径	clusterinstance_namespace required	要查询的 ClusterInstance 的命名空间。	字符串
路径	clusterinstance_name required	要查询的 ClusterInstance 的名称。	字符串

1.2.2.3.3. 响应

HTTP 代码	描述	模式
200	成功	无内容
403	禁止访问	无内容
404	未找到资源	无内容
500	内部服务错误	无内容
503	服务不可用	无内容

1.2.2.3.4. Tags

siteconfig.open-cluster-management.io

1.2.3. 定义

1.2.3.1. ClusterInstance

重要： 包含字段仅与特定的安装流相关。通过检查相关文档，验证适用于您选择的安装方法的字段。有关辅助安装程序和基于镜像的安装，请参阅以下文档：

Name	描述	模式
apiVersion 必需	`ClusterInstance` 的版本化模式。	字符串
kind 必需	代表 REST 资源的字符串值。	字符串
metadata 必需	`ClusterInstance` 的元数据。	对象
spec 必需	`ClusterInstance` 的规格。	spec
status 必需	`ClusterInstance` 的状态。	Status 对象

spec

Name	描述	模式
additionalNTPSources 可选	指定需要添加到所有集群主机的 NTP 源。它们被添加到任何通过其他方法配置的 NTP 源中。	数组
baseDomain required	指定用于部署集群的基域。	字符串
caBundleRef optional	引用包含主机可信证书捆绑包的 `ConfigMap` 对象。`ConfigMap` 对象中的 `tls-ca-bundle.pem` 条目被写入 `/etc/pki/ca-trust/extracted/pem/tls-ca-bundle.pem`。	字符串
clusterName 必需	指定集群的名称。	字符串
clusterNetwork optional	指定 pod 的 IP 地址池列表。	数组
clusterType optional	指定集群类型。支持以下值： `SNO` single-node OpenShift `HighlyAvailable` Multi-node OpenShift	字符串
cpuPartitioningMode optional	决定在安装时为 CPU 工作负载分区设置的集群。通过将 `cpuPartitioningMode` 的值设置为 `AllNodes` 来配置工作负载分区。要完成配置，请在 `PerformanceProfile` CR 中指定 `isolated` 和 `reserved` CPU。默认值为 `None`。	字符串
diskEncryption optional	为集群启用或禁用磁盘加密。	对象
extraAnnotations optional	使用以下格式指定要应用到呈现的模板的额外集群级别注解： extraAnnotations: ClusterDeployment: myClusterAnnotation: success	对象
extraLabels optional	使用以下格式指定要应用到呈现的模板的额外集群级别标签： extraLabels: ManagedCluster: common: "true" label-a : "value-a"	对象
extraManifestsRefs optional	指定包含要应用到集群的额外清单的 `ConfigMap` 对象引用列表。	数组
holdInstallation optional	设置为 `true` 以防止在使用 Assisted Installer 时进行安装。您可以完成检查和验证步骤，但在 `RequirementsMet` 条件变为 `true` 后，安装不会开始，直到 `holdInstallation` 字段被设置为 `false` 为止。	bool
ignitionConfigOverride optional	指定用户覆盖初始 Ignition 配置。	字符串
installConfigOverrides optional	定义安装配置参数。	字符串
machineNetwork optional	指定机器的 IP 地址池列表。	数组
networkType optional	指定要安装的 Container Network Interface (CNI)插件。IPv4 或单节点 OpenShift 集群的默认值为 `OpenShiftSDN`。	字符串
platformType 可选	定义您要安装的特定平台的名称。支持以下值： `裸机` `vSphere` `Nutanix` `外部` `""` `None`	字符串
代理可选	定义用于集群安装配置的代理设置。	对象
pruneManifests 可选	通过指定 `apiVersion` 和 `Kind` 值，定义要删除的集群级别清单列表。	数组
pullSecretRef required	配置 `pull-secret` 文件以拉取镜像。在创建 `pull-secret` 文件时，请使用与置备主机的 `ClusterInstance` CR 相同的命名空间。	对象
serviceNetwork optional	指定服务的 IP 地址池列表。	数组
sshPublicKey optional	指定提供实例访问权限的公共 Secure Shell (SSH)密钥。此密钥添加到主机以允许 SSH 访问。	字符串
需要节点	指定每个节点的配置参数。	nodes 数组
templateRefs 必需	指定对集群级别模板的引用列表。集群级模板由一个 `ConfigMap` 对象组成，其中 data 字段的键代表安装清单类型。集群级模板会在 `ClusterInstance` CR 中每个集群实例化一次。	数组

节点

Name	描述	模式
automatedCleaningMode optional	将值设为 `metadata` 以仅启用删除磁盘的分区表，而无需完全擦除磁盘。默认值为 `Disabled`。	字符串
bmcAddress required	用于访问主机的 BMC 地址。适用于所有集群类型。有关 BMC 寻址的更多信息，请参阅附加资源中的 BMC 地址。注：在边缘 Telco 用例中，只有虚拟介质才支持与 GitOps ZTP 搭配使用。	字符串
bmcCredentialsName required	配置使用主机 BMC 凭证单独创建的 `bmh-secret` CR。在创建 `bmh-secret` CR 时，请使用与置备主机的 `ClusterInstance` CR 相同的命名空间。	字符串
bootMACAddress required	指定 PXE 引导的 MAC 地址。`libvirt` 虚拟机是由虚拟 BMC 驱动的 libvirt 虚拟机。	字符串
bootMode optional	将主机的引导模式设置为 `UEFI`。默认值为 `UEFI`。使用 `UEFISecureBoot` 在主机上启用安全引导。支持以下值： `UEFI` `UEFISecureBoot` `传统`	字符串
extraAnnotations optional	使用以下格式指定要应用到呈现的模板的额外节点级别注解： extraAnnotations: BareMetalHost: myNodeAnnotation: success	对象
extraLabels optional	指定要应用到渲染的模板的额外节点级别标签。 extraLabels: ManagedCluster: common: "true" label-a : "value-a"	对象
hostName required	定义主机名。	字符串
installerArgs 可选	指定主机的 :op-system-first: 安装程序参数的用户覆盖。	字符串
ignitionConfigOverride optional	指定用户覆盖初始 Ignition 配置。使用此字段为持久性存储分配分区。将磁盘 ID 和大小调整为特定的硬件。	字符串
ironicInspect optional	指定在注册裸机主机时是否运行自动内省。	字符串
nodeLabels optional	在受管集群中为节点指定自定义节点标签。这些是用户不由任何 Red Hat Advanced Cluster Management 组件使用的额外标签。添加自定义节点标签时，可以关联到自定义机器配置池，该池引用该标签的特定配置。在安装过程中添加自定义节点标签使部署过程更高效，并防止在安装完成后进行额外的重启。注：在 `BareMetalHost` 模板中使用时，自定义标签会附加到带有 `bmac.agent-install.openshift.io` 前缀的 `BareMetalHost` 注解中。	对象
nodeNetwork optional	为具有静态网络的节点配置网络设置。	对象
pruneManifests 可选	通过指定 `apiVersion` 和 `Kind` 值，定义要删除的节点级别清单列表。	数组
角色可选	配置节点的角色，如 `master` 或 `worker`。	字符串
rootDeviceHints optional	指定用于部署的设备。建议在重启后保持标识符稳定。例如，`wwn: <disk_wwn>` 或 `deviceName: /dev/disk/by-path/<device_path>`.首选 `<by-path>` 值。有关 stable 标识符的详细列表，请参阅"About root device hints"。您还可以指定该设备的名称、型号、大小或厂商。	对象
templateRefs 必需	指定对节点级别模板的引用列表。节点级别模板由一个 `ConfigMap` 对象组成，其中 data 字段的键代表安装清单类型。为 `ClusterInstance` CR 中的每个节点实例化节点级别的模板一次。	数组

status

Name	描述	模式
conditions 可选	列出与 `ClusterInstance` 资源上执行的操作相关的条件。	conditions 数组
deploymentConditions optional	列出与 `ClusterDeployment` 资源关联的 hive 状态条件。	deploymentConditions 数组
manifestsRendered optional	列出已呈现的清单及其状态。	数组
observedGeneration 可选	跟踪观察到的 `ClusterInstance` 对象的生成。	整数

conditions

类型	描述
ClusterInstanceValidated	表示 SiteConfig operator 验证 `ClusterInstance` `spec` 字段，并验证是否存在所需的工件，如 secret 和额外的清单 `ConfigMap` 对象。
RenderedTemplates	表示 SiteConfig operator 成功验证引用的 Golang 集群模板。
RenderedTemplatesValidated	表示 SiteConfig 操作器呈现安装清单，并且空运行成功。
RenderedTemplatesApplied	表示 SiteConfig operator 创建安装清单，并且底层 Operator 使用它们。
已置备	表示底层 Operator 正在置备集群。

deploymentConditions

类型	描述
ClusterInstallRequirementsMet	表示安装可以启动。
ClusterInstallCompleted	表示集群安装成功。
ClusterInstallFailed	表示集群安装失败。
ClusterInstallStopped	表示集群安装已停止。

其他资源

BMC 地址