V Kube API Guide

Overview:

We provide APIs for deployment and monitor of pod or order. APIs related to specific pod need secret to validate permissions(See V-Kube-Service Quick Start for more details), but some APIs needn't secret such as image checking, host port occupation validation and query valid deployment regions.

Endpoint:

Query valid regions
Check if image exist
Host port occupation validation
Query order information
Pod deployment
Query pod log
Pod deployment

Query valid regions

GET /k8s/regions

response

Status: 200 OK

[
    "region1",
    "region2",
    "region3"
]

Error Response

Status: 200 OK

[]

Check if image exist

GET /k8s/images?image=nginx&tag=stable

Request Parameters

query params

Parameter	Required	Type	Description
`image`	`true`	`String`	Image name to be verified.
`tag`	`true`	`String`	Image tag

response

Status: 200 OK

{
    "status": "OK"
}

Error response

Status Code	Response	Cause
404	{"error":{"code":404,"message":"image does not exist."}}	Image of the tag is not fund in Dock Hub
400	{"error":{"code":400,"message":"image format not allow.Format: image:tag"}}	Invalid format, it should be image:tag

Host port occupation validation

Check if port number has been occupied in specific region

POST /k8s/checkports

Request Parameters

json body

Parameters	Required	Type	Description
`region`	`true`	`String`	Region of ports occupation validation.
`ports`	`true`	`Value`	Ports numbers to be validated.

example：

{
    "region":"ausrine",
    "ports":[22,3306,1234,1111]
}

Response

Status: 200 OK

Status	Occupied	Cause
`NoResource`	"occupied:[]"	No related resources.Such as region doesn't exist.
`InternalErr`	"occupied:[]"	Internal error.
`PortsOccupied`	List all occupied ports，"occupied:[22,3306]"	All or some of selected host ports have been occupied in the region.
`NotOccupied`	"occupied:[]"	All of selected host ports are available.

example：

{
    "occupied": [
        22,
        3306
    ],
    "status": "PortsOccupied"
}

Error Response

Status Code	Response	Cause
400	{"error":{"code":400,"message":"item field empty"}}	Miss parameter. Such as: miss `region` or `ports`

Query order information

Query order information by secret

GET /k8s/order

Request parameter

Headers

Parameter	Required	Type	Description
`secret`	`true`	`String`	Secret to validate permissions of sensitive operations

example

curl --location --request GET 'http://$Endpoint/api/v1/k8s/order' \--header 'secret: 2Vu3Kdxxxxxxxxxxxxxxxxxxxxxxxx'

Response

Status: 200 OK

{
	"createdAt": 1620962741,
	"updatedAt": 1620962788,
	"duration": 100,
	"serviceExpiredDate": "",
	"amount": 18000,
	"amountPaid": 18000,
	"serviceID": "9xxxxxx0xxx6exxxxxxxxx",
	"service": "Container Service",
	"serviceCategoryID": "xxxxxxxxxxxxxxxxxxxxxxxx",
	"provider": "v-kube-service",
	"address": "xxxxxxxxxxxxxxxxxxxxxxxx",
	"recipient": "xxxxxxxxxxxxxxxxxxxxxxxx",
	"id": "xxxxxxxxxxxxxxxxxxxxxxxx",
	"serviceOptions": {
		"portSpecification": "User Specified Service Port",
		"resourceUnit": "2-Unit-Resource"
	},
	"status": "OrderFiled",
	"publicKey": ""
}

Fileds of response

Fileds Name	Type	Description
`createdAt`	`Value`	Order create time
`updatedAt`	`Value`	Order update time
`duration`	`Value`	Service available duration of the order
`serviceExpiredDate`	`String`	Service expired time
`amount`	`Value`	Amount to be paid for order
`amountPaid`	`Value`	Amount has already paid for order
`serviceID`	`String`	Purchased service id
`service`	`String`	Purchased service
`serviceCategoryID`	`String`	Service category id
`provider`	`String`	Service provider(merchant) name
`address`	`String`	Wallet address of service consumer
`recipient`	`String`	Wallet address of service merchant
`id`	`String`	Order id
`serviceOptions`	`Object`	Service option of order
`status`	`String`	Order status
`publicKey`	`String`	Public key used to make order

Error response

Status	Response	Cause
500	server errror	Internal error

Pod deployment

Deploy pod with secret

