首页 / 平台管理 / 应用商店管理 / Operators / 上架/升级/下架 Operator

上架/升级/下架 Operator

OperatorHub 中预置了平台自研和平台认证的 Operator，可满足数据库、监控以及存储等使用场景。通常，预置的 Operator 生命周期会随着平台版本升级而变化，但在平台版本升级间隙，Operator 提供者也许已经对 Operator 的功能进行迭代。此外，随着 Operator 的普及，开源社区或研发者自己也提供了许多功能强大的 Operator 来帮助开发和管理中间件或应用。

为满足与平台版本变更解耦，以及扩展平台预置 Operator 能力的诉求，我们提供了 Operator 上架、升级，及下架方案。

方案概述

本方案用于为平台运维人员、应用开发人员提供 Operator 上架、升级，及下架相关指导。

场景	说明
Operator 上架	除了预置的 Operator 外，支持将用户自研或开源社区的 Operator 添加至 OperatorHub 并使用。平台会对 Operator 进行格式检查和校验（包括镜像、属性字段、版本等），确保待上架的 Operator 符合要求后，开发人员可正常使用 Operator。
Operator 升级	随着 Operator 可管理应用的版本更新或者功能迭代，Operator 本身也需要进行生命周期流转。升级 Operator 指将新版本 Operator 添加至 OperatorHub，以对应使用新功能并保障环境安全。
Operator 下架	将无效或不再支持的 Operator 从 OperatorHub 中移除，帮助减轻后期维护和支持工作。在此之前已通过该 Operator 创建的实例还可正常运行，但无法再进行更新或升级。

名词解释

名词	说明
Bundle 镜像	Operator 上架、升级，及下架方案通过 Bundle 镜像实现。Bundle 镜像需与 Operator 研发者获取，其中包含了 CSV（ClusterServiceVersion）、CRD（CustomResourceDefinitions）以及其他定义了 Operator 所需配置的一系列 YAML 文件。Bundle 镜像仅适用于 Operator 上架、升级，及下架，无法用于直接运行 Operator。

操作流程

根据 OperatorHub 页面展示需求配置供应商类型字段，并获取 Operator Bundle 和运行时镜像。
将 Bundle 和运行时镜像推送至目标环境使用的镜像仓库。通常使用 docker 操作， violet 工具提供了更简化的操作步骤和更完善的操作流程。

说明：研发环境与目标环境的镜像仓库一致时，可忽略此步骤。
1. 生成 Operator 包的 manifest 描述文件，文件包含 Operator 架构、运行时镜像、页面显示名称、icon、链接和关键字等信息。
2. 基于 manifest 将依赖的镜像和 manifest 文件本身打包。
3. 在目标环境中使用 violet 将包推送到私有镜像仓库。
创建或更新 Artifact 资源，在 OperatorHub 页面上架、升级或下架 Operator。

设置供应商类型

为了确保页面能够正确的显示供应商类型，需在 Operator CSV 文件的 metadata.annotations 中设置供应商类型。

供应商类型	provider-type	provider	provider-url
用户上传	custom	填入开发者名称	填入开发者提供的网址
开源社区	community	填入开源社区名称	填入开源社区网址
平台认证	certified	填入平台或第三方名称	填入第三方网址
平台自研	platform	填入平台	填入 OperatorHub 帮助文档网址

说明：

provider-type 为空或非以上标准字段时，均显示为 用户上传。
provider 为空时显示为 -。
provider-url 为空时不支持跳转。如需跳转至 provider 对应的官网地址，请填写 provider-url。

示例如下。

# The csv yaml file in bundle
apiVersion: operators.coreos.com/v1alpha1
kind: ClusterServiceVersion
metadata:
    annotations:
        provider: '{"zh" : "平台","en" : "platform"}'    # 供应商名称
        provider-type: certified    # 供应商类型
        provider-url: http://provider-url    # 供应商链接
    name: PostgreSQL-operator.vX.Y.Z
    namespace: placeholder
spec:{}

传递 Operator 包

当您的目标环境不能直接访问当前研发使用的镜像仓库时，可使用 violet 工具完成 Bundle 和运行时镜像的传递工作。

注意事项

当镜像仓库使用 http 连接时，需要指定 --plain。
当镜像仓库使用 https 连接时，需要传递 username 和 password 参数，详情可通过 -h 获取。

操作步骤

安装 violet 工具。

export ARCH=$(case $(arch) in x86_64) echo "amd64" ;; *) echo $(arch) ;;esac)
curl https://build-nexus.alauda.cn/repository/acp/violet/violet_linux_"${ARCH}" -o violet
mv violet /usr/bin/
chmod a+x /usr/bin/violet

使用 violet 工具生成新的 Operator 包。

方法一：基于现有的 Artifact 创建包

基于现有的 Artifact 创建新的 Operator 包。

violet create topolvm --artifact registry.alauda.cn:60080/acp/topolvm-operator-bundle:v3.11.0 --plain    
# registry.alauda.cn:60080 仓库中需存在 topolvm-operator-bundle:v3.11.0 镜像  

