文档

Install shdctl

Install the shdctl command-line tool, configure registry credentials, and review external CLI requirements
阅读时间10 分钟最后更新于 13 天前

Unity provides
install-shdctl.sh
as part of your Self-Hosted Deployment onboarding package. Every release from 2.0.0 on also includes it under
common/scripts/
, and Copy the install script shows it in full. To move a deployment of an earlier release from vpctl to shdctl, follow Install shdctl 1.0.0 before you pull instead. After you have the script, run the following command:
./install-shdctl.sh latest
The following sections explain the script's options, the external CLIs that shdctl uses for specific operations, and how to configure the registry credentials shdctl uses to pull releases.

Requirements

shdctl is a single Go binary; it has no runtime dependencies of its own. External CLIs are required only for operations that shell out to them:

You need...

Required for...

oras
CLI
The install script (
install-shdctl.sh
shells out to
oras
to pull the binary)
docker
CLI, plus
docker login
to source and target registries
shdctl artifact sync images
(uses
docker pull
/
tag
/
push
/
manifest inspect
/
rmi
) and
shdctl artifact sync preflight
docker login
(to populate
~/.docker/config.json
)
shdctl artifact sync oras
,
shdctl artifact sync images
(reads the release manifest to find the images it names), and
shdctl artifact sync verify
.
oras-go
reads credentials from the Docker credential store, so
verify
doesn't need the
docker
CLI
helm
CLI on
PATH
shdctl release deploy --format helm
and
shdctl release uninstall
kubectl
CLI on
PATH
, plus a kubeconfig
shdctl cluster check
,
shdctl secret deploy
,
shdctl secret export
(reads secrets from one namespace),
shdctl release deploy --format argocd
(applies one
Application
)
cue
CLI (optional)
Only if you want to validate
manifest.yaml
outside shdctl after
shdctl manifest schema --export
. The schema is embedded in the binary, so
shdctl manifest validate
works without it
shdctl release pull
,
shdctl release generate
,
shdctl secret generate
,
shdctl manifest init/validate/schema
, and
shdctl configure
do not shell out to any external CLI.

Install the shdctl binary

The install script automatically detects your OS and architecture and downloads the correct binary from the Unity registry.
Before you run the install script, ensure you have:
  • ORAS CLI: the install script uses it to pull the shdctl binary, but doesn't install it. For installation instructions, refer to Installation (ORAS).
  • Registry credentials: a username and password, which Unity provides.
The script supports interactive mode for users and non-interactive mode for CI and automation.

Interactive mode

  1. Run the script without setting credentials. It prompts you for your username and password:
    ./install-shdctl.sh latest
    You can also pin a specific version:
    ./install-shdctl.sh 1.1.0
  2. Enter your credentials at the prompt:
    [install-shdctl] Logging in to uccmpprivatecloud.azurecr.io (interactive)...[install-shdctl] Please enter your registry credentials:Username: <your-username>Password: <your-password>

Non-interactive mode for CI and automation

For automated environments, set both
ORAS_USERNAME
and
ORAS_PASSWORD
environment variables:
export ORAS_USERNAME="<your-username>"export ORAS_PASSWORD="<your-password>"./install-shdctl.sh latest
You can also pin a specific version:
export ORAS_USERNAME="<your-username>"export ORAS_PASSWORD="<your-password>"./install-shdctl.sh 1.1.0

Custom installation directory

Specify a custom installation directory as the second argument:
./install-shdctl.sh latest /opt/bin
The script creates a missing directory, with
sudo
when you cannot create it yourself —
/opt/bin
as a non-root user, for instance.

Script actions

The script performs the following actions:
  • Auto-detects your platform (
    linux
    /
    darwin
    /
    windows
    ) and architecture (
    amd64
    /
    arm64
    ). This detection applies to the machine you run shdctl on. The cluster nodes must be
    amd64
    . For more information, refer to Node pools.
  • Checks whether the
    oras
    CLI is installed. If it isn't, the script exits with a link to the ORAS installation instructions. Install
    oras
    , and then run the script again.
  • Authenticates to the registry by using interactive or non-interactive mode based on environment variables. The login stays in your Docker credential store afterwards; run
    oras logout <registry>
    if you don't want it kept.
  • Downloads and extracts the correct shdctl binary.
  • Installs it to
    /usr/local/bin
    or the directory you specify, using
    sudo
    to create that directory or copy into it when you cannot.
  • Links the tool's previous name,
    vpctl
    , to it (except on Windows), so scripts that still call
    vpctl
    keep working until shdctl 2.0.0.
  • Verifies the installation by running
    shdctl version
    .

Environment variables

Variable

Required

Default

Description

ORAS_USERNAME
No*-Registry username (for non-interactive mode)
ORAS_PASSWORD
No*-Registry password (for non-interactive mode)
ORAS_REGISTRY
No
uccmpprivatecloud.azurecr.io
Registry URL
* Both
ORAS_USERNAME
and
ORAS_PASSWORD
must be set together for non-interactive mode, or both unset for interactive mode.

