API 使用指引

1. 调用方式

1.1. 创建访问凭证

访问【平台管理】控制台，在左侧找到【组织资源】，选择【访问凭证】，新建一个访问凭证。

1.2. 访问 API

TKEStack上各种资源的接口均以 Kubernetes 原生 API 的形式提供，所有接口使用统一的前缀: http://console.tke.com:8080/platform，请求中需要将上一步申请的访问凭证以"Authorization: Bearer ${访问凭证}"的形式放入 header。

以查询集群信息为例，使用的请求如下：

  1. curl -H "Authorization: Bearer xxxxxxx" \
  2. "http://console.tke.com:8080/platform/apis/platform.tkestack.io/v1/clusters"

1.3. 查看特定集群的 Namespace

查看集群所包含的 Namespace 需要传递 “X-TKE-ClusterName: cls-xxx” 的 header，cls-xxx 为特定集群 ID

  1. curl -H "Authorization: Bearer xxxxxxx" \
  2. -H "X-TKE-ClusterName: cls-xxx" \
  3. "http://console.tke.com:8080/platform/api/v1/namespaces"

2. 通过 API 创建应用

2.1. 非 TApp 应用（deployment，statefulset，daemonset）

  1. curl 'http://console.tke.com:8080/platform/apis/apps/v1/namespaces/命名空间/工作负载类型/工作负载名称' 
  3. -X PATCH
  5. -H 'Content-Type:application/strategic-merge-patch+json' 
  7. -H 'X-TKE-ClusterName:所属集群'
  9. -H 'Authorization: Bearer 访问凭证'
  11. -d '{"spec":{"template":{"spec":{"containers":[{"name":"容器名称","image":"容器镜像"}]}}}}'

工作负载类型： 选择需要更新的工作负载类型（deployment，statefulset， daemonset） 所属集群：填写所要更新容器所属集群。 命名空间：填写所要更新容器所属的命名空间。 工作负载名称：填写所要更新容器的工作负载名称。 容器名称：填写所要更新容器的名称。 访问凭证：填写访问该容器资源的访问凭证，可以在“tkestack-组织资源-访问凭证“中获取该信息（访问凭证有过期时间，如过期需要重新创建）。 容器镜像：填写所要更新的Docker镜像

2.2. TApp

TApp 是自研的应用类型，更新镜像需要两步，首先获取当前的容器 spec，调整镜像名后在调用更新接口

2.2.1. 获取tapp spec

  1. curl 'http://console.tke.com:8080/platform/apis/platform.tkestack.io/v1/clusters/所属集群/tapps?namespace=命名空间&name=工作负载名称'
  3. -X GET
  5. -H 'Authorization: Bearer 访问凭证'

返回值示例：

{"apiVersion":"apps.tkestack.io/v1","kind":"TApp","metadata":{"creationTimestamp":"2020-06-10T13:35:54Z","generation":8,"labels":{"k8s-app":"kevintest","qcloud-app":"kevintest"},"name":"kevintest","namespace":"default","resourceVersion":"13925571","selfLink":"/apis/apps.tkestack.io/v1/namespaces/default/tapps/kevintest","uid":"0269fb69-fa87-42f8-9c3a-e1f96cef40f1"},"spec":{"forceDeletePod":true,"replicas":1,"selector":{"matchLabels":{"k8s-app":"kevintest","qcloud-app":"kevintest"}},"template":{"metadata":{"creationTimestamp":null,"labels":{"k8s-app":"kevintest","qcloud-app":"kevintest","tapp_template_hash_key":"9636164821252331163","tapp_uniq_hash_key":"9518255606018677371"}},"spec":{"containers":[{"image":"mirrors.tencent.com/elsanli/devops-demo:62","imagePullPolicy":"Always","livenessProbe":{"failureThreshold":10,"periodSeconds":10,"successThreshold":1,"tcpSocket":{"port":8888},"timeoutSeconds":2},"name":"test","readinessProbe":{"failureThreshold":10,"periodSeconds":30,"successThreshold":1,"tcpSocket":{"port":8888},"timeoutSeconds":2},"resources":{"limits":{"cpu":"100m","memory":"48Mi"},"requests":{"cpu":"100m","memory":"25Mi"}}}],"restartPolicy":"Always"}},"updateStrategy":{}},"status":{"appStatus":"Running","observedGeneration":7,"readyReplicas":0,"replicas":1,"scaleLabelSelector":"k8s-app=kevintest,qcloud-app=kevintest","statuses":{"0":"Pending"}}}

2.3. 更新 TApp 镜像

从上一步返回值中获取想要更新的整个容器的 spec，替换其中的 image 字段，这样做是为了避免将其他字段覆盖为空

  1. curl ''http://console.tke.com:8080/platform/apis/platform.tkestack.io/v1/clusters/所属集群/tapps?namespace=命名空间&name=工作负载名称'
  3. -X PATCH
  5. -H 'Content-Type:application/merge-patch+json' 
  7. -H 'X-TKE-ClusterName:所属集群'
  9. -H 'Authorization: Bearer 访问凭证'
  11. -d '{"spec":{"template":{"spec":{"containers":[{"name":"容器名称","image":"容器镜像","resources":{"limits":{"cpu":"100m","memory":"48Mi"},"requests":{"cpu":"100m","memory":"25Mi"}},"livenessProbe":{"tcpSocket":{"port":8888},"timeoutSeconds":2,"periodSeconds":10,"successThreshold":1,"failureThreshold":10},"readinessProbe":{"tcpSocket":{"port":8888},"timeoutSeconds":2,"periodSeconds":30,"successThreshold":1,"failureThreshold":10},"imagePullPolicy":"Always"}]}},"templates":null}}

