更新时间:2026-09-30 GMT+08:00

创建AddonInstance

功能介绍

根据提供的插件模板,安装插件实例。

调用方法

请参见如何调用API。

URI

POST /api/v3/addons

请求参数

表1 请求Header参数

参数

是否必选

参数类型

描述

Content-Type

是

String

参数解释:

消息体的类型(格式),默认为application/json,有其他取值时会在具体接口中专门说明。

约束限制:

GET方法不做校验

取值范围:

不涉及

默认取值:

不涉及

X-Auth-Token

是

String

参数解释:

调用接口的认证方式分为Token和AK/SK两种,如果您使用的Token方式,此参数为必填,请填写Token的值,获取方式请参见获取token。

约束限制:

不涉及

取值范围:

不涉及

默认取值:

不涉及

表2 请求Body参数

参数

是否必选

参数类型

描述

kind

是

String

参数解释:

API类型,固定值"Addon",该值不可修改,该字段传入无效。

约束限制:

该值不可修改

取值范围:

  • Addon

默认取值:

Addon

apiVersion

是

String

参数解释:

API版本,固定值"v3",该值不可修改,该字段传入无效。

约束限制:

该值不可修改

取值范围:

  • v3

默认取值:

v3

metadata

是

AddonMetadata object

参数解释:

插件基本信息,集合类的元素类型,包含一组由不同名称定义的属性。

约束限制:

不涉及

取值范围:

不涉及

默认取值:

不涉及

spec

是

InstanceRequestSpec object

参数解释:

spec是集合类的元素类型,内容为插件实例安装/升级的具体请求信息。

约束限制:

不涉及

取值范围:

不涉及

默认取值:

不涉及

表3 AddonMetadata

参数

是否必选

参数类型

描述

uid

否

String

参数解释:

插件实例唯一ID标识,创建成功后系统自动生成。

约束限制:

不涉及

取值范围:

不涉及

默认取值:

不涉及

name

否

String

参数解释:

插件名称

约束限制:

不涉及

取值范围:

不涉及

默认取值:

不涉及

alias

否

String

参数解释:

插件别名。

约束限制:

不涉及

取值范围:

不涉及

默认取值:

不涉及

labels

否

Map<String,String>

参数解释:

插件标签,key/value对格式,接口保留字段,填写不会生效。

约束限制:

不涉及

取值范围:

不涉及

默认取值:

不涉及

annotations

否

Map<String,String>

参数解释:

插件注解,由key/value组成。

约束限制:

不涉及

取值范围:

  • 安装时固定值为{"addon.install/type":"install"}

  • 升级时固定值为{"addon.upgrade/type":"upgrade"}

默认取值:

不涉及

updateTimestamp

否

String

参数解释:

更新时间

约束限制:

不涉及

取值范围:

不涉及

默认取值:

不涉及

creationTimestamp

否

String

参数解释:

创建时间,创建成功后系统自动生成,填写无效。

约束限制:

不涉及

取值范围:

不涉及

默认取值:

不涉及

表4 InstanceRequestSpec

参数

是否必选

参数类型

描述

version

否

String

参数解释:

待安装、升级插件的版本号,例如1.0.0。

约束限制:

  • 安装:该参数非必传,如果不传,匹配集群支持的最新版本。

  • 升级:该参数必传,需指定版本号。

取值范围:

不涉及

默认取值:

不涉及

clusterID

是

String

参数解释:

集群ID

约束限制:

不涉及

取值范围:

不涉及

默认取值:

不涉及

values

是

Map<String,Object>

参数解释:

插件模板安装参数(各插件不同),升级插件时需要填写全量安装参数,未填写参数将使用插件模板中的默认值,当前插件安装参数可通过查询插件实例接口获取。

约束限制:

不涉及

取值范围:

不涉及

默认取值:

不涉及

addonTemplateName

是

String

参数解释:

待安装插件模板名称,如coredns。

