Red Hat Summit 红帽全球峰会支持控制台（Console）开发人员开始试用联系人

1.2. ClusterInstance API

deprecated ： API 的文档已弃用。使用控制台或 oc 命令中的 API Explorer 查看当前和支持的 API。

1.2.1. 概述
复制链接

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

1.2.1.1. 版本信息
复制链接

版本 2.7

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}
Copy to Clipboard Toggle word wrap
1.2.2.1.1. 描述
复制链接

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

1.2.2.1.2. 参数
复制链接
Expand
类型Name描述模式

标头

COOKIE
必需

身份验证：Bearer {ACCESS_TOKEN} ; ACCESS_TOKEN 是用户访问令牌。

字符串

路径

clusterinstance_namespace
必需

要查询的 ClusterInstance 的命名空间。

string

路径

clusterinstance_name
必需

要查询的 ClusterInstance 的名称。

string

1.2.2.1.3. 响应
复制链接
Expand
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>
Copy to Clipboard Toggle word wrap
1.2.2.2.1. 描述
复制链接

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

1.2.2.2.2. 参数
复制链接
Expand
类型Name描述模式

标头

COOKIE
必需

身份验证：Bearer {ACCESS_TOKEN} ; ACCESS_TOKEN 是用户访问令牌。

字符串

Body

body
必需

描述要创建的安装清单的参数。

ClusterInstance

路径

clusterinstance_namespace
必需

要使用的 ClusterInstance 的命名空间。

string

路径

clusterinstance_name
必需

要使用的 ClusterInstance 的名称。

string

1.2.2.2.3. 响应
复制链接
Expand
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
                                }
                            ]
                        }
                    }
                }
            }
        ]
    }
}
Copy to Clipboard Toggle word wrap

1.2.2.3. 查询单个集群
复制链接

GET /siteconfig.open-cluster-management.io/v1alpha1/<clusterinstance_namespace>/<clusterinstance_name>
Copy to Clipboard Toggle word wrap
1.2.2.3.1. 描述
复制链接

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

1.2.2.3.2. 参数
复制链接
Expand
类型Name描述模式

标头

COOKIE
必需

身份验证：Bearer {ACCESS_TOKEN} ; ACCESS_TOKEN 是用户访问令牌。

字符串

路径

clusterinstance_namespace
必需

要查询的 ClusterInstance 的命名空间。

string

路径

clusterinstance_name
必需

要查询的 ClusterInstance 的名称。

string

1.2.2.3.3. 响应
复制链接
Expand
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
复制链接

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

Expand
Name描述模式

apiVersion
必需

ClusterInstance 的版本化模式。

string

kind
必需

代表 REST 资源的字符串值。

字符串

metadata
必需

ClusterInstance 的元数据。

object

spec
必需

ClusterInstance 的规格。

spec

status
必需

ClusterInstance 的状态。

Status 对象

spec

Expand
Name描述模式

additionalNTPSources
optional

指定需要添加到所有集群主机的 NTP 源。它们被添加到任何通过其他方法配置的 NTP 源中。

数组

baseDomain
必需

指定用于部署集群的基域。

string

caBundleRef
optional

引用包含主机可信证书捆绑包的 ConfigMap 对象。ConfigMap 对象中的 tls-ca-bundle.pem 条目被写入 /etc/pki/ca-trust/extracted/pem/tls-ca-bundle.pem。

string

clusterImageSetNameRef
required

指定指示要部署的 OpenShift Container Platform 版本的 ClusterImageSet 对象的名称。

string

clusterName
必需

指定集群的名称。

string

clusterNetwork
可选

指定 pod 的 IP 地址池列表。

数组

clusterType
可选

指定集群类型。支持以下值：

SNO
single-node OpenShift
HighlyAvailable
Multi-node OpenShift

string

cpuPartitioningMode
optional

