上架软件包

平台提供了一个命令行工具 violet，用于将从 Marketplace 的 Customer Portal 中下载的软件包上架到平台。

violet 支持上架以下类型的软件包：

Operator
Cluster Plugin
Helm Chart

当 Cluster Plugins 或 OperatorHub 中某个软件包的状态显示为 Absent 时，需要使用此工具上传相应的软件包。

violet 的上架过程主要包括以下步骤：

从软件包中提取并获取信息
将镜像推送到镜像仓库
在平台上创建 Artifact 和 ArtifactVersion 资源

下载工具

登录到 Customer Portal，进入 Downloads 页面，然后单击 CLI Tools。下载与您的操作系统和架构匹配的二进制文件。

下载后，将工具安装到您的服务器或 PC 上。

对于 Linux 或 macOS

对于非 root 用户：

# Linux x86
sudo mv -f violet_linux_amd64 /usr/local/bin/violet && sudo chmod +x /usr/local/bin/violet
# Linux ARM
sudo mv -f violet_linux_arm64 /usr/local/bin/violet && sudo chmod +x /usr/local/bin/violet
# macOS x86
sudo mv -f violet_darwin_amd64 /usr/local/bin/violet && sudo chmod +x /usr/local/bin/violet
# macOS ARM
sudo mv -f violet_darwin_arm64 /usr/local/bin/violet && sudo chmod +x /usr/local/bin/violet

对于 root 用户：

# Linux x86
mv -f violet_linux_amd64 /usr/bin/violet && chmod +x /usr/bin/violet
# Linux ARM
mv -f violet_linux_arm64 /usr/bin/violet && chmod +x /usr/bin/violet
# macOS x86
mv -f violet_darwin_amd64 /usr/bin/violet && chmod +x /usr/bin/violet
# macOS ARM
mv -f violet_darwin_arm64 /usr/bin/violet && chmod +x /usr/bin/violet

对于 Windows

下载文件并将其重命名为 violet.exe，或者使用 PowerShell 重命名：
# Windows x86 mv -Force violet_windows_amd64.exe violet.exe
在 PowerShell 中运行该工具。

注意：如果工具路径未添加到环境变量中，则在运行命令时必须指定完整路径。

前提条件

权限要求

您必须提供有效的平台凭据，可以是用户名和密码，也可以是平台令牌。
账号的 role 属性必须设置为 System，且 role 名称必须为 platform-admin-system。

**注意：**如果您的账号的 role 属性设置为 Custom，则无法使用此工具。

用法

通用参数

多个 violet 命令会接受以下参数。具体用法请参见各命令部分。

平台连接参数

--platform-address <platform access URL>     # The access URL of the platform, e.g., "https://example.com"
--platform-username <platform user>          # The username of the platform user
--platform-password <platform password>      # The password of the platform user
--platform-token <platform token>            # The platform access token; cannot be used together with username/password
--client-id <OAuth client ID>                # OAuth client ID for username/password login; ignored when --platform-token is set. Override "alauda-auth" only for custom OAuth clients.

要创建或管理平台令牌，请登录平台 Web Console，打开 Profile > API Tokens，并创建一个具有合适过期时间的令牌。有关详细信息，请参见 API 认证。

镜像仓库参数

--dest-repo <image repository address>       # Specify the destination image repository address, e.g., "harbor.demo.io"
--username <registry user>                   # The username of the specified image registry
--password <registry password>               # The password of the specified image registry
--no-auth                                    # Specify if the image registry does not require authentication
--plain                                      # Specify if the image registry uses HTTP instead of HTTPS

WARNING

IPv6 地址限制

对于 --platform-address 和 --dest-repo 参数：

如果使用的是 IP 地址（而不是域名），则不支持 IPv6 格式
仅支持 IPv4 地址或域名

violet show

在上架软件包之前，请使用 violet show 命令预览其详细信息。

violet show topolvm-operator.v2.3.0.tgz
Name: NativeStor
Type: bundle
Arch: [linux/amd64]
Version: 2.3.0

violet show topolvm-operator.v2.3.0.tgz --all
Name: NativeStor
Type: bundle
Arch: []
Version: 2.3.0
Artifact: harbor.demo.io/acp/topolvm-operator-bundle:v3.11.0
RelateImages: [harbor.demo.io/acp/topolvm-operator:v3.11.0 harbor.demo.io/acp/topolvm:v3.11.0 harbor.demo.io/3rdparty/k8scsi/csi-provisioner:v3.00 ...]

violet list

