ForwardKubernetesApi--容器服务-火山引擎

文档中心

立即注册

导航

ForwardKubernetesApi

最近更新时间：2024.09.23 14:30:51首次发布时间：2022.08.22 10:51:01

代理转发 Kubernetes 原生 API。

接口说明

通过该 API，转发请求到您集群的 API Server，访问集群内 Kubernetes 原生资源对象。推荐您使用Kubernetes 原生 API，使用方法，请参见官方文档。

请求说明

请求方式：POST
请求地址：https://open.volcengineapi.com/?Action=ForwardKubernetesApi&Version=2022-05-12

请求参数

调用该 API 时的请求参数如下，除此之外还需传入公共请求参数。公共请求参数说明，请参见公共参数。

参数	类型	是否必选	示例值	描述
Action	String	是	ForwardKubernetesApi	接口名称。当前 API 的名称为 `ForwardKubernetesApi`。
Version	String	是	2022-05-12	接口版本。当前 API 的版本为 `2022-05-12`。
ClusterId	String	是	cc5sil****	目标集群 ID。可以调用 ListClusters 接口，获取集群 ID。注意集群必须处于`{Running,[Ok]}`或`{Updating,[Progressing]}`状态。可调用 ListClusters 接口获取集群当前的状态。
Method	String	是	POST	请求方法，取值： GET POST PUT PATCH DELETE
Path	String	是	/api/v1/namespaces/default/configmaps	请求路径，例如 `/api/v1/namespaces/test/configmaps`。
Body	String	否	{"apiVersion": "v1",\n "kind": "ConfigMap",\n "metadata": {\n "name": "test0"\n },\n "data": {\n "k": "v",\n "a": "b"\n }\n}	请求体，必须为 JSON 格式的字符串内容，且大小不超过 1.5 MB。当 Method 为 GET、DELETE 时可以不填。 Method 为 POST、PUT、PATCH 时必须填写。
Headers	Array of Header	否	[ { "Key": "Content-Type", "Value": "application/json-patch+json" } ]	请求头。当`Method=PATCH`时才生效。

参数	类型	是否必选	示例值	描述
Key	String	否	Content-Type	请求头的 Key。当前仅支持设置 Content-Type，以使用不同的 PATCH 方法。说明支持 jsonPatch、mergePatch、strategicMergePatch 三种 PATCH 方法。三种方法的具体差异，请参见 Kubernetes Patch 文档。请求头的 Key 和 Value 使用方法，请参见本文下方 jsonPatch ConfigMap、mergePatch ConfigMap、strategicMergePatch ConfigMap。
Value	String	否	application/json-patch+json	请求头的 Value。当 Key 为 Content-Type 时，取值： application/strategic-merge-patch+json（默认值） application/json-patch+json application/merge-patch+json 说明支持 jsonPatch、mergePatch、strategicMergePatch 三种 PATCH 方法。三种方法的具体差异，请参见 Kubernetes Patch 文档。请求头的 Key 和 Value 使用方法，请参见本文下方 jsonPatch ConfigMap、mergePatch ConfigMap、strategicMergePatch ConfigMap。

参数

类型

是否必选

示例值

描述

Key

String

否

Content-Type

请求头的 Key。当前仅支持设置 Content-Type，以使用不同的 PATCH 方法。

说明

支持 jsonPatch、mergePatch、strategicMergePatch 三种 PATCH 方法。三种方法的具体差异，请参见 Kubernetes Patch 文档。
请求头的 Key 和 Value 使用方法，请参见本文下方 jsonPatch ConfigMap、mergePatch ConfigMap、strategicMergePatch ConfigMap。

Value

String

否

application/json-patch+json

请求头的 Value。当 Key 为 Content-Type 时，取值：

application/strategic-merge-patch+json（默认值）
application/json-patch+json
application/merge-patch+json

说明

