#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

#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 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.
Before digging into the examples, here are some common OPTIONAL parameters used in the commands:

--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
--clusters <cluster names>                   # Specify target clusters, separated by commas (e.g., region1,region2)

--dest-repo <image repository URL>           # Specify the destination image repository URL. MUST be specified when uploading extensions to a standby cluster.
                                                 When `--dest-repo` is specified, either the authentication info of the image registry or `--no-auth` MUST be provided.
--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.

--skip-crs                                   # Skip creating `Artifact` and `ArtifactVersion` resources, only push images.
                                                 This prevents Operators or Cluster Plugins from being updated prematurely during the <Term name="productShort" /> upgrade process.
--skip-push                                  # Only create `Artifact` and `ArtifactVersion` resources, while images are not pushed.

#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://example.com" \
  --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 only images from all packages in a directory

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> \
  --skip-crs \
  --platform-address "https://example.com" \
  --platform-username "<platform_user>" \
  --platform-password "<platform_password>"

#Create only CRs from all packages in a directory

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> \
  --skip-push \
  --platform-address "https://example.com" \
  --platform-username "<platform_user>" \
  --platform-password "<platform_password>"
  --clusters "<cluster_name>"