instant3Dhub on Kubernetes#

Read First#

Kubernetes is the targeted platform for running instant3Dhub. Therefore, this guide assumes a k8s 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 necessery components and services to run completely in kubernetes without the need to setup external services. However not all services. However it is possible to use exernal services like PostgreSQL, ELK stack and RabbitMQ. Setting up these external services is recommend in some scenarios and specially 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 or as a sidecar on the apigw component.

  • Services: Currently only the SharedSession, SpaceStore, Measurement and Query services are enabled. This means a range of functionalities will not be available in webvis and other API-libraries.

  • Security/Signatues: The third main version instant3Dhub is designed to include security on all layers of the system like controlling the access to the management APIs, resource APIs, the services or the data that goes through the system. It is not yet possible to configure custom keys.

Installation#

Transfer docker images#

Our docker images are available on our public registry images.threey.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 availablity of our registry. For transfering 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.

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 please continue reading to know which configuration you need to set. There are four main configuration that are required and need to be adjusted before you deploy. These configuration are:

  • licenseServer

  • storage

  • entrypoints

  • registry

helm install [release-name] instant3dhub/instant3dhub

As an alternative please consider the reference scripts located here

License Server#

Instant3Dhub license server must be installed outside your k8s cluster and shoud be accessible from within the cluster so you can use the features of instant3Dhub. For information on how to install the license server please follow these instructions

Now you can set the address to the license server with the –set parameter.

helm install [release-name] instant3dhub/instant3dhub \
  --set licenseServer=license.yourdomain.com:8200

Storage#

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

In case you have a storage class that provides PVs dynamically, the option storage.class can be set to to be the name of your storage class via the –set parameter.

helm install [release-name] instant3dhub/instant3dhub \
  --set licenseServer=license.yourdomain.com:8200 \
  --set storage.class=your-storage-class

Otherwise, make sure that you create the following static PVs with their corresonding labels:

Name

Size

Labels

cache_volume

20GB

app: idhub-cache & instance: <The-name-of-namespace>

postgres_volume

5GB

app: idhub-postgres & instance: <The-name-of-namespace>

elastic_volume

5GB

app: idhub-elastic & instance: <The-name-of-namespace>

entrygw_volume

2GB

app: idhub-entrygw & instance: <The-name-of-namespace>

rabbitmq_volume

1GB

app: idhub-rabbitmq & instance: <The-name-of-namespace>

If you create the PVs manually with the correct labels, the storage.class parameter does not need to be set then.

An example of static persistent volumes can be found here

Access#

In order for the system to address its resources properly, the entry points for the system have to 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.

helm install [release-name] instant3dhub/instant3dhub \
  --set licenseServer=license.yourdomain.com:8200 \
  --set storage.class=your-storage-class \
  --set entrypoints={https://proxy.yourdomain.com:30000}

Images Registry#

You should make sure that you are using the correct registry for pulling the docker images. Once you have transfered the images to your registry, you can set the URL in helm chart.

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

At this point you should have all the requirements to run instant3Dhub. 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 corrctly 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, we recommend using k8s secrets to store the connection string. The secrets can be referenced then using these values 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.

These values need to be set in our helm chart values then.

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.