CrateDB Edge

Crate.io is pleased to announce CrateDB Edge, the hybrid cloud database solution integrating CrateDB clusters and the CrateDB Cloud software stack with on-premise or customer-controlled cloud infrastructure.

The process of getting CrateDB Edge running is far easier than it may seem, thanks to the support for Edge deployment built into the CrateDB Cloud Console, our own web UI. Even so, there are some steps involved, and some requirements have to be met in order for it to work. This tutorial therefore serves as an end-to-end walkthrough of the process and of these prerequisites.

Table of contents

Disclaimer

CrateDB Edge is currently in public beta. CrateDB Edge and related services are provided on an “as is” basis and may change at any time. Crate.io provides no guarantees or warrant regarding the usability or performance of CrateDB Edge. The CrateDB Cloud Service Level Agreement (SLA) is expressly disclaimed for the use of CrateDB Edge and related services. By using CrateDB Edge, you agree to these terms and conditions.

Should you find any errors, bugs, or functionality problems while using the CrateDB Edge public beta, please let us know via our contact page or our support email.

Prerequisites

Certain hardware and software specifications must be met in order to make use of CrateDB Edge. The most important of these is that you must provide a working Kubernetes cluster, one that meets the following requirements:

  • It must contain at least three nodes (for high availability). You can also run development workloads on a single-node cluster. Note, however, that you will only be able to provision single-node CrateDB “clusters”;

  • Sufficient CPU per node to run the CrateDB Cloud software stack and the OS (we recommend at least 4 CPU cores for reliable performance);

  • A Kubernetes version > 1.15;

  • A Kubernetes load balancer for accessing CrateDB Clusters;

  • A storage class for persistent data.

Beyond this, using the CrateDB Cloud stack requires creating a CrateDB Cloud account and an organization, which will become the owner of the Edge region in which the cluster can be deployed. One must also access the CrateDB Cloud Console in order to deploy the cluster itself, using the provided script. These steps will be explained below.

Some Kubernetes knowledge, especially regarding networking and storage, is recommended when using CrateDB Edge, especially when using it as-is. If you’re uncertain, you may benefit from using CrateDB Edge in combination with tools as described at the end of this tutorial.

Note

A special note about bare metal Kubernetes clusters: CrateDB Edge should work on any bare metal cluster, but the CrateDB instances running within require a load balancer for outside access. If you do not have a load balancer (for example MetalLB), you can still access the CrateDB clusters within, but you will need to figure out the node ports to use.

Sign up

To use the CrateDB Cloud software, you must first sign up. Follow the steps outlined in this tutorial to do so.

Create an organization

When you first log in to the CrateDB Cloud Console after having created an appropriate account, you will arrive at the Organization overview page. Here you will be prompted to create an organization.

CrateDB Console organization creation screen

Fill out the name of the organization and click the Create organization button. After a short moment, the organization will be created and you can proceed.

You will be taken to the Subscriptions tab of the Organization overview page. You will be prompted to create a new subscription. However, for the purposes of CrateDB Edge deployment, you want to deploy directly into a given region, either one hosted by a cloud provider or a custom region of your own. (Both routes will be explained here.) To do so, go to the Regions tab in the same overview.

Create a custom region

In the Regions tab, it is possible to create a custom region. You will want to do this if you are hosting your cluster locally and are not relying on existing cloud providers to host your database infrastructure.

The Regions tab shows an overview of regions hosted by cloud providers as well as the option to create your own.

CrateDB Console regions screen

To create a custom region, simply fill out a name for the region and click on the Create edge region button.

Once you have done so, it will show your custom region.

CrateDB Console custom region screen

A preconfigured script will appear in the custom region field that you have just created. To proceed, open your local CLI and follow the steps in the next section of the tutorial. (You may want to keep the CrateDB Cloud Console open in your browser in the meantime.)

Apply the script

You can use the copy function provided in the custom region field to copy the script into your own CLI. Simply paste it there and execute the script. The script will check whether your local setup conforms to the prerequisites listed above. If one or more prerequisites fail, the script will notify you of this, and you will have to install them to proceed. (We recommend Helm for tracking and installing dependencies on Kubernetes.)

Note

You must have wget installed for the script to function.

Manifest and verification

Once you satisfy the prerequisites, the script will ask for your confirmation to install CrateDB Edge. Type Y or y to continue. The script will then download the manifest files for the CrateDB Edge service and apply them.