支持 jsonPatch、mergePatch、strategicMergePatch 三种 PATCH 方法。三种方法的具体差异，请参见 Kubernetes Patch 文档。
请求头的 Key 和 Value 使用方法，请参见本文下方 jsonPatch ConfigMap、mergePatch ConfigMap、strategicMergePatch ConfigMap。

返回参数

本接口返回参数如下表所示，公共返回参数请参见返回结果。

参数	类型	示例值	描述
Code	Integer	200	kube-apiserver 返回的 HTTP 状态码。
Body	String	{"kind":"ConfigMap","apiVersion":"v1","metadata":{"name":"test0","namespace":"default","uid":"f36da08a-19ba-4a1a-b58c-49a7df226bf1","resourceVersion":"4054998","creationTimestamp":"2021-10-09T08:49:17Z","managedFields":[{"manager":"___2go_build_main_go","operation":"Update","apiVersion":"v1","time":"2021-10-09T08:49:17Z","fieldsType":"FieldsV1","fieldsV1":{"f:data":{".":{},"f:a":{},"f:k":{}}}}]},"data":{"a":"b","k":"v"}}\n	Kube-apiserver 返回的响应内容。

示例

List ConfigMaps

请求示例

以查询集群内 default 命名空间下的所有配置项为例。

POST https://open.volcengineapi.com/?Action=ForwardKubernetesApi&Version=2022-05-12
Content-Type: application/json
{
    "Method": "GET",
    "ClusterId": "cc52sgo****",
    "Path": "/api/v1/namespaces/default/configmaps"
}

返回示例

{
    "ResponseMetadata": {
        "RequestId": "",
        "Action": "ForwardKubernetesApi",
        "Version": "2022-05-12",
        "Service": "",
        "Region": ""
    },
    "Result": {
        "Code": 200,
        "Body": "{\"kind\":\"ConfigMapList\",\"apiVersion\":\"v1\",\"metadata\":{\"resourceVersion\":\"4054939\"},\"items\":[{\"metadata\":{\"name\":\"kube-root-ca.crt\",\"namespace\":\"default\",\"uid\":\"c792626b-b85e-469f-8bb5-4dd******\",\"resourceVersion\":\"359\",\"creationTimestamp\":\"2021-09-18T11:22:44Z\",\"managedFields\":[{\"manager\":\"kube-controller-manager\",\"operation\":\"Update\",\"apiVersion\":\"v1\",\"time\":\"2021-09-18T11:22:44Z\",\"fieldsType\":\"FieldsV1\",\"fieldsV1\":{\"f:data\":{\".\":{},\"f:ca.crt\":{}}}}]},\"data\":{\"ca.crt\":\"-----BEGIN CERTIFICATE-----\\nMIIC6jCCAd******\\n-----END CERTIFICATE-----\\n\"}}]}\n",
    }
}

Get ConfigMap

请求示例

以查询集群内 default 命名空间下的名为 test0 的配置项为例。

POST https://open.volcengineapi.com/?Action=ForwardKubernetesApi&Version=2022-05-12
Content-Type: application/json
{
    "Method": "GET",
    "ClusterId": "cc52sgo****",
    "Path": "/api/v1/namespaces/default/configmaps/test0"
}

返回示例

{
    "ResponseMetadata": {
        "RequestId": "",
        "Action": "ForwardKubernetesApi",
        "Version": "2022-05-12",
        "Service": "",
        "Region": ""
    },
    "Result": {
        "Code": 200,
        "Body": "{\"kind\":\"ConfigMap\",\"apiVersion\":\"v1\",\"metadata\":{\"name\":\"test0\",\"namespace\":\"default\",\"uid\":\"f36da08a-19ba-4a1a-b58c-49******\",\"resourceVersion\":\"4054998\",\"creationTimestamp\":\"2021-10-09T08:49:17Z\",\"managedFields\":[{\"manager\":\"___2go_build_main_go\",\"operation\":\"Update\",\"apiVersion\":\"v1\",\"time\":\"2021-10-09T08:49:17Z\",\"fieldsType\":\"FieldsV1\",\"fieldsV1\":{\"f:data\":{\".\":{},\"f:a\":{},\"f:k\":{}}}}]},\"data\":{\"a\":\"b\",\"k\":\"v\"}}\n",
    }
}

