Rancher 2.6 API扩展开发入门示例

1. Rancher开发概述

本部分简单介绍 Rancher Server 架构和各个组件的功能，例如：用户如何通过 Rancher Server 或授权集群端点控制下游集群，以及如何通过授权集群访问端点管理下游集群。这对于Rancher API扩展来说是必须的基础知识，能够更好的理解为什么要这么做。
本文默认读者已经对 Docker 和 Kubernetes 有一定的了解。如果您需要了解 Kubernetes 组件的工作机制和原理，请查阅 Kubernetes 概念。

1.1 Rancher Server 架构

Rancher Server 由认证代理（Authentication Proxy）、Rancher API Server、集群控制器（Cluster Controller）、etcd 节点和集群 Agent（Cluster Agent） 组成。除了集群 Agent 以外，其他组件都部署在 Rancher Server 中。

下图描述的是用户通过 Rancher Server 管控 Rancher 部署的 Kubernetes 集群（RKE 集群）和托管的 Kubernetes 集群的（EKS）集群的流程。以用户下发指令为例，指令的流动路径如下：

1. 首先，用户通过 Rancher UI（现在是dashboard ） Rancher 命令行工具（Rancher CLI）输入指令；由于两者都是再调用Rancher API来实现的，所以直接调用 Rancher API 接口也可以达到相同的效果。
2. 用户通过 Rancher 的代理认证后，指令会进一步下发到 Rancher Server 。
3. 与此同时，Rancher Server 也会执行容灾备份，将数据备份到 etcd 节点。
4. 然后 Rancher Server 把指令传递给集群控制器。集群控制器把指令传递到下游集群的 Agent，最终通过 Agent 把指令下发到指定的集群中。

所以说，我们如果要扩展Rancher功能，其实针对的核心工作对象之一就是Rancher API Server。

1.2 控制K8S集群

我们通过两个用户 Bob 和 Alice 的案例，来讲解 Rancher 启动和管理下游集群的具体过程，和每个 Rancher 组件的作用。
下图演示了集群控制器、集群 Agent 和 Node Agent 是如何允许 Rancher 控制下游集群的。

图中的数字和对应的描述如下：

1. 认证代理
2. 集群控制器和集群 Agent
3. 节点 Agents
4. 授权集群端点

1.2.1 认证代理

图左上角一个叫做 Bob 的用户希望查看下游集群“User Cluster 1”里面正在运行的 pod。Bob 发起的请求会首先经过认证代理，通过认证之后，Rancher 的 认证代理才会把 API 调用命令转发到下游集群。

认证代理集成了多种认证方式，如本地认证、活动目录认证、GitHub 认证等。在发起每一个 Kubernetes API 调用请求的时候，认证代理会去确认请求方的身份，在转发调用命令前，请设置正确的 Kubernetes impersonation 的消息头。

Rancher 使用 Service Account （Service Accout 提供了一种方便的认证机制）和 Kubernetes 进行交互。

默认状态下，Rancher 生成一个包含认证信息的kubeconfig文件，为 Rancher Server 和下游集群的 Kubernetes API Server 之间的通信提供认证。该文件包含了访问集群的所有权限。这也是上一篇文章中使用K3D生成一个K3S集群，在用户主空间下要生成的一个配置文件。

1.2.2 集群控制器和集群 Agent

每一个下游集群都有一个集群 Agent 保持下游集群的集群控制器与 Rancher Server 之间的信息畅通。

集群控制器具有以下功能：

• 检测下游集群的资源变化，如内存使用率、CPU 使用率等
• 把下游集群从“当前”状态变更到“目标”状态
• 配置集群和项目的访问控制策略
• 通过调用 Docker Machine 和 Kubernetes Engine，如 RKE 和 GKE，创建集群。

默认状态下，集群控制器连接 Agent，Rancher 才可以与下游集群通信。如果集群 Agent 不可用，集群控制器可以连接到节点 Agent，通过节点 Agent 实现用户和集群之间的通信。

集群 Agent，也叫做“cattle-cluster-agent”，是在下游集群中运行的组件，它具有以下功能：

• 连接使用 Rancher 部署的 Kubernetes 集群（RKE 集群）中的 Kubernetes API。
• 管理集群内的工作负载，pod 创建和部署。
• 根据每个集群的设置，配置 Role 和 RoleBindings
• 实现集群和 Rancher Server 之间的消息传输，包括事件，指标，健康状况和节点信息等。

1.2.3 节点 Agent

如果集群 Agent 不可用，下游集群中的其中一个节点 Agent 会创建一个通信管道，由节点 Agent 连接到集群控制器，实现下游集群和 Rancher 之间的通信。

1.2.4 授权集群端点

Rancher Server 和下游集群之间有明显的延迟，或 Rancher Server 不可用时，用户可以通过授权集群端点连接下游集群，实现 Rancher Server 和集群之间的通信，降低网络延迟。

需要注意的是，只有 Rancher 部署的 Kubernetes 集群（RKE 集群）可以使用授权集群端点这个功能。其他类型的集群，如导入的集群、托管的集群等，并不能够使用此功能。

1.3 Rancher Server 组件和源代码

下图说明了 Rancher Server 都有哪些组件：

Rancher 的 GitHub 源代码仓库如下：

- Rancher server 的主代码库
- Rancher UI（现在是dashboard）
- Rancher API UI
- Norman
- Types
- Rancher 命令行(Rancher CLI)
- 应用商店

通过一段时间的了解，可以发现。Rancher 提供了一个容器管理平台的功能，同时它还是一套API框架，便于用户自己去扩展K8S的功能，或者在Rancher的基础之上集成其他的功能(比如Rancher集成了Haverster)。上面只列举了 Rancher 最重要的组件，大家可以去Github上了解更多信息。

