Merge pull request #445 from Somefive/jenkins_docs

Docs: add jenkins tutorial

blog/2021-09-02-kubevela-jenkins-cicd.md

@@ -289,6 +289,8 @@ pipeline {
 }
 ```
 
+> NOTE: the deploy stage is written with KubeVela v1.1. The apiserver interaction method is updated in KubeVela v1.2, leveraging VelaUX (the UI dashboard) and webhook trigger. If you are using KubeVela v1.2.0+, you should refer to the latest documents.
+
 ## Performance
 
 After finishing the configuration process described above, the whole process of continuous delivery has already been set up. Let's check how it works.

docs/tutorials/jenkins.md

@@ -0,0 +1,57 @@
+---
+title: Working with Jenkins
+---
+
+### Introduction
+
+The workflow execution of KubeVela application can be triggered by webhooks. Therefore, it is rather easy for user to integrate KubeVela with existing Continuous Integration platforms, such as Jenkins or Gitlab.
+
+In KubeVela 1.2, [VelaUX](../install#3-install-velaux) provides webhook triggers for applications to use. Only a simple curl command in Jenkins pipeline is needed to bridge CI and CD systems.
+
+In this section, we will demonstrate how to integrate KubeVela with Jenkins in details.
+
+### Prerequisite
+
+The following requirements are needed to be ensured before starting this tutorial
+- KubeVela v1.2.0 with VelaUX installed.
+- Jenkins installed.
+- VelaUX can be accessed by Jenkins. (If KubeVela is installed in an offline environment, you need to check this condition.)
+
+### Create Application
+
+To use triggers, we need to create a new application on VelaUX first. For example, let's deploy a new WebService type application and use LoadBalancer to expose port 80 for access.
+
+![alt](../resources/acr-trigger-newapp.png)
+
+### Setup Webhook Trigger for Jenkins
+
+In the application view, we can see a default trigger as below
+
+![alt](../resources/app-trigger.jpg)
+
+Click **Manual Trigger**, we can see the Webhook URL and the Curl Command. Either one is available to copy and use into Jenkins pipeline script.
+
+![alt](../resources/app-trigger-webhook.jpg)
+
+### Use Webhook in Jenkins
+
+To use the webhook in Jenkins, we can paste the Curl Command in either Jenkins *Freestyle* project or *Pipeline* project.
+- In *Freestyle* project, click **Add Build Step** and select **Execute Shell**. Copy the Curl Command above into it.
+- In *Pipeline* projetct, similarly copy the Curl Command and wraps it with a `sh` command like the code below
+```groovy
+stage('Deploy') {
+    steps {
+        sh '''#!/bin/bash
+            set -ex
+            curl -X POST -H 'content-type: application/json' --url http://47.251.6.101/api/v1/webhook/mbn6wckzh5lul3m2 -d '{"upgrade":{"kubevela-jenkins-ci-demo":{"image":"busybox"}},"codeInfo":{"commit":"","branch":"","user":""}}'
+        '''
+    }
+}
+```
+Now when jenkins execute these build steps, it will notify KubeVela to execute the application workflow automatically.
+
+![alt](../resources/jenkins-run.jpg)
+
+### Advanced: Secure your Webhook URL
+
+The KubeVela webhook url in Jenkins can be secured by storing it in Jenkins credentials, instead of directly referring it in the project. You can set up a `secret text` type credential in Jenkins and use it in the project.

i18n/zh/docusaurus-plugin-content-blog/2021-09-02-kubevela-jenkins-cicd.md

@@ -288,6 +288,8 @@ pipeline {
 }
 ```
 
+> 备注：上述的 Deploy 阶段是基于 KubeVela 1.1 版本的。在 KubeVela 1.2 版本中，Jenkins 对接 KubeVela APIServer 的方法发生了变化，需要使用 VelaUX（UI 控制面板）和 WebHook 触发器。如果你使用的是 KubeVela v1.2.0+，你需要参考对应版本的相关文档。
+
 ## 实际表现
 
 在完成上述的配置流程后，持续交付的流程便已经搭建完成。我们可以来检验一下它的效果。

i18n/zh/docusaurus-plugin-content-docs/current/tutorials/jenkins.md

@@ -0,0 +1,57 @@
+---
+title: 对接 Jenkins
+---
+
+### 简介
+
+KubeVela 应用的工作流可以通过 Webhook 触发器触发。这使得诸如 Jenkins 或是 Gitlab 之类的持续集成系统对接 KubeVela 非常简单。
+
+在 KubeVela 1.2 中，[VelaUX](../install#3-install-velaux) 提供了便捷的应用触发器。只需要在 Jenkins 的流水线中添加一条简单的 Curl 命令就可以对接 CI 和 CD 系统。
+
+本文将详细介绍如何对接 KubeVela 与 Jenkins。
+
+### 准备
+
+在开始本文教程之前，需要先确认一下的事项
+- 安装了 KubeVela v1.2.0+ 版本，并开启了 VelaUX 插件。
+- 安装了 Jenkins。
+- VelaUX 需要能够被 Jenkins 访问到。（如果 KubeVela 被安装在了离线环境中，需要额外确认这一条件）
+
+### 创建应用
+
+为了使用应用触发器，我们首先需要在 VelaUX 上创建一个新的应用。比如我们选择一个 WebService 类型的应用并使用 LoadBalancer 来暴露它的 80 端口。
+
+![alt](../resources/acr-trigger-newapp.png)
+
+### 设置 Webhook 触发器
+
+在应用面板上，我们可以找到一个默认的触发器，如下图所示
+
+![alt](../resources/app-trigger.jpg)
+
+点击 **Manual Trigger**，我们可以看到 Webhook URL 和 Curl Command。我们可以在 Jenkins 的流水线中使用任意一个。
+
+![alt](../resources/app-trigger-webhook.jpg)
+
+### 在 Jenkins 中使用 Webhook
+
+为了在 Jenkins 中使用 Webhook，我们可以将上文得到的 Curl Command 复制到 Jenkins 的 *Freestyle* 项目或是 *Pipeline* 项目中。
+- 在 *Freestyle* 项目中，点击 **Add Build Step** 并选择 **Execute Shell**。将上文的 Curl Command 复制到其中。
+- 在 *Pipeline* 项目中，类似地复制 Curl Command 并用 `sh` 命令将其按下图所示方式包装。
+```groovy
+stage('Deploy') {
+    steps {
+        sh '''#!/bin/bash
+            set -ex
+            curl -X POST -H 'content-type: application/json' --url http://47.251.6.101/api/v1/webhook/mbn6wckzh5lul3m2 -d '{"upgrade":{"kubevela-jenkins-ci-demo":{"image":"busybox"}},"codeInfo":{"commit":"","branch":"","user":""}}'
+        '''
+    }
+}
+```
+现在当 Jenkins 执行构建步骤的时候，它便会通知 KubeVela 来自动的执行应用工作流，完成部署。
+
+![alt](../resources/jenkins-run.jpg)
+
+### 进阶：安全存储 Webhook URL
+
+KubeVela 的 Webhook URL 可以通过 Jenkins credential 安全地存储，并在 Jenkins 项目中引用。

sidebars.js

@@ -28,6 +28,7 @@ module.exports = {
         "tutorials/helm",
         "tutorials/consume-cloud-services",
         "tutorials/k8s-object",
+        "tutorials/jenkins",
         "tutorials/trigger",
         "case-studies/gitops",
         "tutorials/scaler",