Create ConfigMap

请求示例

以在集群内 default 命名空间下创建配置项为例。

POST https://open.volcengineapi.com/?Action=ForwardKubernetesApi&Version=2022-05-12
Content-Type: application/json
{
    "Method": "POST",
    "ClusterId": "cc52sgo****",
    "Path": "/api/v1/namespaces/default/configmaps",
    "Body": "{\"apiVersion\": \"v1\",\n  \"kind\": \"ConfigMap\",\n  \"metadata\": {\n    \"name\": \"test0\"\n  },\n  \"data\": {\n    \"k\": \"v\",\n    \"a\": \"b\"\n  }\n}"
}

返回示例

{
    "ResponseMetadata": {
        "RequestId": "",
        "Action": "ForwardKubernetesApi",
        "Version": "2022-05-12",
        "Service": "",
        "Region": ""
    },
    "Result": {
        "Code": 201,
        "Body": "{\"kind\":\"ConfigMap\",\"apiVersion\":\"v1\",\"metadata\":{\"name\":\"test0\",\"namespace\":\"default\",\"uid\":\"f36da08a-19ba-4a1a-b58c-49******\",\"resourceVersion\":\"4055171\",\"creationTimestamp\":\"2021-10-09T08:49:17Z\",\"managedFields\":[{\"manager\":\"___2go_build_main_go\",\"operation\":\"Update\",\"apiVersion\":\"v1\",\"time\":\"2021-10-09T08:49:17Z\",\"fieldsType\":\"FieldsV1\",\"fieldsV1\":{\"f:data\":{\".\":{},\"f:a\":{},\"f:k\":{}}}}]},\"data\":{\"a\":\"bd\",\"k\":\"v\"}}\n",
    }
}

Update ConfigMap

请求示例

以在集群内 default 命名空间下更新名为 test0 的配置项为例。

POST https://open.volcengineapi.com/?Action=ForwardKubernetesApi&Version=2022-05-12
Content-Type: application/json
{
    "Method": "PUT",
    "ClusterId": "cc52sgo****",
    "Path": "/api/v1/namespaces/default/configmaps/test0",
    "Body": "{\"apiVersion\": \"v1\",\n  \"kind\": \"ConfigMap\",\n  \"metadata\": {\n    \"name\": \"test0\"\n  },\n  \"data\": {\n    \"k\": \"v\",\n    \"a\": \"bd\"\n  }\n}"
}

返回示例

{
    "ResponseMetadata": {
        "RequestId": "",
        "Action": "ForwardKubernetesApi",
        "Version": "2022-05-12",
        "Service": "",
        "Region": ""
    },
    "Result": {
        "Code": 200,
        "Body": "{\"kind\":\"ConfigMap\",\"apiVersion\":\"v1\",\"metadata\":{\"name\":\"test0\",\"namespace\":\"default\",\"uid\":\"f36da08a-19ba-4a1a-b58c-49******\",\"resourceVersion\":\"4055171\",\"creationTimestamp\":\"2021-10-09T08:49:17Z\",\"managedFields\":[{\"manager\":\"___2go_build_main_go\",\"operation\":\"Update\",\"apiVersion\":\"v1\",\"time\":\"2021-10-09T08:49:17Z\",\"fieldsType\":\"FieldsV1\",\"fieldsV1\":{\"f:data\":{\".\":{},\"f:a\":{},\"f:k\":{}}}}]},\"data\":{\"a\":\"bd\",\"k\":\"v\"}}\n",
    }
}

strategicMergePatch ConfigMap

请求示例