约束限制:

不涉及

取值范围:

不涉及

默认取值:

不涉及

响应参数

状态码:201

表5 响应Body参数

参数

参数类型

描述

kind

String

参数解释:

API类型,固定值"Addon",该值不可修改。

取值范围:

  • Addon

apiVersion

String

参数解释:

API版本,固定值"v3",该值不可修改。

取值范围:

  • v3

metadata

AddonMetadata object

参数解释:

基本信息,为集合类的元素类型,包含一组由不同名称定义的属性

取值范围:

不涉及

spec

InstanceSpec object

参数解释:

spec是集合类的元素类型,内容为插件实例具体信息,实例的详细描述主体部分都在spec中给出。

取值范围:

不涉及

status

AddonInstanceStatus object

参数解释:

插件实例状态信息。

取值范围:

不涉及

表6 AddonMetadata

参数

参数类型

描述

uid

String

参数解释:

插件实例唯一ID标识,创建成功后系统自动生成。

取值范围:

不涉及

name

String

参数解释:

插件名称

取值范围:

不涉及

alias

String

参数解释:

插件别名。

取值范围:

不涉及

labels

Map<String,String>

参数解释:

插件标签,key/value对格式,接口保留字段,填写不会生效。

取值范围:

不涉及

annotations

Map<String,String>

参数解释:

插件注解,由key/value组成。

取值范围:

  • 安装时固定值为{"addon.install/type":"install"}

  • 升级时固定值为{"addon.upgrade/type":"upgrade"}

updateTimestamp

String

参数解释:

更新时间

取值范围:

不涉及

creationTimestamp

String

参数解释:

创建时间,创建成功后系统自动生成,填写无效。

取值范围:

不涉及

表7 InstanceSpec

参数

参数类型

描述

clusterID

String

参数解释:

集群ID

取值范围:

不涉及

version

String

参数解释:

插件模板版本号,如1.0.0。

取值范围:

不涉及

addonTemplateName

String

参数解释:

插件模板名称,如coredns。

取值范围:

不涉及

addonTemplateType

String

参数解释:

插件模板类型。

取值范围:

  • helm:表示使用Helm包进行部署的模板类型

  • static:表示静态模板类型

addonTemplateLogo

String

参数解释:

插件模板logo图片的地址。

取值范围:

不涉及

addonTemplateLabels

Array of strings

参数解释:

插件模板所属类型。

取值范围:

不涉及

description

String

参数解释:

插件模板描述。

取值范围:

不涉及

values

Map<String,Object>

参数解释:

插件模板安装参数(各插件不同),请根据具体插件模板信息填写安装参数。

取值范围:

不涉及

表8 AddonInstanceStatus

参数

参数类型

描述

status

String

参数解释:

插件实例状态。

取值范围:

  • running:运行中,表示插件全部实例状态都在运行中,插件正常使用。

  • abnormal:不可用,表示插件状态异常,插件不可使用。可单击插件名称查看实例异常事件。

  • installing:安装中,表示插件正在安装中。

  • installFailed:安装失败,表示插件安装失败,需要卸载后重新安装。

  • upgrading:升级中,表示插件正在更新中。

  • upgradeFailed:升级失败,表示插件升级失败,可重试升级或卸载后重新安装。

  • deleting:删除中,表示插件正在删除中。

  • deleteFailed:删除失败,表示插件删除失败,可重试卸载。

  • deleteSuccess:删除成功,表示插件删除成功。

  • available:部分就绪,表示插件下只有部分实例状态为运行中,插件部分功能可用。

  • rollbacking:回滚中,表示插件正在回滚中。

  • rollbackFailed:回滚失败,表示插件回滚失败,可重试回滚或卸载后重新安装。

  • unknown:未知状态,表示插件模板实例不存在。

Reason

String

参数解释:

插件安装失败原因。

取值范围:

不涉及

message

String

参数解释:

