Artifacts Management and hsk8s (Hyperscience Kubernetes CLI)

  • Updated on Aug 13, 2025
  • Published on Sep 17, 2024
  • 6 minute(s) read
Prev Next

Background

The Hyperscience Platform is deployed using multiple container images. You can obtain these images from the public Hyperscience container registry and then either copy all of them to your internal registry or set up your internal registry to cache them.

Hyperscience provides a utility called hsk8s to help with this process. While it's not required, it can automate the synchronization of images to your internal registry (the first option mentioned above). You should use the latest version of hsk8s if possible. Even if you choose to cache the images, hsk8s is still useful for other tasks like setting up Helm, generating support bundles, and copying other assets like machine learning models .

To run the Hyperscience platform on Kubernetes, you'll also need to have Helm and Kubectl installed.

Hyperscience Kubernetes CLI

Installation

Hyperscience token

The following steps require a Hyperscience token to access the public Hyperscience artifacts. If you do not have one, contact your Hyperscience representative for assistance. Once you have it, export the HS_TOKEN environment variable with its value:

export HS_TOKEN=<your_token>
$HS_TOKEN=<your_token>

Make sure to replace <your_token> with the actual value.

Supported OS / architecture combinations

The following OS/architecture combinations are supported:

  • darwin-arm64

  • darwin-amd64

  • linux-arm

  • linux-amd64

  • windows-arm64

  • windows-amd64

Download the binary and install

Darwin and Linux

You can download the binary from our asset-hosting partner with the following URL scheme. Replace with the architecture where you are running it.

export HS_K8S_CLIENT_ARCH=
export HS_K8S_CLIENT_VERSION=latest

# Using your token in the url
curl -OL "https://dl.cloudsmith.io/${HS_TOKEN}/hyperscience/prod/raw/names/hsk8s-${HS_K8S_CLIENT_ARCH}/versions/${HS_K8S_CLIENT_VERSION}/hsk8s-${HS_K8S_CLIENT_ARCH}-${HS_K8S_CLIENT_VERSION}.tgz"

# Or using basic auth
curl -OL -u token:${HS_TOKEN} "https://dl.cloudsmith.io/basic/hyperscience/prod/raw/names/hsk8s-${HS_K8S_CLIENT_ARCH}/versions/${HS_K8S_CLIENT_VERSION}/hsk8s-${HS_K8S_CLIENT_ARCH}-${HS_K8S_CLIENT_VERSION}.tgz"

After you've successfully downloaded the binary, you need to untar it, change its permissions, and move it to a directory in your $PATH:

tar -xvf hsk8s-${HS_K8S_CLIENT_ARCH}-${HS_K8S_CLIENT_VERSION}.tgz
chmod 744 hsk8s-${HS_K8S_CLIENT_ARCH}
mv hsk8s-${HS_K8S_CLIENT_ARCH} /usr/local/bin/hsk8s

Test that you've installed the binary correctly with the following command:

hsk8s version

Windows

You can download the binary from our asset-hosting partner with the following URL scheme. Replace with the architecture where you are running it.

$HS_K8S_CLIENT_ARCH = 
$HS_K8S_CLIENT_VERSION = "latest"
$HSK8S_URL = "https://dl.cloudsmith.io/${HS_TOKEN}/hyperscience/prod/raw/versions/${HS_K8S_CLIENT_VERSION}/hsk8s-${HS_K8S_CLIENT_ARCH}.exe"
Invoke-WebRequest $HSK8S_URL -OutFile hsk8s.exe

Depending on your Windows setup, you may add the file directory to your system’s PATH variable and persist the config. Test that you've installed the binary correctly with the following command:

.\hsk8s.exe version

Usage

Downloading container Images

hsk8s can be used to copy container images from Hyperscience repositories to your own. The application uses the Docker HTTP V2 Registry API to handle communication, so a local docker installation is NOT required. The application does require network access to our publicly-available repositories, as well as network access to your own internal container registry.

You will need 4 distinct repositories with the following default names:

  • forms

  • sdm_blocks

  • trainer

  • hyperoperator

These names can be overridden with the hsk8s parameters --forms-repo, --blocks-repo, --trainer-repo, and --operator-repo, respectively.

Examples

IMPORTANT: All internal repositories must already exist before running the commands below.

Streaming Images to AWS ECR

This command will stream images from Hyperscience repositories to an ECR Registry of your choice. The user running this command will need to be logged in to the https://aws.amazon.com/cli/ under a profile that has the following IAM permissions:

  • ecr:BatchGetImage

  • ecr:BatchCheckLayerAvailability

  • ecr:CompleteLayerUpload

  • ecr:GetDownloadUrlForLayer

  • ecr:InitiateLayerUpload

  • ecr:PutImage

  • ecr:UploadLayerPart

To see all the options of the command, type:

hsk8s image stream --help

Now you can run the command:

hsk8s image stream 0123456789.dkr.ecr.us-east-1.amazonaws.com --token $HS_TOKEN --aws

Note: In the command above, replace 0123456789.dkr.ecr.us-east-1.amazonaws.com with your ECR registry endpoint. Note that it doesn't contain the repository name. You can obtain the name through the AWS Console or CLI.

Alternatively, if you cannot use hsk8s for image streaming, you can do it directly with docker. In that case, except for the above repositories, you will also need to stream a supporting image for the trainer database, as shown below. hsk8s does that automatically.

