企业官网建设流程全解析

• 文档
• 教程
• 云原生

导读

GitLab Source 是 Knative Eventing 提供的一个事件源（Event Source）示例，它负责把 GitLab 仓库产生的事件（如 push、issue 变更）自动注册为 GitLab Webhook，再将传入的事件包装成 CloudEvents 并投递给 Knative Service 等下游消费者。本文以 code-samples/eventing/gitlab-source/README.md 为主线，完整还原从安装事件源、准备 GitLab 令牌、创建 Secret、声明GitLabSource自定义资源，到验证事件链路与清理资源的全流程，并结合本仓库的 Event Sources 总览 与 版本发布记录 补充实现层面的细节。读完本文，你将掌握如何在任意 Knative 集群上把 GitLab 项目事件平滑地送入 Knative 事件体系。

GitLab Event Source 在 Knative 事件体系中的定位

在 Knative Eventing 中，事件源是一个 Kubernetes 自定义资源（CR），它充当事件生产者与事件接收方（sink）之间的桥梁。sink 可以是普通 Kubernetes Service、Knative Service、Channel 或 Broker。Event Sources 总览 将 GitLab Source 的状态标注为 Beta、维护者为 Knative，并给出官方定义：

GitLabSource 会在指定的 GitLab 仓库上为指定的事件类型注册 Webhook，监听传入的事件，并将其传递给消费者。

GitLab Source 的完整工作链路可以概括为：

1. 用户创建GitLabSourceCR 并指定projectUrl、要订阅的eventTypes以及作为 sink 的 Knative Service；
2. 事件源的控制器使用accessToken调用 GitLab API，在目标项目上自动创建 Webhook；
3. GitLab 项目发生匹配的事件时，GitLab 向集群的 Webhook 地址发起回调；
4. 事件源校验回调请求（使用secretToken），把负载转换为 CloudEvents 并投递给 sink。

在 本仓库的示例清单 中，GitLab source 与 GitHub source 并列作为"将外部平台事件接入 Knative Service"的典型 YAML 示例，实现语言为 YAML 清单。由于事件通过标准 HTTP POST 传输并遵循 CloudEvents 规范，消费者可以用任意语言实现。

前置条件

在开始之前，需要确认以下四项条件已经就绪（对应原文档 Prerequisites 部分）：

1. Knative Serving：一个可被公网访问的 Kubernetes 集群，并已安装 Knative Serving；
2. 域名配置：Knative Serving 已配置域名（使用自定义域名），以便生成对外可达的 Service URL；
3. 静态公网 IP：集群必须使用静态 IP 地址（具体请参考云厂商文档），保证 GitLab 能够稳定回调到集群；
4. Knative Eventing：已安装 Knative Eventing，因为 GitLabSource 依赖 Eventing 的事件投递能力。

之所以强调"公网可访问 + 静态 IP"，是因为 GitLab 的 Webhook 回调方向是从 GitLab 服务器主动访问你的集群，集群侧必须提供一个稳定且可达的 HTTP 端点，这正是本示例与一般"集群内事件"场景最大的不同点。

安装 GitLab Event Source

GitLab Event Source 的代码仓库位于knative-extensions/eventing-gitlab。根据 v0.18 版本发布记录 中的说明，GitLab source 的发布工件在 v0.18 时已从knative/eventing-contrib迁移到knative-extensions/eventing-gitlab，因此安装时应直接使用后者 releases 页面中的gitlab.yaml工件。

安装步骤：前往 releases 页面找到包含gitlab.yaml工件的最新版本，把下面的<RELEASE>替换为实际版本号后执行：

kubectl apply -f https://github.com/knative-extensions/eventing-gitlab/releases/download/<RELEASE>/gitlab.yaml

部署完成后，用下面的命令确认控制器（controller manager）已正常运行：

kubectl -n knative-sources get pods --selector control-plane=gitlab-controller-manager

