Installation Instructions

Introduction
TileDB Cloud Enterprise edition is available for installation in Kubernetes clusters though a helm chart. The helm chart will install all components of TileDB Cloud. The instructions below will walk you though getting the helm chart, getting access to the private docker registry and setting up the installation.
Accounts
In order to use the enterprise edition you will need to get access to the private docker registry and the private helm registry. Please contact your TileDB, Inc account representative for credentials to these services.
Installation
Prerequisites
Kubernetes
A Kubernetes cluster is required for installation. Setting up a Kubernetes cluster is outside the scope of this document, please contact your account representative if you need assistance with this.
Kubernetes Components
The minimum Kubernetes version support is v1.14.0. If your cluster is older than this you will need to upgrade.
You will also need the following components configured in your cluster:
​Metric Server for auto-scaling
​Ingress for exposing the service
Helm
Helm charts are used for the installation of TileDB Cloud Enterprise services in the Kubernetes cluster. You will need to have helm v3 installed on your local machine to facilitate the installation. Helm v3 does not require any components inside the Kubernetes cluster.
MariaDB
MariaDB 10.3 or newer is required. This is used for persistant storage of user acocunt details, organizations, tasks and more. While MySQL should be compatible only MariaDB 10.3 or newer are officially supported.
Add Helm Repository
To get started with you will need to add the TileDB helm chart repository. This repository requires authentication, please use the username/password provided to you by your account representative.
# TileDB Chart is for the TileDB Cloud service itself
helm repo add tiledb https://charts.tiledb.com --username <provided by TileDB>
Create Kubernetes Namespace
TileDB cloud will be installed into a dedicated namespace, tiledb-cloud
kubectl create namespace tiledb-cloud
Create Custom Values.yaml
Before you install TileDB Cloud Enterprise it is important to setup and customize your installation. This involves creating a custom values file for helm. Below is a sample file you can save and edit.
Save this value as values.yaml . There are several required changes, all sections which require changes are prefixed with a comment of # REQUIRED:. Examples of the changes needed including setting your docker registry authentication details, updating the domain names you would like to deploy TileDB Cloud too.
values.yaml
# Default values for tiledb-cloud-enterprise.
# This is a YAML-formatted file.
​
# Should hosted notebooks be enabled? If you would like to disable them set this to false
notebooks:
  enabled: true
​
# REQUIRED: Set the docker registry image credentials to pull TileDB Cloud docker images
# The password should be provided to you by your account representative
imageCredentials:
  username: "tiledbdocker"
  password: ""
​
##################################
# TileDB Cloud REST API settings #
##################################
tiledb-cloud-rest:
  # Service Account to run deployment under
  # Change this if you have different RBAC requirements
  serviceAccountName: default
​
  # The autoscaling of the service can be adjusted if required
  # The following settings are the recommended defaults
  autoscaling:
    enabled: true
    minReplicas: 2
    maxReplicas: 300
    targetCPUUtilizationPercentage: 80
    targetMemoryUtilizationPercentage: 50
  
  # .spec.volumes
  #volumes:
  #  - name: test
  #    emptyDir: {}
  #  - name: nfs-volume
  #    nfs:
  #      server: nfs.example.com
  #      path: /nfs/
​
  # .spec.containers[*].volumeMounts
  # A volume with the same name declared here
  # must exist in volumes.
  #volumeMounts:
  #  - name: test
  #    mountPath: /test
  #    readOnly: true
  #  - name: nfs-volume
  #    mountPath: /nfs_data
​
  # key:value pairs defined below are configured
  # as ENV variables on all rest pod containers
  #extraEnvs:
  #  - KEY1: value1
  #  - KEY2: value2
  
  # Config ingress, be sure to set the url to where you want to expose the api
  ingress:
    annotations:
      # Configure any needed annotations. For instance if you are using a different ingress besides nginx set that here
      kubernetes.io/ingress.class: nginx
    url:
      # REQUIRED: Change this to the hostname you'd like the API service to be at
      - api.tiledb.example.com
    # optional TLS
    tls: []
    #  - secretName: chart-example-tls
    #    hosts:
    #      - chart-example.local