以在集群内 default 命名空间下通过 patch 更新名为 test0 的配置项为例。
不添加Headers["Content-Type"]时，使用默认 strategicMergePatch 策略。

POST https://open.volcengineapi.com/?Action=ForwardKubernetesApi&Version=2022-05-12
Content-Type: application/json
{
    "Method": "PATCH",
    "ClusterId": "cc52sgo****",
    "Path": "/api/v1/namespaces/default/configmaps/test0",
    "Body": "{\"data\": {\n    \"k\": \"v\",\n    \"a\": \"baa\"\n}}",
    "Headers": [
        {
            "Key": "Content-Type",
            "Value": "application/strategic-merge-patch+json"
        }
    ]
}

返回示例

{
    "ResponseMetadata": {
        "RequestId": "",
        "Action": "ForwardKubernetesApi",
        "Version": "2022-05-12",
        "Service": "",
        "Region": ""
    },
    "Result": {
        "Code": 200,
        "Body": "{\"kind\":\"ConfigMap\",\"apiVersion\":\"v1\",\"metadata\":{\"name\":\"test0\",\"namespace\":\"default\",\"uid\":\"f36da08a-19ba-4a1a-b58c-49******\",\"resourceVersion\":\"4055269\",\"creationTimestamp\":\"2021-10-09T08:49:17Z\",\"managedFields\":[{\"manager\":\"___2go_build_main_go\",\"operation\":\"Update\",\"apiVersion\":\"v1\",\"time\":\"2021-10-09T08:49:17Z\",\"fieldsType\":\"FieldsV1\",\"fieldsV1\":{\"f:data\":{\".\":{},\"f:a\":{},\"f:k\":{}}}}]},\"data\":{\"a\":\"baa\",\"k\":\"v\"}}\n",
    }
}

mergePatch ConfigMap

请求示例

以在集群内 default 命名空间下通过 patch 更新名为 test0 的配置项为例。

POST https://open.volcengineapi.com/?Action=ForwardKubernetesApi&Version=2022-05-12
Content-Type: application/json
{
    "Method": "PATCH",
    "ClusterId": "cc52sgo****",
    "Path": "/api/v1/namespaces/default/configmaps/test0",
    "Body": "{\"data\": {\n    \"k\": \"v\",\n    \"aa\": \"baaa\"\n}}",
    "Headers": [
        {
            "Key": "Content-Type",
            "Value": "application/merge-patch+json"
        }
    ]
}

返回示例

{
    "ResponseMetadata": {
        "RequestId": "",
        "Action": "ForwardKubernetesApi",
        "Version": "2022-05-12",
        "Service": "",
        "Region": ""
    },
    "Result": {
        "Code": 200,
        "Body": "{\"kind\":\"ConfigMap\",\"apiVersion\":\"v1\",\"metadata\":{\"name\":\"test0\",\"namespace\":\"default\",\"uid\":\"f36da08a-19ba-4a1a-b58c-49******\",\"resourceVersion\":\"4055492\",\"creationTimestamp\":\"2021-10-09T08:49:17Z\",\"managedFields\":[{\"manager\":\"___2go_build_main_go\",\"operation\":\"Update\",\"apiVersion\":\"v1\",\"time\":\"2021-10-09T08:54:01Z\",\"fieldsType\":\"FieldsV1\",\"fieldsV1\":{\"f:data\":{\".\":{},\"f:a\":{},\"f:aa\":{},\"f:k\":{}}}}]},\"data\":{\"a\":\"baa\",\"aa\":\"baaa\",\"k\":\"v\"}}\n",
    }
}

jsonPatch ConfigMap

请求示例

以在集群内 default 命名空间下通过 patch 更新名为 test0 的配置项为例。