安装错误详情。

取值范围:

不涉及

targetVersions

Array of strings

参数解释:

此插件版本,支持升级的集群版本。

取值范围:

不涉及

currentVersion

Versions object

参数解释:

当前插件实例使用的具体插件版本信息。

取值范围:

不涉及

isRollbackable

Boolean

参数解释:

是否支持回滚到插件升级前的插件版本。

取值范围:

  • true:支持回滚

  • false:不支持回滚

previousVersion

String

参数解释:

插件升级或回滚前的版本。

取值范围:

不涉及

表9 Versions

参数

参数类型

描述

version

String

参数解释:

插件版本号。

取值范围:

不涉及

input

Object

参数解释:

插件安装参数。

取值范围:

不涉及

stable

Boolean

参数解释:

是否为稳定版本。

取值范围:

  • true:稳定版本

  • false:非稳定版本

translate

Object

参数解释:

供界面使用的翻译信息。

取值范围:

不涉及

supportVersions

Array of SupportVersions objects

参数解释:

支持集群版本号。

取值范围:

不涉及

creationTimestamp

String

参数解释:

创建时间。

取值范围:

不涉及

updateTimestamp

String

参数解释:

更新时间。

取值范围:

不涉及

表10 SupportVersions

参数

参数类型

描述

clusterType

String

参数解释:

支持的集群类型。

取值范围:

  • VirtualMachine:CCE集群,控制节点架构为X86

  • BareMetal:裸金属集群,控制节点部署在裸金属服务器上

clusterVersion

Array of strings

参数解释:

支持的集群版本(正则表达式)。

取值范围:

不涉及

category

Array of strings

参数解释:

作用的集群类型。

取值范围:

  • CCE:CCE Standard集群

  • Turbo:CCE Turbo集群

请求示例

安装1.17.15版本的coredns插件,插件规格为2500qps,插件实例数指定为2。

{
  "kind" : "Addon",
  "apiVersion" : "v3",
  "metadata" : {
    "annotations" : {
      "addon.install/type" : "install"
    }
  },
  "spec" : {
    "clusterID" : "1b2ec02d-a3b2-11ec-b0d0-0255ac100099",
    "version" : "1.17.15",
    "addonTemplateName" : "coredns",
    "values" : {
      "basic" : {
        "cluster_ip" : "10.247.3.10",
        "image_version" : "1.17.15",
        "platform" : "linux-amd64",
        "swr_addr" : "<Replace_SWR_address>",
        "swr_user" : "hwofficial",
        "rbac_enabled" : true
      },
      "flavor" : {
        "name" : 2500,
        "replicas" : 2,
        "resources" : [ {
          "limitsCpu" : "500m",
          "limitsMem" : "512Mi",
          "name" : "coredns",
          "requestsCpu" : "500m",
          "requestsMem" : "512Mi"
        } ]
      },
      "custom" : {
        "stub_domains" : { },
        "upstream_nameservers" : [ ],
        "cluster_id" : "1b2ec02d-a3b2-11ec-b0d0-0255ac100099",
        "tenant_id" : "0504201b6c80256b2f08c0099f0c8fe4"
      }
    }
  }
}

响应示例

状态码:201

表示创建插件实例成功。