1.3.1 Rancher 仓库目录结构

我们使用 git 命令 将rancher仓库下载到本地，

git clone https://github.com/rancher/rancher.git

下载到本地之后，可以通过git checkout 命令来切换分支，如下命令将会把Rancher仓库版本切换到V2.6.8分支

git checkout release/v2.6.8

如果开发过程中，我们需要使用rancher源来覆盖本地所做的所有更新，可以使用git checkout .来实现

git checkout .

由此，我们得到了一个如上图所示的目录结构，下面是针对这个目录结构的简要说明。

目录			简介
chart			用户部署server的helm chart
cleanup			脚本，清理一些源码缓存等
package			各种镜像打包，rancher server，rancher agent 等
pkg			核心功能
	api/norman/store		功能最终实现代码,例如 workload ：pkg/api/norman/store/workload/workload_store.go
	api/norman/server/userstored/proxy_store.py		用户在 rancher server 集群中调用 user k8s集群是使用的 proxy代理
	apis（原types项目）		management.cattle.io cluster.cattle.io project.cattle.io
	schemas（原types项目）		Api 的定义 例如：定义 workload api的文件 pkg/schemas/project.cattle.io/v3/schema.go -> WorkLoadTypes
		mapper	作用 norman 到 k8s api 参数的转换，如：参数rancher要k8s没有，norman 转换
		management.cattle.io	rancher server管理相关的功能，与下面的两个带io结束的包一起组成了二次开发API侧的核心
		cluster.cattle.io	k8s集群管理相关的功能
		project.cattle.io	项目管理相关的功能，类似“工作台”
	codegen（原types项目）		通过用户自定义的“types” 结构中的//geclient等注释 使用 go generate生成代码
		generator	原 types 项目中的 generator 文件
	types (原 types 项目)		原types项目中的 config 文件
	controllers		二次开发后台控制端的核心
		management	用来管理Rancher Server的内部功能
		managementagent	从2.4版本的user拆分而来
		managementlegacy	从2.4版本的user拆分而来
		managementuser	从2.4版本的user拆分而来
	multiclustermanager		2.4版本之前原server目录，自定义扩展rancher_api时使用
scripts			脚本目录，配合makefile使用
tests			集成测试工具
dockerfile.dapper			Rancher 的dapper编译工具，通过这个文件来编译项目

注意：2.4版本之前，原 types 中的 schemas 和 apis 是统一放对应的 xxx.cattle.io 目录下的在v3文件夹下的，现在分开拆成 apis, schemas。其中，在 apis 的 v3 中定义功能的结构体，在 schemas 的 v3 中定义api 引入 apis 中定义的结构体(struct)。

2. Rancher API 组织（以workload为例）

• 我们查看RancherAPI UI 在v3/project/schemas/workload 会发现 server 中没有workload 相关的url。
• 因为这个是从norman中定义的具体位置在：types目录下。因rancher2.5以后types合并到rancher里面，所以workload api定义的文件在pkg/schema/project.cattle.io/v3/schema.go -> WorkLoadTypes。
• 上面WorkLoadTypes 函数通过norman 最终转换为 v3/project/schemas/workload 这个形式。
• Types 中定义的api 最终实现代码在norman中，具体位置是pkg/api/norman/store/workload/workload_store.go。
  

3. Norman 框架及API分类

Rancher中核心的API框架就是Norman。它负责生成rancher中api，并负责讲RancherAPI 转换成K8S API。并为K8S API的使用创建了一种新的便捷的方式。https://xxx/v3 这个目录下展示的api都是由norman生成的，Norman能够面向 k8s 的 api 框架进行无缝集成，提供更加便捷的方式来构建k8s controller。

• store

   将数据 CRD 转换初始化到 k8s 中
  

• types

   将rancher schema 转换为 norman
  

• example

   启动norman项目生成api url  和 rancher v3 url一样
  

下面是Rancher API的分类

种类	访问路径	简介
Management API	/v3	用户认证登录后可以访问，主要用于Rancher Server的管理
Auth API	/v3-public /v3/token	用户身份认证API
K8S Proxy API	/k8s/clusters	对K8S集群直接连接访问使用的API，或者K8S原生的API
Dialer API	/v3/connect /v3/connect/register	rancher server 和agent 通信使用的API 状态推送给Rancher内部的API
RKE Node config API	/v3/connect/config	初始化RKE集群时node、driver使用的API

4. API 扩展开发示例

4.1 添加自定义结构体Faa

在 pkg/apis/management.cattle.io/v3 下面添加faa_types.go文件，代码如下：

package v3

import metav1 "k8s.io/apimachinery/pkg/apis/meta/v1"

// +genclient
// +genclient:nonNamespaced
// +k8s:deepcopy-gen:interfaces=k8s.io/apimachinery/pkg/runtime.Object

type Faa struct {
   
	metav1.TypeMeta   `json:",inline"`
	metav1.ObjectMeta `json:"metadata,omitempty"`

	Spec   FaaSpec   `json:"spec"`
	Status FaaStatus `json:"status"`
}

type FaaSpec struct {
   
	// norman:"nullable" norman 规范
	Bar bool `json:"bar" norman:"nullable"`
}

type FaaStatus struct {
   
	Msg string `json:"msg"`
}

// action 入参结构体
type EchoActionInput struct {
   
	Echo bool `json:"echo"`
}

这里定义后的结构体，将来在Rancher API UI中可以使用 http:xxx/v3/faas访问到。
注意：在定义结构体时，结构体上面有些注释这是在使用Rancher的 code generator 时需要给函数定义一些语义，具体用法请查阅