​
  restConfig:
    # REQUIRED: Set the private dockerhub registry credentials, these are the same as the `imageCredentials` above
    ContainerRegistry:
      DockerhubUserName: "tiledbdocker"
      DockerhubPassword: ""
​
    # REQUIRED: Set the signing secret for api tokens, this should be a secure value
    # We recommend creating a random value with `openssl rand -hex 32`
    TokenSigningSecret: "Secret"
    # REQUIRED: This is needed for the TileDB Jupyterlab Prompt User Options extension
    CorsAllowedOrigins:
      - "https://jupyterhub.tiledb.example.com"
    # REQUIRED: Define supported storage types and locations, if you want to use NFS
    # enable "local"
    StorageLocationsSupported:
      - "s3"
      #- "local"
      #- "hdfs"
      #- "azure"
      #- "gcs"
      
    ArraySettings:
      # When enabled, AWS credentials will be auto-discovered
      # from the Environment, config file, EC2 metadata etc.
      AllowS3NoCredentials: false
      
    Email:
      # Should users be required to confirm their email addresses
      # By default email confirmation is disabled as this requires a working SMTP setup
      DisableConfirmation: False
      # REQUIRED: The UI Server address is used for sending a link to the reset password email
      UIServerAddress: "https://console.tiledb.example.com"
      # Email Accounts
      Accounts:
        Noreply: "[email protected]"
        Admin: "[email protected]"
​
    # REQUIRED: Configure main database. It is recommended to host a MariaDB or MySQL instance outside of the kubernetes cluster
    Databases:
      # `main` is a required database configuration
      main:
        Driver: mysql
        Host: "{{ .Release.Name }}-mariadb.{{ .Release.Namespace }}.svc.cluster.local"
        Port: 3306
        Schema: tiledb_rest
        Username: tiledb_user
        Password: password
​
    # Set log level, 1=Panic, 2=Fatal, 3=Error, 4=Warning, 5=Info, 6=Debug
    LogVerbosity: 4