docker pull docker.cloudsmith.io/hyperscience/prod/postgres:16.6-alpine
docker tag docker.cloudsmith.io/hyperscience/prod/postgres:16.6-alpine 0123456789.dkr.ecr.us-east-1.amazonaws.com/trainer:postgres...16.6-alpine
docker push 0123456789.dkr.ecr.us-east-1.amazonaws.com/trainer:postgres...16.6-alpine

Streaming Images to Google Artifact Registry

To push to GCP's Artifact Registry, you must first configure its authentication as explained in Google's Store Docker container images in Artifact Registry. The user pushing the images will require the Artifact Registry Writer role (roles/artifactregistry.writer) (see Google’s Artifact Registry Roles and Permissions).

Then, running the following command will push all images that Hyperscience needs to the my-repo repository. In contrast to other Docker registries, you will need to create only the top-level repository in GAR. The others will be created automatically when the first image is pushed.

hsk8s image stream us-east4-docker.pkg.dev/my-project-id/my-repo --token $HS_TOKEN

Streaming Only Forms to a Private Repository

Sample:

hsk8s image stream your-docker-registry.net --token $HS_TOKEN --forms --forms-repo hyperscience-forms --basic username:password --forms-version 40.0.3

This example demonstrates a few of the many options supported by the hk8s image stream subcommand:

  1. To connect to a private docker repository that supports basic authentication, you can use the --basic flag like so: --basic username:password

  2. To stream only the main Hyperscience image (forms), you can use the --forms flag. Likewise, the command also supports streaming only --blocks, --trainer and --operator. These flags can be combined to stream different combinations of components.

  3. To specify a target repository that's different from the default, you can use the --forms-repo, --blocks-repo, --trainer-repo or --operator-repo flags.

  4. To specify a specific application version to download (that is not latest), you can use --forms-version or --operator-version. Since the block versions must match the forms version, the --forms-version flag is used for all of those images.

  5. To stream trainer of another version, you can issue a command like: hsk8s image stream your-docker-registry.net  --trainer --forms-version  --token $HS_TOKEN

Going back to the above command, this command will stream the forms:40.0.3 image to your-docker-registry.net/hyperscience-forms:40.0.3 using Basic Auth credentials.

Installing kubectl

For instructions on installing kubectl, see the Kubernetes documentation:

Example kubectl setup to access EKS

This example assumes Bash shell is being used. It is trivial to translate it to PowerShell as needed for a Windows environment. Create a file named hs_env.bash with the following content:

export HS_K8S_NAMESPACE=hyperscience-dev
export HS_KUBECTL_CONTEXT=hyperscience-dev
export HS_HELM_RELEASE=hyperscience-dev
export HS_HELM_CHART=hyperscience/hyperscience

You can replace hyperscience-dev with any names you want, but leave hyperscience/hyperscience as it is.

Import the environment from the newly created file:

source hs_env.bash

Then, import the config for your EKS cluster:

aws eks update-kubeconfig --region  --name  --alias $HS_KUBECTL_CONTEXT
kubectl config use-context $HS_KUBECTL_CONTEXT
kubectl config set-context $HS_KUBECTL_CONTEXT --namespace=$HS_K8S_NAMESPACE

Alternatively, follow the instructions in Google's Install kubectl and configure cluster access for guidance on how to authenticate to a GKE cluster in the Google Cloud Platform.

Set up the Helm repository

IMPORTANT: Setting up the repository requires a local installation of Helm, the package manager for Kubernetes. If you don't have the tool, you should follow Helm's Installing Helm instructions first.

After you install Helm, run:

hsk8s helm add --token $HS_TOKEN

to add the Hyperscience Helm Repository to your local repository cache.

Now you can run commands like helm repo update, which will fetch the latest version of the Hyperscience's package for Helm (called chart in Helm's language) from the remote repository.

Without using hsk8s

If you skip hsk8s installation, you may set the Helm repository by using this endpoint:

HS_HELM_REPO_URL="https://dl.cloudsmith.io/basic/hyperscience/prod/helm/charts/"

The following example shows how to configure the Hyperscience Helm repo for your local system without hsk8s. You may also use your HS_HELM_REPO_URL, username, and HS_TOKEN to add the Hyperscience Helm repo to a local registry, just as you would for JFrog Artifactory or similar repositories.

helm repo add hyperscience https://dl.cloudsmith.io/basic/hyperscience/prod/helm/charts/ --username token --password $HS_TOKEN

Container image cacheing

If you decide to set container image caching on your container registry instead of syncing container images manually each time, you need to configure your registry and adjust the Helm chart with the proper container image prefixes.

Set up your container-registry product with the necessary information to proxy and cache the image requests from the Kubernetes cluster:

Repo URL: docker.cloudsmith.io
Username: hyperscience/prod
Password: $HS_TOKEN

Then, update the values.yaml file with the following information (see Helm Chart for information on values.yaml):

# The specific paths may be dependent on the particular contianer registry in use.
# Image names should be similar to your-artifactory-url.net/your-repo-name/hyperscience/prod/forms:42.0.0
# In your values.yaml, you'll need to include the following, with repository values being something like this:
app:
  repository: "your-artifactory-url.net/your-repo-name/hyperscience/prod/forms"
blocks:
  repository: "your-artifactory-url.net/your-repo-name/hyperscience/prod/sdm_blocks"
operator:
  repository: "your-artifactory-url.net/your-repo-name/hyperscience/prod/hyperoperator"
trainer:
  repository: "your-artifactory-url.net/your-repo-name/hyperscience/prod/trainer"
  db:
    repository: "your-artifactory-url.net/your-repo-name/hyperscience/prod/postgres"