# Karmada API
#### Karmada API说明
Karmada API 是提供 Karmada 功能服务并负责其状态存储的基于资源 (RESTful) 的编程接口。它支持通过标准HTTP请求方法（POST、PUT、PATCH、DELETE、GET）进行查询、创建、更新和删除各类联邦资源。了解详细的Karmada API信息请参见[Karmada API](https://karmada.io/zh/docs/next/category/karmada-api)。
UCS支持通过API网关调用Karmada API。
#### 通过API网关调用Karmada API
Karmada API 可以通过API网关调用，其URL格式为：**https://** *{fleetname}* **.fleet.ucs.** *{region}* **-dev.myhuaweicloud.com/** *{uri}* ，其中有三个参数。
表1URL中的参数说明 
| 参数          | 描述                                                                                                                                                                                                                                                                                                  |
|:---|:---|
| {fleetname} | 舰队名称，可在控制台内舰队基本信息中获取。                                                                                                                                                                                                                                                                               |
| {region}    | 服务应用区域的URL，可以通过[终端节点（Endpoint）](https://support.huaweicloud.com/api-ucs/ucs_api_0002.html#ucs_api_0002__section18343125114919)获取。 示例：华北-北京四的Region为cn-north-4                                                                                                         |
| {uri}       | 资源路径，也即API访问路径。从具体接口的URI模块获取，请参见[Karmada API](https://karmada.io/zh/docs/next/category/karmada-api)。 示例：根据需要调用的接口设置，例如需要查看一个Deployment的详情，则请求方法为GET，接口uri为**/apis/apps/v1/namespaces/default/deployments**，其中{namespace}为集群命名空间名称，本示例为default。 |
   
1. 登录[UCS控制台](https://console.huaweicloud.com/ucs/?#/aether/dashboard)，单击目标容器舰队名进入"容器舰队信息"页面，在"舰队基本信息"中单击"kubectl"。
   
   图1kubectl连接信息   
   ![](https://support.huaweicloud.com/api-ucs/zh-cn_image_0000002497836614.gif "点击放大")
   
   
2. 参照页面中的提示信息，选择对应的项目名称、虚拟私有云(VPC)、控制节点子网以及有效期，单击"下载"，下载kubectl配置文件。 
   下载下来的文件名为kubeconfig.json。
   图2kubectl连接联邦实例   
   ![](https://support.huaweicloud.com/api-ucs/zh-cn_image_0000002529676581.gif "点击放大")
   ![](https://support.huaweicloud.com/api-ucs/public_sys-resources/notice_3.0-zh-cn.png)
   kubeconfig.json文件中存在安全泄露风险，请您务必妥善保存。
   kubectl配置文件有效期可根据实际需求选择，下拉列表内可选范围为：5年、1年、6个月、30天、15天、14天、13天...1天，最短为1天。
   
   
3. 在执行机上安装和配置kubectl。 
   1. 拷贝kubectl及其配置文件到上述所选的vpc和子网下的执行机的/home目录下。
   
   2. 登录到您的执行机，配置kubectl **cd /home**
      **chmod +x kubectl**
      **mv -f kubectl /usr/local/bin**
      **mkdir -p $HOME/.kube**
      **mv -f kubeconfig.json $HOME/.kube/config**
      
   
   
   
   
4. 根据URL格式进行拼接，确定请求的URL。 
   - **{fleetname}**为舰队名称，可在控制台内舰队基本信息中获取。
   
   - **{region** **}** 为Web服务入口点的URL，可以通过[终端节点（Endpoint）](https://support.huaweicloud.com/api-ucs/ucs_api_0002.html#ucs_api_0002__section18343125114919)获取。
   
   - **{uri}** 为资源路径，也即API访问的路径，从具体接口的URI模块获取，请参见[Karmada API](https://karmada.io/zh/docs/next/category/karmada-api)。
   
   
   则调用接口查看联邦内所有deployment信息的URL示例如下：
   ```
   https://r******.fleet.ucs.cn-north-4-dev.myhuaweicloud.com/apis/apps/v1/namespaces/default/deployments
   ```
   
   
5. 创建Admin Role 获取请求对应bearer token。
   
   1. 将如下内容保存为admin-role.yaml文件。
      ```
      kind: ClusterRoleBinding
      apiVersion: rbac.authorization.k8s.io/v1
      metadata:
        name: admin
        annotations:
          rbac.authorization.kubernetes.io/autoupdate: "true"
      roleRef:
        kind: ClusterRole
        name: cluster-admin
        apiGroup: rbac.authorization.k8s.io
      subjects:
      - kind: ServiceAccount
        name: admin
        namespace: kube-system
      ---
      apiVersion: v1
      kind: ServiceAccount
      metadata:
        name: admin
        namespace: kube-system
        labels:
          kubernetes.io/cluster-service: "true"
          addonmanager.kubernetes.io/mode: Reconcile
      ```
      
   
   2. 使用**kubectl apply -f admin-role.yaml**创建对应的service-account及权限。
   
   3. 使用**kubectl create token admin --namespace kube-system** 获取账户对应bearer token。
   
   4. 设置环境变量token，其值为上一步获取的bearer token。
   
   
   
   
6. 使用接口指定的请求方法，并设置请求Header参数。如果接口要求添加Body参数，可参考[Karmada API](https://karmada.io/zh/docs/next/category/karmada-api)添加接口对应的结构体。
   
   例如使用curl命令调用创建Deployment接口，请求方法为POST，并添加对应的Body体。
   示例：本示例将使用nginx.json文件，创建一个名为nginx的deployment负载，该工作负载使用nginx:latest镜像并包含两个Pod，每个Pod占用100mCPU、200Mi内存。在该工作负载创建完成后，您可以继续参考上述步骤，从[Karmada API](https://karmada.io/zh/docs/next/category/karmada-api)获取PropagationPolicy对应的URI，创建分发策略。
   ```
   curl --location --request POST 'https://r*****.fleet.ucs.cn-north-4-dev.myhuaweicloud.com/apis/apps/v1/deployments' \
   --header 'Content-Type: application/json' \
   --header 'Authorization: Bearer $token' \
   --data @nginx.json
   ```
   请求中包含的Header参数如下：
   表2请求Header参数 
   | 参数            | 是否必选 | 参数类型   | 描述                                                       |
   |:---|:---|:---|:---|
   | Content-Type  | 是    | String | 消息体的类型，仅支持application/json                               |
   | Authorization | 是    | String | 获取bearer token的方式请参见[5]。 |
      
   nginx.json文件内容如下：
   ```
   {
       "apiVersion": "apps/v1",
       "kind": "Deployment",
       "metadata": {
           "name": "nginx"
       },
       "spec": {
           "replicas": 2,
           "selector": {
               "matchLabels": {
                   "app": "nginx"
               }
           },
           "template": {
               "metadata": {
                   "labels": {
                       "app": "nginx"
                   }
               },
               "spec": {
                   "containers": [
                       {
                           "image": "nginx:latest",
                           "name": "container-0",
                           "resources": {
                               "limits": {
                                   "cpu": "100m",
                                   "memory": "200Mi"
                               },
                               "requests": {
                                   "cpu": "100m",
                                   "memory": "200Mi"
                               }
                           }
                       }
                   ],
                   "imagePullSecrets": [
                       {
                           "name": "default-secret"
                       }
                   ]
               }
           }
       }
   }
   ```
   
   
 
#### API流控说明
为了确保集群联邦实例稳定运行，防止API服务过载，联邦实例配置流控规则。
![](https://support.huaweicloud.com/api-ucs/public_sys-resources/notice_3.0-zh-cn.png)
若默认配置的流控值不满足业务诉求，请提交工单联系工程师处理。