Install on k3s

k3s is a lightweight Kubernetes distribution that is ideal for running on your local computer. This guide explains how to install Drasi on k3s using k3d, a lightweight wrapper to run k3s in docker. It is an easy to use option for doing local development and testing of Drasi, Drasi extensions, and Drasi-based solutions.

Prerequisites

This guide assumes you are familiar with Kubernetes and know how to use kubectl to manage a Kubernetes cluster.

On the computer where you will install k3d/k3s, you need to install the following software:

• kubectl
• docker

Install k3d

The k3d installation instructions describe multiple ways to install k3d on macOS, Windows, and Linux. The options include downloading binaries, using a package manager, and building from source. Review the available installation options and use one to install k3d on your computer before continuing.

Create a k3s Cluster

To create a k3s cluster, open a terminal or command prompt and run the following command:

k3d cluster create

During the cluster creation, you will see output similar to this:

INFO[0000] Prep: Network
INFO[0000] Created network 'k3d-k3s-default'
INFO[0000] Created image volume k3d-k3s-default-images
INFO[0000] Starting new tools node...
INFO[0001] Creating node 'k3d-k3s-default-server-0'
INFO[0001] Pulling image 'ghcr.io/k3d-io/k3d-tools:5.7.4'
INFO[0002] Pulling image 'docker.io/rancher/k3s:v1.30.4-k3s1'
INFO[0003] Starting node 'k3d-k3s-default-tools'
INFO[0008] Creating LoadBalancer 'k3d-k3s-default-serverlb'
INFO[0010] Pulling image 'ghcr.io/k3d-io/k3d-proxy:5.7.4'
INFO[0014] Using the k3d-tools node to gather environment information
INFO[0014] Starting new tools node...
INFO[0014] Starting node 'k3d-k3s-default-tools'
INFO[0016] Starting cluster 'k3s-default'
INFO[0016] Starting servers...
INFO[0016] Starting node 'k3d-k3s-default-server-0'
INFO[0019] All agents already running.
INFO[0019] Starting helpers...
INFO[0019] Starting node 'k3d-k3s-default-serverlb'
INFO[0026] Injecting records for hostAliases (incl. host.k3d.internal) and for 3 network members into CoreDNS configmap...
INFO[0028] Cluster 'k3s-default' created successfully!
INFO[0028] You can now use it like this:
kubectl cluster-info

This will create a k3s cluster named k3d-k3s-default and set the current kubectl context to the new cluster. Now you can manage the k3s cluster using familiar Kubernetes management tools such as kubectl and the Kubernetes extension for Visual Studio Code.

Get the Drasi CLI

You will install Drasi on the k3s cluster using the Drasi CLI.

You can get the Drasi CLI for your platform using one of the following options:

• macOS
• Windows PowerShell
• Linux
• Binaries
• Build from Source

curl -fsSL https://raw.githubusercontent.com/drasi-project/drasi-platform/main/cli/installers/install-drasi-cli.sh | /bin/bash

iwr -useb "https://raw.githubusercontent.com/drasi-project/drasi-platform/main/cli/installers/install-drasi-cli.ps1" | iex

wget -q "https://raw.githubusercontent.com/drasi-project/drasi-platform/main/cli/installers/install-drasi-cli.sh" -O - | /bin/bash

This guide focuses on how to install Drasi on a k3s cluster and covers only a few features of the Drasi CLI. Refer to the Drasi CLI Command Reference for a complete description of the functionality it provides.

Install Drasi on the k3s Cluster

To install Drasi on the k3s cluster using all default settings, simply run the command:

drasi init

This will install the version of Drasi that matches the version of the Drasi CLI that you are using and will create the Drasi environment in the drasi-system namespace, which will be created if it doesn’t exist. The Drasi container images will be pulled from the main Drasi container registry located on ghcr.io.

The drasi init command gives you control over certain aspects of the install process and the configuration of the Drasi environment through these flags and argument:

• --dapr-runtime-version <version>: Specifies the Dapr runtime version to install. The default value is “1.10.0”.
• --dapr-sidecar-version <version>: Specifies the Dapr sidecar (daprd) version to install. The default value is “1.9.0”.
• --local: If set, the Drasi CLI will use locally available images to install Drasi instead of pulling them from a remote container registry.
• -n|--namespace <namespace>: Specifies the Kubernetes namespace to install Drasi into. This namespace will be created if it does not exist. The default value is “drasi-system”.
• --registry <registry>: Address of the container registry to pull Drasi images from. The default value is “ghcr.io”.
• --version <tag>: Container image version tag to use when pulling Drasi images. The default value is the version tag of the Drasi CLI, which is available through the drasi version command.

