# Artifacts Management and hsk8s (Hyperscience Kubernetes CLI)

- Updated on Nov 4, 2025
- Published on Sep 17, 2024
- 6 minute(s) read

## 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. 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:

Bash

```bash
export HS_TOKEN=<your_token>
```

PowerShell

```powershell
$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.

Bash

```bash
export HS_K8S_CLIENT_ARCH=darwin-arm64 # ensure you use the appropriate arch from the list above for your own system
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`:

Bash

```bash
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:

Bash

```bash
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.

PowerShell

```powershell
$HS_K8S_CLIENT_ARCH=windows-amd64 # ensure you use the appropriate arch from the list above for your own system
$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 to persist the config. Test that you've installed the binary correctly with the following command:

PowerShell

```powershell
.

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](https://docs.docker.com/registry/spec/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

**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  [https://aws.amazon.com/cli/](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:

Bash

```bash
hsk8s image stream --help
```

Now you can run the command:

Bash

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

**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 (opens in new tab)](https://cloud.google.com/artifact-registry/docs/docker/store-docker-container-images#auth). The user pushing the images will require the Artifact Registry Writer role (`roles/artifactregistry.writer`) (see Google’s [Artifact Registry Roles and Permissions (opens in new tab)](https://cloud.google.com/iam/docs/roles-permissions/artifactregistry#artifactregistry.writer)).

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.

Custom

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

**Streaming Only Forms to a Private Repository**

Sample:

Bash

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

## Installing `kubectl`

For instructions on installing `kubectl`, see the Kubernetes documentation:

- [Linux instructions (opens in new tab)](https://kubernetes.io/docs/tasks/tools/install-kubectl-linux/)
- [MacOS instructions (opens in new tab)](https://kubernetes.io/docs/tasks/tools/install-kubectl-macos/)
- [Windows instructions (opens in new tab)](https://kubernetes.io/docs/tasks/tools/install-kubectl-windows/)

### Example `kubectl` setup to access EKS

This example assumes Bash shell is being used. Create a file named `hs_env.bash` with the following content:

Bash

```bash
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:

Bash

```bash
source hs_env.bash
```

Then, import the config for your EKS cluster:

Bash

```bash
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 (opens in new tab)](https://cloud.google.com/kubernetes-engine/docs/how-to/cluster-access-for-kubectl) for guidance on how to authenticate to a GKE cluster in the Google Cloud Platform.

## Set up the Helm repository

After you install Helm, run:

Bash

```bash
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:

Custom

```shell
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.

Custom

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

## Container image caching

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:

Custom

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

Then, update the `values.yaml` file with the following information:

Custom

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