POST /api/v1/k8s/deploy

Request parameter

Headers

Parameter	Required	Type	Description
secret	true	string	Secret to validate permissions of sensitive operation

json body

Parameter	Required	Type	Description
`nodeSelector`	`true`	`Object`	Region selector object
`nodeSelector`:`region`	`true`	`String`	Selected region to deploy pod
`containers`	`true`	`Array-Object`	Container object.
`containers`:`name`	`true`	`String`	Container name
`containers`:`imageName`	`true`	`String`	Image deployed inner container
`containers`:`ports`	`false`	`Array-Object`	Container port and host port mapping
`containers`:`ports`:`containerPort`	`false`	`value`	Container port number
`containers`:`ports`:`hostPort`	`false`	`value`	Host port which container port map
`containers`:`resource`	`true`	`Object`	Container resource object
`containers`:`resource`:`memory`	`true`	`String`	Container memory size，Total memory size of containers have to be less or equal to memory size set by order. Unit: Mi, Gi
`containers`:`command`	`false`	`String`	Command which run container. Format: `"command":"/bin/sh\n-c\ntail -f /dev/null"`
`containers`:`args`	`false`	`String`	argment to run container. Format: `"args": "--vm\n1\n--vm-bytes\n500M\n--vm-hang\n1"`

example

{
	"nodeSelector": {
		"region": "ausrine"
	},
	"containers": [{
		"name": "container1",
		"imageName": "nginx",
		"ports": [{
			"containerPort": 80,
			"hostPort": 2999
		}],
		"resource": {
			"memory": "100Mi"
		}
	}]
}

Query pod log

Query pod log with secret

GET /k8s/pod/log

Request parameter

Headers

Parameter	Required	Type	Description
secret	true	string	Secret to validate permissions of sensitive operations

Response

Status: 200 OK

"/docker-entrypoint.sh: /docker-entrypoint.d/ is not empty, will attempt to perform configuration\n/docker-entrypoint.sh: Looking for shell scripts in /docker-entrypoint.d/\n/docker-entrypoint.sh: Launching /docker-entrypoint.d/10-listen-on-ipv6-by-default.sh\n10-listen-on-ipv6-by-default.sh: info: Getting the checksum of /etc/nginx/conf.d/default.conf\n10-listen-on-ipv6-by-default.sh: info: Enabled listen on IPv6 in /etc/nginx/conf.d/default.conf\n/docker-entrypoint.sh: Launching /docker-entrypoint.d/20-envsubst-on-templates.sh\n/docker-entrypoint.sh: Launching /docker-entrypoint.d/30-tune-worker-processes.sh\n/docker-entrypoint.sh: Configuration complete; xxx

Error response

Status	Response	Cause
500	server errror	Internal error

Query pod status data

Query pod status information with secret

GET /k8s/pod/status

Request parameter

Headers

Parameter	Required	Type	Description
`secret`	`true`	`String`	Secret to validate permissions of sensitive operations

Resonse

Status:200 OK

