Updated on 2024-04-23 GMT+08:00

Creating a Service

Function

This API is used to create a service.

Only the platinum edition supports service-related functions.

URI

POST /v2/{project_id}/edgemgr/services

Table 1 Path parameters

Parameter

Mandatory

Type

Description

project_id

Yes

String

Project ID.

Request

Table 2 Parameters in the request header

Parameter

Mandatory

Type

Description

Content-Type

Yes

String

Message body type (format).

The default value application/json is recommended.

X-Auth-Token

Yes

String

User token. The token can be obtained by calling the IAM API used to obtain a user token. The value of X-Subject-Token in the response header is the user token.

Table 3 Parameters in the request body

Parameter

Mandatory

Type

Description

service

No

ServiceReqDetail object

Service details.

Table 4 ServiceReqDetail

Parameter

Mandatory

Type

Description

meta_data

Yes

SvcMetadata object

Static properties of the service.

spec

Yes

SvcSpec object

Dynamic properties of the service.

Table 5 SvcMetadata

Parameter

Mandatory

Type

Description

labels

No

Map<String,String>

List of customized labels.

name

Yes

String

Service name. The name contains a maximum of 64 characters starting with a letter and ending with a letter or digit. Only lowercase letters, digits, and hyphens (-) are allowed.

Table 6 SvcSpec

Parameter

Mandatory

Type

Description

cluster_ip

No

String

Virtual service IP address.

external_ips

No

Array of strings

List of external IP addresses. This parameter is not supported currently.

external_name

No

String

External domain name. This parameter is not supported currently.

ports

No

Array of SvcPort objects

List of service ports to be exposed.

selector

Yes

Map<String,String>

Label selector, which is used to select the pods with the specified labels for management.

type

No

String

Service type.

Table 7 SvcPort

Parameter

Mandatory

Type

Description

name

No

String

The service port must be named in the {protocol}-{suffix} format, where {protocol} can be tcp or http. IEF provides routing capabilities based on protocols defined on ports. For example, name:http-0 and name:tcp-0 are valid port names, while name:http2forecast is invalid.

node_port

No

String

Port number mapped to the physical machine when spec.type is set to NodePort.

port

No

String

Port on which the service listens.

protocol

No

String

Protocol, for example, TCP.

target_port

No

String

Port number of the backend pod to which requests are forwarded.

Response

When the status code is 201, the response parameters are as follows.

Table 8 Parameters in the response body

Parameter

Type

Description

service

ServiceRespDetail object

Service details.

Table 9 ServiceRespDetail

Parameter

Type

Description

created_at

String

Creation time.

id

String

Service ID.

meta_data

SvcMetadata object

Static properties of the service.

project_id

String

Tenant ID.

spec

SvcSpec object

Dynamic properties of the service.

updated_at

String

Update time.

Table 10 SvcMetadata

Parameter

Type

Description

labels

Map<String,String>

List of customized labels.

name

String

Service name. The name contains a maximum of 64 characters starting with a letter and ending with a letter or digit. Only lowercase letters, digits, and hyphens (-) are allowed.

Table 11 SvcSpec

Parameter

Type

Description

cluster_ip

String

Virtual service IP address.

external_ips

Array of strings

List of external IP addresses. This parameter is not supported currently.

external_name

String

External domain name. This parameter is not supported currently.

ports

Array of SvcPort objects

List of service ports to be exposed.

selector

Map<String,String>

Label selector, which is used to select the pods with the specified labels for management.

type

String

Service type.

Table 12 SvcPort

Parameter

Type

Description

name

String

The service port must be named in the {protocol}-{suffix} format, where {protocol} can be tcp or http. IEF provides routing capabilities based on protocols defined on ports. For example, name:http-0 and name:tcp-0 are valid port names, while name:http2forecast is invalid.

node_port

String

Port number mapped to the physical machine when spec.type is set to NodePort.

port

String

Port on which the service listens.

protocol

String

Protocol, for example, TCP.

target_port

String

Port number of the backend pod to which requests are forwarded.

When the status code is 400, the response parameters are as follows:

Table 13 Parameters in the response body

Parameter

Type

Description

error_code

String

Error code.

error_message

String

Error message.

When the status code is 500, the response parameters are as follows:

Table 14 Parameters in the response body

Parameter

Type

Description

error_code

String

Error code.

error_message

String

Error message.

Example Request

{
  "service" : {
    "meta_data" : {
      "name" : "service-example",
      "labels" : { }
    },
    "spec" : {
      "cluster_ip" : "None",
      "external_ips" : [ ],
      "external_name" : "",
      "ports" : [ {
        "name" : "http-0",
        "port" : "8888",
        "target_port" : "80",
        "protocol" : "TCP",
        "node_port" : ""
      } ],
      "selector" : {
        "app" : "ief-nginx"
      },
      "type" : ""
    }
  }
}

Example Response

Example response with status code 201:

{
  "service" : {
    "id" : "81acf9ff-de6d-4736-8d1a-f43bb058e79d",
    "project_id" : "e78acc02d9d141eda5ca8e88fa35f6f8",
    "meta_data" : {
      "name" : "service-example"
    },
    "spec" : {
      "selector" : {
        "app" : "ief-nginx"
      },
      "ports" : [ {
        "name" : "http-0",
        "protocol" : "TCP",
        "port" : "8888",
        "target_port" : "80"
      } ],
      "cluster_ip" : "None"
    },
    "created_at" : "2020-07-08 01:23:25.845332209 +0000 UTC",
    "updated_at" : "2020-07-08 01:23:25.845332209 +0000 UTC"
  }
}

Status Codes

Status Code

Description

201

Creation succeeded.

400

Error response.

500

Error response.

Error Codes

For details, see Error Codes.