In the final stage, the script will loop over the services and check their availability. It continues doing this until all required services have become available. Note that this may take some time, which depends among other things on how fast a certificate can be issued.

Help and parameters

Use the --help parameter to find an overview of the available parameters for the script.

The parameters are defined as follows:

Usage:
cratedb-cloud-edge.sh <token> [options]

Here <token> represents the installation token provided on region creation,
and the [options] are the optional parameters as shown below.

Options:
  --base-url: The URL the manifest should be fetched from
  -d, --debug: Displays a lot of debug information
  --dry-run: Will not apply the downloaded manifest file. This can be used
  for checking the manifest file (edge-manifest.yaml) before applying it.
  -m, --max-execution-time (600): Maximum time in seconds the script should
  run
  --run-prerequisites: Will only run the prerequisites check
  --run-validation: Will only run the post-install validation

Once the services are up and running, the script will report: “Successfully validated installation”. At this point, you can return to the CrateDB Cloud Console.

In the CrateDB Cloud Console you can now deploy a cluster from within your custom Edge region. Go to the Regions tab of the Organization overview to find your custom region and deploy your cluster from there. This will take you to the cluster configuration screen.

Configure the cluster

Configuration

Next, go through the cluster configuration process. You will see your custom Edge region is selected, so no region selection is necessary. You can move directly to the cluster configuration. You can configure your desired hardware values for CPU, RAM, and storage per node manually in the panel provided, as well as the number of nodes you want in your cluster.

Cluster configuration panels for CrateDB Edge

On the right the cluster scale overview shows the total hardware values for the cluster. This is simply the number of nodes you have chosen, multiplied by the values per node you have defined.

At the bottom of the deployment screen you can configure your account settings. Since you have already created an organization, it does not need to be set here. However, you can now define a project that the cluster can be deployed in, as well as the cluster name. You also determine the database username and password that you can use to access the cluster Admin UI later on.

Account settings menu

Note that the cluster name has certain validation requirements: it may contain only numbers, letters, and the dash symbol -. It must begin with a letter and end with a letter or a number, and must be at least three characters long.

You can also here define the backup location of your CrateDB Edge cluster. You have the option of either using the default backup location for CrateDB Cloud, which is managed by us, or use a custom backup location that is convenient to you. This has to be an S3 bucket or a location with an equivalent functionality. In the latter case, you can set the access key and secret here as well. You can test the connection as well; keep in mind that you cannot proceed with a custom backup location unless the connection to it is functional.

Click Next at the bottom right to proceed.

Billing

Finally, you will be taken to a new screen where you can fill out your billing information. Our payment processing is supported by Stripe. At the bottom right you can find the cards accepted by Crate.io. When you have filled out the necessary information, click Deploy below it to deploy your cluster. Do not forget to accept financial authorization by ticking the box at the bottom.

Billing information screen

The payment and billing information you have submitted will be saved in the Billing tab of the Organization overview screen in the CrateDB Cloud Console (i.e., the fifth tab from the left on the same screen you arrived at).

Finish up

You will now be returned to the CrateDB Cloud Console, but this time to the Cluster overview page. A popup menu will remind you of the username and password you selected for connecting to the cluster. Make sure you copy this information to a safe place (e.g., a password manager), as it will not be retrievable past this point.

You can use the Cluster overview page to access your cluster via the Admin UI (see, however, the note below).

Note

If your Kubernetes cluster does not provide a load balancer with an external IP address, you will not be able to access your cluster from the CrateDB Cloud Console.

Use a cloud provider region

Besides creating your own custom region, it is also possible to use CrateDB Edge in combination with an existing cloud provider. To deploy a cluster in this way, follow the initial steps described above until you have created an organization. Then, go to the Regions tab and instead of creating a custom region, choose a cloud provider from the fields provided and click Deploy cluster. You will be referred to the subscription plan screen. Select your desired plan and proceed to the configuration wizard as described above.

Delete a custom region

In order to delete a custom region, click the trashcan icon at the bottom right of the custom region panel. A confirmation screen will appear warning that deletion of a custom region disables access to CrateDB Cloud for that region.

Deleting a custom region does not delete the resources inside that region. To also delete the resources inside the region, run the script provided in the deletion confirmation screen in your local CLI before confirming the deletion in the console. This will uninstall CrateDB Edge from your local Kubernetes cluster.