​
    # LDAP settings. Enable and configure if you wish to allow LDAP for user account login
    # Ldap:
    #   Enable: false
    #   EnableTLS: false
    #   Hosts:
    #     - ldap.example.com
    #   Port: 389
    #   HostsTLS:
    #     - ldap.example.com
    #   PortTLS: 389
    #   BaseDN: DC=ldaplab,DC=local
    #   UserDN: CN=tiledb,CN=Users,DC=ldaplab,DC=local
    #   # can be set via config or env variable (TILEDB_REST_LDAP_PASSWORD)
    #   # Setting via ENV is recommended.
    #   #PASSWORD: ""
    #   CommonNames:
    #     - Users
    #     - IT
    #     - Managers
    #   # OPENLDAP
    #   # Attributes:
    #   #   email: mail
    #   #   name: givenName
    #   #   username: uid
    #   Attributes:
    #     email: mail
    #     name: name
    #     username: userPrincipalName
    
    # Configure TLS settings. If you wish to use TLS inside k8s
    #Certificate:
      # Absolute path to certificate
      #CertFile: ""
      # Absolute path to private key
      #PrivateKey: ""
      # TLS Minimum Version options
      # 0x0301 #VersionTLS10
      # 0x0302 #VersionTLS11
      # 0x0303 #VersionTLS12
      # 0x0304 #VersionTLS13
      #MinVersion: 0x0304
      # TLS 1.0 - 1.2 cipher suites. Leaving empty will enable all
      #TLS10TLS12CipherSuites:
        # - 0x0005 #TLS_RSA_WITH_RC4_128_SHA
        # - 0x000a #TLS_RSA_WITH_3DES_EDE_CBC_SHA
        # - 0x002f #TLS_RSA_WITH_AES_128_CBC_SHA
        # - 0x0035 #TLS_RSA_WITH_AES_256_CBC_SHA
        # - 0x003c #TLS_RSA_WITH_AES_128_CBC_SHA256
        # - 0x009c #TLS_RSA_WITH_AES_128_GCM_SHA256
        # - 0x009d #TLS_RSA_WITH_AES_256_GCM_SHA384
        # - 0xc007 #TLS_ECDHE_ECDSA_WITH_RC4_128_SHA
        # - 0xc009 #TLS_ECDHE_ECDSA_WITH_AES_128_CBC_SHA
        # - 0xc00a #TLS_ECDHE_ECDSA_WITH_AES_256_CBC_SHA
        # - 0xc011 #TLS_ECDHE_RSA_WITH_RC4_128_SHA
        # - 0xc012 #TLS_ECDHE_RSA_WITH_3DES_EDE_CBC_SHA
        # - 0xc013 #TLS_ECDHE_RSA_WITH_AES_128_CBC_SHA
        # - 0xc014 #TLS_ECDHE_RSA_WITH_AES_256_CBC_SHA
        # - 0xc023 #TLS_ECDHE_ECDSA_WITH_AES_128_CBC_SHA256
        # - 0xc027 #TLS_ECDHE_RSA_WITH_AES_128_CBC_SHA256
        # - 0xc02f #TLS_ECDHE_RSA_WITH_AES_128_GCM_SHA256
        # - 0xc02b #TLS_ECDHE_ECDSA_WITH_AES_128_GCM_SHA256
        # - 0xc030 #TLS_ECDHE_RSA_WITH_AES_256_GCM_SHA384
        # - 0xc02c #TLS_ECDHE_ECDSA_WITH_AES_256_GCM_SHA384
        # - 0xcca8 #TLS_ECDHE_RSA_WITH_CHACHA20_POLY1305_SHA256
        # - 0xcca9 #TLS_ECDHE_ECDSA_WITH_CHACHA20_POLY1305_SHA256
      # TLS 1.3 cipher suites. Leaving empty will enable all
      #TLS13CipherSuites:
        # - 0x1301 #TLS_AES_128_GCM_SHA256
        # - 0x1302 #TLS_AES_256_GCM_SHA384
        # - 0x1303 #TLS_CHACHA20_POLY1305_SHA256
      #PreferServerCipherSuites: false
      # CurveID is the type of a TLS identifier for an elliptic curve
      # Leaving empty will enable all
      #CurveID:
        # - 23 #CurveP256 CurveID
        # - 24 #CurveP384 CurveID
        # - 25 #CurveP521 CurveID
        # - 29 #X25519
    
​
  # It is not recommend to run the database inside k8s for production use, but it is helpful for testing
  mariadb:
    # Set to true if you wish to deploy a database inside k8s for testing
    enabled: false
    image:
      repository: bitnami/mariadb
      tag: 10.5.8
      pullPolicy: IfNotPresent
    auth:
      # Auth parameters much match with the restConfig.Databases.main above
      database: tiledb_rest
      username: tiledb_user
      password: password
      rootPassword: changeme
    primary:
      # Enable persistence if you wish to save the database, again running in k8s is not recommend for production use
      persistence:
        enabled: false
      # Set security context to user id of mysqld user in tiledb-mariadb-server
      podSecurityContext:
        enabled: true
        fsGroup: 999
      containerSecurityContext:
        enabled: true
        runAsUser: 999
​
####################################
# TileDB Cloud UI Console settings #
####################################
tiledb-cloud-ui:
  # Service Account to run deployment under
  # Change this if you have different RBAC requirements
  serviceAccountName: default
​
  # The autoscaling of the service can be adjusted if required
  # The following settings are the recommended defaults
  autoscaling:
    enabled: true
    minReplicas: 2
    maxReplicas: 300
    targetCPUUtilizationPercentage: 80
    targetMemoryUtilizationPercentage: 50
​
  # REQUIRED: set the url of the jupyterhub server
  config:
    JupyterhubURL: "https://jupyterhub.tiledb.example.com"
​
  # REQUIRED: Config ingress, be sure to set the hostname to where you want to expose the UI
  ingress:
    enabled: true
    annotations:
      # Configure any needed annotations. For instance if you are using a different ingress besides nginx set that here
      kubernetes.io/ingress.class: nginx
    # REQUIRED: Set URL for web console
    url: 
      - console.tiledb.example.com
    # optional TLS
    tls: []
