🚀Quick-Start Guide

Our self-hosted solution is currently in alpha and available to a limited group of customers. Features and setup options are subject to change. Interested in early access? Reach out to your Customer Success Manager to learn more, or contact [email protected].

Current limitations:

• S3 and the data execution service is not available at the moment. Data will be stored on Laputa's volume. Instant migration will be available when S3 and the data execution service is ready.

• Migration between v2 and v3 is not stable.

• The login page is still in development. Rolling updates has been enabled for the login page and may introduce issues.

• SAML2 is not supported at the moment. We recommend using SSO via OIDC instead.

If you notice unexpected behavior, do not hesitate to contact us through predefined channels:

• Slack (available during the alpha period)

• Your Customer Success Manager.

• [email protected].

This topic includes instructions for installing and running Toucan on Kubernetes using Helm Charts.

Helm is an open-source command line tool used for managing Kubernetes applications. It is a graduate project in the CNCF Landscape.

Before you begin

To install Toucan using Helm, ensure you have completed the following:

• Install a Kubernetes server on your machine (or use a managed Kubernetes). For information about installing Kubernetes, refer to Install Kubernetes.

In this guide, we will use the minikube cluster.

• Install the latest stable version of Helm. For information on installing Helm, refer to Install Helm.

• Install the latest stable version of kubectl. For information on installing kubectl, refer to Install kubectl.

• Have access to the Toucan Toco's Quay registry. If you don't have access, contact us using our mail address: [email protected].

• Have a Curity Community Edition license. You can sign up for one here.

• Install cert-manager on the Kubernetes Cluster to generate TLS certificates. For information on installing cert-manager, refer to Install cert-manager.

• An Ingress controller setup on the Kubernetes Cluster. For information on installing an Ingress controller, refer to Install an Ingress controller. We'll assume you are using the Nginx Ingress controller.

If you are using minikube, please enable the ingress addon and follow the steps described in "Ingress DNS | minikube".

• A DNS set up for the Toucan Toco's domain which points to your Ingress controller Load Balancer IP. For this example, we will use demo.toucantoco.test as the main domain, and auth-demo.toucantoco.test as the authentication domain.

If you are using minikube, please enable the ingress-dns addon and follow the steps described in "Ingress DNS | minikube".

Install Toucan using Helm

Overview

How Helm is used

You can simply consider the "Toucan Stack" Helm Chart as a single package.

To customize the chart, Helm can overrides the default values file by specifying additional values files. You can read more about it in the official Helm documentation.

Login to the Toucan Toco's Quay registry

We are assuming you have a terminal open in /work/ directory. You can open your terminal in any directory, but make sure you are in a directory reserved for this project.

To sign in to the Quay registry with Helm, run the following command:

shell: /work/

helm registry login quay.io

To fetch your Quay credentials, you can generate an encrypted password on Quay.io:

1. Go to Account Settings.

2. Go to the "Gear Menu" on the left side menu.

3. Click on "Generate Encrypted Password"

   

   Fetching Quay encrypted password

(optional) Use minikuge sample configuration

Run the following command:

shell: /work/

helm pull oci://quay.io/toucantoco/charts/toucan-stack

This command will download the latest Helm Charts from the Toucan Toco's Quay registry.

Extract the values.minikube.yaml from the tgz file which will help define the configuration for the Toucan Stack Helm Charts:

shell: /work/

# -x: extract
# -v: verbose
# -z: compressed
# -f <file>: file
# --strip-components: remove leading directories (toucan-stack/values.minikube.yaml -> values.minikube.yaml)
# toucan-stack/values.minikube.yaml: file to extract inside the archive
tar -xvzf toucan-stack-*.tgz --strip-components=1 toucan-stack/values.minikube.yaml

yaml: /work/values.minikube.yaml (extract)

global:
  defaultStorageClass: standard
  hostname: demo.toucantoco.test
  imagePullSecrets:
    - dockerconfigjson