当看到状态为Running的 Pod 时，说明事件源控制器已就绪，可以进入用户侧配置：创建 GitLab Webhook 以及一个消费 GitLab 事件的函数（Knative Service）。

第一步：创建接收事件的 Knative Service

为了验证事件链路，先创建一个最简单的 Knative Service 作为事件接收方。它的职责是把收到的每个事件直接打印到标准输出（stdout），即通常所说的 event_display。

原文档给出的event-display.yaml内容如下：

apiVersion: serving.knative.dev/v1 kind: Service metadata: name: gitlab-event-display spec: template: spec: containers: - image: gcr.io/knative-releases/knative.dev/eventing/cmd/event_display

创建该 Service：

kubectl -n default apply -f event-display.yaml

event_display镜像来自 Knative Eventing 官方的命令行工具镜像，它把收到的 CloudEvents 以结构化文本形式打印到日志中，非常适合用来观察事件源是否正常工作。这也是 GitHub source 示例 使用的同一套验证思路——两个外部平台事件源共用同一个消息转储器模式。

第二步：创建 GitLab 访问令牌与 Webhook 密钥

GitLabSource 需要两个令牌才能工作：

• accessToken（项目访问令牌）：GitLabSource 用它调用 GitLab API 来注册仓库 Webhook，因此该令牌必须具有api访问范围（scope），否则无法创建仓库 Webhook；
• secretToken（Webhook 密钥）：你自己选定的一段随机字符串，GitLabSource 用它校验来自 GitLab 的传入 Webhook 请求，防止伪造事件。

在 GitLab 的项目设置中创建 project access token（api范围）后，把两个令牌写入secret.yaml：

apiVersion: v1 kind: Secret metadata: name: gitlabsecret type: Opaque stringData: accessToken: <personal_access_token_value> secretToken: <random_string>

提示：可以用下面这条命令生成一个随机secretToken：

head -c 8 /dev/urandom | base64

然后通过 kubectl 创建 Secret：

kubectl -n default apply -f secret.yaml

这里采用 Kubernetes Secret +secretKeyRef的引用方式而非明文直填，是 Knative 事件源配置的标准做法：GitLabSourceCR 中只声明对 Secret 的引用，令牌值本身不会出现在事件源清单里，降低了泄漏风险。

第三步：创建 GitLabSource 事件源

现在创建一个具体命名空间下的GitLabSourceCR。需要把projectUrl替换为你自己的 GitLab 项目地址，例如https://gitlab.com/knative-examples/functions。

原文档给出的gitlabsource.yaml如下：

apiVersion: sources.knative.dev/v1alpha1 kind: GitLabSource metadata: name: gitlabsource-sample spec: eventTypes: - push_events - issues_events projectUrl: <project url> accessToken: secretKeyRef: name: gitlabsecret key: accessToken secretToken: secretKeyRef: name: gitlabsecret key: secretToken sink: ref: apiVersion: serving.knative.dev/v1 kind: Service name: gitlab-event-display

逐项说明关键字段：

应用该清单：

kubectl -n default apply -f gitlabsource.yaml

从实现角度看，Event Sources 总览 特别提醒：从 Kafka、RabbitMQ 等其他消息技术导入事件的事件源，不需要负责设置datacontenttype之类的可选属性，这是原始事件生产者的职责；事件源只是在属性已存在时进行透传。GitLabSource 这类基于 Webhook 的事件源同理，事件负载的datacontenttype: application/json由 GitLab 回调与事件源共同决定，下游消费者可直接解析 JSON 负载。

第四步：验证事件链路

1. 确认 Webhook 已注册

进入 GitLab 项目的Settings >> Webhooks页面，应该能看到一条指向你 Knative 集群的新 Webhook。这说明事件源控制器已成功用 accessToken 调用了 GitLab API 完成注册。

2. 触发 push 事件并查看日志