​
#########################################
# TileDB Cloud Hosted Notebook Settings #
#########################################
jupyterhub:
  proxy:
    # REQUIRED: Set a signing secret here with `openssl rand -hex 32`
    secretToken: "Secret"
  # The pre-puller is used to to ensure the docker images for notebooks are prepulled to each node
  # This can improve notebook startup time, but add additional storage requirements to the nodes
  # If you wish to use dedicated k8s node groups for notebooks, see:
  # https://zero-to-jupyterhub.readthedocs.io/en/0.8.2/optimization.html?highlight=labels#using-a-dedicated-node-pool-for-users
  prePuller:
    hook:
      enabled: false
    continuous:
      # NOTE: if used with a Cluster Autoscaler, also add user-placeholders
      enabled: false
​
  scheduling:
    # You can enable at least one warm instance for users by enabling the userPlaceholder
    userPlaceholder:
      enabled: false
      replicas: 1
    # Disable podPriority, it is only useful if userPlaceholders are enabled
    podPriority:
      enabled: false
​
  singleuser:
    # REQUIRED: Set the private registry credentials, these are the same as the `imageCredentials` above
    imagePullSecret:
      username: "tiledbdocker"
      password: ""
    startTimeout: 900
    # Set the size of the user's persisted disk space in notebooks
    storage:
      capacity: 2G
     # JupyterHub expects the Kubernetes Storage Class to be configured
     # with "volumeBindingMode: Immediate" and "reclaimPolicy: Retain".
     # If your default Storage Class does not support this, you can
     # create a new one and configure it bellow.
     #dynamic:
     #  storageClass: "jupyterhub"
​
  hub:
    # REQUIRED: Set the private registry credentials, these are the same as the `imageCredentials` above
    imagePullSecret:
      username: "tiledbdocker"
      password: ""
    # REQUIRED: Set the domain for the REST API and the oauth2 service
    # it is likely you just need to replace `example.com` with your own internal domain
    # This should match the tiledb-cloud-rest settings above and the hydra settings below
    extraEnv:
      OAUTH2_AUTHORIZE_URL: "https://oauth2.tiledb.example.com/oauth2/auth"
      OAUTH2_USERDATA_URL: "https://oauth2.tiledb.example.com/userinfo"
      TILEDB_REST_HOST: "https://api.tiledb.example.com"
​
  ingress:
    enabled: true
    # REQUIRED: set the ingress domain for hosted notebooks
    hosts:
      - "jupyterhub.tiledb.example.com"
    annotations:
      # Configure any needed annotations. For instance if you are using a different ingress besides nginx set that here
      kubernetes.io/ingress.class: "nginx"
    tls:
    # REQUIRED: set the TLS information for hosted notebooks
      - hosts:
        - jupyterhub.tiledb.example.com
        secretName: jupyterhub-tls
​
  auth:
    type: custom
    custom:
      className: 'oauthenticator.tiledb.TileDBCloud'
      config:
        # REQUIRED: Set the oauth2 secret, this should be a secure value
        # We recommend creating a random value with `openssl rand -hex 32`
        client_secret: "Secret"
        # REQUIRED: Set the domain for the jupyterhub and the oauth2 service
        # it is likely you just need to replace `example.com` with your own internal domain
        # This should match the ingress settings above and the hydra settings below
        oauth_callback_url: "https://jupyterhub.tiledb.example.com/hub/oauth_callback"
        token_url: "https://oauth2.tiledb.example.com/oauth2/token"
        auth_url: "https://oauth2.tiledb.example.com/oauth2/auth"
        userdata_url: "https://oauth2.tiledb.example.com/userinfo"
    state:
      # REQUIRED: Set the jupyterhub auth secret for persistence, this should be a secure value
      # We recommend creating a random value with `openssl rand -hex 32`
      cryptoKey: "Secret"
