#Upload Packages

The platform provides a command-line tool violet, which is used to upload packages downloaded from the Marketplace in the Customer Portal to the platform.

violet supports uploading the following types of packages:

• Operator
• Cluster Plugin
• Helm Chart

When the status of a package in Cluster Plugins or OperatorHub is shown as Absent, you need to use this tool to upload the corresponding package.

The upload process of violet mainly includes the following steps:

1. Extract and retrieve information from the package
2. Push images to the image registry
3. Create Artifact and ArtifactVersion resources on the platform

#Download the Tool

Log in to the Customer Portal, navigate to the Downloads page, and click CLI Tools. Download the binary that matches your operating system and architecture.

After downloading, install the tool on your server or PC.

#For Linux or macOS

For non-root users:

# 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

For root users:

# 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

#For Windows

1. Download the file and rename it to violet.exe, or use PowerShell to rename it:

   # Windows x86
   mv -Force violet_windows_amd64.exe violet.exe

2. Run the tool in PowerShell.

Note: If the tool path is not added to your environment variables, you must specify the full path when running commands.

#Prerequisites

Permission requirements

• You must provide a valid platform user account (username and password).
• The account must have the role property set to System and the role name must be platform-admin-system.

Note: If the role property of your account is set to Custom, you cannot use this tool.

#Usage

#Common Parameters

Several violet commands accept the following parameters. Refer to individual command sections for specific usage.

#Platform Connection Parameters

--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 (default: "alauda-auth")

#Image Registry Parameters

--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

#violet show

Before uploading a package, use the violet show command to preview its details.

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

When upgrading the platform, use violet list to list the L4/L5 applications installed in the current environment and export the result to a YAML file. The generated file can then be uploaded to Alauda Cloud so that the required extension packages can be downloaded.

The command lists the following application types:

• ModulePlugin — cluster plugins whose lifecycle type is aligned or agnostic.
• OperatorBundle — installed operators.
• Chart — Helm chart applications created from chart references.

By default, the command prints the YAML content to stdout and writes it to apps.yaml in the current directory.

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

You can also authenticate with a platform token instead of username and password:

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

To export only applications installed in specific clusters, specify multiple cluster names separated by commas:

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

Example output:

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

#Optional Flags

--clusters <cluster names>                   # List applications installed in the specified clusters, separated by commas
--output-file <output file>                  # File path for the output application list (default: "apps.yaml")
--debug                                      # Use debug log level

For platform connection parameters (--platform-address, --platform-username, --platform-password, --platform-token, --client-id), see Common Parameters.

#violet gc

Use violet gc to clean up uninstalled L3/L4 Operator and ClusterPlugin resources. The command checks OperatorView and ModulePluginView records in the global cluster, then removes resources that are no longer installed or no longer match the installed version.

The command can delete the following resource types:

• Artifact — artifacts for uninstalled operators.
• ArtifactVersion — old artifact versions for installed operators. The currently installed CSV or version is kept.
• ModulePlugin — cluster plugins that are not installed in any cluster.
• ModuleConfig — obsolete cluster plugin configuration records.

By default, the command scans all clusters visible to the platform user and prints a summary of deleted resources.

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

You can also authenticate with a platform token instead of username and password:

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

To clean up resources related to specific clusters only, specify multiple cluster names separated by commas:

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

Example output:

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

If no resources are deleted, the command prints:

No resources were deleted.

#Optional Flags

--clusters <cluster names>                   # Recycle resources in the specified clusters, separated by commas
--debug                                      # Use debug log level

For platform connection parameters (--platform-address, --platform-username, --platform-password, --platform-token, --client-id), see Common Parameters.

#violet verify

Use the violet verify command to verify the signature of one or more packages before uploading them. Two verification methods are supported: checksum and GPG. The package (.tgz) and its corresponding signature file must be located in the same directory.

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

Example output:

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

Explanation:

• Verified successfully with GPG — The listed files have been successfully verified using GPG signature files (with .sig extension).
• Verified successfully with checksum — Files verified using checksum files (e.g., .sha256) passed the integrity check.
• Verification failed — The listed files failed verification due to mismatched or invalid signatures.
• No verification file found — No corresponding .sig (GPG) or checksum file was found in the directory.

#Optional Flags

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

#violet push

The following examples illustrate common usage scenarios.

For platform connection and image registry parameters, see Common Parameters.

#Optional Flags

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

--skip-crs and --skip-push cannot be specified together.

When --dest-repo is specified, either the authentication info of the image registry or --no-auth MUST be provided.

#Upload an Operator to Multiple Clusters

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

#Upload an Operator to a Standby Global Cluster

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>"

#Upload a Cluster Plugin

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

#Upload a Helm Chart to the chart repository

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

#Push all packages at once

When multiple packages are downloaded from the Marketplace, you can place them in the same directory and upload them all at once:

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