Installing an Add-on Instance

Function

This API is used to install an add-on instance by using an add-on template.

Calling Method

For details, see Calling APIs.

URI

POST /api/v3/addons

Request Parameters

**Table 1** Request header parameters
Parameter	Mandatory	Type	Description
Content-Type	Yes	String	Definition: Type (or format) of the request body. The default value is application/json. Other values of this field will be provided for specific APIs, if any. Constraints: GET requests are not validated. Range: N/A Default Value: N/A
X-Auth-Token	Yes	String	Details: Requests for calling an API can be authenticated using either a token or AK/SK. If token-based authentication is used, this parameter is mandatory and must be set to a user token. For details, see Obtaining a User Token. Constraints: None Options: N/A Default value: N/A

**Table 2** Request body parameters
Parameter	Mandatory	Type	Description
kind	Yes	String	Definition: API type. The value is fixed at Addon and cannot be changed. A specified value does not take effect. Constraints: The value cannot be changed. Range: Addon Default Value: Addon
apiVersion	Yes	String	Definition: API version. The value is fixed at v3 and cannot be changed. A specified value does not take effect. Constraints: The value cannot be changed. Range: v3 Default Value: v3
metadata	Yes	AddonMetadata object	Definition: Basic information about an add-on. Metadata is a collection of attributes. Constraints: N/A Range: N/A Default Value: N/A
spec	Yes	InstanceRequestSpec object	Definition: Detailed description of an add-on installation or upgrade Constraints: N/A Range: N/A Default Value: N/A

**Table 3** AddonMetadata
Parameter	Mandatory	Type	Description
uid	No	String	Definition: Unique ID of an add-on pod, which is automatically generated by the system after the add-on pod is created Constraints: N/A Range: N/A Default Value: N/A
name	No	String	Definition: Add-on name Constraints: N/A Range: N/A Default Value: N/A
alias	No	String	Definition: Add-on alias Constraints: N/A Range: N/A Default Value: N/A
labels	No	Map<String,String>	Definition: Add-on labels in key-value pairs. This is a reserved field. A specified value is invalid. Constraints: N/A Range: N/A Default Value: N/A
annotations	No	Map<String,String>	Definition: Add-on annotations in the format of key-value pairs Constraints: N/A Range: The value is fixed at {"addon.install/type":"install"} during installation. The value is fixed at {"addon.upgrade/type":"upgrade"} during an upgrade. Default Value: N/A
updateTimestamp	No	String	Definition: Update time Constraints: N/A Range: N/A Default Value: N/A
creationTimestamp	No	String	Definition: Creation time, which is automatically generated after creation. A specified value does not take effect. Constraints: N/A Range: N/A Default Value: N/A

**Table 4** InstanceRequestSpec
Parameter	Mandatory	Type	Description
version	No	String	Definition: Version of the add-on to be installed or upgraded, for example, 1.0.0 Constraints: During installation, this parameter is optional. If not specified, the latest version supported by the cluster is used. During an upgrade, this parameter is mandatory and the version must be specified. Range: N/A Default Value: N/A
clusterID	Yes	String	Definition: Cluster ID Constraints: N/A Range: N/A Default Value: N/A
values	Yes	Map<String,Object>	Definition: Add-on template installation parameters (varying depending on the add-on). During the add-on upgrade, you need to specify all the installation parameters. If the parameters are not specified, the default values in the add-on template are used. The current add-on installation parameters can be obtained through the API for querying add-on pods. Constraints: N/A Range: N/A Default Value: N/A
addonTemplateName	Yes	String	Definition: Name of the add-on template to be installed, for example, coredns Constraints: N/A Range: N/A Default Value: N/A

Response Parameters

Status code: 201

**Table 5** Response body parameters
Parameter	Type	Description
kind	String	Definition: API type. The value is fixed at Addon and cannot be changed. Range: Addon
apiVersion	String	Definition: API version. The value is fixed at v3 and cannot be changed. Range: v3
metadata	AddonMetadata object	Definition: Basic information. Metadata is a collection of attributes. Range: N/A
spec	InstanceSpec object	Definition: Details about an add-on pod Range: N/A
status	AddonInstanceStatus object	Definition: Add-on pod status Range: N/A