在 GitLab 项目上执行一次 push 操作，然后查看gitlab-event-displayService 背后 Pod 的日志。如果一切正常，你会看到类似下面这样的 CloudEvents 结构化输出（原文档给出的示例）：

☁️ cloudevents.Event Validation: valid Context Attributes, specversion: 0.3 type: dev.knative.sources.gitlabsource.Push Hook source: https://gitlab.com/<user>/<project> id: f83c080f-c2af-48ff-8d8b-fd5b21c5938e time: 2020-03-12T11:08:41.414572482Z datacontenttype: application/json Data, { <Event payload> }

这段输出可以从几个维度解读：

• type为dev.knative.sources.gitlabsource.Push Hook，标明事件由 GitLabSource 产生、语义为 GitLab 的 Push Hook；
• source指向触发事件的 GitLab 项目地址，用于区分事件来源；
• specversion: 0.3说明该事件遵循 CloudEvents 0.3 规范（Validation: valid表示通过校验）；
• id、time分别标识事件的唯一性与发生时间，datacontenttype: application/json表明Data部分是 JSON 负载。

关于事件属性的稳定性，可以参考 v0.19 版本发布记录 中针对 eventing-gitlab 的三项改进：声明 GitLabSource 实例发出的事件类型，使其作为 Knative EventTypes 传播；对发出 CloudEvents 的type属性进行净化，避免包含空格和大写字母；保证source属性稳定且可预测。也就是说，你在日志中看到的type/source字段格式正是经过版本迭代规范化后的结果，下游消费者可以放心依据这两个字段做过滤与路由。

3. 用触发器消费事件（进阶）

sink直接指向 Knative Service 是最简单的投递方式。若希望按事件类型分流处理，可以改为把 sink 指向 Broker，再通过 Trigger 按type过滤——例如只把dev.knative.sources.gitlabsource.Push Hook转发给某个 CI 校验服务，而把 Issue 事件转发给工单处理服务。关于 Broker/Trigger 的用法，可以参考 Eventing 总览 中"用 Trigger 基于事件属性从 Broker 消费事件"的介绍。

清理资源

验证完毕后，按依赖顺序清理即可。删除 GitLabSource 会同时移除它在 GitLab 项目上注册的 Webhook：

kubectl --namespace default delete --filename gitlabsource.yaml

随后删除事件接收 Service 与 Secret：

kubectl --namespace default delete --filename event-display.yaml kubectl --namespace default delete --filename secret.yaml

注意：先删除gitlabsource.yaml再删除其他资源，可确保 Webhook 被干净地反注册，避免 GitLab 侧残留指向已失效集群地址的钩子。

版本与维护现状

• 维护者：Knative 社区（Beta 状态），详见 Event Sources 总览；
• 代码仓库演进：v0.18 起发布工件迁移至knative-extensions/eventing-gitlab（v0.18 发布记录）；
• 事件属性规范化：v0.19 起支持声明并传播 EventTypes，同时对 CloudEvents 的type做净化、对source做稳定化（v0.19 发布记录）；
• 仓库内部导航：本仓库的 Go 模块入口 golang/eventing-gitlab.html 指向knative.dev/eventing-gitlab模块，重定向配置 中也将旧的versioned/eventing/samples/gitlab-source/README.md路径重定向到code-samples/eventing/gitlab-source/README.md，说明该示例目前即以此文档为准。

小结

通过本示例你可以看到 Knative Eventing 接入外部平台事件的标准套路：先安装事件源控制器，再准备令牌类 Secret，接着声明GitLabSourceCR（指定eventTypes、projectUrl、令牌引用与 sink），最后用 event_display 验证端到端链路。这套流程同样适用于 GitHub source 等其他 Webhook 类事件源——差异主要在于令牌的获取方式与事件类型命名。掌握了 GitLabSource，你就掌握了把 GitLab 生态事件（CI/CD、Issue、Merge Request 等）接入 Knative 驱动型应用的基础能力。

• 文档
• 教程
• 云原生