所属集群：填写所要更新容器所属集群。 命名空间：填写所要更新容器所属的命名空间。 工作负载名称：填写所要更新容器的工作负载名称。 容器名称：填写所要更新容器的名称。 访问凭证：填写访问该容器资源的访问凭证，可以在“tkestack-组织资源-访问凭证“中获取该信息（访问凭证有过期时间，如过期需要重新创建）。 容器镜像：填写所要更新的Docker镜像

3. 通过 API 增删集群节点

只能对独立集群的节点进行增删操作，不可操作导入集群。

3.1. 增加节点

URL: http://console.tke.com:8080/platform/apis/platform.tkestack.io/v1/machines

Method: POST

Headers:

  1. Content-Type: application/json
  2. Authorization: Bearer xxx

按照以下命令的格式，将中文部分替换成实际值，发送请求。请求成功后，会返回被创建的Machine对象。

  1. curl -X POST \
  2. "http://console.tke.com:8080/platform/apis/platform.tkestack.io/v1/machines" \
  3. -H "Content-Type: application/json" \
  4. -H "Authorization: Bearer 你的访问凭证" \
  5. -d '
  6. {
  7.     "kind": "Machine",
  8.     "apiVersion": "platform.tkestack.io/v1",
  9.     "metadata": {
  10.         "generateName": "mc-"
  11.     },
  12.     "spec": {
  13.         "finalizers": [
  14.             "machine"
  15.         ],
  16.         "tenantID": "租户ID（联系平台管理员获取）",
  17.         "clusterName": "集群ID，可通过页面查看（不是集群名称）",
  18.         "type": "Baremetal",
  19.         "ip": "节点IP",
  20.         "port": 节点SSH端口（int）,
  21.         "username": "root",
  22.         "password": "节点root密码(需经base64编码)"
  23.     }
  24. }'

password base64编码：

echo -n $PASSWORD | base64 假设password原文为123456，则生成的base64编码为MTIzNDU2

PS: 使用 echo 命令时一定加上 -n 参数

3.2. 查看节点

URL: http://console.tke.com:8080/platform/apis/platform.tkestack.io/v1/machines/${machine.metadata.name}

Method: GET

Headers:

  1. Authorization: Bearer xxx

假设平台中有 name 为 mc-brd44nzd 的 Machine 对象：

  1. {
  2.   "kind": "Machine",
  3.   "apiVersion": "platform.tkestack.io/v1",
  4.   "metadata": {
  5.     "name": "mc-brd44nzd",
  6.     "generateName": "mc-",
  7.     "selfLink": "/apis/platform.tkestack.io/v1/machines/mc-brd44nzd",
  8.     "uid": "9ef7c08f-c535-4e99-b11d-9f7d02be19f5",
  9.     "resourceVersion": "343953553",
  10.     "creationTimestamp": "2020-02-27T00:25:02Z"
  11.   },
  12.   "spec": {
  13.     "finalizers": [
  14.       "machine"
  15.     ],
  16.     "tenantID": "default",
  17.     "clusterName": "xxxx",
  18.     "type": "Baremetal",
  19.     "ip": "xxxxxx",
  20.     "port": 36000,
  21.     "username": "root",
  22.     "password": "xxxxxx"
  23.   }
  24. }

则查看该 Machine 部署进度的请求为：

  1. curl "http://console.tke.com:8080/platform/apis/platform.tkestack.io/v1/machines/mc-brd44nzd" \
  2. -H "Authorization: Bearer 你的访问凭证"

3.3. 删除节点

URL: http://console.tke.com:8080/platform/apis/platform.tkestack.io/v1/machines/${machine.metadata.name}

Method: DELETE

Headers:

  1. Authorization: Bearer xxx

假设平台中有 name 为 mc-brd44nzd 的 Machine 对象，则删除节点的请求为：

  1. curl -X DELETE "http://console.tke.com:8080/platform/apis/platform.tkestack.io/v1/machines/mc-brd44nzd" \
  2. -H "Authorization: Bearer 你的访问凭证"

4. 通过 API 获取业务信息

4.1. 查看自身所在业务

  1. curl 'http://console.tke.com:8080/business/apis/business.tkestack.io/v1/portal' \
  2. -X GET \
  3. -H "Authorization: Bearer 访问凭证"

4.2. 查看特定业务包含的 Namespace 信息

  1. curl 'http://console.tke.com:8080/business/apis/business.tkestack.io/v1/namespaces/prj-xxx/namespaces' \
  2. -X GET \
  3. -H "Authorization: Bearer 访问凭证"
  4. prj-xxx 为业务 id

4.3. 查看特定业务信息

  1. curl 'http://console.tke.com:8080/business/apis/business.tkestack.io/v1/projects/prj-xxx' \
  2. -X GET \
  3. -H 'Authorization: Bearer 访问凭证'
  4. prj-xxx为业务id