**Table 6** AddonMetadata
Parameter	Type	Description
uid	String	Definition: Unique ID of an add-on pod, which is automatically generated by the system after the add-on pod is created Range: N/A
name	String	Definition: Add-on name Range: N/A
alias	String	Definition: Add-on alias Range: N/A
labels	Map<String,String>	Definition: Add-on labels in key-value pairs. This is a reserved field. A specified value is invalid. Range: N/A
annotations	Map<String,String>	Definition: Add-on annotations in the format of key-value pairs Range: The value is fixed at {"addon.install/type":"install"} during installation. The value is fixed at {"addon.upgrade/type":"upgrade"} during an upgrade.
updateTimestamp	String	Definition: Update time Range: N/A
creationTimestamp	String	Definition: Creation time, which is automatically generated after creation. A specified value does not take effect. Range: N/A

**Table 7** InstanceSpec
Parameter	Type	Description
clusterID	String	Definition: Cluster ID Range: N/A
version	String	Definition: Add-on template version, for example, 1.0.0 Range: N/A
addonTemplateName	String	Definition: Add-on template name, for example, coredns Range: N/A
addonTemplateType	String	Definition: Add-on template type Range: helm: Helm packages static: static templates
addonTemplateLogo	String	Definition: URL for obtaining an add-on template logo Range: N/A
addonTemplateLabels	Array of strings	Definition: Add-on template type Range: N/A
description	String	Definition: Add-on template description Range: N/A
values	Map<String,Object>	Definition: Add-on template installation parameters (varying depending on the add-on). Configure the parameters based on the add-on template. Range: N/A

**Table 8** AddonInstanceStatus
Parameter	Type	Description
status	String	Definition: Add-on pod status Range: running: All of the add-on pods are running. This specifies that the add-on runs properly. abnormal: The add-on is abnormal and cannot be used. You can click the add-on name to view exceptions. installing: The add-on is being installed. installFailed: The add-on installation failed. You need to uninstall the add-on and install it again. upgrading: The add-on is being upgraded. upgradeFailed: The add-on upgrade failed. You can retry the upgrade or uninstall the add-on and install it again. deleting: The add-on is being deleted. deleteFailed: The add-on failed to be deleted. You can retry the uninstallation. deleteSuccess: The add-on was deleted. available: Only some instances of the add-on are running. This specifies that some functions of the add-on are available. rollbacking: The add-on is being rolled back. rollbackFailed: The add-on failed to be rolled back. You can retry the rollback or uninstall and reinstall the add-on. unknown: The add-on template instance does not exist.
Reason	String	Definition: Cause of an add-on installation failure Range: N/A
message	String	Definition: Installation error details Range: N/A
targetVersions	Array of strings	Definition: Cluster versions that support the add-on upgrade Range: N/A
currentVersion	Versions object	Definition: Information about the current add-on version Range: N/A
isRollbackable	Boolean	Definition: Whether the add-on version can be rolled back to the source version Range: true: Rollback is supported. false: Rollback is not supported.
previousVersion	String	Definition: The add-on version before an upgrade or rollback Range: N/A

**Table 9** Versions
Parameter	Type	Description
version	String	Definition: Add-on version Range: N/A
input	Object	Definition: Add-on installation parameters Range: N/A
stable	Boolean	Definition: Whether the version is stable Range: true: The version is stable. false: The version is unstable.
translate	Object	Definition: Translation information used by the GUI Range: N/A
supportVersions	Array of SupportVersions objects	Definition: Supported cluster versions Range: N/A
creationTimestamp	String	Definition: Creation time Range: N/A
updateTimestamp	String	Definition: Update time Range: N/A

**Table 10** SupportVersions
Parameter	Type	Description
clusterType	String	Definition: Supported cluster type VirtualMachine is supported. Range: VirtualMachine: CCE cluster, where master nodes are x86 servers BareMetal: bare metal cluster, where master nodes are BMSs
clusterVersion	Array of strings	Definition: Supported cluster version (regular expression) Range: N/A
category	Array of strings	Definition: The cluster type to which the configurations apply Range: CCE: CCE standard clusters Turbo: CCE Turbo clusters

Example Requests

Install the CoreDNS add-on v1.17.15. The add-on specification is 2500 QPS, and the number of add-on instances is 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"
      }
    }
  }
}

Example Responses

Status code: 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"
    }
  }
}

Status Codes

Status Code	Description
201	The add-on pod has been created.

Error Codes

See Error Codes.

Parent topic: Add-on Management

Previous topic: Add-on Management

Next topic: Listing Add-on Templates