决定在安装时为 CPU 工作负载分区设置的集群。通过将 cpuPartitioningMode 的值设置为 AllNodes 来配置工作负载分区。要完成配置，请在 PerformanceProfile CR 中指定 isolated 和 reserved CPU。默认值为 None。

string

diskEncryption
可选

为集群启用或禁用磁盘加密。

object

extraAnnotations
可选

使用以下格式指定要应用到呈现的模板的额外集群级别注解：

extraAnnotations:
  ClusterDeployment:
    myClusterAnnotation: success
Copy to Clipboard Toggle word wrap

object

extraLabels
可选

使用以下格式指定要应用到呈现的模板的额外集群级别标签：

extraLabels:
  ManagedCluster:
    common: "true"
    label-a : "value-a"
Copy to Clipboard Toggle word wrap

object

extraManifestsRefs
optional

指定包含要应用到集群的额外清单的 ConfigMap 对象引用列表。

数组

holdInstallation
optional

设置为 true 以防止在使用 Assisted Installer 时进行安装。您可以完成检查和验证步骤，但在 RequirementsMet 条件变为 true 后，安装不会开始，直到 holdInstallation 字段被设置为 false 为止。

bool

ignitionConfigOverride
optional

指定用户覆盖初始 Ignition 配置。

string

installConfigOverrides
optional

定义安装配置参数。

string

machineNetwork
可选

指定机器的 IP 地址池列表。

数组

networkType
可选

指定要安装的 Container Network Interface (CNI)插件。IPv4 或单节点 OpenShift 集群的默认值为 OpenShiftSDN。

string

platformType
可选

定义您要安装的特定平台的名称。支持以下值：

  • 裸机
  • vSphere
  • Nutanix
  • 外部
  • ""
  • None

string

代理
可选

定义用于集群安装配置的代理设置。

object

pruneManifests
可选

通过指定 apiVersion 和 Kind 值，定义要删除的集群级别清单列表。

数组

pullSecretRef
required

配置 pull-secret 文件以拉取镜像。在创建 pull-secret 文件时，请使用与置备主机的 ClusterInstance CR 相同的命名空间。

object

serviceNetwork
可选

指定服务的 IP 地址池列表。

数组

sshPublicKey
可选

指定提供实例访问权限的公共 Secure Shell (SSH)密钥。此密钥添加到主机以允许 SSH 访问。

string

需要 节点

指定每个节点的配置参数。

nodes 数组

templateRefs
required

指定对集群级别模板的引用列表。集群级模板由一个 ConfigMap 对象组成，其中 data 字段的键代表安装清单类型。集群级模板会在 ClusterInstance CR 中每个集群实例化一次。

数组

节点

Expand
Name描述模式

automatedCleaningMode
optional

取消注释并将值设置为 metadata，以只启用删除磁盘分区表，而无需完全擦除磁盘。默认值为 Disabled。

string

bmcAddress
必需

用于访问主机的 BMC 地址。适用于所有集群类型。有关 BMC 寻址的更多信息，请参阅附加资源中的 BMC 地址。在边缘 Telco 用例中，只有虚拟介质可用于 GitOps ZTP。

string

bmcCredentialsName
required

配置使用主机 BMC 凭证单独创建的 bmh-secret CR。在创建 bmh-secret CR 时，请使用与置备主机的 ClusterInstance CR 相同的命名空间。

string

bootMACAddress
必需

指定 PXE 引导的 MAC 地址。libvirt 虚拟机是由虚拟 BMC 驱动的 libvirt 虚拟机。

string

bootMode
可选

将主机的引导模式设置为 UEFI。默认值为 UEFI。使用 UEFISecureBoot 在主机上启用安全引导。支持以下值：

  • UEFI
  • UEFISecureBoot
  • Legacy

string

extraAnnotations
可选

使用以下格式指定要应用到呈现的模板的额外节点级别注解：

extraAnnotations:
  BareMetalHost:
    myNodeAnnotation: success
Copy to Clipboard Toggle word wrap

object

extraLabels
可选