升级平台时，使用 violet list 列出已安装的扩展，并将结果导出到 YAML 文件。生成的文件随后可以上传到 Alauda Cloud，以便下载所需的扩展软件包。

violet list 涵盖生命周期为 Aligned 或 Agnostic 的扩展。Core 插件会随集群升级而升级，不通过 violet list 管理。

该命令会列出以下应用类型：

ModulePlugin — 生命周期类型为 aligned 或 agnostic 的 Cluster Plugin。
OperatorBundle — 已安装的 Operator。
Chart — 由 chart 引用创建的 Helm Chart 应用。

默认情况下，该命令会将 YAML 内容打印到 stdout，并将其写入当前目录下的 apps.yaml。

violet list \
  --platform-address "https://example.com" \
  --platform-username "<platform_user>" \
  --platform-password "<platform_password>"

您也可以使用平台令牌进行认证，而不是使用用户名和密码：

violet list \
  --platform-address "https://example.com" \
  --platform-token "<platform_token>"

要仅导出安装在特定集群中的应用，请指定多个以逗号分隔的集群名称：

violet list \
  --platform-address "https://example.com" \
  --platform-token "<platform_token>" \
  --clusters "global,region1" \
  --output-file "./apps.yaml"

示例输出：

applications:
  topolvm-operator:
    displayName: NativeStor
    type: OperatorBundle
    installed:
      - clusterName: global
        version: 2.3.0
  log-center:
    displayName: Log Center
    type: ModulePlugin
    installed:
      - clusterName: region1
        version: v1.2.0

可选标志

--output-file <output file>                  # The path of the output plugin list file

关于平台连接参数（--platform-address、--platform-username、--platform-password、--platform-token、--client-id），请参见通用参数。

violet gc

使用 violet gc 清理生命周期为 Aligned 或 Agnostic 的未安装 Operator 和 Cluster Plugin 资源。该命令会删除已不再安装或已不再匹配已安装版本的资源。

该命令可以删除以下资源类型：

Artifact — 已卸载 Operator 的 Artifact。
ArtifactVersion — 已安装 Operator 的旧 ArtifactVersion。会保留当前安装的 CSV 或版本。
ModulePlugin — 未安装在任何集群中的 Cluster Plugin。
ModuleConfig — 过时的 Cluster Plugin 配置记录。

violet gc 通过检查 global 集群中的 OperatorView 和 ModulePluginView 记录来确定清理候选项。

DANGER

violet gc 会从 global 集群中删除资源，并且不提供 dry-run 模式或撤销操作。仅应在已记录的维护窗口期间运行，并在使用 --clusters 之前确认目标集群。

默认情况下，该命令会扫描平台用户可见的所有集群，并打印已删除资源的摘要。

violet gc \
  --platform-address "https://example.com" \
  --platform-username "<platform_user>" \
  --platform-password "<platform_password>"

您也可以使用平台令牌进行认证，而不是使用用户名和密码：

violet gc \
  --platform-address "https://example.com" \
  --platform-token "<platform_token>"

要仅清理与特定集群相关的资源，请指定多个以逗号分隔的集群名称：

violet gc \
  --platform-address "https://example.com" \
  --platform-token "<platform_token>" \
  --clusters "global,region1"

示例输出：

GC Summary:
TYPE                 NAME                                               CLUSTER
------------------------------------------------------------------------------------------
Artifact             opensearch-operator                                region1
ArtifactVersion      opensearch-operator.v2.8.0                         region1
ModuleConfig         log-center-default                                 global

如果没有删除任何资源，命令会打印：

No resources were deleted.

可选标志

--clusters <cluster names>                   # Limit cleanup to the specified clusters, separated by commas
--debug                                      # Use debug log level

关于平台连接参数（--platform-address、--platform-username、--platform-password、--platform-token、--client-id），请参见通用参数。

violet verify

使用 violet verify 命令在上架之前验证一个或多个软件包的签名。支持两种验证方式：checksum 和 GPG。软件包（.tgz）及其对应的签名文件必须位于同一目录中。

violet verify example.tgz
# or verify all packages within a directory
violet verify packages_dir_name

示例输出：

verify path: /path/to/packages
====== Verification Summary ======
Verified successfully with GPG: 2 file(s)
  - /path/to/packages/redis-operator.tgz
  - /path/to/packages/mysql-operator.tgz

Verified successfully with checksum: 1 file(s)
  - /path/to/packages/nginx-controller.tgz

Verification failed: 1 file(s)
  - /path/to/packages/etcd-operator.tgz

No verification file found: 1 file(s)
  - /path/to/packages/demo-plugin.tgz

说明：