{
    "name": "71b60598-e176-4357-95b0-0e75e586363a-c57f44868-s7drh",
    "podStatus": {
        "phase": "Running",
        "conditions": [
            {
                "type": "Initialized",
                "status": "True",
                "lastProbeTime": null,
                "lastTransitionTime": "2021-05-13T08:37:46Z"
            },
            {
                "type": "Ready",
                "status": "True",
                "lastProbeTime": null,
                "lastTransitionTime": "2021-05-13T08:37:52Z"
            },
            {
                "type": "ContainersReady",
                "status": "True",
                "lastProbeTime": null,
                "lastTransitionTime": "2021-05-13T08:37:52Z"
            },
            {
                "type": "PodScheduled",
                "status": "True",
                "lastProbeTime": null,
                "lastTransitionTime": "2021-05-13T08:37:46Z"
            }
        ],
        "hostIP": "158.69.246.226",
        "podIP": "10.1.251.97",
        "podIPs": [
            {
                "ip": "10.1.251.97"
            }
        ],
        "startTime": "2021-05-13T08:37:46Z",
        "containerStatuses": [
            {
                "name": "nginx-test",
                "state": {
                    "running": {
                        "startedAt": "2021-05-13T08:37:52Z"
                    }
                },
                "lastState": {},
                "ready": true,
                "restartCount": 0,
                "image": "docker.io/library/nginx:latest",
                "imageID": "docker.io/library/nginx@sha256:df13abe416e37eb3db4722840dd479b00ba193ac6606e7902331dcea50f4f1f2",
                "containerID": "containerd://35626fabf29f62980a49889a8169928b062e4f5b14061bd12c2c6e50eb86403f",
                "started": true
            }
        ],
        "qosClass": "Burstable"
    },
    "podSpec": {
        "volumes": [
            {
                "name": "default-token-rd8kd",
                "secret": {
                    "secretName": "default-token-rd8kd",
                    "defaultMode": 420
                }
            }
        ],
        "containers": [
            {
                "name": "nginx-test",
                "image": "nginx",
                "ports": [
                    {
                        "hostPort": 2999,
                        "containerPort": 80,
                        "protocol": "TCP"
                    }
                ],
                "resources": {
                    "limits": {
                        "memory": "2Gi"
                    },
                    "requests": {
                        "cpu": "513m",
                        "memory": "2Gi"
                    }
                },
                "volumeMounts": [
                    {
                        "name": "default-token-rd8kd",
                        "readOnly": true,
                        "mountPath": "/var/run/secrets/kubernetes.io/serviceaccount"
                    }
                ],
                "terminationMessagePath": "/dev/termination-log",
                "terminationMessagePolicy": "File",
                "imagePullPolicy": "Always"
            }
        ],
        "restartPolicy": "Always",
        "terminationGracePeriodSeconds": 30,
        "dnsPolicy": "ClusterFirst",
        "nodeSelector": {
            "region": "giltine"
        },
        "serviceAccountName": "default",
        "serviceAccount": "default",
        "nodeName": "giltine",
        "securityContext": {},
        "imagePullSecrets": [
            {
                "name": "us-east-2-ecr-registry"
            }
        ],
        "schedulerName": "default-scheduler",
        "tolerations": [
            {
                "key": "node.kubernetes.io/not-ready",
                "operator": "Exists",
                "effect": "NoExecute",
                "tolerationSeconds": 300
            },
            {
                "key": "node.kubernetes.io/unreachable",
                "operator": "Exists",
                "effect": "NoExecute",
                "tolerationSeconds": 300
            }
        ],
        "priority": 0,
        "enableServiceLinks": true,
        "preemptionPolicy": "PreemptLowerPriority"
    },
    "annotations": {
        "cni.projectcalico.org/podIP": "10.1.251.97/32",
        "cni.projectcalico.org/podIPs": "10.1.251.97/32",
        "kubernetes.io/egress-bandwidth": "1024M",
        "kubernetes.io/ingress-bandwidth": "1024M"
    }
}

Field Name	Type	Description
`name`	`String`	the `name` of `pod`
`podStatus`	`Object`	represents information about the status of a `pod`
`podSpec`	`Object`	a description of a `pod`
`annotations`	`Object`	annotations is an unstructured key value map stored with a resource

Field of podStatus

Field	Type	Description
`phase`	`String`	the `phase` of a `Pod` is a simple, high-level summary of where the Pod is in its lifecycle
`conditions`	`Array-Object`	current service state of `pod`
`hostIP`	`String`	IP address of the host to which the pod is assigned
`podIP`	`String`	IP address allocated to the pod. Routable at least within the cluster.
`podIPs`	`Array-Object`	podIPs holds the IP addresses allocated to the pod
`startTime`	`String`	RFC 3339 date and time at which the object was acknowledged by the Kubelet. This is before the Kubelet pulled the container image(s) for the pod.
`containerStatuses`	`Array-Object`	The list has one entry per container in the manifest.Each entry is currently the output of `docker inspect`
`qosClass`	`String`	The Quality of Service (QOS) classification assigned to the pod based on resource requirements

Filed of conditions

Field	Type	Description
`type`	`String`	Type is the type of the condition
`status`	`String`	Status is the status of the condition
`lastProbeTime`	`null`	Last time we probed the condition
`lastTransitionTime`	`String`	Last time the condition transitioned from one status to another

Field of podIPs

Field	Type	Description
`ip`	`String`	ip is an IP address (IPv4 or IPv6) assigned to the pod

Field of containerStatus