For example, to install Drasi 0.1.3 in the drasi-dev namespace, you would run the following command:

drasi init --version 0.1.3 -n drasi-dev

The following shows the output you would expect from a successful installation of Drasi 0.1.3:

Installing Drasi with version 0.1.3 from registry ghcr.io
ℹ Dapr not installed
✓ Dapr installed successfully
✓ Infrastructure deployed
  ✓ app=drasi-redis is online
  ✓ app=drasi-mongo is online
✓ Control plane is online
  ✓ drasi/infra=api is online
  ✓ drasi/infra=resource-provider is online
✓ Query container created
  ✓ Apply: QueryContainer/default: complete
  ✓ Wait QueryContainer/default online
✓ Default source providers created
  ✓ Apply: SourceProvider/PostgreSQL: complete
  ✓ Apply: SourceProvider/SQLServer: complete
  ✓ Apply: SourceProvider/CosmosGremlin: complete
✓ Default reaction providers created
  ✓ Apply: ReactionProvider/Debug: complete
  ✓ Apply: ReactionProvider/Debezium: complete
  ✓ Apply: ReactionProvider/EventGrid: complete
  ✓ Apply: ReactionProvider/Gremlin: complete
  ✓ Apply: ReactionProvider/Result: complete
  ✓ Apply: ReactionProvider/SignalR: complete
  ✓ Apply: ReactionProvider/StorageQueue: complete
  ✓ Apply: ReactionProvider/StoredProc: complete

Note that the Drasi installation also installs a number of dependencies, including:

• Dapr
• Redis
• Mongo DB.

If drasi init completes without error, the Drasi environment is ready for use and you can start to create Sources, Continuous Queries, and Reactions.

Troubleshooting Installation Problems

If any of installation steps fail, a check mark will appear next to the failed step and the installation process will abort. For example:

ℹ Dapr not installed
✓ Dapr installed successfully
✓ Infrastructure deployed
  ✗ Timed out waiting for app=drasi-redis
  ✗ Timed out waiting for app=drasi-mongo
✓ Control plane is online
  ✗ Timed out waiting for drasi/infra=api
  ✗ Timed out waiting for drasi/infra=resource-provider
●∙∙ Creating query container...
Error: drasi API not available

Sometimes, drasi init can fail due to transient errors, usually due to failed network connections or timeouts experienced while downloading and installing dependencies. In these situations you can simply rerun the same drasi init command and the Drasi CLI will attempt to complete the remaining incomplete steps.

To verify Dapr was installed successfully, you can check what Dapr pods are running using the command:

kubectl get pods -n dapr-system

Which should show output similar to this:

NAME                                     READY   STATUS    RESTARTS        AGE
dapr-dashboard-5cc65d985f-qzqbg          1/1     Running   0               10m
dapr-operator-5d98f57c86-kspwk           1/1     Running   0               10m
dapr-placement-server-0                  1/1     Running   0               10m
dapr-sentry-697bdc6cc4-xprww             1/1     Running   0               10m
dapr-sidecar-injector-56c4c4b485-n48bg   1/1     Running   0               10m

Deleting Drasi

To delete a Drasi environment that is installed in the default drasi-system namespace, run the command:

drasi uninstall

The Drasi CLI will delete the drasi-system namespace containing the Drasi environment. Everything in that namespace will be deleted and cannot be recovered, so the Drasi CLI will prompt you to confirm you want to uninstall with the following message:

Uninstalling Drasi
Deleting namespace:  drasi-system
Are you sure you want to uninstall Drasi from the namespace drasi-system? (yes/no)

Type yes and hit enter to proceed.

Once Drasi is successfully uninstalled you will see the following confirmation message:

Drasi uninstalled successfully

To force the uninstall to proceed without prompting you to confirm you can add the -y or --yes flag to the command:

drasi uninstall --yes

To delete a Drasi environment from a specific namespace, include the -n flag:

drasi uninstall -n drasi-dev

Deleting the k3s cluster

To delete the k3s cluster and everything it contains, including the Drasi environment, run this command:

k3d cluster delete

You will see the following output:

INFO[0000] Deleting cluster 'k3s-default'
INFO[0003] Deleting cluster network 'k3d-k3s-default'
INFO[0003] Deleting 1 attached volumes...
INFO[0003] Removing cluster details from default kubeconfig...
INFO[0003] Removing standalone kubeconfig file (if there is one)...
INFO[0003] Successfully deleted cluster k3s-default!