​
########################################
# TileDB Cloud Oauth2 Service Settings #
########################################
hydra:
  hydra:
    # REQUIRED: Set the domain for the jupyterhub
    # it is likely you just need to replace `example.com` with your own internal domain
    # This should match the ingress settings above and the hydra settings below
    dangerousAllowInsecureRedirectUrls:
      - http://jupyterhub.tiledb.example.com/hub/oauth_callback
    config:
      # Optionally set the internal k8s cluster IP address space to allow non-ssl connections from
      # This defaults to all private IP spaces
      # tls:
        # allow_termination_from:
          # Set to cluster IP
          # - 172.20.0.0/12 
      secrets:
        # REQUIRED: Set the oauth2 secret, this should be a secure value
        # We recommend creating a random value with `openssl rand -hex 32`
        system: secret
        cookie: secret
      # REQUIRED: Set MariaDB Database connection, this defaults to the in k8s development settings. 
      # You will need to set this to the same connection parameters as the tiledb-cloud-rest section
      dsn: "mysql://tiledb_user:[email protected](tiledb-cloud-mariadb.tiledb-cloud.svc.cluster.local:3306)/tiledb_rest"
      urls:
        self:
          # REQUIRED: Update the domain for the oauth2 service and the web console ui
          # It is likely you can just replace `example.com` with your own internal domain
          issuer: "https://oauth2.tiledb.example.com/"
          public: "https://oauth2.tiledb.example.com/"
        login: "https://console.tiledb.example.com/oauth2/login"
        consent: "https://console.tiledb.example.com/oauth2/consent"
​
  # Configure ingress for oauth2 service
  ingress:
    public:
      annotations:
        # Configure any needed annotations. For instance if you are using a different ingress besides nginx set that here
        kubernetes.io/ingress.class: nginx
      hosts:
        # REQUIRED: set the ingress domain for oauth2 service
        - host: "oauth2.tiledb.example.com"
          paths: ["/"]
      tls:
        # REQUIRED: set the TLS information for oauth2 service
        - hosts:
            - "oauth2.tiledb.example.com"
          secretName: hydra-tls
​
######################
# Ingress Controller #
######################
ingress-nginx:
  # This is provided for ease of testing, it is recommend to establish your own ingress which fits your environment
  enabled: false
  ## nginx configuration
  ## Ref: https://github.com/kubernetes/ingress/blob/master/controllers/nginx/configuration.md
  ##
  controller:
    name: controller
    autoscaling:
      enabled: true
      minReplicas: 2
​
    config:
      use-proxy-protocol: "true"
      log-format-escape-json: "true"
      log-format-upstream: '{ "time": "$time_iso8601", "remote_addr": "$proxy_protocol_addr", "x-forward-for": "$proxy_add_x_forwarded_for", "request_id": "$req_id", "remote_user": "$remote_user", "bytes_sent": $bytes_sent, "request_time": $request_time, "status": $status, "vhost": "$host", "request_proto": "$server_protocol", "path": "$uri", "request_query": "$args", "request_length": $request_length, "duration": $request_time, "method": "$request_method", "http_referrer": "$http_referer", "http_user_agent": "$http_user_agent" }'
      # Set timeouts to 1 hour
      proxy-send-timeout: "3600"
      proxy-read-timeout: "3600"
      send-timeout: "3600"
      client-max-body-size: "3076m"
      proxy-body-size: "3076m"
      proxy-buffering: "off"
      proxy-request-buffering: "off"
      proxy-http-version: "1.1"
​
    ingressClass: nginx
​
    ## Allows customization of the external service
    ## the ingress will be bound to via DNS
    publishService:
      enabled: true
​
    service:
      annotations:
        # Set any needed annotations. The default ones we have set are for aws ELB nginx
        service.beta.kubernetes.io/aws-load-balancer-proxy-protocol: '*'
        # Set aws-load-balancer-internal to allow all traffic from inside
        # the vpc only, the -internal makes it not accessible to the internet
        service.beta.kubernetes.io/aws-load-balancer: '0.0.0.0/0'
        # Set timeout to 1 hour
        service.beta.kubernetes.io/aws-load-balancer-connection-idle-timeout: '3600'
​
      ## Set external traffic policy to: "Local" to preserve source IP on
      ## providers supporting it
      ## Ref: https://kubernetes.io/docs/tutorials/services/source-ip/#source-ip-for-services-with-typeloadbalancer
      externalTrafficPolicy: "Local"
​
      type: LoadBalancer