To finalize the deletion of the custom region, enter the name of your region into the form.

CrateDB Edge deletion confirmation screen

Install CrateDB Edge using tools

You can combine CrateDB Edge with external tools for ease of use, such as managed Kubernetes providers and self-hosted Kubernetes distributions. In the former category, we have tested AWS, Azure, Digital Ocean, and GCP with the CrateDB Edge stack, and for the latter the distributions described below. In the walkthroughs below, we provide by way of example a guide for using Digital Ocean as a managed Kubernetes provider with CrateDB Edge, and guides for two of the most common Kubernetes distributions: MicroK8s and K3s.

Note

These guides are provided as example scenarios only. Other managed Kubernetes providers or preconfigured Kubernetes distributions may also work with CrateDB Edge.

These are third-party tools and Crate.io is not responsible for them. That said, we have tested the instructions provided below for functionality. Users less familiar with customizing their Kubernetes stack on their own may find either of these approaches a practical solution for easier CrateDB Edge setup.

Digital Ocean

Below is a step-by-step guide to using Digital Ocean as a managed Kubernetes provider in combination with CrateDB Edge. The steps are merely examples of a process validated by us; other methods may work also. We provide this information for ease of use and to illustrate how to work with CrateDB Edge.

Signup

First you must sign up with Digital Ocean. On the Kubernetes page, click Sign up and make an account. Verify your email address to proceed. (Digital Ocean may also require a token pre-payment.)

Create Kubernetes cluster

Create a Kubernetes cluster using the Digital Ocean cloud interface, under “Manage”, then “Kubernetes”. When configuring the cluster, make sure to choose an option with sufficient hardware capacity. For example, when choosing the Basic machine type, use the Max plan for that type to ensure sufficient power. Then proceed to deploy the cluster.

Configuration

While the Kubernetes cluster is installing, use the link provided to locally download the configuration YAML file and note the local address of the file. Install kubectl if you have not done so already. Then point the Kubeconfig configuration path to where you stored the YAML file:

export KUBECONFIG=~<file source>

Subsequently, wait for the install to finish and check that the nodes are running as intended:

kubectl get nodes

Set up Edge region

Now, go to the CrateDB Cloud Console and create a custom CrateDB Edge region. Follow the steps outlined from the CrateDB sign up onwards to proceed. Run the script the CrateDB Cloud Console shows in the panel for the custom region you just created and install prerequisites as necessary.

Define storage class

Eventually, the script will indicate that there is no crate-premium storage class available. To define this storage class correctly, copy the default storage class Digital Ocean provides, then change the the name to crate-premium in the copied file. For example, using kubectl and Vim:

kubectl get sc do-block-storage -o yaml | grep -vi is-default-class | sed -e 's/name: do-block-storage/name: crate-premium/' | kubectl create -f -

Then re-run the script until it is successful.

Deploy Edge cluster

Finally, return to the CrateDB Cloud Console and click on Deploy cluster in the custom region when it is available. Follow the steps described above to proceed. At the end of the process, you should have a working CrateDB Edge install on Digital Ocean managed Kubernetes.

MicroK8s

Below is a full walkthrough of how to get CrateDB Edge up and running on MicroK8s. The steps are merely examples of a process validated by us; other methods may work also. We provide this information for ease of use and to illustrate how to work with CrateDB Edge.

Set up MicroK8s

Follow the instructions from the MicroK8s docs. For the purposes of this tutorial, we assume a snap-based distribution, such as Ubuntu. On this occasion, you’ll be setting up a three-node Kubernetes cluster. You can also use a single node for testing purposes if you wish. Regardless, the installation instructions must be run on every node you set up.

sudo snap install microk8s --classic --channel=1.21

sudo usermod -a -G microk8s $USER
sudo chown -f -R $USER ~/.kube

microk8s status --wait-ready
microk8s kubectl get nodes

alias kubectl='microk8s kubectl'

microk8s enable dns storage

Set up cluster

On one of the nodes, run the command to get joining instructions. This will print the command that you need to run on the other two nodes to create a Kubernetes cluster.

microk8s add-node

Join nodes to cluster

Now SSH into the two remaining nodes and run the command you received on the first node.

root@ub11:~# microk8s join <IP of first node>:25000/<cluster id>
Contacting cluster at <IP address>
Waiting for this node to finish joining the cluster...