指定要应用到渲染的模板的额外节点级别标签。

extraLabels:
  ManagedCluster:
    common: "true"
    label-a : "value-a"
Copy to Clipboard Toggle word wrap

object

主机名
必需

定义主机名。

string

installerArgs
可选

指定主机的 :op-system-first: 安装程序参数的用户覆盖。

string

ignitionConfigOverride
optional

指定用户覆盖初始 Ignition 配置。使用此字段为持久性存储分配分区。将磁盘 ID 和大小调整为特定的硬件。

string

ironicInspect
可选

指定在注册裸机主机时是否运行自动内省。

string

nodeLabels
可选

在受管集群中为节点指定自定义节点标签。这些是用户不由任何 Red Hat Advanced Cluster Management 组件使用的额外标签。添加自定义角色时，它可以与引用该角色的特定配置的自定义机器配置池相关联。在安装过程中添加自定义标签或角色可使部署过程更高效，并防止在安装完成后进行额外的重启。

注： 在 BareMetalHost 模板中使用时，自定义标签会附加到带有 bmac.agent-install.openshift.io 前缀的 BareMetalHost 注解中。

object

nodeNetwork
optional

为具有静态网络的节点配置网络设置。

object

pruneManifests
可选

通过指定 apiVersion 和 Kind 值，定义要删除的节点级别清单列表。

数组

角色
可选

配置节点的角色，如 master 或 worker。

string

rootDeviceHints
可选

指定用于部署的设备。建议在重启后保持标识符稳定。例如，wwn: <disk_wwn> 或 deviceName: /dev/disk/by-path/<device_path>.首选 <by-path> 值。有关 stable 标识符的详细列表，请参阅"About root device hints"。您还可以指定该设备的名称、型号、大小或厂商。

object

templateRefs
required

指定对节点级别模板的引用列表。节点级别模板由一个 ConfigMap 对象组成，其中 data 字段的键代表安装清单类型。为 ClusterInstance CR 中的每个节点实例化节点级别的模板一次。

数组

status

Expand
Name描述模式

conditions
可选

列出与 ClusterInstance 资源上执行的操作相关的条件。

conditions 数组

deploymentConditions
可选

列出与 ClusterDeployment 资源关联的 hive 状态条件。

deploymentConditions 数组

manifestsRendered
可选

列出已呈现的清单及其状态。

数组

observedGeneration
可选

跟踪观察到的 ClusterInstance 对象的生成。

整数

conditions

Expand
类型描述

ClusterInstanceValidated

表示 SiteConfig operator 验证 ClusterInstance spec 字段，并验证是否存在所需的工件，如 secret 和额外的清单 ConfigMap 对象。

RenderedTemplates

表示 SiteConfig operator 成功验证引用的 Golang 集群模板。

RenderedTemplatesValidated

表示 SiteConfig 操作器呈现安装清单，并且空运行成功。

RenderedTemplatesApplied

表示 SiteConfig operator 创建安装清单，并且底层 Operator 使用它们。

已置备

表示底层 Operator 正在置备集群。

deploymentConditions

Expand
类型描述

ClusterInstallRequirementsMet

表示安装可以启动。

ClusterInstallCompleted

表示集群安装成功。

ClusterInstallFailed

表示集群安装失败。

ClusterInstallStopped

表示集群安装已停止。

其他资源

返回顶部
Red Hat logoGithubredditYoutubeTwitter

学习

尝试、购买和销售

社区

关于红帽文档

通过我们的产品和服务，以及可以信赖的内容，帮助红帽用户创新并实现他们的目标。 了解我们当前的更新.

让开源更具包容性

红帽致力于替换我们的代码、文档和 Web 属性中存在问题的语言。欲了解更多详情，请参阅红帽博客.

關於紅帽

我们提供强化的解决方案，使企业能够更轻松地跨平台和环境（从核心数据中心到网络边缘）工作。

Theme

© 2025 Red Hat