diff --git a/.vuepress/config-sidebar.js b/.vuepress/config-sidebar.js index 32c0a95..98fed7b 100644 --- a/.vuepress/config-sidebar.js +++ b/.vuepress/config-sidebar.js @@ -60,6 +60,7 @@ let sidebar = { title: '配置 Kuboard v3', collapsable: true, children: [ + 'v3/auth-user-sso', 'v3/proxy', 'v3/tls', 'v3-upgrade', diff --git a/install/v3/auth-user-sso.assets/image-20201114095004698.png b/install/v3/auth-user-sso.assets/image-20201114095004698.png new file mode 100644 index 0000000..46760aa Binary files /dev/null and b/install/v3/auth-user-sso.assets/image-20201114095004698.png differ diff --git a/install/v3/auth-user-sso.assets/image-20201114095804049.png b/install/v3/auth-user-sso.assets/image-20201114095804049.png new file mode 100644 index 0000000..dc7a9ea Binary files /dev/null and b/install/v3/auth-user-sso.assets/image-20201114095804049.png differ diff --git a/install/v3/auth-user-sso.assets/image-20201114100349010.png b/install/v3/auth-user-sso.assets/image-20201114100349010.png new file mode 100644 index 0000000..8bf15ec Binary files /dev/null and b/install/v3/auth-user-sso.assets/image-20201114100349010.png differ diff --git a/install/v3/auth-user-sso.md b/install/v3/auth-user-sso.md new file mode 100644 index 0000000..b1056d8 --- /dev/null +++ b/install/v3/auth-user-sso.md @@ -0,0 +1,39 @@ + + +# 为单点登录的用户/用户组授权 + +当您配置 Kuboard 与 gitlab / github / ldap 实现单点登录以后,Kuboard 并不管理用户基本信息、用户组信息、用户与用户组之间的映射信息,这些信息需要您在 gitlab / github/ ldap 中管理和配置。 + +默认情况下,只有 `KUBOARD_ROOT_USER` 参数指定的用户可以执行 Kuboard 中的所有操作,其他用户通过单点登录进入 Kuboard 系统后,除了退出系统,几乎什么事情也做不了。为了让单点登录的用户获得合适的权限,您需要在 Kuboard 中为对应的用户/用户组授权。下面描述了为指定用户授权的操作步骤: + +* 为用户添加角色绑定 + + 如下图所示,导航到 ***用户*** 列表菜单,点击 ***为用户添加角色绑定*** 按钮 + + ![Kuboard-V3-用户授权](./auth-user-sso.assets/image-20201114095004698.png) + + 在图中的弹出对话框输入单点登录用户系统中的用户名,点击确定。 + +* 切换到 ***角色绑定(全局)*** + + 点击上图中的确定之后,将进入用户的授权界面,如下图所示,此时请切换到 ***角色绑定(全局)*** 标签页,点击 ***创建角色绑定*** 按钮。 + + ![Kuboard-V3-用户授权](./auth-user-sso.assets/image-20201114095804049.png) + + + +* 创建角色绑定 + + 选择角色,点击确定后,用户将具备该角色指定的权限。 + + ![Kuboard-V3-用户授权](./auth-user-sso.assets/image-20201114100349010.png) + + + +::: tip 注意 + +* 全局角色绑定,用户可以在所有 Kubernetes 集群范围内执行该角色授予的权限; +* 集群角色绑定,用户只能在指定的 Kubernetes 集群范围内执行该角色授予的权限; +* 通常,以为用户组授权比为单个用户授权更为灵活和方便。 + +::: diff --git a/install/v3/install-github.assets/image-20201114140336932.png b/install/v3/install-github.assets/image-20201114140336932.png new file mode 100644 index 0000000..1b86eca Binary files /dev/null and b/install/v3/install-github.assets/image-20201114140336932.png differ diff --git a/install/v3/install-github.assets/image-20201114153558542.png b/install/v3/install-github.assets/image-20201114153558542.png new file mode 100644 index 0000000..f65505c Binary files /dev/null and b/install/v3/install-github.assets/image-20201114153558542.png differ diff --git a/install/v3/install-github.assets/image-20201114154213721.png b/install/v3/install-github.assets/image-20201114154213721.png new file mode 100644 index 0000000..55dffee Binary files /dev/null and b/install/v3/install-github.assets/image-20201114154213721.png differ diff --git a/install/v3/install-github.assets/image-20201114154856032.png b/install/v3/install-github.assets/image-20201114154856032.png new file mode 100644 index 0000000..09b7c1a Binary files /dev/null and b/install/v3/install-github.assets/image-20201114154856032.png differ diff --git a/install/v3/install-github.assets/image-20201114155605975.png b/install/v3/install-github.assets/image-20201114155605975.png new file mode 100644 index 0000000..8602b11 Binary files /dev/null and b/install/v3/install-github.assets/image-20201114155605975.png differ diff --git a/install/v3/install-github.assets/image-20201114164729229.png b/install/v3/install-github.assets/image-20201114164729229.png new file mode 100644 index 0000000..a49ed4d Binary files /dev/null and b/install/v3/install-github.assets/image-20201114164729229.png differ diff --git a/install/v3/install-github.assets/image-20201115230700829.png b/install/v3/install-github.assets/image-20201115230700829.png new file mode 100644 index 0000000..86bf7c9 Binary files /dev/null and b/install/v3/install-github.assets/image-20201115230700829.png differ diff --git a/install/v3/install-github.md b/install/v3/install-github.md index 78f01cb..46e2ef4 100644 --- a/install/v3/install-github.md +++ b/install/v3/install-github.md @@ -10,6 +10,7 @@ meta: + Kuboard 支持多种认证方式: * 内建用户库 @@ -17,6 +18,134 @@ Kuboard 支持多种认证方式: * GitHub Enterprise / github.com * LDAP -本文将要描述如何使用 GitHub 用户登录 Kuboard。 +本文描述了如何配置 Kuboard v3 使其与 github.com / github ee 实现单点登录。 -预计在 kuboard v3.0.0-alpha.5 支持此认证方式。 +## 前提条件 + +* 用于安装 Kuboard v3.0 的机器已经安装了 docker,并且版本不低于 docker 19.03 +* 您已经有自己的 Kubernetes 集群,并且版本不低于 Kubernetes v1.13 +* 您已经安装好了 github ee 或者您打算直接使用 github.com 中的账号 + +## 部署计划 + +在正式安装 kuboard v3 之前,需做好一个简单的部署计划的设计,在本例中,各组件之间的连接方式,如下图所示: + +* 用户通过 https://github.com 访问 github.com; + +* 用户通过 http://kuboard.mycompany.com 访问 Kuboard v3; + +* Kuboard 通过 https://github.com 访问 GitHub API; + +* 安装在 Kubernetes 中的 Kuboard Agent 通过 `kuboard.mycompany.com` 访问 Kuboard 的 Web 服务端口 80 / 443 和 Kuboard Agent Server 端口 10081。 + + +![image-20201115230700829](install-github.assets/image-20201115230700829.png) + +本例子中,假设: + +* 您已经准备好了一个 Linux 服务器用于安装 Kuboard-V3 +* 您将要配置 Kuboard 使用 github.com 实现单点登录 + * 也可以支持自己本地安装的 GitHub Enterprise Edition + + + +## 准备 GitHub + +* 在 github.com (或者 github ee)中导航到 ***Settings / Developer settings*** 菜单,如下图所示: + + ![image-20201114153558542](./install-github.assets/image-20201114153558542.png) + +* 在 ***Settings / Developer settings*** 菜单中导航到 ***OAuth Apps*** 菜单,如下图所示: + + ![image-20201114154213721](./install-github.assets/image-20201114154213721.png) + +* 在上图中点击 ***New OAuth App***,并填写如下表单: + + | 字段名称 | 字段取值 | 字段描述 | + | -------------------------- | ----------------------------------------- | ------------------------------------------------------------ | + | Application name | kuboard-v3 | 标识用,填写任意名称即可 | + | Homepage URL | http://kuboard.mycompany.com | 根据 [部署计划](#部署计划),此处应该填写 http://kuboard.mycompany.com | + | Application description | Kuboard v3.0.0 | 描述,可以为空 | + | Authorization callback URL | http://kuboard.mycompany.com/sso/callback | 根据 [部署计划](#部署计划),此处应该填写 http://kuboard.mycompany.com/sso/callback,`/sso/callback` 为 Kuboard 中处理 OAuth 回调的 URL 路径 | + + ![image-20201114154856032](./install-github.assets/image-20201114154856032.png) + +* 在上图中点击 ***Register application*** 按钮之后,将进入新创建的 OAuth application 的详情页面,在该页面可以获得 ***Client ID*** 和 ***Client Secret*** 两个字段,如下图所示: + + ![image-20201114155605975](./install-github.assets/image-20201114155605975.png) + + + +## 启动 Kuboard + +使用如下命令启动 Kuboard v3: +``` sh +sudo docker run -d \ + --restart=unless-stopped \ + --name=kuboard \ + -p 80:80/tcp \ + -p 10081:10081/udp \ + -p 10081:10081/tcp \ + -v /root/kuboard-data:/data \ + -e KUBOARD_LOGIN_TYPE="github" \ + -e KUBOARD_ENDPOINT="http://kuboard.mycompany.com" \ + -e KUBOARD_ROOT_USER="shaohq" \ + -e GITHUB_CLIENT_ID="17577d45e4de7dad88e0" \ + -e GITHUB_CLIENT_SECRET="ff738553a8c7e9ad39569c8d02c1d85ec19115a7" \ + eipwork/kuboard:v3-alpha +``` + +::: tip 参数说明 +* 建议将此命令保存为一个 shell 脚本,例如 `start-kuboard.sh`,后续升级 Kuboard 或恢复 Kuboard 时,需要通过此命令了解到最初安装 Kuboard 时所使用的参数; +* 第 4 行,Kuboard v3.0 需要暴露 `80` 端口,如安装指令的第三行所示,默认映射到了宿主机的 `80` 端口,您可以根据自己的情况选择宿主机的其他端口; +* 第 5、6 行,Kuboard v3.0 需要暴露 `10081` 端口 TCP / UDP,默认映射到了宿主机的 `10081` 端口,您可以根据自己的情况选择宿主机的其他端口; +* 第 7 行,Kuboard v3.0 的持久化数据存储在 `/data` 目录,默认映射到了宿主机的 `/root/kuboard-data` 路径,请根据您自己的情况进行调整; +* 第 8 行,将 Kuboard v3.0 与 GitHub 进行单点登录集成时,必须指定环境变量 `KUBOARD_LOGIN_TYPE` 为 `github` (适用于 github.com / github-ee); +* 第 9 行,必须指定 `KUBOARD_ENDPOINT` 环境变量为访问 Kuboard 界面的 URL;(如 [部署计划](#部署计划) 中所描述,本例子中,使用 `http://kuboard.mycompany.com` 作为通过执行此命令启动的 Kuboard 的访问 URL);此参数不能以 `/` 结尾; +* 第 10 行,必须指定 `KUBOARD_ROOT_USER`,使用该 GitHub 用户登录到 Kuboard 以后,该用户具备 Kuboard 的所有权限; +* 第 11 行,必须指定 `GITHUB_CLIENT_ID`,该参数来自于 [准备 GitHub](#准备-github) 步骤中创建的 GitHub OAuth Application 的 `Client ID` 字段 +* 第 12 行,必须指定 `GITHUB_CLIENT_SECRET`,该参数来自于 [准备 GitHub](#准备-github) 步骤中创建的 GitHub OAuth Application 的 `Client Secret` 字段 +::: + +::: tip GitHub EE +上面的命令行可以用于和 github.com 集成,如果您使用 GitHub Enterprise,需要在命令行中增加如下两个参数: +* `GITHUB_HOSTNAME`,GitHub Enterprise 的 hostname,如 + ```sh + -e GITHUB_HOSTNAME="github.mycompany.com" + ``` +* `GITHUB_ROOT_CA`,如果您的 GitHub Enterprise 使用了自签名证书,则需要指定 GITHUB_ROOT_CA,否则,可以忽略此参数,如: + ```sh + -v /path/to/your/rootca.crt:/github-root-ca.crt + -e GITHUB_ROOT_CA="/github-root-ca.crt" + ``` +::: + + +## 访问 Kuboard 界面 + +* 在浏览器中输入 `http://kuboard.mycompany.com`,您将被重定向到 GitLab 登录界面; +* 在 GitLab 登录界面使用 docker run 命令中 `KUBOARD_ROOT_USER` 参数指定的用户完成登录后,GitLab 将提示您是否授权访问 Kuboard,如下图所示: + + ![image-20201113215827177](./install-gitlab.assets/image-20201113215827177.png) + +* 点击上图中的 ***Authorize*** 按钮后,您将成功登录 Kuboard 界面,第一次登录时,界面显示如下所示: + + 根据 [部署计划](#部署计划) 的设想,如下表单的填写内容为: + + | 参数名称 | 参数值 | 参数说明 | + | ---------------------------------------------------- | ------------------------------------------------------------ | ------------------------------------------------------------ | + |
Kuboard UI 访问地址
|
http://kuboard.mycompany.com
| 根据 [部署计划](#部署计划) ,安装在 Kubernetes 中的 Kuboard Agent 通过 http://kuboard.mycompany.com 这个 URL 访问 Kuboard Web 界面,此处为 Kubernetes 集群和 Kuboard 浏览器端用户设定了不同的访问域名(在 docker run 命令的 `KUBOARD_ENDPOINT` 参数指定)。 | + | Agent Server Host | kuboard.mycompany.com | 根据 [部署计划](#部署计划) ,安装在 Kubernetes 中的 Kuboard Agent 通过 kuboard.mycompany.com 解析到 Kuboard 所在宿主机的 IP 地址 | + | Agent Server UDP 端口 | 10081 | 此端口必须与 docker run 命令中映射的 10081/udp 端口一致 | + | Agent Server TCP 端口 | 10081 | 此端口必须与 docker run 命令中映射的 10081/tcp 端口一致 | + + + ![image-20201115230236714](install-gitlab.assets/image-20201115230236714.png) + +* 点击上图中的 ***保存*** 按钮,您将进入 Kuboard 集群列表页,此时,您可以向 Kuboard 添加 Kubernetes 集群,如下图所示: + + ![image-20201113221543277](./install-gitlab.assets/image-20201113221543277.png) + +## 授权用户访问 Kuboard + +默认情况下,只有 `KUBOARD_ROOT_USER` 参数指定的用户可以执行 Kuboard 中的所有操作,其他用户通过单点登录进入 Kuboard 系统后,除了退出系统,几乎什么事情也做不了。为了让单点登录的用户获得合适的权限,您需要在 Kuboard 中为对应的用户/用户组授权。请参考 [为单点登录的用户/用户组授权](./auth-user-sso.html) diff --git a/install/v3/install-gitlab.assets/image-20201112230944049.png b/install/v3/install-gitlab.assets/image-20201112230944049.png new file mode 100644 index 0000000..036c82e Binary files /dev/null and b/install/v3/install-gitlab.assets/image-20201112230944049.png differ diff --git a/install/v3/install-gitlab.assets/image-20201112232710461.png b/install/v3/install-gitlab.assets/image-20201112232710461.png new file mode 100644 index 0000000..40fb603 Binary files /dev/null and b/install/v3/install-gitlab.assets/image-20201112232710461.png differ diff --git a/install/v3/install-gitlab.assets/image-20201113212028264.png b/install/v3/install-gitlab.assets/image-20201113212028264.png new file mode 100644 index 0000000..cce6c57 Binary files /dev/null and b/install/v3/install-gitlab.assets/image-20201113212028264.png differ diff --git a/install/v3/install-gitlab.assets/image-20201113215827177.png b/install/v3/install-gitlab.assets/image-20201113215827177.png new file mode 100644 index 0000000..eb34580 Binary files /dev/null and b/install/v3/install-gitlab.assets/image-20201113215827177.png differ diff --git a/install/v3/install-gitlab.assets/image-20201113220547459.png b/install/v3/install-gitlab.assets/image-20201113220547459.png new file mode 100644 index 0000000..60cb8d2 Binary files /dev/null and b/install/v3/install-gitlab.assets/image-20201113220547459.png differ diff --git a/install/v3/install-gitlab.assets/image-20201113221543277.png b/install/v3/install-gitlab.assets/image-20201113221543277.png new file mode 100644 index 0000000..10002b3 Binary files /dev/null and b/install/v3/install-gitlab.assets/image-20201113221543277.png differ diff --git a/install/v3/install-gitlab.assets/image-20201115223736418.png b/install/v3/install-gitlab.assets/image-20201115223736418.png new file mode 100644 index 0000000..80b6aef Binary files /dev/null and b/install/v3/install-gitlab.assets/image-20201115223736418.png differ diff --git a/install/v3/install-gitlab.assets/image-20201115230226328.png b/install/v3/install-gitlab.assets/image-20201115230226328.png new file mode 100644 index 0000000..0ebf8af Binary files /dev/null and b/install/v3/install-gitlab.assets/image-20201115230226328.png differ diff --git a/install/v3/install-gitlab.assets/image-20201115230236714.png b/install/v3/install-gitlab.assets/image-20201115230236714.png new file mode 100644 index 0000000..0ebf8af Binary files /dev/null and b/install/v3/install-gitlab.assets/image-20201115230236714.png differ diff --git a/install/v3/install-gitlab.md b/install/v3/install-gitlab.md index b76c37d..4483415 100644 --- a/install/v3/install-gitlab.md +++ b/install/v3/install-gitlab.md @@ -17,6 +17,115 @@ Kuboard 支持多种认证方式: * GitHub Enterprise / github.com * LDAP -本文将要描述如何使用 GitLab 用户登录 Kuboard。 +本文描述了如何配置 Kuboard v3 使其与 gitlab.com / gitlab ee / gitlab ce 实现单点登录。 -预计在 kuboard v3.0.0-alpha.3 支持此认证方式。 +## 前提条件 + +* 用于安装 Kuboard v3.0 的机器已经安装了 docker,并且版本不低于 docker 19.03 +* 您已经有自己的 Kubernetes 集群,并且版本不低于 Kubernetes v1.13 +* 您已经安装好了 gitlab-ce 或者 gitlab-ee,又或者您打算直接使用 gitlab.com 中的账号 + +## 部署计划 + +在正式安装 kuboard v3 之前,需做好一个简单的部署计划的设计,在本例中,各组件之间的连接方式,如下图所示: + +* 用户通过 http://gitlab.mycompany.com 访问 gitlab; + +* 用户通过 http://kuboard.mycompany.com 访问 Kuboard v3; + +* Kuboard 通过 http://gitlab.mycompany.com 访问 GitLab API; + +* 安装在 Kubernetes 中的 Kuboard Agent 通过 `kuboard.mycompany.com` 访问 Kuboard 的 Web 服务端口 80 / 443 和 Kuboard Agent Server 端口 10081。 + + +![image-20201115223736418](install-gitlab.assets/image-20201115223736418.png) + +本例子中,假设: + +* 您已经准备好了一个 Linux 服务器用于安装 Kuboard-V3 +* 您的 gitlab 已经完成安装且版本不低于 11,并且可以从用户的浏览器以及用于安装 Kuboard-V3 的服务器访问到(使用 URL http://gitlab.mycompany.com) + * 本例子支持 gitlab-ce / gitlab-ee,也支持 gitlab.com + + + +## 准备 GitLab + +在 gitlab.com (或者 gitlab ee / gitlab ce)创建 Application,如下图所示: + +表单填写说明: + +| 字段名称 | 字段取值 | 字段说明 | +| ------------ | ------------------------------------------ | ------------------------------------------------------------ | +| Name | kuboad-v3 | 应用程序在 GitLab 中的标识,例如,此处填写了 kuboard-v3 | +| Redirect URI | http://kuboard.my-company.com/sso/callback | 登录成功后的回调 URL,必须填写绝对路径,且必须指定到 kuboard 的 `/sso/callback` 路径 | +| Scopes | read_user / openid / profile / email | 应用程序可以访问的 GitLab 接口范围,对于 Kuboard 而言,必须勾选如下几个选项: read_user / openid / profile / email | + +![image-20201113212028264](./install-gitlab.assets/image-20201113212028264.png) + + + +完成创建后,您将获得 `Application ID` 以及 `Secret` 两个字段的值,如下图所示: + +![image-20201112230944049](./install-gitlab.assets/image-20201112230944049.png) + +## 启动 Kuboard + +使用如下命令启动 Kuboard v3: +``` sh +sudo docker run -d \ + --restart=unless-stopped \ + --name=kuboard \ + -p 80:80/tcp \ + -p 10081:10081/udp \ + -p 10081:10081/tcp \ + -v /root/kuboard-data:/data \ + -e KUBOARD_LOGIN_TYPE="gitlab" \ + -e KUBOARD_ENDPOINT="http://kuboard.mycompany.com" \ + -e KUBOARD_ROOT_USER="shaohq" \ + -e GITLAB_BASE_URL="http://gitlab.mycompany.com" \ + -e GITLAB_APPLICATION_ID="7c10882aa46810a0402d17c66103894ac5e43d6130b81c17f7f2d8ae182040b5" \ + -e GITLAB_CLIENT_SECRET="77c149bd3a4b6870bffa1a1afaf37cba28a1817f4cf518699065f5a8fe958889" \ + eipwork/kuboard:v3-alpha +``` + +::: tip 参数说明 +* 建议将此命令保存为一个 shell 脚本,例如 `start-kuboard.sh`,后续升级 Kuboard 或恢复 Kuboard 时,需要通过此命令了解到最初安装 Kuboard 时所使用的参数; +* 第 4 行,Kuboard v3.0 需要暴露 `80` 端口,如安装指令的第三行所示,默认映射到了宿主机的 `80` 端口,您可以根据自己的情况选择宿主机的其他端口; +* 第 5、6 行,Kuboard v3.0 需要暴露 `10081` 端口 TCP / UDP,默认映射到了宿主机的 `10081` 端口,您可以根据自己的情况选择宿主机的其他端口; +* 第 7 行,Kuboard v3.0 的持久化数据存储在 `/data` 目录,默认映射到了宿主机的 `/root/kuboard-data` 路径,请根据您自己的情况进行调整; +* 第 8 行,将 Kuboard v3.0 与 GitLab 进行单点登录集成时,必须指定环境变量 `KUBOARD_LOGIN_TYPE` 为 `gitlab` (适用于 gitlab.com / gitlab-ee / gitlab-ce); +* 第 9 行,必须指定 `KUBOARD_ENDPOINT` 环境变量为访问 Kuboard 界面的 URL;(如 [部署计划](#部署计划) 中所描述,本例子中,使用 `http://kuboard.mycompany.com` 作为通过执行此命令启动的 Kuboard 的访问 URL);此参数不能以 `/` 结尾; +* 第 10 行,必须指定 `KUBOARD_ROOT_USER`,使用该 GitLab 用户登录到 Kuboard 以后,该用户具备 Kuboard 的所有权限; +* 第 11 行,指定 `GIBLAB_BASE_URL`,(如 [部署计划](#部署计划) 中所描述,本例子中,使用 `http://gitlab.mycompany.com` 作为通过作为 GitLab 的访问 URL,并假设 GitLab 已经事先准备就绪,如果不指定,该参数默认值为 `https://gitlab.com`);此参数不能以 `/` 结尾; +* 第 12 行,必须指定 `GITLAB_APPLICATION_ID`,该参数来自于 [准备 GitLab](#准备-gitlab) 步骤中创建的 GitLab Application 的 `Application ID` 字段 +* 第 13 行,必须指定 `GITLAB_CLIENT_SECRET`,该参数来自于 [准备 GitLab](#准备-gitlab) 步骤中创建的 GitLab Application 的 `Secret` 字段 +::: + +## 访问 Kuboard 界面 + +* 在浏览器中输入 `http://kuboard.mycompany.com`,您将被重定向到 GitLab 登录界面; +* 在 GitLab 登录界面使用 docker run 命令中 `KUBOARD_ROOT_USER` 参数指定的用户完成登录后,GitLab 将提示您是否授权访问 Kuboard,如下图所示: + + ![image-20201113215827177](./install-gitlab.assets/image-20201113215827177.png) + +* 点击上图中的 ***Authorize*** 按钮后,您将成功登录 Kuboard 界面,第一次登录时,界面显示如下所示: + + 根据 [部署计划](#部署计划) 的设想,如下表单的填写内容为: + + | 参数名称 | 参数值 | 参数说明 | + | ---------------------------------------------------- | ------------------------------------------------------------ | ------------------------------------------------------------ | + |
Kuboard UI 访问地址
|
http://kuboard.mycompany.com
| 根据 [部署计划](#部署计划) ,安装在 Kubernetes 中的 Kuboard Agent 通过 http://kuboard.mycompany.com 这个 URL 访问 Kuboard Web 界面,此处为 Kubernetes 集群和 Kuboard 浏览器端用户设定了不同的访问域名(在 docker run 命令的 `KUBOARD_ENDPOINT` 参数指定)。 | + | Agent Server Host | kuboard.mycompany.com | 根据 [部署计划](#部署计划) ,安装在 Kubernetes 中的 Kuboard Agent 通过 kuboard.mycompany.com 解析到 Kuboard 所在宿主机的 IP 地址 | + | Agent Server UDP 端口 | 10081 | 此端口必须与 docker run 命令中映射的 10081/udp 端口一致 | + | Agent Server TCP 端口 | 10081 | 此端口必须与 docker run 命令中映射的 10081/tcp 端口一致 | + + + ![image-20201115230236714](install-gitlab.assets/image-20201115230236714.png) + +* 点击上图中的 ***保存*** 按钮,您将进入 Kuboard 集群列表页,此时,您可以向 Kuboard 添加 Kubernetes 集群,如下图所示: + + ![image-20201113221543277](./install-gitlab.assets/image-20201113221543277.png) + +## 授权用户访问 Kuboard + +默认情况下,只有 `KUBOARD_ROOT_USER` 参数指定的用户可以执行 Kuboard 中的所有操作,其他用户通过单点登录进入 Kuboard 系统后,除了退出系统,几乎什么事情也做不了。为了让单点登录的用户获得合适的权限,您需要在 Kuboard 中为对应的用户/用户组授权。请参考 [为单点登录的用户/用户组授权](./auth-user-sso.html) diff --git a/install/v3/install-ldap.assets/image-20201114170038294.png b/install/v3/install-ldap.assets/image-20201114170038294.png new file mode 100644 index 0000000..ce8fe9c Binary files /dev/null and b/install/v3/install-ldap.assets/image-20201114170038294.png differ diff --git a/install/v3/install-ldap.assets/image-20201114175421773.png b/install/v3/install-ldap.assets/image-20201114175421773.png new file mode 100644 index 0000000..221fe34 Binary files /dev/null and b/install/v3/install-ldap.assets/image-20201114175421773.png differ diff --git a/install/v3/install-ldap.assets/image-20201114180239080.png b/install/v3/install-ldap.assets/image-20201114180239080.png new file mode 100644 index 0000000..67ee373 Binary files /dev/null and b/install/v3/install-ldap.assets/image-20201114180239080.png differ diff --git a/install/v3/install-ldap.assets/image-20201114182400836.png b/install/v3/install-ldap.assets/image-20201114182400836.png new file mode 100644 index 0000000..26d9ef3 Binary files /dev/null and b/install/v3/install-ldap.assets/image-20201114182400836.png differ diff --git a/install/v3/install-ldap.assets/image-20201114182716704.png b/install/v3/install-ldap.assets/image-20201114182716704.png new file mode 100644 index 0000000..c131572 Binary files /dev/null and b/install/v3/install-ldap.assets/image-20201114182716704.png differ diff --git a/install/v3/install-ldap.assets/image-20201114183112103.png b/install/v3/install-ldap.assets/image-20201114183112103.png new file mode 100644 index 0000000..80c4abd Binary files /dev/null and b/install/v3/install-ldap.assets/image-20201114183112103.png differ diff --git a/install/v3/install-ldap.assets/image-20201114183716496.png b/install/v3/install-ldap.assets/image-20201114183716496.png new file mode 100644 index 0000000..58e7819 Binary files /dev/null and b/install/v3/install-ldap.assets/image-20201114183716496.png differ diff --git a/install/v3/install-ldap.assets/image-20201115230620704.png b/install/v3/install-ldap.assets/image-20201115230620704.png new file mode 100644 index 0000000..3080d88 Binary files /dev/null and b/install/v3/install-ldap.assets/image-20201115230620704.png differ diff --git a/install/v3/install-ldap.md b/install/v3/install-ldap.md index 81a48b5..a2d8017 100644 --- a/install/v3/install-ldap.md +++ b/install/v3/install-ldap.md @@ -10,6 +10,7 @@ meta: + Kuboard 支持多种认证方式: * 内建用户库 @@ -17,6 +18,184 @@ Kuboard 支持多种认证方式: * GitHub Enterprise / github.com * LDAP -本文将要描述如何使用 LDAP 用户登录 Kuboard。 +本文描述了如何配置 Kuboard v3 使用 LDAP 实现用户登录。 -预计在 kuboard v3.0.0-alpha.4 支持此认证方式。 +## 前提条件 + +* 用于安装 Kuboard v3.0 的机器已经安装了 docker,并且版本不低于 docker 19.03 +* 您已经有自己的 Kubernetes 集群,并且版本不低于 Kubernetes v1.13 + +## 部署计划 + +在正式安装 kuboard v3 之前,需做好一个简单的部署计划的设计,在本例中,各组件之间的连接方式,如下图所示: + + +* 用户通过 http://kuboard.mycompany.com 访问 Kuboard v3; + +* Kuboard 通过 `localhost:389` 和 `localhost:636` 访问 LDAP; + +* 安装在 Kubernetes 中的 Kuboard Agent 通过 `kuboard.mycompany.com` 访问 Kuboard 的 Web 服务端口 80 / 443 和 Kuboard Agent Server 端口 10081。 + + +![image-20201115230620704](install-ldap.assets/image-20201115230620704.png) + +本例子中,假设: + +* 您已经准备好了一个 Linux 服务器用于安装 Kuboard-V3 + +## 准备 LDAP + +> 本章节将引导您搭建一个测试用的 LDAP,如果您使用已经有的 LDAP,可跳过本章节。 + +* 启动 Open LDAP + + > 下面启动 Open LDAP 的脚本仅用于测试,未考虑如何持久化,如何设置 TLS 等,更多信息请参考该脚本中所用容器的 [帮助文档](https://github.com/osixia/docker-openldap) + ``` sh + docker run -p 389:389 -p 636:636 --name my-openldap-container --detach osixia/openldap:1.4.0 + ``` + +* 启动 phpLDAPadmin + + ```sh + docker run -p 6443:443 \ + --env PHPLDAPADMIN_LDAP_HOSTS=host.docker.internal \ + --detach osixia/phpldapadmin:0.9.0 + ``` + +* 登录 phpLDAPadmin + + 在浏览器输入 `https://kuboard.mycompany.com:6443` ,按下图所示步骤登录 phpLDAPadmin: + + | 字段名称 | 字段值 | 字段描述 | + | -------- | -------------------------- | -------------- | + | Login DN | cn=admin,dc=example,dc=org | 默认管理员用户 | + | Password | admin | 管理员密码 | + + ![image-20201114175421773](./install-ldap.assets/image-20201114175421773.png) + +* 添加用户组 + + 登录成功后,按照下图所示步骤,进入添加分组的表单: + + ![image-20201114180239080](./install-ldap.assets/image-20201114180239080.png) + + 在表单中填写 `mygroup` 然后点击 ***Create Object*** 按钮,创建 `mygroup` 用户组,如下图所示: + + ![image-20201114182400836](./install-ldap.assets/image-20201114182400836.png) + + > 点击 ***Create Object*** 之后的界面中再次点击 ***Commit*** 按钮,才能完成对象的创建。 + +* 添加用户 + + 按照下图所示步骤,进入添加用户的表单: + + ![image-20201114182716704](./install-ldap.assets/image-20201114182716704.png) + + 表单各字段填写说明: + + | 字段名称 | 字段值 | + | -------------- | ------------------ | + | First name | Huanqing | + | Last name | Shao | + | Common Name | Huanqing Shao | + | User ID | shaohq | + | Password | 123456 | + | GID Number | mygroup | + | Home Directory | /home/users/shaohq | + + 表单界面如下所示: + + ![image-20201114183112103](./install-ldap.assets/image-20201114183112103.png) + + 点击上图中的 ***Create Object*** 按钮,然后再点击 ***Commit*** 按钮,将成功创建用户,并进入如下界面。按照如下步骤在该界面中为用户添加邮箱地址字段: + + * 点击 Add new attribute + * 选择 Email 字段类型 + * 填写电子邮箱地址 + * 点击 Update Object 按钮 + + ![image-20201114183716496](./install-ldap.assets/image-20201114183716496.png) + +::: tip LDAP Demo + +此时我们已经准备好了用于演示的 LDAP 环境: + +* 快速安装了一个 LDAP 服务实例 +* 创建了一个用户组 `mygroup` +* 创建了一个用户 `shaohq`,该用户归属于用户组 `mygroup`,其密码为 `123456` + +::: + +## 启动 Kuboard + +使用如下命令启动 Kuboard v3: +``` sh +sudo docker run -d \ + --restart=unless-stopped \ + --name=kuboard \ + -p 80:80/tcp \ + -p 10081:10081/udp \ + -p 10081:10081/tcp \ + -v /Users/shaohuanqing/temp/kuboard-data:/data \ + -e KUBOARD_LOGIN_TYPE="ldap" \ + -e KUBOARD_ENDPOINT="http://kuboard.mycompany.com" \ + -e KUBOARD_ROOT_USER="shaohq" \ + -e LDAP_HOST="host.docker.internal:389" \ + -e LDAP_BIND_DN="cn=admin,dc=example,dc=org" \ + -e LDAP_BIND_PASSWORD="admin" \ + -e LDAP_BASE_DN="dc=example,dc=org" \ + -e LDAP_FILTER="(objectClass=posixAccount)" \ + -e LDAP_USER_NAME="uid" \ + -e LDAP_ID_ATTRIBUTE="uid" \ + -e LDAP_EMAIL_ATTRIBUTE="mail" \ + -e LDAP_DISPLAY_NAME_ATTRIBUTE="cn" \ + -e LDAP_GROUP_SEARCH_BASE_DN="dc=example,dc=org" \ + -e LDAP_GROUP_SEARCH_FILTER="(objectClass=posixGroup)" \ + -e LDAP_USER_MACHER_USER_ATTRIBUTE="gidNumber" \ + -e LDAP_USER_MACHER_GROUP_ATTRIBUTE="gidNumber" \ + -e LDAP_GROUP_NAME_ATTRIBUTE="cn" \ + eipwork/kuboard:v3-alpha +``` + + +::: tip 参数说明 +* 建议将此命令保存为一个 shell 脚本,例如 `start-kuboard.sh`,后续升级 Kuboard 或恢复 Kuboard 时,需要通过此命令了解到最初安装 Kuboard 时所使用的参数; +* 第 4 行,Kuboard v3.0 需要暴露 `80` 端口,如安装指令的第三行所示,默认映射到了宿主机的 `80` 端口,您可以根据自己的情况选择宿主机的其他端口; +* 第 5、6 行,Kuboard v3.0 需要暴露 `10081` 端口 TCP / UDP,默认映射到了宿主机的 `10081` 端口,您可以根据自己的情况选择宿主机的其他端口; +* 第 7 行,Kuboard v3.0 的持久化数据存储在 `/data` 目录,默认映射到了宿主机的 `/root/kuboard-data` 路径,请根据您自己的情况进行调整; +* 第 8 行,将 Kuboard v3.0 与 GitLab 进行单点登录集成时,必须指定环境变量 `KUBOARD_LOGIN_TYPE` 为 `gitlab` (适用于 gitlab.com / gitlab-ee / gitlab-ce); +* 第 9 行,必须指定 `KUBOARD_ENDPOINT` 环境变量为访问 Kuboard 界面的 URL;(如 [部署计划](#部署计划) 中所描述,本例子中,使用 `http://kuboard.mycompany.com` 作为通过执行此命令启动的 Kuboard 的访问 URL);此参数不能以 `/` 结尾; +* 第 10 行,必须指定 `KUBOARD_ROOT_USER`,使用该 GitLab 用户登录到 Kuboard 以后,该用户具备 Kuboard 的所有权限; +* 第 11 行,指定 `GIBLAB_BASE_URL`,(如 [部署计划](#部署计划) 中所描述,本例子中,使用 `http://gitlab.mycompany.com` 作为通过作为 GitLab 的访问 URL,并假设 GitLab 已经事先准备就绪,如果不指定,该参数默认值为 `https://gitlab.com`);此参数不能以 `/` 结尾; +* 第 12 行,必须指定 `GITLAB_APPLICATION_ID`,该参数来自于 [准备 GitLab](#准备-gitlab) 步骤中创建的 GitLab Application 的 `Application ID` 字段 +* 第 13 行,必须指定 `GITLAB_CLIENT_SECRET`,该参数来自于 [准备 GitLab](#准备-gitlab) 步骤中创建的 GitLab Application 的 `Secret` 字段 +::: + +## 访问 Kuboard 界面 + +* 在浏览器中输入 `http://kuboard.mycompany.com`,您将被重定向到 GitLab 登录界面; +* 在 GitLab 登录界面使用 docker run 命令中 `KUBOARD_ROOT_USER` 参数指定的用户完成登录后,GitLab 将提示您是否授权访问 Kuboard,如下图所示: + + ![image-20201113215827177](./install-gitlab.assets/image-20201113215827177.png) + +* 点击上图中的 ***Authorize*** 按钮后,您将成功登录 Kuboard 界面,第一次登录时,界面显示如下所示: + + 根据 [部署计划](#部署计划) 的设想,如下表单的填写内容为: + + | 参数名称 | 参数值 | 参数说明 | + | ---------------------------------------------------- | ------------------------------------------------------------ | ------------------------------------------------------------ | + |
Kuboard UI 访问地址
|
http://kuboard.mycompany.com
| 根据 [部署计划](#部署计划) ,安装在 Kubernetes 中的 Kuboard Agent 通过 http://kuboard.mycompany.com 这个 URL 访问 Kuboard Web 界面,此处为 Kubernetes 集群和 Kuboard 浏览器端用户设定了不同的访问域名(在 docker run 命令的 `KUBOARD_ENDPOINT` 参数指定)。 | + | Agent Server Host | kuboard.mycompany.com | 根据 [部署计划](#部署计划) ,安装在 Kubernetes 中的 Kuboard Agent 通过 kuboard.mycompany.com 解析到 Kuboard 所在宿主机的 IP 地址 | + | Agent Server UDP 端口 | 10081 | 此端口必须与 docker run 命令中映射的 10081/udp 端口一致 | + | Agent Server TCP 端口 | 10081 | 此端口必须与 docker run 命令中映射的 10081/tcp 端口一致 | + + + ![image-20201115230236714](install-gitlab.assets/image-20201115230236714.png) + +* 点击上图中的 ***保存*** 按钮,您将进入 Kuboard 集群列表页,此时,您可以向 Kuboard 添加 Kubernetes 集群,如下图所示: + + ![image-20201113221543277](./install-gitlab.assets/image-20201113221543277.png) + +## 授权用户访问 Kuboard + +默认情况下,只有 `KUBOARD_ROOT_USER` 参数指定的用户可以执行 Kuboard 中的所有操作,其他用户通过单点登录进入 Kuboard 系统后,除了退出系统,几乎什么事情也做不了。为了让单点登录的用户获得合适的权限,您需要在 Kuboard 中为对应的用户/用户组授权。请参考 [为单点登录的用户/用户组授权](./auth-user-sso.html) diff --git a/support/change-log/v3.0.x.md b/support/change-log/v3.0.x.md index b258a7d..b956f1b 100644 --- a/support/change-log/v3.0.x.md +++ b/support/change-log/v3.0.x.md @@ -13,6 +13,25 @@ description: 本文描述了Kuboard_v3.0.x的版本变更说明 Kuboard v3.0.x 的更新说明 +## v3.0.0-alpha.3 + +**发布日期** + +2020年11月15日 + +**新特性** + +* Kuboard 与上游系统实现单点认证登录 + * GitLab 单点认证登录 + * GitHub 单点认证登录 + * LDAP 单点认证登录 +* 单点登录模式下的用户授权 + +**BUG修正** + +* 通用设置 --> 修改页脚文字时,输入框默认不应该为空 +* 集群概览页 --> StorageClass 列表、PV 列表 的链接错误 + ## v3.0.0-alpha.2