Warning

Nightly releases are generated automatically from the latest source code and are intended for experimental purposes only. These builds may contain incomplete or untested features, bugs, or security vulnerabilities, and as such, are not for production use. Users should be aware that nightly releases may cause unexpected behavior, data loss, or system instability. Use of these releases is at the user's own risk, and it is advised to have adequate backups before testing. The software is provided as is with no guarantees or support.

instant3Dhub on Kubernetes¶

Read First¶

Kubernetes is the targeted platform for running instant3Dhub. Therefore, this guide assumes a Kubernetes cluster exists and can be accessed for deployments. Details about the requirements for running instant3Dhub can be found here.

instant3Dhub is shipped with all the necessary components and services to run completely in Kubernetes without the need to setup external services. However, it is possible to use external services like PostgreSQL and RabbitMQ in order to properly ensure data is persisted between version upgrades. Setting up these external services is recommended in some scenarios and especially in production environments.

More information on how to configure instant3Dhub to run with external services can be found below.

Limitations¶

HTTPS: HTTPS is not supported inside the cluster or at the gateway. Currently, HTTPS can be used by adding a proxy outside of the cluster.
Services: Any backend services requiring GPU support are disabled by default. To use these, change the configured number of pods either by scaling or adapting the configuration.

Installation¶

Transfer docker images¶

Our docker images are available on our public registry images.threedy.io and can be pulled from there. However, we recommend that you transfer the images to your own registry as we do not guarantee high availability of our registry. For transferring images to another docker registry, we provide a script.

./transfer_images.sh images.threedy.io registry.yourdomain.com

Install Helm¶

We provide a Helm Chart repository for the deployment of instant3Dhub on Kubernetes.

Therefore, helm should be installed first:

curl -fsSL -o get_helm.sh https://raw.githubusercontent.com/helm/helm/master/scripts/get-helm-3 \
 && chmod 700 get_helm.sh \
 && ./get_helm.sh

We provide three channels for helm packages:

stable: This channel contains the stable release packages of instant3Dhub.
dev: This channel contains all rc and dev packages.
trk_<track-name>: Each track package has its own channel and is named using the suffix trk_ followed by the name of the track.
nightlyrelease: This channel contains the latest developments. In regards to security and stability this will not be on the maturity level of our stable channel’s official releases.

Now, add the instant3Dhub Helm repository from one of the channels:

helm repo add instant3dhub https://repo.threedy.io/api/v4/projects/2/packages/helm/<channel> \
 && helm repo update

You can now deploy using helm install, but first several configuration options are required and must be set before deployment:

license.serialKey
storage.class
entrypoints
registry

These are explained in the following sections.

Configure¶

`license.serialKey`¶

A license is required in order to run instant3Dhub. The license key is used to automatically report billable usage metrics to Threedy. If you do not have a license key, please request one at sales@threedy.io.

For air-gapped environments, an on-premise license server is required. In this case, you will need a separate server on which to install the host-bound license server. See here for more information.

Instead of using a license key, you will then need to set the licenseServer parameter to the address of the license server instead.

`storage.class`¶

instant3Dhub requires a set of volumes for persistence and data exchange between services in the system.

In case you have a storage class that provides persistent volumes dynamically, the storage.class option can be set to the name of your storage class.

Note

If you create the persistent volumes manually with the correct labels, the storage.class option can be skipped.

Otherwise, make sure that you create the following static persistent volumes with their corresponding labels:

Name	Size	Type	Labels
cache_volume	20GB	RWX	app: i3dhub-cache & instance: <k8s-namespace>
postgres_volume	5GB	RWO	app: i3dhub-postgres & instance: <k8s-namespace>
entrygw_volume	2GB	RWX	app: i3dhub-entrygw & instance: <k8s-namespace>
rabbitmq_volume	1GB	RWO	app: i3dhub-rabbitmq & instance: <k8s-namespace>
upload_volume	5GB	RWX	app: i3dhub-uploadsvc & instance: <k8s-namespace>
prometheus_volume	5GB	RWO	app: i3dhub-prometheus & instance: <k8s-namespace>
jaeger_volume	5GB	RWO	app: i3dhub-jaeger & instance: <k8s-namespace>

An example of static persistent volumes can be found here.

`entrypoints`¶

In order for the system to address its resources properly, the entry points for the system must be set. An entry point is a URL from which the system is accessible. For example, if you have proxy in front of your cluster, the entry point must be set to be the URL of the proxy.

`registry`¶

Images will be pulled from the provided registry. After transferring the images to a registry, the registry value should contain the URL of your registry.

Install¶

After determining the required values for the installation, you can now install instant3Dhub with the following command:

helm install [release-name] instant3dhub/instant3dhub \
  --set license.serialKey=key-here \
  --set storage.class=your-storage-class \
  --set entrypoints={https://proxy.yourdomain.com} \
  --set registry=registry.yourdomain.com

As an alternative please consider the reference scripts located here.

The startup and initialization of all containers can take a few minutes, depending on your cluster and registry connection speed. To check the status of the containers run:

watch kubectl get pods -n your-namespace

After all containers are running, the system might take up to one minute to initialize correctly.

Using External Services¶

PostgreSQL¶

The system can optionally work with a previously provisioned PostgreSQL instance. This instance must be initialized correctly with our schema and tables. For that, we provide ansible playbooks to install and initialize postgres manually. For more information please see our guide.

If you are using external PostgresSQL, the connection string must be configured via kubernetes secrets. These secrets can then referenced in our helm chart:

Name	Description
`credentials.postgres.system.secretKeyRef.name`	The name of the secret where the connection string is stored
`credentials.postgres.system.secretKeyRef.key`	The name of the key in the secret’s items.

RabbitMQ¶

The system uses RabbitMQ to dispatch jobs. If you want to use external service for that, it is possible to change the configuration to point instant3Dhub to use the external service.

As with PostgreSQL, these must be set via secrets. The following values need to be set in our helm chart:

Name	Description
`credentials.rabbitmq.secretKeyRef.name`	The name of the secret where the connection string is stored
`credentials.rabbitmq.secretKeyRef.key`	The name of the key in the secret’s items.