# 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.

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.

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.

Parent topic: Add-on Management