extraDeploy:
  - |
    apiVersion: cert-manager.io/v1
    kind: Issuer
    metadata:
      name: 'test-selfsigned-issuer'
    spec:
      selfSigned: {}

# ...

If you are not using minikube, swap the value of defaultStorageClass with the name of the storage class given by your cloud provider, or Kubernetes distribution.

If you are not using ingress-nginx as your ingress controller, swap the value of ingressClassName with the name of your ingress controller.

Install Toucan

After you have set up Helm, you can start to deploy Toucan on your Kubernetes cluster.

When you deploy the Toucan Stack Helm charts, use a separate namespace instead of relying on the default namespace. The default namespace might already have other applications running, which can lead to conflicts and other potential issues.

When you create a new namespace in Kubernetes, you can better organize, allocate, and manage cluster resources. For more information, refer to Namespaces.

1

To create a namespace, run the following command:

shell: /work/

kubectl create namespace toucan

2

Send your Quay credentials to Kubernetes by running the following command:

shell: /work/

# Replace <username> and <password> with your credentials
# docker-registry: The type of secret to create.
# --namespace: The namespace to create the secret in.
# dockerconfigjson: The name of the secret to create.
# --docker-server: The server address of the registry.
# --docker-username: The username for the registry.
# --docker-password: The password for the registry.
kubectl create secret docker-registry --namespace toucan dockerconfigjson --docker-server=quay.io --docker-username="<username>" --docker-password="<password>"

3

Send your Curity credentials to Kubernetes by running the following command:

shell: /work/

# Replace <License> with your Curity license, extracted from the json. It should start with `ey...`
# --namespace: The namespace to create the secret in.
# curity-secret: The name of the secret to create.
# --from-literal: The key and value of the secret to create.
kubectl create secret generic --namespace toucan curity-secret --from-literal=CURITY_LICENSE_KEY="<License>"

4

Deploy Toucan by running the following command:

shell: /work/

# upgrade: The command to upgrade the Toucan Stack Helm charts.
# --install: And install the Toucan Stack Helm charts if they are not already installed.
# --namespace: The namespace to deploy the Toucan Stack Helm charts in.
# toucan-stack: The name of the deployment.
# oci://quay.io/toucantoco/charts/toucan-stack: The Helm chart to deploy.
# --values: The path to the values file, which overrides the default configuration for the Toucan Stack Helm charts.
helm upgrade --install toucan-stack oci://quay.io/toucantoco/charts/toucan-stack \
   --namespace toucan \
   --values values.minikube.yaml

If the installation fails with:

Error: INSTALLATION FAILED: failed post-install: 1 error occurred:
        * timed out waiting for the condition

You should check the health of the deployment. Use kubectl get <deployments/statefulsets/pods> -n toucan to check the status of the deployment. And use kubectl logs <pod-name> -c <container-name> -n toucan to check the logs of the deployment.

We highly recommend using a Kubernetes GUI for troubleshooting like for example Headlamp.

5

To get the Admin password, run the following command:

shell: /work/

kubectl get secret --namespace toucan toucan-stack-auth -o jsonpath='{.data.toucan-admin-password}' | base64 --decode

6

Since this deployment uses a private CA, you need to add the CA certificate to your browser's certificate store.

Fetch the CA certificate from the cluster and add it to your browser's certificate store:

shell: /work/

kubectl get secret --namespace toucan demo.toucantoco.test-cert -o jsonpath='{.data.tls\.crt}' | base64 --decode > demo.toucantoco.test.crt

And import the file demo.toucantoco.test.crt into your browser's certificate store. See this guide.

7

Navigate to https://demo.toucantoco.test in your browser to access Toucan.

8

Login with the Admin credentials. Enter [email protected] for the username. For the password, use the one you got from the previous step.

What's next?

Now that you have a working Toucan deployment, you might be interested in configuring this environment for production use. Feel free to check out:

⚙️Configure email notifications⚙️Configure HTTPS🔑Configure OIDC authentication⚙️Tuning resources⚙️Configure persistence