使用 GPG 成功验证 — 列出的文件已使用 GPG 签名文件（.sig 扩展名）成功验证。
使用 checksum 成功验证 — 使用 checksum 文件（例如 .sha256）验证的文件通过了完整性检查。
验证失败 — 列出的文件由于签名不匹配或无效而验证失败。
未找到验证文件 — 在目录中未找到对应的 .sig（GPG）或 checksum 文件。

可选标志

--debug       Use debug log level.
-h, --help    Display help information for the verify command.

violet push

以下示例展示了常见的使用场景。

关于平台连接和镜像仓库参数，请参见通用参数。

对于非交互式使用，建议使用 --platform-token 而不是 --platform-password。请参见通用参数。

可选标志

--clusters <cluster names>                   # Specify target clusters, separated by commas (e.g., region1,region2)
--target-catalog-source <catalog source>     # Target CatalogSource for operators: "platform", "system", or a custom CatalogSource name (default: "platform")
--target-chartrepo <chart repository>        # Target chart repository for Helm charts (default: "public-charts", the platform-managed Helm repository)
--skip-crs                                   # Skip creating custom resources in the cluster
--skip-push                                  # Skip pushing images and artifacts to the registry

当指定 --dest-repo 时，必须提供镜像仓库的认证信息或 --no-auth。

将 Operator 上架到多个集群

violet push opensearch-operator.v3.14.2.tgz \
  --platform-address "https://example.com" \
  --platform-username "<platform_user>" \
  --platform-password "<platform_password>" \
  --clusters region1,region2

INFO

如果未指定 --clusters，则默认将 Operator 上架到 global 集群。\

将 Operator 上架到备用 global 集群

violet push opensearch-operator.v3.14.2.tgz \
  --platform-address "https://<standby-platform-address>" \
  --platform-username "<platform_user>" \
  --platform-password "<platform_password>" \
  --dest-repo "<standby-cluster-VIP>:11443" --username "<registry-username>" --password "<registry-password>"

WARNING

使用 violet 将软件包上架到备用集群时：

必须指定 --dest-repo <备用集群的 VIP addr>
必须将 --platform-address 设置为备用集群的平台访问地址
必须提供备用集群镜像仓库的认证信息或 --no-auth 参数

否则，软件包将被上架到主集群的镜像仓库，导致备用集群无法安装或升级扩展。

上架 Cluster Plugin

violet push plugins-cloudedge-v0.3.16-hybrid.tgz \
  --platform-address "https://example.com" \
  --platform-username "<platform_user>" \
  --platform-password "<platform_password>"

INFO

上架 Cluster Plugin 时无需指定 --clusters 参数，因为平台会根据其亲和性配置自动分发。如果指定了 --clusters，该参数将被忽略。\

将 Helm Chart 上架到 chart 仓库

violet push plugins-cloudedge-v0.3.16-hybrid.tgz \
  --platform-address "https://example.com" \
  --platform-username "<platform_user>" \
  --platform-password "<platform_password>"

INFO

Helm Charts 只能上架到平台提供的默认 public-charts 仓库。\

一次性推送所有软件包

当从 Marketplace 下载了多个软件包时，可以将它们放在同一目录下并一次性全部上架：

violet push <packages_dir_name> \
  --platform-address "https://example.com" \
  --platform-username "<platform_user>" \
  --platform-password "<platform_password>" \
  --clusters "<cluster_name>"

WARNING

当升级目标是global 集群时，可以省略 --clusters 参数，因为默认会上传到 global 集群。

但是，当升级目标是业务集群时，必须指定 --clusters <workload_cluster_name> 参数。

#上架软件包

#目录

#下载工具

#对于 Linux 或 macOS

#对于 Windows

#前提条件

#用法

#通用参数

#平台连接参数

#镜像仓库参数

#violet show

#violet list

#可选标志

#violet gc

#可选标志

#violet verify

#可选标志

#violet push

#可选标志

#将 Operator 上架到多个集群

#将 Operator 上架到备用 global 集群

#上架 Cluster Plugin

#将 Helm Chart 上架到 chart 仓库

#一次性推送所有软件包

上架软件包

目录

下载工具

对于 Linux 或 macOS

对于 Windows

前提条件

用法

通用参数

平台连接参数

镜像仓库参数

violet show

violet list

可选标志

violet gc

可选标志

violet verify

可选标志

violet push

可选标志

将 Operator 上架到多个集群

将 Operator 上架到备用 global 集群

上架 Cluster Plugin

将 Helm Chart 上架到 chart 仓库

一次性推送所有软件包