​
Installing TileDB Cloud
Once you have created the values.yaml file you can install TileDB Cloud by running the following helm command.
helm install \
--namespace tiledb-cloud \
--values values.yaml \
tiledb-cloud \
tiledb/tiledb-cloud-enterprise
Validating Installation
After you have installed TileDB Cloud you can verify the installation works by performing the following procedure.
Creating an Account
First step is to login to the web UI. The URL is dependent on your installation, in the values.yaml you should have replaced console.tiledb.example.com with the domain to access it on. Navigate in your web browser and create an account.
This step has verified that both the TileDB Cloud UI and TileDB Cloud REST components are working.
Creating your First Array
Now that you have an account we will create your first array. This array will show you that creating, writing and reading it functioning as well as give you an array and a task to view in the UI.
For this section we will use a python script. This script will create, write to and read from an array. Please note there are two sections where you need to adjust the configuration for your TileDB Cloud instance and set the array storage location.
Prerequisites
This section requires the TileDB-Py api installed. You can get this from pip or conda. Once you have TileDB-Py, copy the following script to check_installation.py and modify the first few lines as required.
Python
Python
import numpy as np
import sys
import tiledb
​
# username/password for TileDB Cloud instance
# Note you could also use an api token, which is generally preferred, however
# for simplcity of the example we'll use username/password combo here
username = ""
password = ""
# Where should the array be stored? This can be a object store,
# or a path inside the rest server where a nfs server is mounted
storage_path = "file:///nfs/tiledb_arrays/example"
array_uri = "tiledb://{}/{}/quickstart_sparse".format(username, storage_path)
​
# Set the host to your TileDB Cloud host
host = "http://api.tiledb.example.com"
​
ctx = tiledb.Ctx({"rest.username": username, "rest.password": password, "rest.server_address": host})
​
def create_array():
    # The array will be 4x4 with dimensions "rows" and "cols", with domain [1,4].
    dom = tiledb.Domain(
        tiledb.Dim(name="rows", domain=(1, 4), tile=4, dtype=np.int32, ctx=ctx),
        tiledb.Dim(name="cols", domain=(1, 4), tile=4, dtype=np.int32, ctx=ctx),
        ctx=ctx
    )
​
    # The array will be sparse with a single attribute "a" so each (i,j) cell can store an integer.
    schema = tiledb.ArraySchema(
        domain=dom, sparse=True, attrs=[tiledb.Attr(name="a", dtype=np.int32, ctx=ctx)],
        ctx=ctx
    )
​
    # Create the (empty) array on disk.
    tiledb.SparseArray.create(array_name, schema)
​
​
def write_array():
    # Open the array and write to it.
    with tiledb.SparseArray(array_name, mode="w", ctx=ctx) as A:
        # Write some simple data to cells (1, 1), (2, 4) and (2, 3).
        I, J = [1, 2, 2], [1, 4, 3]
        data = np.array(([1, 2, 3]))
        A[I, J] = data
​
​
def read_array():
    # Open the array and read from it.
    with tiledb.SparseArray(array_name, mode="r", ctx=ctx) as A:
        # Slice only rows 1, 2 and cols 2, 3, 4.
        data = A[1:3, 2:5]
        a_vals = data["a"]
        for i, coord in enumerate(zip(data["rows"], data["cols"])):
            print("Cell (%d, %d) has data %d" % (coord[0], coord[1], a_vals[i]))
​
​
create_array()
write_array()
read_array()
Run this script with:
python check_installation.py
If this script ran and printed out the output, then your installation is working successfully for creating, reading and writing TileDB arrays.
​
Viewing Array in the Web Console
The newly created array, quickstart_sparse should now be viewable in the web console. If you navigate to the arrays page you will see it listed.
Upgrades
When new releases of TileDB Cloud Enterprises are announced you can easily upgrade your installation by first updating the helm repository:
helm repo update tiledb
After the repository is updated you can run the helm upgrade:
helm upgrade --install \
--namespace tiledb-cloud \
--values values.yaml \
tiledb-cloud \
tiledb/tiledb-cloud-enterprise
​
Solutions - Previous
TileDB Cloud Enterprise
MapProxy Installation
Last updated 3 days ago