ForwardKubernetesApi

最近更新时间：2024.02.26 20:17:37

首次发布时间：2022.08.22 10:51:01

代理转发 Kubernetes 原生 API。

使用说明

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

请求参数

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

参数名称	类型	是否必填	示例值	说明
Action	String	是	ForwardKubernetesApi	公共参数，本接口值：ForwardKubernetesApi。
Version	String	是	2022-05-12	公共参数，本接口值：2022-05-12。
ClusterId	String	是	cc52sgoersfekjq******	目标集群 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 和 Value 使用方法，请参见本文下方 Patch ConfigMap。

参数名	参数类型	是否必选	示例值	说明
Key	String	是	Content-Type	请求头的 Key。当前仅支持设置 ContentType，以使用不同的 PATCH 方法。
Value	String	是	application/json-patch+json	请求头的 Value。当 Key 为 Content-Type 时，取值： application/strategic-merge-patch+json（默认值） application/json-patch+json application/merge-patch+json

参数名

参数类型

是否必选

示例值

说明

Key

String

是

Content-Type

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

Value

String

是

application/json-patch+json

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

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

返回参数

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

参数名称	类型	示例值	说明
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 /?Action=ForwardKubernetesApi&Version=2022-05-12 HTTP/1.1 
{
    "Method": "GET",
    "ClusterId": "cc52sgoersfekjq******",
    "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 /?Action=ForwardKubernetesApi&Version=2022-05-12 HTTP/1.1 
{
    "Method": "GET",
    "ClusterId": "cc52sgoersfekjq******",
    "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 /?Action=ForwardKubernetesApi&Version=2022-05-12 HTTP/1.1 
{
    "Method": "POST",
    "ClusterId": "cc52sgoersfekjq******",
    "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 /?Action=ForwardKubernetesApi&Version=2022-05-12 HTTP/1.1 
{
    "Method": "PUT",
    "ClusterId": "cc52sgoersfekjq******",
    "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",
    }
}

Patch ConfigMap

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

支持 jsonPatch、mergePatch、strategicMergePatch 三种策略。三种策略的具体差异，请参见 Kubernetes Patch 文档。

strategicMergePatch：
不添加Headers["Content-Type"]时，使用默认 strategicMergePatch 策略。

请求示例

Post /?Action=ForwardKubernetesApi&Version=2022-05-12 HTTP/1.1
{
    "Method": "PATCH",
    "ClusterId": "cc52sgoersfekjq******",
    "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：

请求示例

Post /?Action=ForwardKubernetesApi&Version=2022-05-12 HTTP/1.1
{
    "Method": "PATCH",
    "ClusterId": "cc52sgoersfekjq******",
    "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：

请求示例

POST /?Action=ForwardKubernetesApi&Version=2022-05-12 HTTP/1.1
{
    "Method": "PATCH",
    "ClusterId": "cc52sgoersfekjq******",
    "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 /?Action=ForwardKubernetesApi&Version=2022-05-12 HTTP/1.1 POST /?Action=ForwardKubernetesApi&Version=2022-05-12 HTTP/1.1 
{
    "Method": "DELETE",
    "ClusterId": "cc52sgoersfekjq******",
    "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}}].	指定集群的当前状态不支持该操作。请确认该接口依赖的集群状态后重试。

使用说明

请求参数

Header

返回参数

正常示例

List ConfigMaps

Get ConfigMap

Create ConfigMap

Update ConfigMap

Patch ConfigMap

DELETE ConfigMap

异常示例

错误码

容器服务

ForwardKubernetesApi

使用说明

请求参数

Header

返回参数

正常示例

List ConfigMaps

Get ConfigMap

Create ConfigMap

Update ConfigMap

Patch ConfigMap

DELETE ConfigMap

异常示例

错误码