Help Center> Cloud Container Engine> API Reference> Kubernetes APIs> Endpoints> Creating an Endpoints Object
View PDF

Creating an Endpoints Object

Function

This API is used to create an Endpoints object.

URI

POST /api/v1/namespaces/{namespace}/endpoints

Table 1 describes the parameters of this API.

Table 1 Parameter description

Parameter

Mandatory

Description

pretty

No

If 'true', then the output is pretty printed.

namespace

Yes

Object name and auth scope, such as for teams and projects.

Request

Request parameters:

Table 2 describes the request parameters.

Table 2 Parameter description

Parameter

Mandatory

Type

Description

kind

Yes

String

Kind is a string value representing the REST resource this object represents. Servers may infer this from the endpoint the client submits requests to. Cannot be updated. In CamelCase.

The value of this parameter is Endpoints.

apiVersion

Yes

String

APIVersion defines the versioned schema of this representation of an object. Servers should convert recognized schemas to the latest internal value, and may reject unrecognized values.

The value of this parameter is v1.

metadata

Yes

metadata object

-

subsets

Yes

subsets object

The set of all endpoints is the union of all subsets. Addresses are placed into subsets according to the IPs they share. A single address with multiple ports, some of which are ready and some of which are not (because they come from different containers) will result in the address being displayed in different subsets for the different ports. No address will appear in both Addresses and NotReadyAddresses in the same subset. Sets of addresses and ports that comprise a service.
Table 3 Data structure of the subsets field

Parameter

Mandatory

Type

Description

addresses

Yes

addresses object

IP addresses which offer the related ports that are marked as ready. These endpoints should be considered safe for load balancers and clients to utilize.

notReadyAddresses

No

addresses object

IP addresses which offer the related ports but are not currently marked as ready because they have not yet finished starting, have recently failed a readiness check, or have recently failed a liveness check.

ports

Yes

ports object

Port numbers available on the related IP addresses.
Table 4 Data structure of the addresses field

Parameter

Mandatory

Type

Description

ip

Yes

String

IP of this endpoint.

targetRef

No

targetRef object

-

hostname

No

String

Host name of this endpoint meant to be used by DNS servers.

nodeName

No

String

Optional: Node hosting this endpoint. This can be used to determine endpoints local to a node.
Table 5 Data structure of the ports field

Parameter

Mandatory

Type

Description

name

No

String

The name of this port (corresponds to ServicePort.Name). Must be a DNS_LABEL. Optional only if one port is defined.

Value length: 0 character < String length ≤ 63 characters.

The string must comply with regular expression [a-z0-9]([-a-z0-9]*[a-z0-9])?.

port

No

Integer

The port number of the endpoint.

Value range: (0,65535].

protocol

No

String

The IP protocol for this port.

This parameter can be set to:

  • TCP
  • UDP

    Default: TCP.
Table 6 Data structure of the targetRef field

Parameter

Mandatory

Type

Description

kind

No

String

Phase is the current lifecycle phase of the namespace.

namespace

No

String

Namespace of the referent.

name

No

String

Name of the referent.

uid

No

String

UID of the referent.

apiVersion

No

String

API version of the referent.

resourceVersion

No

String

Specific resourceVersion to which this reference is made, if any.

NOTE:

This parameter is automatically generated. Do not assign values to this parameter. Otherwise, the API fails to be called.

fieldPath

No

String

If referring to a piece of an object instead of an entire object, this string should contain a valid JSON/Go field access statement, such as desiredState.manifest.containers[2]. For example, if the object reference is to a container within a pod, this would take on a value like: "spec.containers{name}" (where "name" refers to the name of the container that triggered the event) or if no container name is specified "spec.containers[2]" (container with index 2 in this pod). This syntax is chosen only to have some well-defined way of referencing a part of an object.

Example request:

{ 
   "kind": "Endpoints", 
   "apiVersion": "v1", 
   "metadata": { 
     "name": "cluster-test" 
   }, 
   "subsets": [ 
     { 
       "addresses": [ 
         { 
           "ip": "172.16.106.152" 
         } 
       ], 
       "ports": [ 
         { 
           "port": 1 
         } 
       ] 
     }, 
     { 
       "addresses": [ 
         { 
           "ip": "172.16.79.157" 
         } 
       ], 
       "ports": [ 
         { 
           "port": 1 
         } 
       ] 
     } 
       ] 
 }

Response

Response parameters:

For the description about response parameters, see the parameter description in Request.

Example response:

{ 
   "kind": "Endpoints", 
   "apiVersion": "v1", 
   "metadata": { 
     "name": "cluster-test", 
     "namespace": "default", 
     "selfLink": "/api/v1/namespaces/default/endpoints/cluster-test", 
     "uid": "81b1503d-5960-11e6-b444-286ed488fafe", 
     "resourceVersion": "18186", 
     "creationTimestamp": "2016-08-03T09:56:10Z" 
   }, 
   "subsets": [ 
     { 
       "addresses": [ 
         { 
           "ip": "172.16.106.152" 
         }, 
         { 
           "ip": "172.16.79.157" 
         } 
       ], 
       "ports": [ 
         { 
           "port": 1, 
           "protocol": "TCP" 
         } 
       ] 
     } 
       ] 
 }

Status Code

Table 7 describes the status code of this API.

Table 7 Status code

Status Code

Description

201

This operation succeeds, and an Endpoint resource object is returned.

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

Parent topic: Endpoints