{
  "kind" : "Addon",
  "apiVersion" : "v3",
  "metadata" : {
    "uid" : "b748aaea-a984-11ec-987b-0255ac1000bc",
    "name" : "coredns",
    "alias" : "coredns",
    "creationTimestamp" : "2022-03-22T02:06:41Z",
    "updateTimestamp" : "2022-03-22T02:06:41Z"
  },
  "spec" : {
    "clusterID" : "1b2ec02d-a3b2-11ec-b0d0-0255ac100099",
    "version" : "1.17.15",
    "addonTemplateName" : "coredns",
    "addonTemplateType" : "helm",
    "addonTemplateLogo" : "",
    "addonTemplateLabels" : [ "ServiceDiscovery" ],
    "description" : "CoreDNS is a DNS server that chains plugins and provides Kubernetes DNS Services",
    "values" : {
      "basic" : {
        "cluster_ip" : "10.247.3.10",
        "image_version" : "1.17.15",
        "platform" : "linux-amd64",
        "rbac_enabled" : true,
        "swr_addr" : "",
        "swr_user" : "hwofficial"
      },
      "custom" : {
        "cluster_id" : "1b2ec02d-a3b2-11ec-b0d0-0255ac100099",
        "stub_domains" : { },
        "tenant_id" : "0504201b6c80256b2f08c0099f0c8fe4",
        "upstream_nameservers" : [ ]
      },
      "flavor" : {
        "name" : 2500,
        "replicas" : 2,
        "resources" : [ {
          "limitsCpu" : "500m",
          "limitsMem" : "512Mi",
          "name" : "coredns",
          "requestsCpu" : "500m",
          "requestsMem" : "512Mi"
        } ]
      }
    }
  },
  "status" : {
    "status" : "installing",
    "Reason" : "",
    "message" : "",
    "targetVersions" : null,
    "currentVersion" : {
      "version" : "1.17.15",
      "input" : {
        "basic" : {
          "cluster_ip" : "10.247.3.10",
          "image_version" : "1.17.15",
          "platform" : "linux-amd64",
          "swr_addr" : "",
          "swr_user" : "hwofficial"
        },
        "parameters" : {
          "custom" : {
            "stub_domains" : "",
            "upstream_nameservers" : ""
          },
          "flavor1" : {
            "name" : 2500,
            "replicas" : 2,
            "resources" : [ {
              "limitsCpu" : "500m",
              "limitsMem" : "512Mi",
              "name" : "coredns",
              "requestsCpu" : "500m",
              "requestsMem" : "512Mi"
            } ]
          },
          "flavor2" : {
            "name" : 5000,
            "replicas" : 2,
            "resources" : [ {
              "limitsCpu" : "1000m",
              "limitsMem" : "1024Mi",
              "name" : "coredns",
              "requestsCpu" : "1000m",
              "requestsMem" : "1024Mi"
            } ]
          },
          "flavor3" : {
            "name" : 10000,
            "replicas" : 2,
            "resources" : [ {
              "limitsCpu" : "2000m",
              "limitsMem" : "2048Mi",
              "name" : "coredns",
              "requestsCpu" : "2000m",
              "requestsMem" : "2048Mi"
            } ]
          },
          "flavor4" : {
            "name" : 20000,
            "replicas" : 4,
            "resources" : [ {
              "limitsCpu" : "2000m",
              "limitsMem" : "2048Mi",
              "name" : "coredns",
              "requestsCpu" : "2000m",
              "requestsMem" : "2048Mi"
            } ]
          }
        }
      },
      "stable" : true,
      "translate" : {
        "en_US" : {
          "addon" : {
            "changeLog" : "Supported CCE clusters of v1.21.",
            "description" : "CoreDNS is a DNS server that chains plugins and provides Kubernetes DNS Services"
          },
          "description" : {
            "Parameters.custom.stub_domains" : "The target nameserver may itself be a Kubernetes service. For instance, you can run your own copy of dnsmasq to export custom DNS names into the ClusterDNS namespace, a JSON map using a DNS suffix key (e.g. “acme.local”) and a value consisting of a JSON array of DNS IPs.",
            "Parameters.custom.upstream_nameservers" : "If specified, then the values specified replace the nameservers taken by default from the node’s /etc/resolv.conf. Limits:a maximum of three upstream nameservers can be specified, A JSON array of DNS IPs.",
            "Parameters.flavor1.description" : "Concurrent domain name resolution ability  -  External domain name:2500 qps,  Internal domain name:10000 qps",
            "Parameters.flavor1.name" : 2500,
            "Parameters.flavor2.description" : "Concurrent domain name resolution ability  -  External domain name:5000 qps, Internal domain name:20000 qps",
            "Parameters.flavor2.name" : 5000,
            "Parameters.flavor3.description" : "Concurrent domain name resolution ability  -  External domain name:10000 qps, Internal domain name:40000 qps",
            "Parameters.flavor3.name" : 10000,
            "Parameters.flavor4.description" : "Concurrent domain name resolution ability  -  External domain name:20000 qps, Internal domain name:80000 qps",
            "Parameters.flavor4.name" : 20000
          },
          "key" : {
            "Parameters.custom.stub_domains" : "stub domain",
            "Parameters.custom.upstream_nameservers" : "upstream nameservers"
          }
        },
        "fr_FR" : {
          "addon" : {
            "changeLog" : "Prise en charge du cluster 1.21.",
            "description" : "Un serveur DNS qui enchaîne les plug-ins et fournit des services DNS Kubernetes."
          },
          "description" : {
            "Parameters.custom.stub_domains" : "Le serveur de noms cible peut lui-même être un service Kubernetes. Par exemple, vous pouvez exécuter votre propre copie de dnsmasq pour exporter des noms DNS personnalisés dans l'espace de noms ClusterDNS, une carte JSON à l'aide d'une clé de suffixe DNS (par exemple, «acme.local») et une valeur constituée d'un tableau JSON d'adresses IP DNS.",
            "Parameters.custom.upstream_nameservers" : "Si spécifié, les valeurs spécifiées remplacent les serveurs de noms pris par défaut dans le fichier /etc/resolv.conf du nœud. Limites: un maximum de trois serveurs de noms en amont peuvent être spécifiés, un tableau JSON d'adresses IP DNS.",
            "Parameters.flavor1.description" : "Capacité de résolution de nom de domaine simultanée - Nom de domaine externe: 2500 qps, Nom de domaine interne: 10000 qp",
            "Parameters.flavor1.name" : 2500,
            "Parameters.flavor2.description" : "Capacité de résolution de nom de domaine simultanée - Nom de domaine externe: 5000 qps, Nom de domaine interne: 20000 qp",
            "Parameters.flavor2.name" : 5000,
            "Parameters.flavor3.description" : "Capacité de résolution de nom de domaine simultanée - Nom de domaine externe: 10000 qps, Nom de domaine interne: 40000 qp",
            "Parameters.flavor3.name" : 10000,
            "Parameters.flavor4.description" : "Capacité de résolution de nom de domaine simultanée - Nom de domaine externe: 20000 qps, Nom de domaine interne: 80000 qp",
            "Parameters.flavor4.name" : 20000
          },
          "key" : {
            "Parameters.custom.stub_domains" : "stub domain",
            "Parameters.custom.upstream_nameservers" : "serveurs de noms en amont"
          }
        },
        "zh_CN" : {
          "addon" : {
            "changeLog" : "",
            "description" : ""
          },
          "description" : {
            "Parameters.custom.stub_domains" : "",
            "Parameters.custom.upstream_nameservers" : "",
            "Parameters.flavor1.description" : "",
            "Parameters.flavor1.name" : 2500,
            "Parameters.flavor2.description" : "",
            "Parameters.flavor2.name" : 5000,
            "Parameters.flavor3.description" : "",
            "Parameters.flavor3.name" : 10000,
            "Parameters.flavor4.description" : "",
            "Parameters.flavor4.name" : 20000
          },
          "key" : {
            "Parameters.custom.stub_domains" : "",
            "Parameters.custom.upstream_nameservers" : ""
          }
        }
      },
      "supportVersions" : null,
      "creationTimestamp" : "2021-12-14T13:43:15Z",
      "updateTimestamp" : "2022-01-11T14:32:10Z"
    }
  }
}

状态码

状态码

描述

201

表示创建插件实例成功。

错误码

请参见错误码。