Installing an Add-on Instance

Function

This API is used to install an add-on instance by using the add-on template. One or more instances will be created for the installed add-on.

Note

The URL for add-on management is in the format of https://{clusterid}.Endpoint/uri. In the URL, {clusterid} indicates the cluster ID, and uri indicates the resource path, that is, the path for API access.

URI

POST /api/v3/addons

Request

Request parameters:

Table 1 lists the request parameters.

Table 1 Parameters in the request header

Parameter

Mandatory

Description

Content-Type

Yes

Message body type (format). Possible values:

  • application/json;charset=utf-8

  • application/json

X-Auth-Token

Yes

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 on how to obtain a user token, see API Usage Guidelines.

Table 2 Parameters in the request body

Parameter

Mandatory

Type

Description

kind

Yes

String

API type. The value is fixed at Addon and cannot be changed.

apiVersion

Yes

String

API version. The value is fixed at v3 and cannot be changed.

metadata

Yes

metadata object

Basic information about the add-on. Metadata is a collection of attributes.

spec

Yes

spec object

Detailed description of add-on installation or upgrade.

Table 3 Data structure of the metadata field

Parameter

Mandatory

Type

Description

annotations

Yes

Object

Add-on annotations in the format of key-value pairs.

For add-on installation, the value is fixed at {"addon.install/type":"install"}.

Table 4 Data structure of the spec field

Parameter

Mandatory

Type

Description

clusterID

Yes

String

Cluster ID.

version

Yes

String

Version number of the add-on to be installed or upgraded, for example, v1.0.0.

addonTemplateName

Yes

String

Name of the add-on template to be installed, for example, coredns.

values

Yes

Object

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 instances. For details, see Add-on Instance Parameters.

Table 5 Data structure of the values field

Parameter

Mandatory

Type

Description

basic

Yes

Object

Basic add-on information.

custom

No

Object

Custom parameters of the add-on.

Example request:

{
    "metadata": {
        "annotations": {
            "addon.install/type": "install"
        }
    },
    "spec": {
        "clusterID": "9dd81b6e-e8e5-11ea-8aeb-0255ac11161d",
        "version": "1.1.10",
        "addonTemplateName": "gpu-beta",
        "values": {
            "basic": {
                "obs_url": "obs.eu-de.otc.t-systems.com",
                "region": "eu-de",
                "swr_addr": "10.125.7.25:20202",
                "swr_user": "test",
                "rbac_enabled": true
            },
            "custom": {
                "is_driver_from_nvidia": true,
                "nvidia_driver_download_url": "https://us.download.nvidia.com/tesla/396.37/NVIDIA-Linux-x86_64-396.37.run"
            }
        }
    }
}

Response

Response parameters:

For the description about response parameters, see Table 6.

Table 6 Parameters in the response body

Parameter

Type

Description

kind

String

API type. The value is fixed at Addon and cannot be changed.

apiVersion

String

API version. The value is fixed at v3 and cannot be changed.

metadata

metadata object

Basic information about the add-on. Metadata is a collection of attributes.

spec

spec object

Detailed description of the add-on instance.

status

status object

Add-on instance status.

Table 7 Data structure of the metadata field

Parameter

Type

Description

uid

String

Unique ID of the add-on.

name

String

Add-on name.

labels

Object

Add-on labels in the format of key-value pairs.

annotations

Object

Add-on annotations in the format of key-value pairs.

updateTimestamp

String

Time when the add-on was updated.

creationTimestamp

String

Time when the add-on was created.

Table 8 Data structure of the spec field

Parameter

Type

Description

clusterID

String

Cluster ID.

version

String

Add-on template version, for example, v1.0.0.

addonTemplateName

String

Add-on template name, for example, coredns.

addonTemplateType

String

Add-on template type.

addonTemplateLabels

Array of strings

Group to which the add-on template belongs.

addonTemplateLogo

String

OBS address of the current add-on logo.

description

String

Add-on template description.

values

Object

Add-on template installation parameters. These parameters vary depending on the add-on.

Table 9 Data structure of the status field