Field	Type	Description
`name`	`String`	Each container in a pod must have a unique name. Cannot be updated.
`state`	`Object`	Details about the container's current condition.
`lastState`	`Object`	Details about the container's last termination condition.
`ready`	`Boolean`	Specifies whether the container has passed its readiness probe.
`restartCount`	`Value`	The number of times the container has been restarted, currently based on the number of dead containers that have not yet been removed.
`image`	`String`	The image the container is running.
`imageID`	`String`	ImageID of the container's image.
`containerID`	`String`	Container's ID in the format 'docker://<container_id>'.
`started`	`Boolean`	Specifies whether the container has passed its startup probe.

Field of state

Field	Type	Description
`running`	`Object`	Details about a running container
`terminated`	`Object`	Details about a terminated container
`waiting`	`Object`	Details about a waiting container

Field of running

Field	Type	Description
`startedAt`	`String`	Time at which the container was last (re-)started

Field of terminated

Field	Type	Description
`containerID`	`String`	Container's ID in the format 'docker://<container_id>'
`existCode`	`Value`	Exit status from the last termination of the container
`finishedAt`	`String`	Time at which the container last terminated
`message`	`String`	Message regarding the last termination of the container
`reason`	`String`	(brief) reason from the last termination of the container
`signal`	`Value`	Signal from the last termination of the container
`startedAt`	`String`	Time at which previous execution of the container started

Field of waiting

Field	Type	Description
`message`	`String`	Message regarding why the container is not yet running.
`reason`	`String`	(brief) reason the container is not yet running.

Field of podSpec

Field	Type	Description
`activeDeadlineSeconds`	`Value`	Optional duration in seconds the pod may be active on the node relative to `StartTime` before the system will actively try to mark it failed and kill associated containers.
`affinity`	`Object`	If specified, the pod's scheduling constraints
`automountServiceAccountToken`	`Boolean`	`AutomountServiceAccountToken` indicates whether a service account token should be automatically mounted.
`containers`	`Array-Object`	List of containers belonging to the pod.
`dnsConfig`	`Object`	Specifies the DNS parameters of a pod.Parameters specified here will be merged to the generated DNS configuration based on DNSPolicy.
`dnsPolicy`	`String`	Set DNS policy for the pod. Defaults to "ClusterFirst".
`enableServiceLinks`	`Boolean`	`EnableServiceLinks` indicates whether information about services should be injected into pod's environment variables, matching the syntax of Docker links. Optional: Defaults to true.
`ephemeralContainers`	`Array-Object`	List of ephemeral containers run in this pod. Ephemeral containers may be run in an existing pod to perform user-initiated actions such as debugging.
`hostAliases`	`Array-Object`	`HostAliases` is an optional list of hosts and IPs that will be injected into the pod's hosts file if specified. This is only valid for non-hostNetwork pods.
`hostIPC`	`Array-Obejct`	Use the host's ipc namespace. Optional: Default to false.
`hostNetwork`	`Boolean`	Host networking requested for this pod. Use the host's network namespace.If this option is set, the ports that will be used must be specified.Default to false.
`hostPID`	`Boolean`	Use the host's pid namespace. Optional: Default to false.
`hostname`	`String`	Specifies the hostname of the Pod If not specified, the pod's hostname will be set to a system-defined value.
`imagePullSecrets`	`Array-Object`	ImagePullSecrets is an optional list of references to secrets in the same namespace to use for pulling any of the images used by this PodSpec.
`initContainers`	`Array-Object`	List of initialization containers belonging to the pod. Init containers are executed in order prior to containers being started. If any init container fails, the pod is considered to have failed and is handled according to its restartPolicy.
`nodeName`	`String`	`NodeName` is a request to schedule this pod onto a specific node.
`nodeSelector`	`Object`	`NodeSelector` is a selector which must be true for the pod to fit on a node.
`overhead`	`Object`	Overhead represents the resource overhead associated with running a pod for a given RuntimeClass.
`preemptionPolicy`	`String`	`PreemptionPolicy` is the Policy for preempting pods with lower priority
`priority`	`Value`	The priority value. Various system components use this field to find the priority of the pod.The higher the value, the higher the priority.
`priorityClassName`	`String`	If specified, indicates the pod's priority.
`readinessGates`	`Array-Obejct`	If specified, all readiness gates will be evaluated for pod readiness.
`restartPolicy`	`String`	Restart policy for all containers within the pod.
`runtimeClassName`	`String`	RuntimeClassName refers to a RuntimeClass object in the node.k8s.io group,which should be used to run this pod.
`schedulerName`	`String`	If specified, the pod will be dispatched by specified scheduler. If not specified, the pod will be dispatched by default scheduler.
`securityContext`	`Object`	SecurityContext holds pod-level security attributes and common container settings. Optional: Defaults to empty.
`serviceAccountName`	`String`	ServiceAccountName is the name of the ServiceAccount to use to run this pod.
`shareProcessNamespace`	`Boolean`	Share a single process namespace between all of the containers in a pod.
`subdomain`	`String`	If specified, the fully qualified Pod hostname will be "<hostname>.<subdomain>.<pod namespace>.svc.<cluster domain>".
`terminationGracePeriodSeconds`	`Value`	Optional duration in seconds the pod needs to terminate gracefully.
`tolerations`	`Array-Object`	If specified, the pod's tolerations.
`topologySpreadConstraints`	`Array-Object`	TopologySpreadConstraints describes how a group of pods ought to spread across topology domains.
`volumes`	`Array-Object`	List of volumes that can be mounted by containers belonging to the pod.

