🚀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:

• Migration between v2 and v3 is not stable.

• 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.

NOTE: This guide helps you deploy a simple "one-shot" "all-in-one" Toucan Stack, which might not be suitable for production.

We heavily recommend in using an external PostgreSQL database as the one embedded might not be suitable for production:

• Please follow the following guide to connect to your external database: Toucan - External Database

• If you still wish to deploy PostgreSQL inside Kubernetes, we recommend using CloudNativePG:

  • Supports failover and multiple standbys replicas.

  • Supports backups and restores.

  • Supports migrating data from another PostgreSQL instance.

  • Supports audit log, monitoring...

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

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/

# 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>"

Replace <username> and <password> with your credentials.

3

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

shell: /work/

# --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>"

Replace <License> with your Curity license, extracted from the json. It should start with ey....

4

Assuming the DNS is properly configured, and the URLs https//demo.toucantoco.test and https://auth-demo.toucantoco.test are accessible publicly, we'll use cert-manager to generate TLS certificates.

yaml: /work/values.override.yaml

global:
  # Configure the persistence of the stack.
  defaultStorageClass: standard
  # Configure the public endpoint of the stack.
  hostname: demo.toucantoco.test
  # Use the Quay credentials
  imagePullSecrets:
    - dockerconfigjson

canopee:
  ingress:
    enabled: true
    # Use the Nginx Ingress controller
    ingressClassName: nginx
    annotations:
      # Use the cert-manager cluster issuer
      cert-manager.io/cluster-issuer: http01
    tls: true

curity:
  config:
    # Use the deployed license
    license:
      secretName: curity-secret
      secretKey: CURITY_LICENSE_KEY

  runtime:
    ingress:
      enabled: true
      ingressClassName: nginx
      hostname: auth-demo.toucantoco.test
      annotations:
        cert-manager.io/cluster-issuer: http01
      path: /
      tls: true

  admin:
    ingress:
      enabled: true
      ingressClassName: nginx
      hostname: auth-demo.toucantoco.test
      path: /admin
      tls: true

5

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.override.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.

6

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

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