# 回显示例
...
created package topolvm    # 创建成功
...

cd topolvm    # 进入自动生成的 topolvm 文件夹

查看自动解析生成的 manifest 清单文件。

提示：下述示例中包含了 manifest 清单文件需要的字段，可以作为方法二中手动编辑时的参照。

cat manifest.yaml  

# 回显示例
apiVersion: app.alauda.cn/v1beta1
kind: PackageManifest
metadata:
  creationTimestamp: null
  name: topolvm-operator.v2.3.0
spec:
  artifact: registry.alauda.cn:60080/acp/topolvm-operator-bundle:v3.11.0
  info:
    displayName: NativeStor
    icon: PHN2ZyBpxxxx # base64icon #
    keywords:
    - LocalStorage
    - Kubernetes
    - Topolvm
    - Storage
    links:
    - name: Topolvm
      url: https://github.com/alauda/topolvm
    - name: Topolvm-operator
      url: https://github.com/alauda/topolvm-operator
  relatedImages:
  - build-harbor.alauda.cn/acp/topolvm-operator:v3.11.0
  - build-harbor.alauda.cn/acp/topolvm:v3.11.0
  - build-harbor.alauda.cn/3rdparty/k8scsi/csi-provisioner:v3.0.0
  - build-harbor.alauda.cn/3rdparty/k8scsi/csi-provisioner:v2.1.1
  - build-harbor.alauda.cn/3rdparty/k8scsi/csi-resizer:v1.3.0
  - build-harbor.alauda.cn/3rdparty/k8scsi/csi-attacher:v3.3.0
  - build-harbor.alauda.cn/3rdparty/k8scsi/csi-snapshotter:v3.0.2
  - build-harbor.alauda.cn/3rdparty/k8scsi/csi-node-driver-registrar:v2.3.0
  - build-harbor.alauda.cn/3rdparty/k8scsi/livenessprobe:v2.4.0
  type: bundle
  version: 2.3.0

方法二：创建包工作目录后手动编辑

创建空包。

violet create topolvm

cd topolvm # 进入自动生成的 topolvm 文件夹

查看工具生成的默认 manifest 文件。请根据使用需求手动编辑 manifest 文件，修正 name、spec.info、spec.relatedImages 等内容，使得最终编辑结果与方法一中基于 Artifact 生成的文件内容基本一致。

cat manifest.yaml 

# 回显示例
apiVersion: app.alauda.cn/v1beta1
kind: PackageManifest
metadata:
  creationTimestamp: null
  name: nginx
spec:
  arch:
  - linux/amd64
  info:
    displayName: nginx
    icon: ""
    keywords:
    - nginx
    links:
    - name: nginx
      url: example.com
  relatedImages:
  - nginx:latest
  type: chart
  version: v0.1.0

校验包文件。

violet lint .

# 正常示例
lint ok

# 如果 manifest.yaml 文件存在问题则会报错
# 异常示例
WARN[0000] spec.artifact field cannot be empty
lint failed

执行打包操作，将所有的镜像以及 manifest 文件打包成一个 .tgz 文件。

cd topolvm # 进入上一步操作的文件夹内

violet package . --plain  # 执行打包操作

# 回显示例
...
Successfully packaged and saved it to: /root/topolvm/topolvm-operator.v2.3.0.tgz
...

将上一步中生成的 .tgz 文件拷贝并推送至目标环境的镜像仓库。

violet push topolvm-operator.v2.3.0.tgz --plain  --dst-repo 192.168.41.100:60080  # 请根据目标环境实际情况替换 192.168.41.100

# 回显示例
...
You can create PackageManifest into kubernetes cluster
...

安装 kubectl-artifact 插件

kubectl-artifact 插件可以方便快速的完成 Artifact 相关操作，上架、升级均依赖此插件，需要在操作节点（任一 Master）安装。

# metis pod 带了 kubectl-artifact 二进制文件
export METISPOD=$(kubectl get pods -n cpaas-system | grep metis | awk '{print $1}' | head -n 1)
    
# 将二进制文件复制到 shell 当前目录
kubectl cp -n cpaas-system ${METISPOD}:kubectl-artifact kubectl-artifact
    
# 增加可执行权限
chmod a+x kubectl-artifact
    
# 将文件移动到 kubectl 命令所在目录，如果遇到权限不足，请使用 root 或联系机器管理员
mv kubectl-artifact $(dirname $(which kubectl))
    
# 检查是否安装成功，该命令的输出中应该包含 kubectl-artifact 
kubectl plugin list

上架 Operator

上架前，请手动 docker pull 部分依赖镜像，确认镜像能够正常拉取。

准备工作

确认镜像仓库是否需要镜像拉取凭据。若需要，需获取凭据（保密字典）名称。

kubectl get library -n cpaas-system platform -o yaml | grep -A3 imagePullSecrets