Configure registry credentials

Before you can pull releases, configure your registry credentials.
  1. Run the interactive configuration command:
    shdctl configure
    The command prompts you for:
    • Username
    • Password (input is hidden)
    The registry defaults to
    uccmpprivatecloud.azurecr.io
    . To configure credentials for a different registry, pass it as a positional argument:
    shdctl configure set <registry-url>
    .
  2. Alternatively, configure credentials non-interactively. The registry argument is positional and defaults to
    uccmpprivatecloud.azurecr.io
    . You can provide the password by using one of the non-interactive methods in Security: providing registry credentials.
Credentials are stored in
~/.shdctl/config.json
, readable only by your user (
0600
, in a
0700
directory) but not encrypted — protect it like any other credential file. Only
shdctl release pull
reads it;
artifact sync
uses your Docker credentials instead.

Security: providing registry credentials

shdctl configure set
accepts the password through four input modes, listed from most to least preferred for automation:
  1. --password-stdin
    — read the password from stdin. Best for CI/CD pipelines:
    echo "$REGISTRY_PASSWORD" | shdctl configure set <registry-url> --username "$REGISTRY_USERNAME" --password-stdin
  2. SHDCTL_PASSWORD
    environment variable
    — non-interactive without piping. Pair with
    SHDCTL_USERNAME
    . The pre-rename
    VPCTL_USERNAME
    and
    VPCTL_PASSWORD
    are still read, with a deprecation notice, until shdctl 2.0.0:
    export SHDCTL_USERNAME=<username>export SHDCTL_PASSWORD=<password>shdctl configure set <registry-url>
  3. Interactive prompt — the default when you run
    shdctl configure set <registry-url>
    without flags. Password input is hidden.
  4. --password <value>
    flag
    — discouraged. The password is exposed in your shell history and in the process list (
    ps aux
    ). shdctl emits a warning to stderr:
    WARNING: Using --password via the CLI is insecure (visible in shell history and the process list).Use --password-stdin, set SHDCTL_PASSWORD, or omit --password to be prompted interactively.
    Kept for backward compatibility; not recommended.
--password
and
--password-stdin
are mutually exclusive. If neither is set and stdin is not a TTY (and no
SHDCTL_PASSWORD
is in the environment),
shdctl configure set
errors out rather than hanging.
To view or delete stored credentials, and for every
configure
subcommand, refer to Manage registry credentials.

Copy the install script