Parameter

Type

Description

status

String

Add-on instance status.

Reason

String

Cause of unsuccessful add-on installation.

message

String

Installation error details.

targetVersions

Array of strings

Versions to which the current add-on version can be upgraded.

currentVersion

currentVersion object

Current version of the add-on instance.

Table 10 Data structure of the currentVersion field

Parameter

Type

Description

version

String

Add-on version.

input

Object

Add-on installation parameters.

stable

Boolean

Whether the add-on version is a stable release.

translate

Object

Translation information used by the GUI.

supportVersions

Array of supportVersions objects

Cluster versions that support the add-on.

creationTimestamp

String

Time when the add-on was created.

updateTimestamp

String

Time when the add-on was updated.

Table 11 Data structure of the supportVersions field

Parameter

Type

Description

clusterType

String

Cluster type that supports the add-on.

clusterVersion

Array of strings

Cluster versions that support the add-on. The parameter value is a regular expression.

Example response:

{
    "kind": "Addon",
    "apiVersion": "v3",
    "metadata": {
        "uid": "b6ba182c-f7c5-11ea-a975-0255ac111605",
        "name": "gpu-beta",
        "creationTimestamp": "2020-09-16T02:38:33Z",
        "updateTimestamp": "2020-09-16T02:38:33Z"
    },
    "spec": {
        "clusterID": "9dd81b6e-e8e5-11ea-8aeb-0255ac11161d",
        "version": "1.1.10",
        "addonTemplateName": "gpu-beta",
        "addonTemplateType": "helm",
        "addonTemplateLogo": "https://obs.eu-de.otc.t-systems.com/cce-addon-eu-de-aw1hz2u/gpu-betalogo.svg",
        "addonTemplateLabels": [
            "Accelerator"
        ],
        "description": "A device plugin for nvidia.com/gpu resource on nvidia driver",
        "values": {
            "basic": {
                "obs_url": "obs.eu-de.otc.t-systems.com",
                "platform": "linux-amd64",
                "rbac_enabled": true,
                "region": "eu-de",
                "swr_addr": "10.125.7.25:20202",
                "swr_user": "test"
            },
            "custom": {
                "is_driver_from_nvidia": true,
                "nvidia_driver_download_url": "https://us.download.nvidia.com/tesla/396.37/NVIDIA-Linux-x86_64-396.37.run"
            }
        }
    },
    "status": {
        "status": "installing",
        "Reason": "",
        "message": "",
        "targetVersions": null,
        "currentVersion": {
            "version": "1.1.10",
            "input": {
                "basic": {
                    "obs_url": "obs.eu-de.otc.t-systems.com",
                    "region": "eu-de",
                    "swr_addr": "10.125.7.25:20202",
                    "swr_user": "test"
                },
                "parameters": {
                    "custom": {
                        "is_driver_from_nvidia": true,
                        "nvidia_driver_download_url": ""
                    }
                }
            },
            "stable": true,
            "translate": {
                "en_US": {
                    "addon": {
                        "changeLog": "1.Supports both the default driver link address and the user-definable driver address download driver 2.Support kubernetes 1.15/1.17",
                        "description": "A device plugin for nvidia.com/gpu resource on nvidia driver"
                    },
                    "description": {
                        "Parameters.custom.drivers_info.cuda": "CUDA Toolkit",
                        "Parameters.custom.drivers_info.product": "Product",
                        "Parameters.custom.drivers_info.product_series": "Product Series",
                        "Parameters.custom.drivers_info.product_type": "Product Type",
                        "Parameters.custom.nvidia_driver_download_url": "Download the nvidia driver accroding to the input link"
                    },
                    "key": {
                        "Parameters.custom.nvidia_driver_download_url": "Nvidia Driver"
                    }
                }
            },
            "supportVersions": null,
            "creationTimestamp": "2020-08-21T08:25:51Z",
            "updateTimestamp": "2020-08-28T12:21:11Z"
        }
    }
}

Status Codes

Table 12 Status codes

Status Code

Description

201

OK

For the description about error status codes, see Status Code.