POST https://open.volcengineapi.com/?Action=ForwardKubernetesApi&Version=2022-05-12
Content-Type: application/json
{
    "Method": "PATCH",
    "ClusterId": "cc52sgo****",
    "Path": "/api/v1/namespaces/default/configmaps/test0",
    "Body": "[{\"op\": \"replace\", \"path\": \"/data\", \"value\": {\"kkk\": \"vv\"}}]",
    "Headers": [
        {
            "Key": "Content-Type",
            "Value": "application/json-patch+json"
        }
    ]
}

返回示例

{
    "ResponseMetadata": {
        "RequestId": "",
        "Action": "ForwardKubernetesApi",
        "Version": "2022-05-12",
        "Service": "",
        "Region": ""
    },
    "Result": {
        "Code": 200,
        "Body": "{\"kind\":\"ConfigMap\",\"apiVersion\":\"v1\",\"metadata\":{\"name\":\"test0\",\"namespace\":\"default\",\"uid\":\"f36da08a-19ba-4a1a-b58c-49******\",\"resourceVersion\":\"4055664\",\"creationTimestamp\":\"2021-10-09T08:49:17Z\",\"managedFields\":[{\"manager\":\"___2go_build_main_go\",\"operation\":\"Update\",\"apiVersion\":\"v1\",\"time\":\"2021-10-09T08:55:33Z\",\"fieldsType\":\"FieldsV1\",\"fieldsV1\":{\"f:data\":{\".\":{},\"f:kkk\":{}}}}]},\"data\":{\"kkk\":\"vv\"}}\n",
    }
}

DELETE ConfigMap

请求示例

以删除集群内 default 命名空间下名为 test0 的配置项为例。

POST https://open.volcengineapi.com/?Action=ForwardKubernetesApi&Version=2022-05-12
Content-Type: application/json
{
    "Method": "DELETE",
    "ClusterId": "cc52sgo****",
    "Path": "/api/v1/namespaces/default/configmaps/test0"
}

返回示例

{
    "ResponseMetadata": {
        "RequestId": "",
        "Action": "ForwardKubernetesApi",
        "Version": "2022-05-12",
        "Service": "",
        "Region": ""
    },
    "Result": {
        "Code": 200,
        "Body": "{\"kind\":\"Status\",\"apiVersion\":\"v1\",\"metadata\":{},\"status\":\"Success\",\"details\":{\"name\":\"test0\",\"kind\":\"configmaps\",\"uid\":\"8996948b-7eed-4802-83f8-25******\"}}\n",
    }
}

异常示例

ForwardKubernetesApi 接口本身的报错，包括 Action 不存在、网关鉴权不正确等情况，将在 ResponseMetadata 中返回 Error 结构体。示例如下：

{
    "ResponseMetadata": {
        "RequestId": "",
        "Action": "ForwardKubernetesApi",
        "Version": "2022-05-12",
        "Service": "",
        "Region": "",
        "Error": {
            "Code": "InternalError",
            "Message": "action not found",
            "Data": null
        }
    }
}

Kubernetes apiserver 返回的报错，不会以接口错误的形式返回，而是将报错信息填充到 Result 中。示例如下：

{
    "ResponseMetadata": {
        "RequestId": "",
        "Action": "ForwardKubernetesApi",
        "Version": "2022-05-12",
        "Service": "",
        "Region": ""
    },
    "Result": {
        "Code": 409,
        "Body": "{\"kind\":\"Status\",\"apiVersion\":\"v1\",\"metadata\":{},\"status\":\"Failure\",\"message\":\"configmaps \\\"test11\\\" already exists\",\"reason\":\"AlreadyExists\",\"details\":{\"name\":\"test11\",\"kind\":\"configmaps\"},\"code\":409}\n",
    }
}

错误码

本接口错误码如下表所示，公共错误码请参见公共错误码。

HTTP 状态码	错误码	错误信息	说明
400	OperationDenied.ClusterStatus	The action has been denied due to wrong cluster status {{statusPhase}} and [{{statusConditions}}].	指定集群的当前状态不支持该操作。请确认该接口依赖的集群状态后重试。