You need to enable JavaScript to run this app.
导航

ForwardKubernetesApi

最近更新时间2023.07.25 10:15:25

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

代理转发 Kubernetes 原生 API。

使用说明

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

请求参数

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

参数名称类型是否必填示例值说明
ActionStringForwardKubernetesApi公共参数,本接口值:ForwardKubernetesApi。
VersionString2022-05-12公共参数,本接口值:2022-05-12。

ClusterId

String

cc52sgoersfekjq******

目标集群 ID。 可以调用 ListClusters 接口,获取集群 ID。

注意

集群必须处于{Running,[Ok]}{Updating,[Progressing]}状态。可调用 ListClusters 接口获取集群当前的状态。

Method

String

POST

请求方法,取值:

  • GET
  • POST
  • PUT
  • PATCH
  • DELETE
PathString/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。

  • MethodGETDELETE 时可以不填。
  • MethodPOSTPUTPATCH 时必须填写。

Headers

Array of Header

[ { "Key": "Content-Type", "Value": "application/json-patch+json" }
]

请求头。
Method=PATCH时才生效。

请求头的 KeyValue 使用方法,请参见本文下方 Patch ConfigMap

参数名参数类型是否必选示例值说明
KeyStringContent-Type请求头的 Key。当前仅支持设置 ContentType,以使用不同的 PATCH 方法。

Value

String

application/json-patch+json

请求头的 Value。当 KeyContent-Type 时,取值:

  • application/strategic-merge-patch+json(默认值)
  • application/json-patch+json
  • application/merge-patch+json

返回参数

参数名称类型示例值说明
CodeInteger200kube-apiserver 返回的 HTTP 状态码。
BodyString{\"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\"}}\nKube-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 状态码错误码错误信息描述
400OperationDenied.ClusterStatusThe action has been denied due to wrong cluster status {{statusPhase}} and [{{statusConditions}}].指定集群的当前状态不支持该操作。请确认该接口依赖的集群状态后重试。