文档

通过 Goland 部署和升级插件

更新时间:
一键部署

前提条件

版本要求

  • 已安装 GoLand 2021.2 及以上版本。

  • 已安装 mosn-intellij 1.0.4 及以上版本。

    安装步骤如下:

    1. 在 Goland 首页单击 Plugins

    2. 选择 Installed > install plugin from disk,然后选择 >= mosn-intellij-1.0.4.zip

      image..png
    3. 重启 GoLand。

  • 控制面部署版本要求:

    升级 Cloudmesh 至 1.15.0 及以上版本(2023 年 7 月发布)。

    说明

    当前版本有部分功能无法使用,升级之后可以使用全部功能。

插件项目配置

插件项目需将etc/ant/env_conf中包含的配置改成正确环境信息:

  • SOFA_INSTANCE_ID:连接的租户 Instance ID。中间件默认 000001。

  • APPNAME:容器代理的 App 名称。

  • SOFA_ANTVIP_ENDPOINT:连接测试环境的 AntVIP。

  • SOFA_ACCESS_KEY:连接测试环境 Accesskey ID (测试环境默认不鉴权,无需修改)。

  • SOFA_SECRET_KEY:连接测试环境 Accesskey Secret(测试环境默认不鉴权,无需修改)。

网络要求

  • 如果研发环境和控制面网络直接互通,无需额外配置。

  • 如果研发网络和控制面是网络隔离,但是可以通过 K8s 的转发机制进行交互,您可以通过以下步骤配置,在 GoLand 中直接部署和升级。

    1. 开启本地 7777 端口,然后转发到测试环境 MeshServer 的 7777 端口。

      kubectl --kubeconfig <kube config> -n <dsr namespace> port-forward sts/meshserver 7777:7777
    2. 在插件项目application.properties配置本地直连。

      mesh.server.address=127.0.0.1:7777

    以访问 ack 环境为例,kubeconfig 本地文件假设为ack,命令如下:

    kubectl --kubeconfig ack -n sofamesh port-forward sts/meshserver 7777:7777

项目无缝升级

在低于 mosn-intellij 1.0.4 版本创建的项目,需要一键刷新升级至最新脚手架功能集:

  • 拉齐 makefile。

  • 拉齐 MOSN 的编译脚本和启动脚本。

  • 创建插件版本信息。

  • 创建项目属性文件application.properties

升级方式如下:

  1. 右键单击项目任意目录。

  2. 在菜单栏选择 Mosn Go Plugin > Refresh

    image..png

    执行后,老的脚手架工程,会自动刷新工程结构。如下图所示:

    image..png

部署插件

步骤一:编译插件

单插件编译

在 Goland 中完成编译,支持白屏化或者快捷键操作(Windows 系统暂不支持插件开发)。支持使用快捷键编译单插件(macOS 系统使用image.png;Linux 系统使用 Alt+Ctrl+win+B),也支持在右键菜单中单击对应选项(选中 configs 或者 plugins 节点内单个文件夹名称)。步骤如下:

  1. plugins 中选中具体插件名称。

    例如 plugins/codecs/brpc 插件。

  2. 通过以下方式触发 GoLand 插件编译:

    • (推荐)在 plugins/codecs/bprc 节点中按下快捷键(macOS 系统使用image.png;Linux 系统使用 Alt+Ctrl+win+B),自动触发 GoLand 插件编译。

      说明

      后续示例均以快捷键操作为例。

      image.png
    • 右键单击 plugins/codecs/bprc 节点,然后选择 Mosn Go Plugin > Compile brpc with dependency...。

      image.png

    插件编译后:

    • 会自动构建插件类型前缀_插件名作为终端显示编译信息。

    • 输出文件存放在 build 文件夹中,包含插件的编译 so。

说明

协议插件编译也支持关联自动编译拦截器、协议转换插件(提升本地研发效率),具体配置如下:

  1. application.properties中分别添加key, ${protocol}为具体协议名。

    codec.${protocol}.filter=
    codec.${protocol}.transcoder=
  2. plugins/codecs/bprc 节点中按下快捷键(macOS 系统使用image.png;Linux 系统使用 Alt+Ctrl+win+B)后,自动触发 GoLand 插件编译。

    image.png

多插件编译