# 不需要凭据的示例，说明镜像仓库未开启 Basic 认证
  imagePullSecrets: []
# 需要凭据的示例，镜像凭据名称类似 global-registry-auth
  imagePullSecrets:
    - global-registry-auth

操作步骤

在 Operator 所在集群的控制节点上，设置环境变量。

注意：环境变量仅作用于当前登录环境。未完成所有操作前，一旦退出，需要重新设置。

export NAME="topolvm-operator"                            # 名称
export DISPLAYNAME="topolvm-operator"                     # 页面展示名称
export VERSION="v2.3.0"                                   # 版本号
export DESCRIPTION="topolvm operator bundle images"       # 描述
export REGISTRY="build-harbor.example.cn"                 # Bundle 镜像所在的仓库地址
export REPOSITORY="acp/topolvm-operator-bundle"           # 仓库项目路径
export SECRETNAME="global-registry-auth"                  # 用于访问镜像仓库的凭据，请根据凭据查询结果填写。若未开启 Basic 认证，设置为 default

创建 Artifact，用于往 OperatorHub 中添加 Operator。

cat << EOF | kubectl create -f -
apiVersion: app.alauda.io/v1alpha1
kind: Artifact
metadata:
  name: ${NAME}
  namespace: cpaas-system
  labels:
    cpaas.io/library: platform
spec:
  artifactVersionSelector:
    matchLabels:
      cpaas.io/artifact-version: ${NAME}
  displayName: ${DISPLAYNAME}
  description: ${DESCRIPTION}
  registry: ${REGISTRY}
  repository:  ${REPOSITORY}
  type: bundle
  present: true
  imagePullSecrets:
    - ${SECRETNAME}
EOF

创建 ArtifactVersion。

kubectl artifact createVersion --artifact ${NAME}  --tag="${VERSION}" --namespace cpaas-system

检查 Artifact 对应的 ArtifactVersion 资源。

kubectl get artifactversion -A | grep  ${NAME}

当同时查得 Present 和 Success 字段时，说明 Operator 添加成功。

# 回显示例
cpaas-system   topolvm-operator.v1.0.0                 topolvm-operator                 Present   Success

重启 catalog pod 来刷新 packagemanifests（对应 OperatorHub 界面），并检查其中内容是否与步骤 1 中配置一致。

kubectl get pod -A |grep catalog| awk '{print "kubectl delete pod -n ", $1, $2}' | bash

kubectl get packagemanifests -n cpaas-system ${NAME} -o yaml    # 请根据实际情况修改 namespace

等待约 1 分钟左右，登录平台，在 应用商店管理 > Operators 界面可找到该 Operator。
尝试部署 Operator 并创建实例。
- 若都能正常操作，说明 Operator 上架成功。
- 否则，可参考故障处理排查并修复。

故障处理

问题描述：Operator 上架失败，经查发现 artifactversion 中记录的 Operator 版本重复。

kubectl get artifactversion -A |grep ${NAME} # 可以看到两个版本

kubectl describe artifactversion topolvm-operator -n cpaas-system # 提示 pending Reson=AlreadyAdd

解决方案：删除多余 Operator。

kubectl delete artifactversion {旧的 artifactversion} -n cpaas-system

kubectl get pod -A |grep olm| awk '{print "kubectl delete pod -n ", $1, $2}' | bash

kubectl get pod -A | grep ${NAME}

升级 Operator

准备工作

使用 violet 打包新版本 Operator 的 Bundle 及依赖镜像，并推送至目标环境的镜像仓库。

操作步骤

在 Operator 所在集群的控制节点上，查看 Artifact 资源的名称。
```
kubectl get artifact -n cpaas-system
```

设置环境变量。

export NAME="topolvm-operator"         # Artifact 资源的名称
export VERSION="v2.3.1"                # 升级后的版本号

创建 ArtifactVersion。

kubectl artifact createVersion --artifact ${NAME}  --tag="${VERSION}" --namespace cpaas-system

检查是否创建了相应的 ArtifactVersion 资源。
```
kubectl get artifactversion -A | grep ${NAME}
```

重建 catalog-operator。

kubectl delete pods -n cpaas-system -l app=catalog-operator

等待约 1 分钟左右，登录平台并选择 应用商店管理 > Operators。
- 如果 Operator 使用 自动升级策略，可看到升级相关提示，耐心等待即可。
- 如果 Operator 使用 手动升级策略，请按提示完成后续操作。

下架 Operator

在 Operator 所在集群的控制节点上，设置环境变量。
```
export NAME="topolvm-operator"                            # 名称
```
修改 Operator 的展示状态：将 spec.present 取值从 true 改成 false。
```
kubectl edit -n cpaas-system artifact ${NAME}
```
等待约 1 分钟左右，登录平台，在 应用商店管理 > Operators 界面已找不到该 Operator。

提示：下架 Operator 后，由于已无法在 OperatorHub 中运维通过该 Operator 创建的实例。建议按需回收实例以释放相关资源。