Field of volumes

Field	Type	Description
`name`	`String`	Volume's name.
`secret`	`Object`	Secret represents a secret that should populate this volume.

Field of secret

Field	Type	Description
`secretName`	`String`	Name of the secret in the pod's namespace to use
`defaultMode`	`Value`	Optional: mode bits to use on created files by default.Defaults to 0644.

Field of containers

Field	Type	Description
`name`	`String`	Name of the container
`image`	`String`	Docker image name
`ports`	`Array-Object`	List of ports to expose from the container.
`resources`	`Object`	Compute Resources required by this container.
`volumeMounts`	`Array-Object`	Pod volumes to mount into the container's filesystem. Cannot be updated.
`terminationMessagePath`	`Value`	Optional: Path at which the file to which the container's termination message will be written is mounted into the container's filesystem.
`terminationMessagePolicy`	`String`	Indicate how the termination message should be populated.
`imagePullPolicy`	`String`	Image pull policy. One of Always, Never, IfNotPresent. Defaults to Always
`args`	`Array-String`	Arguments to the entrypoint. The docker image's CMD is used if this is not provided.

Field of ports

Field	Type	Description
`hostPort`	`Value`	Number of port to expose on the host. If specified, this must be a valid port number, 0 < x < 65536.
`containerPort`	`Value`	Number of port to expose on the pod's IP address. This must be a valid port number, 0 < x < 65536.
`protocol`	`String`	Protocol for port. Must be UDP, TCP, or SCTP. Defaults to "TCP".

Field of resources

Field	Type	Description
`limits`	`Object`	Limits describes the maximum amount of compute resources allowed.
`requests`	`Object`	Requests describes the minimum amount of compute resources required.

Field of limits

Field	Type	Description
`memory`	`String`	unit:Ki \| Mi \|Gi \|Ti \|Pi \|Ei
`cpu`	`String`	unit:m

Field of requests

Field	Type	Description
`memory`	`String`	nit:Ki \|Mi \|Gi \|Ti \|Pi \|Ei
`cpu`	`String`	unit:m

Field of volumeMounts

Field	Type	Description
`name`	`String`	This must match the Name of a Volume.
`readOnly`	`Boolean`	Mounted read-only
`mountPath`	`String`	Path within the container at which the volume should be mounted. Must not contain ':'.

Field of nodeSelector

Filed	Type	Description
`region`	`String`	node belongs to the `region`

Field of imagePullSecrets

Field	Type	Description
`name`	`String`	Name of the referent

Field of tolerations

Field	Type	Description
`key`	`String`	Key is the taint key that the toleration applies to.
`operator`	`String`	Operator represents a key's relationship to the value. Valid operators are Exists and Equal.
`effect`	`String`	Effect indicates the taint effect to match.
`tolerationSeconds`	`Value`	TolerationSeconds represents the period of time the toleration (which must be of effect NoExecute, otherwise this field is ignored) tolerates the taint.

Field of annotations

Field	Type	Description
`cni.projectcalico.org/podIP`	`String`	ip
`cni.projectcalico.org/podIPs`	`String`	ip
`kubernetes.io/egress-bandwidth`	`String`	egress
`kubernetes.io/ingress-bandwidth`	`String`	ingress

← V Kube Web Console