支持在 plugins 子目录多个插件同时编译,尤其在多协议插件开发更为便捷(包括更快编译速度)。支持使用快捷键编译同类型多个插件(macOS 系统使用image.png;Linux 系统使用 Alt+Ctrl+win+B),也支持在右键菜单中单击对应选项(选中 configs 或者 plugins 节点内直接子节点文件夹名称)。操作步骤如下:

  1. plugins 中选中插件类型(codecs、stream_filters、transcoders...)节点。

    例如 plugins/codecs 协议类型插件。

  2. plugins/codecs 节点中按下快捷键,自动触发 GoLand 多个同类型插件编译。

    所有协议插件并行编译。

    image..png

步骤二:打包插件

打包单插件

当源码测试完成后,可以通过 GoLand 打包成插件单元,用于分发多环境部署。支持使用快捷键打包单插件(macOS 系统使用image.png;Linux 系统使用 Alt+Ctrl+win+P),也支持在右键菜单中单击对应选项 ( 选中 configs 或者 plugins 节点内单个插件名称 )。操作步骤如下:

  1. plugins 中选中具体插件名称。

    例如 plugins/codecs/brpc 插件。

  2. plugins/codecs/bprc 节点中按下快捷键,自动触发 Goland 插件打包。

    • 会自动构建插件类型前缀_插件名作为终端显示打包信息。

    • 在 macOS 机器上,会自动触发 amd64 架构编译,然后再打包。

    • 输出文件存放在build/target中,包含插件 zip 包。

    image.png

打包多插件

支持在 plugins 子目录对多个插件同时打包。支持使用快捷键打包同类型多个插件(macOS 系统使用image.png;Linux 系统使用 Alt+Ctrl+win+P),也支持在右键菜单中单击对应选项(选中 configs 或者 plugins 节点内直接子节点文件夹名称)。操作步骤如下:

  1. plugins 中选中插件类型(codecs、stream_filters、transcoders...)节点。

    例如 plugins/codecs 协议类型插件。

  2. plugins/codecs 节点中按下快捷键后,自动触发 GoLand 多个同类型插件打包。

    • 会自动构建插件类型前缀_插件名作为终端显示打包信息。

    • 在 macOS 机器上,会自动触发 amd64 架构编译,然后再打包。

    • 输出文件存放在build/target中,包含插件 zip 包。

    image.png

步骤三:部署插件

部署单插件

当插件完成本地测试,您可以将插件单元包通过 GoLand 上传到服务网格控制台,方便后续 Sidecar 注入配置。支持使用快捷键部署单插件(macOS 系统使用image..png;Linux 系统使用 Alt+Ctrl+win+D),也支持在右键菜单中单击对应选项 ( 选中 configs 或者 plugins 节点内单个插件名称 )。操作步骤如下:

  1. configs 中选中具体插件名称。

    例如 configs/codecs 插件。

  2. configs/codecs 节点按下快捷键后,自动触发 GoLand 插件部署。

    • 会自动构建插件类型前缀_插件名作为终端显示打包信息。

    • 在 macOS 机器上,会自动触发 amd64 架构编译,然后再打包。

    • 文件会自动部署到服务网格控制台。

    image..png

    提示部署完成后,可在服务网格控制台查看插件信息:

    image..png
说明

通过 GoLand 部署,省去了手工上传插件包的步骤,简化研发步骤。部署上传后,可以在 Sidecar 注入规则中关联插件。更多信息请参见 HTTP 插件的上传和部署 中,Sidecar 注入规则关联插件部分介绍。

部署多插件

支持在 plugins 子目录对多个插件同时部署。支持使用快捷键部署同类型多个插件(macOS 系统使用image..png;Linux 系统使用 Alt+Ctrl+win+D),也支持在右键菜单中单击对应选项(选中 configs 或者 plugins 节点内直接子节点文件夹名称)。操作步骤如下:

  1. plugins 中选中插件类型(codecs、stream_filters、transcoders...)节点。

    例如 configs/codecs 协议类型插件。

  2. configs/codecs 节点中按下快捷键,自动触发 GoLand 多个同类型插件部署。

    • 会自动构建插件类型前缀_插件名作为终端显示打包信息。

    • 在 macOS 机器上,会自动触发 amd64 架构编译,然后再打包。

    • 文件会自动部署到服务网格控制台。

    image..png

    提示部署完成后,可在服务网格控制台查看插件信息:

    image..png

升级插件

当插件和 Sidecar 运行时因为 API 变更导致不兼容修改时,可以通过插件升级机制自动将插件的依赖和 Sidecar 运行时版本对齐,并自动编译和上传部署,简化插件升级。

