diff --git a/learning/k8s-advanced/proxy/auth-proxy.assets/image-20200308101542457.png b/learning/k8s-advanced/proxy/auth-proxy.assets/image-20200308101542457.png new file mode 100644 index 0000000..4191c92 Binary files /dev/null and b/learning/k8s-advanced/proxy/auth-proxy.assets/image-20200308101542457.png differ diff --git a/learning/k8s-advanced/proxy/auth-proxy.assets/image-20200308102538049.png b/learning/k8s-advanced/proxy/auth-proxy.assets/image-20200308102538049.png new file mode 100644 index 0000000..9ce5659 Binary files /dev/null and b/learning/k8s-advanced/proxy/auth-proxy.assets/image-20200308102538049.png differ diff --git a/learning/k8s-advanced/proxy/auth-proxy.assets/image-20200308105924109.png b/learning/k8s-advanced/proxy/auth-proxy.assets/image-20200308105924109.png new file mode 100644 index 0000000..2964f66 Binary files /dev/null and b/learning/k8s-advanced/proxy/auth-proxy.assets/image-20200308105924109.png differ diff --git a/learning/k8s-advanced/proxy/auth-proxy.md b/learning/k8s-advanced/proxy/auth-proxy.md new file mode 100644 index 0000000..92d38d6 --- /dev/null +++ b/learning/k8s-advanced/proxy/auth-proxy.md @@ -0,0 +1,123 @@ +--- +vssueId: 184 +# lessAds: true +description: Kubernetes教程:本文介绍了如何通过 Kuboard 的 Auth Proxy 实现与对后端服务的单点登录。 +meta: + - name: keywords + content: Kubernetes教程,K8S,kubectl proxy +--- + +# Kuboard Proxy - Auth Proxy + + + +Kuboard Proxy 提供了 Auth Proxy 的功能,本文以 Grafana 为例,介绍如何使用 Kuboard Proxy 实现 Grafana 与 Kuboard 的单点登录。 + +参考 [Grafana Auth Proxy Authentication](https://grafana.com/docs/grafana/latest/auth/auth-proxy/) ,我们知道 Grafana 支持多种认证登录方式(Auth Proxy、LDAP、OAuth、Goole、Azure AD、GitHub、GitLab、SAML 等),Auth Proxy 是其中的一种。 + +一般来说,使用 Auth Proxy,需要在反向代理服务器(Nginx、Apache等)上配置复杂的参数。本文描述了,如何使用 Kuboard Proxy 的功能配置 Grafana Auth Proxy 的步骤。 + +[[TOC]] + +## 前提 + +* 您已经安装了 Kubernetes 集群(不低于 v1.13),如果没有,请参考 [安装 Kubernetes 单 Master 节点](/install/install-k8s.html); +* 您已经安装了 Kuboard (不低于 v1.0.7.1),如果没有,请参考 [安装 Kuboard](/install/v3/install.html) + +## 安装 Grafana + +* 创建 `grafana-ns` namespace; + + 参考 [名称空间管理](/guide/cluster/namespace.html) + +* 在名称空间 `grafana-ns` 中创建 `grafana-pvc` 存储卷声明; + + 参考 [创建存储卷声明](/guide/namespace/pvc.html) + +* 在名称空间 `grafana-ns` 中创建 `grafana` 工作负载; + + 点击 ***创建工作负载*** 按钮,并填写如下表单: + + | 区块 | 字段名称 | 填写内容 | 字段说明 | + | -------- | ------------------------ | ------------------------------------------------------------ | ------------------------------------------------------------ | + | 基本信息 | 服务类型 | Deployment | | + | | 服务分层 | 监控层 | | + | | 服务名称 | monitor-grafana | | + | | 服务描述 | Grafana | | + | | 副本数量 | 1 | | + | 数据卷 | 数据卷名称 | grafana-volume | | + | | 数据卷类型 | 存储卷声明 | | + | | 存储卷名称 | grafana-pvc | | + | 工作容器 | 容器名称 | grafana | | + | | 镜像 | grafana/grafana:6.6.2 | | + | | 环境变量 | GF_SERVER_ROOT_URL=
/proxy/http/grafana-ns/monitor-grafana/:/3000/ | Kuboard Proxy 代理后的 web 路径 | + | | 环境变量 | GF_AUTH_PROXY_ENABLED=true | 为 Grafana 启用 Auth Proxy 认证方式 | + | | 环境变量 | GF_SECURITY_ADMIN_USER=kuboard-user | 将 `kuboard-user` 设置为 Grafana 的默认管理用户 | + | | 挂载点 -> 容器内路径 | /var/lib/grafana | 将 grafana 产生的数据存储到数据卷中,避免 grafana 重启后,配置的随容器的销毁而丢失 | + | | 挂载点 -> 数据卷 | grafana-volume | | + | | 挂载点 -> 数据卷内子路径 | grafana | | + | 访问方式 | Service类型 | ClusterIP | | + | | Port -> 协议 | TCP | | + | | Port -> 服务端口 | 3000 | | + | | Port -> 容器端口 | 3000 | Grafana 的默认端口为 3000 | + + > Kuboard Proxy 代理后的路径格式如下: + > + > /proxy/\/\/\/:/\/ + > * **protocol**: 为容器内应用所接受的传输协议,可选值为 http / https; + > * **namespace**:被代理对象所在的名称空间; + > * **service-name**:被代理 Service 的名称; + > * **port**:目标端口 + + + + 截图如下所示: + + ![image-20200308101542457](./auth-proxy.assets/image-20200308101542457.png) + + + +## 配置 Kuboard Proxy + +* 完成 Grafana 的部署以后,进入到 `monitor-grafana` 的工作负载查看界面; + +* 在工作负载查看页面点击 ***访问方式 Service*** 区域中的 ***代理*** 按钮; + +* 点击 ***代理配置信息*** 后的 ***修改*** 按钮,修改 Kuboard Proxy 的代理配置; + + 填写表格: + + | 字段名称 | 填写内容 | 填写说明 | + | ------------------- | ---------------- | ------------------------------------------------------------ | + | 用户名添加到 Header | X-WEBAUTH-USER | Grafana Auth Proxy 从请求头中的 X-WEBAUTH-USER获取到当前登录用户的信息;填写此字段后,Kuboard Proxy 会始终将当前登录 Kuboard 的用户名写入到发现后端服务的 HTTP 请求头中,因此,可实现从 Kuboard 到 Grafana 的单点登录 | + | 组名添加到 Header | X-WEBAUTH-GROUPS | 同上,但是用于从 KuboardProxy 向 Grafana 传递用户所属分组的信息。
Grafana 只在企业版中处理此字段,请参考 [Team Sync](https://grafana.com/docs/grafana/latest/auth/auth-proxy/#team-sync-enterprise-only) | + | Cookie TTL | 空白 | 默认使用环境变量 KUBOARD_PROXY_COOKIE_TTL 的取值,或者 36000 | + | 禁用 Rebase | 禁用 | Grafana 系统中配置了环境变量 `GF_SERVER_ROOT_URL` ,并且 Grafana 可以正确处理 web 上下文因此,无需在 Kuboard Proxy 中做 [Rebase](./rebase.html) | + + > 由于 Grafana 只在企业版中处理 X-WEBAUTH-GROUPS 字段,如果您使用的是 Grafana 社区版,请自行在登录后的 Grafana 中配置 Teams 信息。 + + 截图如下所示: + + ![image-20200308102538049](./auth-proxy.assets/image-20200308102538049.png) + +* 填写完成后,点击 ***确定*** 按钮,保存表单。 + + > KuboardProxy 的配置信息存储在 Service 的注解 annotation 中。 + +## 访问 Grafana + +* 完成 Grafana 的部署以后,进入到 `monitor-grafana` 的工作负载查看界面; + +* 在工作负载查看页面点击 ***访问方式 Service*** 区域中的 ***代理*** 按钮; + +* 点击 ***在浏览器窗口中打开*** 按钮,即可在新窗口中打开 Grafana 界面。 + + 如果您使用 kuboard-user 登录,则您在 Grafana 中是系统管理员的角色,可以对 Grafana 做任何配置,截图如下所示: + + ![image-20200308105924109](./auth-proxy.assets/image-20200308105924109.png) + +## 直接导入 + +本文所创建的 Grafana 部署可以直接导入: +* 请在此处下载 kuboard_grafana_proxy_demo.yaml ; +* 请参考 [导入 example 微服务](/guide/example/import.html) 了解如何在 Kuboard 中导入配置。 diff --git a/learning/k8s-advanced/proxy/authorization.assets/image-20200308111421525.png b/learning/k8s-advanced/proxy/authorization.assets/image-20200308111421525.png new file mode 100644 index 0000000..19be2b7 Binary files /dev/null and b/learning/k8s-advanced/proxy/authorization.assets/image-20200308111421525.png differ diff --git a/learning/k8s-advanced/proxy/authorization.md b/learning/k8s-advanced/proxy/authorization.md new file mode 100644 index 0000000..7d8683f --- /dev/null +++ b/learning/k8s-advanced/proxy/authorization.md @@ -0,0 +1,25 @@ +--- +vssueId: 184 +# lessAds: true +description: Kubernetes教程:本文介绍了如何授权用户访问 Kuboard Proxy。 +meta: + - name: keywords + content: Kubernetes教程,K8S,kubectl proxy +--- + +# Kuboard Proxy - 授权 + + + +如果要授权用户使用 Kuboard Proxy,请为其分配如下权限: + +| apiGroups | resources | resourceNames | verbs | +| --------- | ------------------------------ | ------------- | ------ | +| v1 | services/proxy
pods/proxy | | create | +| v1 | services
pods | | get | + +截图如下所示: + +![访问KuboardProxy所需权限](./authorization.assets/image-20200308111421525.png) + +请参考 [使用Kuboard管理ServiceAccount及RBAC](/learning/k8s-advanced/sec/kuboard.html) 了解更多关于如何在 Kuboard 中完成授权操作的信息。 diff --git a/learning/k8s-advanced/proxy/index.assets/nginx-service-access.png b/learning/k8s-advanced/proxy/index.assets/nginx-service-access.png new file mode 100644 index 0000000..cdf2869 Binary files /dev/null and b/learning/k8s-advanced/proxy/index.assets/nginx-service-access.png differ diff --git a/learning/k8s-advanced/proxy/index.assets/nginx-service-config.png b/learning/k8s-advanced/proxy/index.assets/nginx-service-config.png new file mode 100644 index 0000000..1ed086c Binary files /dev/null and b/learning/k8s-advanced/proxy/index.assets/nginx-service-config.png differ diff --git a/learning/k8s-advanced/proxy/index.assets/nginx-service-curl.png b/learning/k8s-advanced/proxy/index.assets/nginx-service-curl.png new file mode 100644 index 0000000..3f0e169 Binary files /dev/null and b/learning/k8s-advanced/proxy/index.assets/nginx-service-curl.png differ diff --git a/learning/k8s-advanced/proxy/index.assets/nginx-service-discovery.png b/learning/k8s-advanced/proxy/index.assets/nginx-service-discovery.png new file mode 100644 index 0000000..d039572 Binary files /dev/null and b/learning/k8s-advanced/proxy/index.assets/nginx-service-discovery.png differ diff --git a/learning/k8s-advanced/proxy/index.assets/nginx-service.png b/learning/k8s-advanced/proxy/index.assets/nginx-service.png new file mode 100644 index 0000000..0b6c9c6 Binary files /dev/null and b/learning/k8s-advanced/proxy/index.assets/nginx-service.png differ diff --git a/learning/k8s-advanced/proxy/index.md b/learning/k8s-advanced/proxy/index.md new file mode 100644 index 0000000..1b4fe9c --- /dev/null +++ b/learning/k8s-advanced/proxy/index.md @@ -0,0 +1,115 @@ +--- +vssueId: 184 +# lessAds: true +sharingTitle: 快速调试 Kubernetes 上部署的应用程序 +description: Kubernetes教程:本文介绍了如何 Kuboard Proxy 的特点和使用方法 +meta: + - name: keywords + content: Kubernetes教程, kubectl proxy, +--- + +# Kuboard Proxy + + + +借助 Kuboard Proxy,登录 Kuboard 的用户可以直接访问 Service/Pod,而无需为 Service 做额外的 NodePort、Ingress 等配置。Kuboard Proxy 是 `kubectl proxy` 命令一种替代选项。 + +与 `kubectl proxy` 相比: +* 用户可以直接在 Kuboard 界面进行操作,而无需使用命令行; +* 用户权限控制; +* 支持更加细致的 rebase 控制; +* 可以对接支持 Auth-Proxy 认证方式的后端服务,实现单点登录,例如 [Grafana](https://grafana.com/docs/grafana/v6.5/auth/auth-proxy/)。 + +本文后面的章节将描述 Kuboard Proxy 的基本使用方法。并有另外三篇文档对 Kuboard Proxy 做进一步的阐述: +* [授权用户访问 Kuboard Proxy](./authorization.html) +* [为什么我的网页通过 Kuboard Proxy 代理后显示不正常 - Rebase - (少数情况)](./rebase.html) +* [通过 Auth-Proxy 实现 Grafana 与 Kuboard 的单点登录](./auth-proxy.html) + +## 使用 Kuboard Proxy 访问 Service + +按照如下步骤,可以非常方便地使用 Kuboard Proxy: + +* 进入工作负载查看页面,此处以 [Kubernetes 入门 -- 公布应用程序](/learning/k8s-basics/expose.html) 中创建的 nginx 作为例子,如下图所示: + + ![Kubernetest教程_使用KuboardProxy](./index.assets/nginx-service.png) + +* 点击上图中 ***红色箭头指向的按钮***,将打开如下代理发现界面: + + 界面中显示了三个区域: + + * KuboardProxy 代理配置信息,点击 ***编辑*** 按钮后可以 [修改KuboardProxy配置](#修改KuboardProxy代理配置); + * KuboardProxy 代理发现信息; + * 访问代理目标(显示了代理的进一步操作区): + * 选择代理协议,此处支持 `http`、 `https` 两种选择,该协议要访问的容器内端口所支持的协议; + * 选择访问方法,可以直接在浏览器中打开网页,也可以通过 crul/postman 等测试工具调用容器内的 restful 接口。 + + ![Kubernetest教程_使用KuboardProxy](./index.assets/nginx-service-discovery.png) + +* 通过代理访问目标 Service + + * 点击 ***在浏览器窗口中打开*** 按钮,将直接打开一个新窗口,并显示目标页面,如下所示: + + ![Kubernetest教程_使用KuboardProxy](./index.assets/nginx-service-access.png) + + * 点击 ***使用 curl/postman 访问目标代理***,将显示如下对话框: + + 复制对话框中的代码,并在命令行终端执行,可以获得代理目标服务返回的响应。 + + > 这种做法在进行 API 测试时非常方便。 + + ![Kubernetest教程_使用KuboardProxy](./index.assets/nginx-service-curl.png) + +## 修改KuboardProxy代理配置 + +KuboardProxy代理的设置有: + +* 环境变量 + * 全局生效; +* 代理设置 + * 只针对 Service/Pod 的单个端口代理生效; + +### 环境变量 + +与 KuboardProxy 相关的环境变量有如下两个: + +| 名称 | 变量类型 | 默认值 | 描述 | +| ------------------------ | -------- | ------ | ------------------------------------------------------------ | +| KUBOARD_AUTH_ENCRYPT_KEY | String | 随机 |
  • 如果不配置,每次重启 Kuboard 时,随机生成;
  • 如果配置,该字段必须为一个长度为32的字符串,可以由字母和数字组成;
  • Kuboard 使用 [AES-256算法](https://www.zhihu.com/question/34563299/answer/59176478) 生成加密 Cookie,客户端使用此 Cookie,可以通过 KuboardProxy 认证,并实现代理访问;
  • 当您的 Kuboard 副本数大于 1 时,请务必配置此参数,否则不同 Kuboard 副本的 ENCRYPT_KEY 不同时,Kuboard Proxy 将不能正常工作;
  • | +| KUBOARD_PROXY_COOKIE_TTL | Long | 36000 |
  • 单位秒,默认值为36000(即10小时);
  • 访问代理时,所用 cookie 的有效时长;
  • 如果 Service/Pod 上没有特殊配置,则使用此处的设置。
  • | + + + +### 代理配置 + +在 KuboardProxy 对话框上,点击 ***修改*** 按钮,可以修改针对该端口的 KuboardProxy 设置参数,如下图所示: + +![Kubernetest教程_使用KuboardProxy](./index.assets/nginx-service-config.png) + +可以配置的参数有: + +| 名称 | 类型 | 默认值 | 描述 | +| --------------------- | ------- | --------------------------------------------- | ---------------------------------------- | +| 用户名添加到 Header | String | X-WEBAUTH-USER | [Auth-Proxy](./auth-proxy.html) 重要参数 | +| 组名添加到 Header | String | X-WEBAUTH-GROUP | [Auth-Proxy](./auth-proxy.html) 重要参数 | +| Cookie TTL / 单位:秒 | Long | 环境变量KUBOARD_PROXY_COOKIE_TTL
    或36000 | Cookie 的有效时长 | +| 禁用 Rebase | Boolean | false | 禁用 [Rebase](./rebase.html) | + + + +## 使用 Kubectl Proxy + +使用 `kubectl proxy` 之前,请确保您已经 [在客户端配置 kubectl](/install/config-kubectl.html)。如果已经配置,可按照如下步骤使用 `kubectl proxy`。 + +* 执行命令以启动 `kubectl proxy` 程序 + + ``` sh + kubectl proxy + ``` + +* 通过代理访问您的服务/Pod: + + * 以上述 `example` 名称空间的 Service `web-example` 为例,如需要使用 http 协议访问该 Service 的 80 端口,实现上面使用 Kuboard Proxy 的例子中一样的访问效果,请在浏览器打开如下链接: + + ``` + http://localhost:8001/api/v1/namespaces/example/services/http:web-example:80/proxy/ + ``` diff --git a/learning/k8s-advanced/proxy/rebase.md b/learning/k8s-advanced/proxy/rebase.md new file mode 100644 index 0000000..451df26 --- /dev/null +++ b/learning/k8s-advanced/proxy/rebase.md @@ -0,0 +1,112 @@ +--- +vssueId: 184 +# lessAds: true +description: Kubernetes教程:本文介绍了 Kuboard Proxy 的 Rebase 功能。 +meta: + - name: keywords + content: Kubernetes教程,K8S,kubectl proxy +--- + +# Kuboard Proxy - Rebase + + + +## 为什么要 Rebase + +Rebase 是在使用反向代理的情况下,解决前端页面加载所依赖资源时如何计算资源路径的问题。 + +要完整显示一个前端页面,浏览器除了从服务器加载该页面本身的 html 文件之外,还需要加载一系列该文件引用的资源文件,甚至被引用资源文件引用的其他的资源文件。在使用代理的情况下,正常加载页面本身的 html 文件(即入口文件)通常不会出现问题,但是,被引用的资源文件则不一定能正确加载到。因为,代理服务器很有可能会改变页面所在的上下文。 + +以 [导入 example](/guide/example/import.html) 中导入的 Eureka 服务为例,直接通过域名的方式访问该服务的 URL 为: +

    + + http://cloud-eureka.example.demo.eip.work/ + + + 您所使用的 URL 可能与这个不一样 + +

    + +访问该 URL 后,所得的 html 代码如下所示: +> 为了节省篇幅,下面只截取了一些代码片段。 + +``` html {3,6,11,14} + + + + + Eureka + + + +... +
  • + Last 1000 since startup +
  • +... + +... + + +``` + +上述代码中: +* 第3行代码定义了文档的 base 路径 `/`,该文档应用的所有资源(如果以相对路径的方式引用)都将基于此 base 路径进行计算,例如: + * 第6行的 `eureka/css/wro.css`,进行路径计算之后,结果是 `http://cloud-eureka.example.demo.eip.work/eureka/css/wro.css`; + * 第14行的 `eureka/js/wro.js`,进行路径计算之后,结果是 `http://cloud-eureka.example.demo.eip.work/eureka/js/wro.j`; +* 以 `/` 开头的路径,仍然从根路径开始计算,例如: + * 第11行的 `/lastn`,进行路径计算之后,结果是 `http://cloud-eureka.example.demo.eip.work/lastn`; + +但是,如果您使用 KuboardProxy 访问此页面时,页面的路径是 `https://kuboard.demo.eip.work/proxy/http/example/web-example/:/80/`,在这种情况下,如果代理响应的结果和上面的代码保持一致,以上述第6行代码为例,由于第三行 base 路径仍然为 `/`,则 `eureka/css/wro.css`,进行路径计算之后,结果是 `http://cloud-eureka.example.demo.eip.work/eureka/css/wro.css`;由于代理为 Web 应用增加了 `/proxy/http/example/web-example/:/80/` 作为上下文,此时 `http://cloud-eureka.example.demo.eip.work/eureka/css/wro.css` 这样的 URL 是访问不到期望的资源的。以此类推,其他这种相对资源也都将不能正常加载。 + +> 如果使用 kubectl proxy 访问,页面路径是 `http://localhost:8001/api/v1/namespaces/example/services/http:cloud-eureka:9200/proxy` + +对于这种情况,为了使网页能够正常工作,Kuboard Proxy、kubectl proxy 都对代理的响应结果做了 **Rebase**,即修改 base 的路径,修改 `/` 的路径。Rebase 之后,浏览器通过 Kuboard Proxy 实际获取到的 HTML 代码如下所示,这时,该网页所有依赖的资源就可以正常加载,网页也就可以正常工作了: + +``` html {3,6,11,14} + + + + + Eureka + + + +... +
  • + Last 1000 since startup +
  • +... + +... + + +``` + +## Kuboard Proxy 怎样做 Rebase + +Kuboard Proxy 针对 `text/html` / `application/javascript` 这两种类型的响应内容做了如下形式的文本替换: +| 替换前 | 替换后 | kubectl proxy | +|--------|-------|---------------| +|`src="/` | `src="/proxy/http/example/web-example/:/80/` | 替换 | +|`src=/` | `src=/proxy/http/example/web-example/:/80/` | 替换 | +|`href="/` | `href="/proxy/http/example/web-example/:/80/` | 替换 | +|`href=/` | `href=/proxy/http/example/web-example/:/80/` | 替换 | +|`baseURL="/` | `baseURL="/proxy/http/example/web-example/:/80/` | 不替换 | +|`baseURL=/` | `baseURL=/proxy/http/example/web-example/:/80/` | 不替换 | + +> * kubectl proxy 只替换了 `text/html` 类型响应中的 `src="/`、`src=/`、`href="/`、`href=/`; +> * Kuboard Proxy 额外处理了 `application/javascript` 类型的响应,并且替换了 `baseURL="/`、和 `baseURL=/`,以应对使用 [axios](http://www.axios-js.com/) 作为 http 库的前端网站,例如 [导入 example](/guide/example/import.html) 中导入的 web-example 服务的页面,在 Kuboard Proxy 中就可以正常通过 Restful 接口获取到动态数据,而如果通过 kubectl proxy,则获取不到的动态数据; + +::: warning 风险 +由于对 `text/html` / `application/javascript` 这两种类型的响应做了简单的纯文本搜索和替换,不排除可能会发生不恰当替换的风险,例如: +* html 页面中的出现了文本内容(不是 html 标签) `src="/`、`href=/` 等,该内容也将被替换掉; +* 如果您通过 KuboardProxy 进行 Restful 接口调用,不存在此风险,因为 Restful 接口的响应类型是 `application/json` +::: + +## Kuboard Proxy 禁用 Rebase + +在少数情况下,您可能需要禁用 Rebase: +* 您的 Web 页面非常好地处理了部署在不同 web 上下文时的情况,例如:[通过 Kuboard-Proxy 实现 Kuboard 与 Grafana 的单点登录](./auth-proxy.html)。 + +禁用 Rebase 的步骤,请参考 [KuboardProxy 代理配置](./#代理配置)