If you don't have the onboarding package or a release package, save the following script as
install-shdctl.sh
, make it executable with
chmod +x install-shdctl.sh
, and run it as Install the shdctl binary describes:
#!/usr/bin/env bash# install-shdctl.sh - Install shdctl from ORAS registry## Usage:# ./install-shdctl.sh <version> [install-dir]## Arguments:# version Required. The shdctl version to install (e.g. 1.0.0, latest)# install-dir Optional. Directory to install shdctl into (default: /usr/local/bin)## Environment variables:# ORAS_REGISTRY Registry URL (default: uccmpprivatecloud.azurecr.io)# ORAS_USERNAME Registry username (optional; if unset, interactive login is used)# ORAS_PASSWORD Registry password (optional; if unset, interactive login is used)## The script auto-detects the current OS and architecture, pulls the# matching shdctl archive from the ORAS registry, and installs it.set -euo pipefail# ── Defaults ──────────────────────────────────────────────────────────ORAS_REGISTRY="${ORAS_REGISTRY:-uccmpprivatecloud.azurecr.io}"INSTALL_DIR="${2:-/usr/local/bin}"# ── Helpers ───────────────────────────────────────────────────────────info() { echo "[install-shdctl] $*"; }error() { echo "[install-shdctl] ERROR: $*" >&2; exit 1; }# ── Validate arguments ───────────────────────────────────────────────VERSION="${1:-}"if [ -z "$VERSION" ]; then echo "Usage: $0 <version> [install-dir]" echo "" echo "Environment variables:" echo " ORAS_REGISTRY Registry URL (default: uccmpprivatecloud.azurecr.io)" echo " ORAS_USERNAME Registry username (optional; prompts interactively if unset)" echo " ORAS_PASSWORD Registry password (optional; prompts interactively if unset)" exit 1fi# Determine login mode: non-interactive (CI) vs interactive (human)if [ -n "${ORAS_USERNAME:-}" ] && [ -n "${ORAS_PASSWORD:-}" ]; then LOGIN_MODE="ci"elif [ -z "${ORAS_USERNAME:-}" ] && [ -z "${ORAS_PASSWORD:-}" ]; then LOGIN_MODE="interactive"else # One is set but not the other — likely a misconfiguration error "Both ORAS_USERNAME and ORAS_PASSWORD must be set for non-interactive login, or both must be unset for interactive login"fi# ── Detect OS ─────────────────────────────────────────────────────────detect_os() { local os os="$(uname -s)" case "$os" in Linux*) echo "linux" ;; Darwin*) echo "darwin" ;; MINGW*|MSYS*|CYGWIN*) echo "windows" ;; *) error "Unsupported operating system: $os" ;; esac}# ── Detect architecture ──────────────────────────────────────────────detect_arch() { local arch arch="$(uname -m)" case "$arch" in x86_64|amd64) echo "amd64" ;; aarch64|arm64) echo "arm64" ;; *) error "Unsupported architecture: $arch" ;; esac}# ── Check ORAS CLI is present ─────────────────────────────────────────ensure_oras() { if command -v oras &>/dev/null; then info "oras already installed: $(oras version 2>/dev/null || echo 'unknown')" return fi error "oras CLI is not installed. Please install it before running this script. Installation instructions: https://oras.land/docs/installation/"}# ── Main ──────────────────────────────────────────────────────────────OS="$(detect_os)"ARCH="$(detect_arch)"info "Detected platform: ${OS}/${ARCH}"info "Installing shdctl v${VERSION} to ${INSTALL_DIR}"# Ensure oras CLI is availableensure_oras# Login to ORAS registryif [ "$LOGIN_MODE" = "ci" ]; then info "Logging in to ${ORAS_REGISTRY} (non-interactive)..." echo "${ORAS_PASSWORD}" | oras login "${ORAS_REGISTRY}" \ --username "${ORAS_USERNAME}" \ --password-stdinelse info "Logging in to ${ORAS_REGISTRY} (interactive)..." info "Please enter your registry credentials:" oras login "${ORAS_REGISTRY}"fi# Prepare temp directory for downloadWORK_DIR="$(mktemp -d)"trap 'rm -rf "$WORK_DIR"' EXIT# Pull from registryORAS_REF="${ORAS_REGISTRY}/releases/cli/shdctl_${OS}_${ARCH}:${VERSION}"info "Pulling ${ORAS_REF}..."oras pull "$ORAS_REF" -o "$WORK_DIR"# Find the archive.# When pulling "latest", the actual filename still contains the original version# (e.g. shdctl_0.3.1_linux_amd64.tar.gz), so we match by extension pattern# rather than exact name.if [ "$OS" = "windows" ]; then ARCHIVE_GLOB="shdctl_*_${OS}_${ARCH}.zip"else ARCHIVE_GLOB="shdctl_*_${OS}_${ARCH}.tar.gz"fiARCHIVE_PATH=$(find "$WORK_DIR" -name "$ARCHIVE_GLOB" -type f 2>/dev/null | head -1)if [ -z "$ARCHIVE_PATH" ]; then error "Could not find archive matching $ARCHIVE_GLOB after pull"fiinfo "Found archive: $(basename "$ARCHIVE_PATH")"# Extractinfo "Extracting archive..."EXTRACT_DIR="$(dirname "$ARCHIVE_PATH")"if [ "$OS" = "windows" ]; then BINARY_NAME="shdctl.exe" unzip -q "$ARCHIVE_PATH" -d "$EXTRACT_DIR"else BINARY_NAME="shdctl" tar -xzf "$ARCHIVE_PATH" -C "$EXTRACT_DIR"fiBINARY_PATH="${EXTRACT_DIR}/${BINARY_NAME}"chmod +x "$BINARY_PATH"# Installinfo "Installing shdctl to ${INSTALL_DIR}..."# A directory under a root-owned parent (/opt/bin as a non-root user) needs sudo# to create, the same way the copy below needs it to write into one.if ! mkdir -p "$INSTALL_DIR" 2>/dev/null; then info "Creating ${INSTALL_DIR} with sudo..." sudo mkdir -p "$INSTALL_DIR"fiif [ -w "$INSTALL_DIR" ]; then mv "$BINARY_PATH" "${INSTALL_DIR}/${BINARY_NAME}"else sudo mv "$BINARY_PATH" "${INSTALL_DIR}/${BINARY_NAME}"fi# Leave the pre-1.0.0 name working through 1.x. A symlink rather than a# copy: shdctl reads argv[0], so a process started through it sees "vpctl" and# prints the deprecation notice, which a second copy of the binary would do just# as well but would also have to be kept in step on every upgrade.# TODO: remove in shdctl 2.0.0.if [ "$OS" != "windows" ]; then LEGACY_PATH="${INSTALL_DIR}/vpctl" info "Linking the previous name ${LEGACY_PATH} -> ${BINARY_NAME} (removed in 2.0.0)" if [ -w "$INSTALL_DIR" ]; then ln -sf "$BINARY_NAME" "$LEGACY_PATH" else sudo ln -sf "$BINARY_NAME" "$LEGACY_PATH" fifi# Verifyinfo "Verifying installation...""${INSTALL_DIR}/${BINARY_NAME}" versioninfo "shdctl v${VERSION} installed successfully at ${INSTALL_DIR}/${BINARY_NAME}"