Use a storage solution

The MicroK8s setup will require a storage solution. In this case, the tutorial shows how to do so using Longhorn, a distributed storage solution for Kubernetes. You can follow the Longhorn installation instructions as described below. (Other storage solutions for Kubernetes may work as well.)

First the installation:

kubectl apply -f https://raw.githubusercontent.com/longhorn/longhorn/v1.1.1/deploy/longhorn.yaml

Then you need to specify the root directory:

kubectl -n longhorn-system edit deployment longhorn-driver-deployer

- name: KUBELET_ROOT_DIR
value: /var/snap/microk8s/common/var/lib/kubelet

Set up Edge region

At this stage, you can create an Edge region via the CrateDB Cloud Console. Follow the steps outlined above from the CrateDB sign up onwards to proceed.

Run the script

Run the script with the following command:

wget -qO- https://console.cratedb.cloud/edge/cratedb-cloud-edge.sh > edge-installer.sh
chmod u+x edge-installer.sh
./edge-installer --dry-run  <token>

Note that dry-run provides, as the name suggests, a method to test the installation by generating the manifests that are going to be applied without applying them. This gives you an opportunity to verify them before the full install.

The <token> in question is the token you receive from the CrateDB Console Edge region field in the Regions tab of the Organization Overview. For more information on this section of the CrateDB Console, refer to our CrateDB Cloud Console overview.

With this, you should be ready to use CrateDB Edge via Microk8s.

K3S

Below is a full walkthrough of how to get CrateDB Edge up and running on K3S. The steps are merely examples of a process validated by us; other methods may work also. We provide this information for ease of use and to illustrate how to work with CrateDB Edge.

Set up K3S

A simple way to bootstrap the K3S setup is with k3sup. However, this tutorial assumes you will use K3S native, which offers more granularity. Also, this setup is suitable for a multi-node cluster.

First you have to set up the master node:

export INSTALL_K3S_VERSION="v1.19.10+k3s1"
curl -sfL https://get.k3s.io | sh -s - --disable=traefik

mkdir ~/.kube
cp /etc/rancher/k3s/k3s.yaml ~/.kube/config
export KUBECONFIG=~/.kube/config
kubectl config set-context default
kubectl get node -o wide

Next, get the token:

cat /var/lib/rancher/k3s/server/node-token

Note that the master node will operate both as a master and as a worker.

Join nodes to cluster

Next, you set up other worker nodes (as many as applicable to your use case):

export token=<token>
export INSTALL_K3S_VERSION="v1.19.10+k3s1"
curl -sfL https://get.k3s.io | K3S_URL="https://ub1:6443" K3S_TOKEN=$token sh -

Uninstall

If you need to uninstall, run:

/usr/local/bin/k3s-agent-uninstall.sh

Use a storage solution

The K3S setup for CrateDB Edge will require a storage solution. In this case, the tutorial shows how to do so using Longhorn, a distributed storage solution for Kubernetes. You can follow the Longhorn installation instructions as described below. (Other storage solutions for Kubernetes may work as well.)

First the installation:

kubectl apply -f https://raw.githubusercontent.com/longhorn/longhorn/v1.1.1/deploy/longhorn.yaml

Then you need to specify the root directory. Note that unlike in the Microk8s example above, you need to redirect the directory:

kubectl -n longhorn-system edit deployment longhorn-driver-deployer

    - name: KUBELET_ROOT_DIR
    value: /var/lib/rancher/k3s/agent/kubelet  ..... /var/lib/kubelet

Set up Edge region

At this stage, you can create an Edge region via the CrateDB Cloud Console. Follow the steps outlined above from the CrateDB sign up onwards to proceed.

Run the script

Run the script with the following command:

wget -qO- https://console.cratedb.cloud/edge/cratedb-cloud-edge.sh > edge-installer.sh
chmod u+x edge-installer.sh
./edge-installer --dry-run  <token>

Note that dry-run provides, as the name suggests, a method to test the installation by generating the manifests that are going to be applied without applying them. This gives you an opportunity to verify them before the full install.

The <token> in question is the token you receive from the CrateDB Console Edge region field in the Regions tab of the Organization Overview. For more information on this section of the CrateDB Console, refer to our CrateDB Cloud Console overview.

With this, you should be ready to use CrateDB Edge via K3S.

Feedback

How helpful was this page?