工作原理

  • GoLand 会根据用户选择的 Sidecar 注入规则(包含了使用的所有插件)和需要升级的 Sidecar 容器镜像,在本地获取远程镜像,然后扫描本地项目和 Sidecar 容器镜像的共同依赖,以升级 Sidecar 容器镜像依赖为准,将本地插件依赖做原地更新,并自动触发编译、打包和新插件单元上传部署。

  • GoLand 根据选择的注入规则,感知到正在使用的插件,和本地项目做比对。如果插件属于本项目,会触发升级和部署。如果插件不属于本项目,在部署后会提示缺少的插件。

  • 为了减少不必要的升级次数,在同一个项目内包含全量插件,可以全量升级插件。

前提条件

  • 有正在用的 Sidecar 插件注入规则(关联了插件),并且规则是开启状态。

  • 在开始升级前,需要完成以下步骤:

    1. 创建需要升级的新 Sidecar 镜像和版本。

      在服务网格控制台 Sidecar 管理 > Sidecar 版本管理 页面创建需要升级的新 Sidecar 镜像和版本。

    2. 在 GoLand 控制面板(在项目根目录右键单击 Mosn Go Plugin > Desploy)选择待升级的 Sidecar 注入规则和需要升级的新 Sidecar 镜像和版本。

    3. 升级 Sidecar 注入规则。

      触发升级成功后,在服务网格控制台找到待升级的 Sidecar 注入规则,然后单击 升级,生成新的注入规则。您需要在新规则内选择和 GoLand 控制面板一致的新 Sidecar 镜像和版本,并确认自动关联的插件升级信息。

    4. 重新注入 Sidecar。

      在服务网格控制台的 服务目录 页面,单击应用名进入应用详情。如果已经注入 Sidecar,单击 下线 后,再单击 注入,应用会使用新版本的插件。

升级步骤

示例说明如下:

  • 假设服务网格控制台 bRPC 协议插件关联了协议转换插件 brpc2ehttp。

    如下图所示:

    image..png
  • brpc2ehttp 协议转换插件包含转换规则(规则内容任意,仅供测试)。

    如下图所示:

    image..png
  • 在 Sidecar 注入规则中引用协议插件brpc 1.0.0-dev

测试将插件brpc1.0.0-dev升级到brpc1.0.1-dev版本,操作步骤如下:

  1. 新增 Sidecar 版本。

    在服务网格控制台的 Sidecar 版本管理 页面新增 Sidecar 版本,填写必要的镜像和依赖版本信息。

    依赖版本一般项目交付会包含。

    image..png
  2. 升级插件。

    1. 在 GoLand 控制面板的项目根目录,右键选择 Mosn Go Plugin > Deploy,会弹出升级面板。

      Mesh Server Address 根据步骤 1 配置的 ACVIP 地址从注册中心自动获取,或者显示直连本地 127.0.0.1 的转发地址。

    2. 选择正确的注入规则(用于获取在用的插件)、指定升级后的插件版本以及正确的待升级的 Sidecar 镜像。

      GoLand 在本地不存在该镜像时,会首先拉取镜像,然后执行本地依赖升级和编译、打包操作。

      说明

      如果环境无法拉取对应镜像时,可以通过docker savedocker load命令将镜像装载到本地,并且通过docker tag命令将镜像名称修改为和升级的镜像名称一致。

      image..png

      插件已经全量部署上传后,会提示所有插件已成功部署。

      image..png
  3. 关联确认插件。

    在服务网格控制台确认新版本的插件都已上传,并且关联了正确关系后(包括插件配置),需要手动触发升级规则,将新版本的插件做一次关联确认。

    1. 在服务网格控制台的 Sidecar 版本管理 页面,单击旧插件的 Sidecar 注入规则右侧的 升级

      需确认和 GoLand 上传选择的 inject rule 是同一个。

      image..png
    2. 在配置参数步骤中,选择升级后的 Sidecar 版本(包含镜像)。

      需确认和 GoLand 上传选择的 image 是同一个。

      image..png
    3. 单击 保存

      会提示关闭旧的注入规则,开启新的注入规则。

      image..png
    4. 重新注入 Sidecar。

      如果需要插件生效,您需要在 服务目录 页面单击应用名进入应用详情。如果已经注入 Sidecar,单击 下线 后,再单击 注入,应用会使用新版本的插件。

      image..png