diff --git a/docs/index.md b/docs/index.md index d607595..c36392b 100644 --- a/docs/index.md +++ b/docs/index.md @@ -159,7 +159,6 @@ Networking & Connectivity API How Tos Croud CLI -tutorials/edge/index Reference ::: diff --git a/docs/tutorials/deploy/stripe.rst b/docs/tutorials/deploy/stripe.rst index 6e22e44..accedae 100644 --- a/docs/tutorials/deploy/stripe.rst +++ b/docs/tutorials/deploy/stripe.rst @@ -59,10 +59,6 @@ by selecting the "Request new region" button and filling out the form. .. image:: ../../_assets/img/deployment-region-request.png :alt: CrateDB Cloud Console Deployment New Region Request -If you are deploying an :ref:`Cloud on Kubernetes ` -cluster, you can choose your custom region by selecting the "Add a custom edge -region" link. - Compute ------- diff --git a/docs/tutorials/edge/custom-backup.md b/docs/tutorials/edge/custom-backup.md deleted file mode 100644 index adb57b7..0000000 --- a/docs/tutorials/edge/custom-backup.md +++ /dev/null @@ -1,40 +0,0 @@ -(edge-custom-backup)= -# Custom backup location - -This guide introduces a feature of CrateDB Cloud on Kubernetes that lets -users specify their backup location. This gives you full ownership and -control of your data when using CrateDB Cloud on Kubernetes. - -(edge-custom-backup-prereqs)= -## Prerequisites - -* This guide describes only the final deployment stage of the CrateDB - Cloud on Kubernetes cluster. For the full instructions, see either the - {ref}`Self-hosted Edge `, or the - {ref}`Managed Edge ` tutorials. -* The custom backup location only supports [Amazon S3 - bucket](https://aws.amazon.com/s3/) or S3-compatible storage. - -(edge-custom-backup-config)= -## Configuration - -If you're using an Amazon S3 bucket, you will need the Access Key ID -and the Secret Access Key of the user that has access to the bucket that -you want to backup your data to. - -If you're using non-Amazon S3 storage, you will also need to specify an -endpoint URL of the storage. - -![Custom backup location configuration](../../_assets/img/custom-backup-config.png) - -After you have put in your details, you can deploy the cluster. - -Your cluster will now automatically backup to your storage every hour. -You can also make a manual backup with [COPY TO -statement](https://crate.io/docs/crate/reference/en/5.0/sql/statements/copy-to.html). - -:::{note} -If you plan to do manual backups of certain files often, we encourage -you to enable the bucket versioning. That way, you can access older -revisions of the saved files. -::: diff --git a/docs/tutorials/edge/index.md b/docs/tutorials/edge/index.md deleted file mode 100644 index c1fb780..0000000 --- a/docs/tutorials/edge/index.md +++ /dev/null @@ -1,97 +0,0 @@ -(cloud-on-kubernetes)= -# CrateDB Cloud on Kubernetes - -**CrateDB Cloud on Kubernetes** is the hybrid cloud database solution -integrating CrateDB clusters and the CrateDB Cloud software stack with -on-premise or customer-controlled cloud infrastructure. - -## Introduction - -The CrateDB Cloud on Kubernetes concept is simple. You bring your own -Kubernetes infrastructure - whether in a production site, office, laboratory, -or local setup, or in your existing managed cloud infrastructure on AWS, -Azure, or GCP. - -Wherever it may be located, we provide the full experience of CrateDB -Cloud to that Kubernetes environment. You keep your existing -infrastructure setup and you get all the benefits of CrateDB Cloud on -top: from quick deployment to seamless scaling and easy cluster -management. - -(cloud-on-kubernetes-details)= -## Details - -The process of getting CrateDB Cloud on Kubernetes running is -supported by the CrateDB Cloud Console. - -Even so, there are some steps involved, and some requirements have to be -met in order for it to work. This section of the documentation intends -to serve as an end-to-end walkthrough of the corresponding process and -prerequisites. - -(cloud-on-kubernetes-tutorials)= -## Tutorials - -In these tutorials, we first introduce the signup and configuration -process for a local Kubernetes installation. Next, we explain the -process end-to-end for using AKS and EKS services. After that, we -outline the installation method for some lightweight Kubernetes -distributions, like K3s and Microk8s. - -Then, we explain how to set up a custom backup location, so you can keep -full ownership of your data backups. - -We also introduce a way to monitor your CrateDB Cloud on Kubernetes cluster -in the visualization tool Grafana coupled with Loki and Prometheus. - -::::{grid} 2 2 2 3 -:margin: 4 4 0 0 -:gutter: 1 - -:::{grid-item-card} {octicon}`info` Introduction -:link: edge-disclaimer -:link-type: ref -Find about about hardware and software prerequisites for -running CrateDB Cloud on Kubernetes. -::: - -:::{grid-item-card} {octicon}`people` Managed Kubernetes -:link: edge-providers -:link-type: ref -In this section, we provide more specific installation instructions -for some managed Kubernetes providers. -::: - -:::{grid-item-card} {octicon}`person` Self-hosted Kubernetes -:link: edge-self-hosted -:link-type: ref -In this section, we outline installation instructions for some -third-party supported self-hosted options. -::: - -:::{grid-item-card} {octicon}`package-dependencies` Custom backup location -:link: edge-custom-backup -:link-type: ref -This guide introduces a feature of CrateDB Cloud on Kubernetes -that lets users specify their backup location. -::: - -:::{grid-item-card} {octicon}`pulse` Monitoring -:link: edge-monitoring -:link-type: ref -Learn how to monitor CrateDB Cloud on Kubernetes using Prometheus, -Loki, and Grafana. -::: - -:::: - -:::{toctree} -:hidden: -:maxdepth: 1 - -Introduction -Managed Kubernetes options -Self-hosted Kubernetes -Custom backup location -Monitor CrateDB Cloud on Kubernetes -::: diff --git a/docs/tutorials/edge/introduction.md b/docs/tutorials/edge/introduction.md deleted file mode 100644 index 78fa7f8..0000000 --- a/docs/tutorials/edge/introduction.md +++ /dev/null @@ -1,277 +0,0 @@ -(edge-disclaimer)= -# Introduction - -:::{note} -You must have [wget](https://www.gnu.org/software/wget/) and -[jq](https://stedolan.github.io/jq/) installed for the script to -function. CrateDB Edge is currently in Pre-Release. CrateDB Edge and -related services are provided on an "as is" basis and may change at -any time. CrateDB provides no guarantees or warranty 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 until further notice. 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 Pre-Release, please let us know using the [contact -page](https://crate.io/contact/) or *support@crate.io*. -::: - -(edge-prereqs)= -## 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 as - well as sufficient compute to run the CrateDB instances desired. We - recommend the use of a K8s autoscaler. For reference, the CrateDB - Edge stack - without Grafana or Loki - requires about 2 CPUs and - 2500 Mi of memory. We recommend at least 4 CPUs per node for - reliable performance. -* A Kubernetes version 1.20, 1.21, or 1.22; -* A storage class for persisting your data (SSD recommended). As - outlined in the installation script, CrateDB Edge expects the - storage classes `crate-premium` (SSD) and `crate-standard` (SSD or - Spindle). Also ensure that you are able to set the field - `allowVolumeExpansion` to `true`. -* Unless you are experienced with operating Kubernetes clusters, we - recommend to start with a dedicated Kubernetes cluster for CrateDB - Edge. If you use an existing Kubernetes setup, be aware that the - following components will be set up during installation of CrateDB - Edge, which may interfere with your existing configuration: - * cert-manager (version 1.6.1) - * ingress-nginx (version 1.2.3) - * Optionally, Grafana, Loki, or Promtail (via Helm). - -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 -{ref}`cloud providers or third-party tools ` -as described further down in 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](https://metallb.universe.tf/)), you can -still access the CrateDB clusters within, but you will need to figure -out the node ports to use. -::: - -(edge-signup)= -## Sign up - -To use the CrateDB Cloud software, you must first sign up. Follow the -steps outlined in {ref}`this tutorial ` to do so. - -(edge-create-org)= -## 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. - -![Create an organization](../../_assets/img/free-trial-organization.png) - -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. After you create your first organization, -you will be taken to the Dashboard tab of said organization. - -(edge-create-custom)= -## 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](../../_assets/img/cloud-regions.png) - -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](../../_assets/img/cloud-custom-region.png) - -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.) - -(edge-script)= -## 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](https://helm.sh/docs/intro/quickstart/) -for tracking and installing dependencies on Kubernetes.) - -:::{note} -You must have [wget](https://www.gnu.org/software/wget/) and -[jq](https://stedolan.github.io/jq/) installed for the script to -function. -::: - -(edge-manifest-verification)= -### 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. - -(edge-help-parameters)= -### Help and parameters - -Use the `--help` parameter to find an overview of the available -parameters for the script. - -The parameters are defined as follows: - -:::{code} console -Usage: -cratedb-cloud-edge.sh [options] - -Here 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. - -(edge-upgrade)= -## Upgrade the Edge Region - -Components of a deployed Edge Region are not updated automatically. -Because of this, users should update their Edge Regions regularly to -continue getting new features, bugfixes, and security updates. - -If your region is outdated, you will see a *Upgrade this Edge region* -button next to your region: - -![CrateDB Console regions screen](../../_assets/img/edge-region-upgrade.png) - -Clicking it will show you a command that updates your Edge Region. Paste -the command into the environment where your Edge cluster is deployed to -upgrade it. - -(edge-config)= -## Configure the cluster - -### Configuration - -Next, go through the cluster configuration process. You will see that a -cluster can now be deployed to your custom region. You can move directly -to the cluster configuration. Configure your desired hardware values for -CPU, RAM, storage, and number of nodes. - -![Cluster configuration panels for CrateDB Edge](../../_assets/img/cloud-edge-config.png) - -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. - -You can also 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. Clicking the the Test Connection -button will check whether a connection to your backup location can be -established. Keep in mind that you cannot proceed with a custom backup -location unless the connection is functional. - -That's it. As you're using your own equipment in this case, no need to -provide the billing details. - -## 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. -::: - -(edge-cloud-region)= -## Use a cloud provider region - -Aside from 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 {ref}`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 -{ref}`configuration wizard ` as described above. - -(edge-delete-region)= -## 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 dialog 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](../../_assets/img/cloud-edge-delete.png) diff --git a/docs/tutorials/edge/managed-kubernetes.md b/docs/tutorials/edge/managed-kubernetes.md deleted file mode 100644 index 0eca922..0000000 --- a/docs/tutorials/edge/managed-kubernetes.md +++ /dev/null @@ -1,478 +0,0 @@ -(edge-providers)= -# Managed Kubernetes options - -In this section, we provide more specific installation instructions for -some managed Kubernetes providers, such as [Azure AKS](edge-providers-aks), -[Amazon EKS](edge-providers-eks), [Digital Ocean](edge-providers-do) -and [Google Cloud Platform](edge-providers-gc). - -:::{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 CrateDB is not responsible for those -tools. That said, we have tested the instructions provided below for -functionality. Users less familiar with customizing their Kubernetes -stack on their own may find any of these approaches a practical solution -for easier CrateDB Edge setup. - -(edge-providers-aks)= -## Azure AKS - -Below is a step-by-step guide to using Azure AKS 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. - -(edge-providers-aks-sign-up)= -### Sign up - -First you must [sign up with Azure -AKS](https://azure.microsoft.com/en-us/free/services/kubernetes-service/). -On the AKS page, click the *Start Free* button or use the pay-as-you-go -option. If you have an Azure account already, you can use this account -to sign up with. Once signed up, continue to the Azure portal. - -(edge-providers-aks-create-cluster)= -### Create kubernetes cluster - -In the Azure portal, find the "Kubernetes services" option. (You can -use the search bar at the top to do so.) You will see an overview of any -Kubernetes services you may already have running. Click on *Create*, -then *Create Kubernetes cluster*. - -In the configuration menu, choose the desired subscription and resource -group or create a new one. Name your cluster as you wish and select the -desired region. We recommend using the default Kubernetes version. -Finally, pick the server availability you want, which affects your AKS -pricing. - -For the node size, it is important to conform to the -{ref}`minimum requirements set out above `. For this -reason, we strongly recommend choosing a VM size that is at least 4 CPUs -and 8GiB of RAM, for example the "D4s_v3" combination. Additionally, -we recommend using at least 3 nodes for a production-grade -high-availability setup. Other settings may be left on default or -adjusted as desired depending on your production requirements. (The -default settings should be fully functional for CrateDB Edge.) Then -proceed with creating the cluster. This process may take some time. - -If you have [kubectl](https://kubernetes.io/docs/tasks/tools/) -installed, you can check on the node status once it is finished by -running in the [Azure -CLI](https://docs.microsoft.com/en-us/cli/azure/install-azure-cli) the -command - -:::{code} console -az aks get-credentials --resource-group --name -::: - -followed by - -:::{code} console -kubectl get nodes -::: - -which will show you all nodes. When all nodes are set to 'Ready', the -cluster is functioning properly. (Make sure you are in the right -subscription before running the commands, or this process will not -work.) - -After cluster deployment, you can click on *Go to resource* in the Azure -Portal to check that all configurations are as intended. - -(edge-providers-aks-cok-setup)= -### Set up CrateDB Cloud on Kubernetes region - -Sign up with, or log into, the [CrateDB Cloud -Console](https://console.cratedb.cloud). Go to the Regions tab in the -Subscription overview and create a custom Edge region by clicking on -*Create Edge region*. When the region has appeared in the regions list, -it will show a script that you can copy into your CLI. Do so and confirm -installation of CrateDB Edge on the correct cluster. The script will -prompt you for installation of the prerequisite tools as needed. To -configure the necessary storage classes, follow the instructions given -in the script and then rerun the script command. - -The script, once run, will validate the installation of the CrateDB Edge -stack. You can also check that everything is operational by going to -your Kubernetes service in the Azure portal and checking the tab -Workloads, under Kubernetes Resources. - -(edge-providers-aks-cok-deploy)= -### Deploy CrateDB Cloud on Kubernetes cluster - -Finally, return to the CrateDB Cloud Console and click on *Deploy -cluster* in the custom region you have created. Follow the -{ref}`steps described above ` to configure your CrateDB -Cloud cluster. At the end of the process, you should have a working -CrateDB Edge install on Azure AKS managed Kubernetes. - -(edge-providers-eks)= -## Amazon EKS - -Below is a step-by-step guide to using Amazon EKS 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. - -:::{note} -Amazon EKS cluster configuration has some complexity relating to the -structure of AWS security management. The steps below try to provide a -step-by-step guide, but may become outdated as AWS changes its -interfaces or functionality. Since CrateDB is not responsible for EKS, -we cannot guarantee this documentation remains fully in line with the -latest AWS user flow. You can find current details on the [EKS cluster -creation -docs](https://docs.aws.amazon.com/eks/latest/userguide/create-cluster.html). -::: - -(edge-providers-eks-sign-up)= -### Sign up - -First you must [create an AWS -account](https://portal.aws.amazon.com/billing/signup) and log in with -it. If you have an AWS account already, proceed directly to the [AWS -Management Console](https://aws.amazon.com/console/). Find the Elastic -Kubernetes Service (you can search with the search bar at the top). - -(edge-providers-eks-create-cluster)= -### Create Kubernetes cluster - -At the EKS portal, click the *Add cluster* button and hit *Create* to -create a new cluster. Having done that, you will arrive at the -Kubernetes cluster configuration. Give it a name and use the latest -version of Kubernetes, as long as it is < 1.22. Set the service role -according to your requirements. (Note: you can set the region at the top -right, next to the user settings.) - -Networking settings can be left to default or adjusted as desired. The -same applies to logging. Finish with *Create*. The EKS cluster will now -be created. - -(edge-providers-eks-config)= -### Configuration - -Once the cluster is set to *active* in the EKS cluster configuration -panel, it will be ready to be configured (you may still see a banner at -the top stating it is being created). - -Make sure to add the necessary IAM role policies if you created a -cluster with Kubernetes 1.20 or earlier, or a cluster of 1.21 or later -that uses the IPv4 family (this corresponds to the default settings.) -Under Configuration, go to *Cluster IAM Role ARN* and click the link -below it. This will lead to the IAM Management Console. In this console, -click *Add permissions*, then *Add policies*. Search for -"Amazon_EKS_CNI_Policy". Tick the box and then click *Attach -policies*. - -Under cluster Configuration, now go to *Add node group*. Configure the -node group by adding a name, assigning it a suitable [node IAM -role](https://docs.aws.amazon.com/eks/latest/userguide/create-node-role.html) -(you can create one in the IAM Management Console if necessary). Click -*Next*. In the compute and scaling configuration, assure that the -{ref}`minimum requirements set out above ` are met. We -recommend choosing at least 4 CPUs and at least 8GiB of RAM, for example -the "t3.xlarge" instance type. Your disk size should be adequate to -your needs - we recommend at least 8 GiB per node. For production-grade -clusters, always assure a minimum of 3 nodes. For the network -configuration, adjust to your preferences or leave it to the default -settings. Hit *Create* to create the node group. - -In the [AWS CLI](https://aws.amazon.com/cli/), enter the following -command (make sure you are logged in properly): - -:::{code} console -aws eks update-kubeconfig --region --name -::: - -You can check everything is working correctly with -[kubectl](https://kubernetes.io/docs/tasks/tools/): - -:::{code} console -kubectl get nodes -::: - -(edge-providers-eks-cok-setup)= -### Set up CrateDB Cloud on Kubernetes region - -Sign up with, or log into, the [CrateDB Cloud -Console](https://console.cratedb.cloud). Go to the Regions tab in the -Subscription overview and create a custom Edge region by clicking on -*Create Edge region*. When the region has appeared in the regions list, -it will show a script that you can copy into your CLI. Do so and confirm -installation of CrateDB Edge on the correct cluster. The script will -prompt you for installation of the prerequisite tools as needed. To -configure the necessary storage classes, follow the instructions given -in the script and then rerun the script command. - -Note that for EKS the default storage class is not called `default` but -will have a different name, e.g. `gp2` or `gp3`. You have to adjust the -script accordingly. For more info, refer to the [documentation on AWS -storage -classes](https://kubernetes.io/docs/concepts/storage/storage-classes/#aws-ebs). -You can find the relevant storage class name with kubectl: - -:::{code} console -kubectl get sc -::: - -The script, once run, will validate the installation of the CrateDB Edge -stack. You can check everything is running correctly in the EKS cluster -interface. - -(edge-providers-eks-cok-deploy) -### Deploy CrateDB Cloud on Kubernetes cluster - -Finally, return to the CrateDB Cloud Console and click on *Deploy -cluster* in the custom region you have created. Follow the -{ref}`steps described above ` to configure your CrateDB -Cloud cluster. At the end of the process, you should have a working -CrateDB Edge install on AWS EKS managed Kubernetes. - -(edge-providers-do)= -## 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. - -(edge-providers-do-sign-up)= -### Sign up - -First you must sign up with [Digital Ocean](https://www.digitalocean.com/). 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.) - -(edge-providers-do-cluster)= -### 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. - -(edge-providers-do-config)= -### 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](https://kubernetes.io/docs/tasks/tools/) -if you have not done so already. Then point the Kubeconfig configuration -path to where you stored the YAML file: - -:::{code} console -export KUBECONFIG=~ -::: - -Subsequently, wait for the install to finish and check that the nodes -are running as intended: - -:::{code} console -kubectl get nodes -::: - -(edge-providers-do-setup)= -### Set up Edge region - -Now, go to the CrateDB Cloud Console and create a custom CrateDB Edge -region. Follow the steps outlined -{ref}`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. - -(edge-providers-do-storage-class)= -### 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: - -:::{code} console -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. - -(edge-providers-do-deploy)= -### 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 -{ref}`steps described above ` to proceed. At the end of -the process, you should have a working CrateDB Edge install on Digital -Ocean managed Kubernetes. - -(edge-providers-gc)= -## Google Cloud Platform - -Below is a full walkthrough of how to get CrateDB Edge up and running on -Google Cloud. 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. In this example, we -use Google Cloud's Kubernetes Engine with a standard setup. - -(edge-providers-gc-sign-up)= -### Sign up - -Signing up for Google Cloud is very straightforward. You can use your -existing Google account, and after you set up the Cloud billing you are -eligible for 90-day, $300 trial period. For details, see [Google Cloud -Free Program -documentation](https://cloud.google.com/free/docs/gcp-free-tier). - -(edge-providers-gc-cluster)= -### Create Kubernetes cluster - -The first step is to create a new Kubernetes cluster in the Google Cloud -console. We recommend using a GKE Standard cluster. When configuring the -nodes, it is important to remember that CrateDB Cloud Cluster needs at -least 3 CPU cores and at least 5 GiB of memory per node. For better -performance, it is also recommended to use compute-optimized nodes. - -![Google Cloud console cluster config](../../_assets/img/gcloud-node-config.png) - -(edge-providers-gc-config)= -### Configuration - -Once your cluster is running, some configuration is needed. You will -need to install the [gcloud -CLI](https://cloud.google.com/sdk/docs/install) and -[kubectl](https://kubernetes.io/docs/tasks/tools/) to configure the -cluster. - -To connect to your cluster from your console, use the command that -appears after clicking the **CONNECT** button in the Google Cloud -console. It will look similar to this: - -:::{code} console -gcloud container clusters get-credentials cluster-1 --zone us-central1-c --project key-decorator-356217 -::: - -After successfully connecting, a message similar to this should be -displayed: - -:::{code} console -kubeconfig entry generated for cluster-1. -::: - -Now that you are connected, you can configure the cluster using -*kubectl*. - -One thing that the CrateDB Cloud Edge deployment script can't currently -do is create a storage class for Kubernetes, you need to create them -yourself. A good way is to start by displaying existing storage classes: - -:::{code} console -kubectl get sc -::: - -There should be one called `standard (default)`. You can edit the -storage class by redirecting its yaml code to a new file. Do that with -this command: - -:::{code} console -kubectl get sc standard -o yaml > sc.yaml -::: - -This will write create a new .yaml file called **sc.yaml**. Initially, -it should look something like this: - -:::{code} yaml -allowVolumeExpansion: true -apiVersion: storage.k8s.io/v1 -kind: StorageClass -metadata: - annotations: - storageclass.kubernetes.io/is-default-class: "true" - creationTimestamp: "2022-07-21T03:26:32Z" - labels: - addonmanager.kubernetes.io/mode: EnsureExists - name: standard - resourceVersion: "897" - uid: 5d6bc49a-c46b-4222-bf36-0b7dfbd872d2 -parameters: - type: pd-standard -provisioner: kubernetes.io/gce-pd -reclaimPolicy: Delete -volumeBindingMode: Immediate -::: - -From this default storage class, you need to create two new classes: -`crate-standard` and `crate-premium` - -The yaml file for those should look like this: - -:::{code} yaml -allowVolumeExpansion: true -apiVersion: storage.k8s.io/v1 -kind: StorageClass -metadata: - name: crate-standard -parameters: - type: pd-standard -provisioner: kubernetes.io/gce-pd -reclaimPolicy: Delete -volumeBindingMode: Immediate -::: - -Once you edit the `sc.yaml` file, save it and apply it with this -command: - -:::{code} console -kubectl create -f sc.yaml -::: - -This will create the new `crate-standard` storage class. Repeat the -steps for the `crate-premium` class: - -:::{code} yaml -allowVolumeExpansion: true -apiVersion: storage.k8s.io/v1 -kind: StorageClass -metadata: - name: crate-premium -parameters: - type: pd-standard -provisioner: kubernetes.io/gce-pd -reclaimPolicy: Delete -volumeBindingMode: Immediate -::: - -:::{code} yaml -kubectl create -f sc.yaml -::: - -The only difference between them is the `name` parameter. After issuing -`kubectl get sc` you should now be able to see the new classes: - -:::{code} console -NAME PROVISIONER RECLAIMPOLICY VOLUMEBINDINGMODE ALLOWVOLUMEEXPANSION AGE -crate-premium kubernetes.io/gce-pd Delete Immediate true 44s -crate-standard kubernetes.io/gce-pd Delete Immediate true 7s -::: - -For a basic installation, this is all that is needed in terms of -configuration. - -(edge-providers-gc-deploy)= -### Deploy a cluster - -All that remains now is to use the command that is generated after -creating an edge region in the CrateDB Cloud console. E.g.: - -:::{code} console -bash <(wget -qO- https://console.cratedb-dev.cloud/edge/cratedb-cloud-edge.sh) gAAAAABi2O81bYA8_qWQUU8svABjDdh0qNo1ZainUxDwx6MocxKJjBZ0X7Gw15QRj4LNIXZgoe7pig1fCJc_YC7UTnGacyi6Jn1-geiMBm1AGUOzXAjUIVUeCUV7jQCEtZjo4bWXaQzg7cr0bzkiLARK029M9PVTbtZbUJtO1HsFqUgnyP1-7exnylPkJ67NVwqD-ixKNdr_Ie6o5SxYlmhhjIge9fnAvQhtcURy-z4H0jBXhA7vURIL2CFXX4yWd30E-Wd1tnvP -::: - -Now you can {ref}`deploy the cluster `. \ No newline at end of file diff --git a/docs/tutorials/edge/monitoring.md b/docs/tutorials/edge/monitoring.md deleted file mode 100644 index 4d59f2f..0000000 --- a/docs/tutorials/edge/monitoring.md +++ /dev/null @@ -1,224 +0,0 @@ -(edge-monitoring)= -# Monitor CrateDB Cloud on Kubernetes - -This tutorial introduces a way to set up monitoring of your CrateDB -Cloud on Kubernetes cluster. The visualization tool -[Grafana](https://grafana.com/) is used together with -[Prometheus](https://grafana.com/oss/prometheus/) and -[Loki](https://grafana.com/oss/loki/) to monitor the cluster performance -and browse logs, respectively. - -(edge-monitoring-prereqs)= -## Prerequisites - -* The CrateDB Cloud on Kubernetes installation script requires Helm 3 - to be present in the system. -* For a deployment with Grafana, Loki, and Prometheus, we recommend at - least 5 CPUs and 5 GiB of memory per CrateDB node for acceptable - performance. - -(edge-monitoring-deployment)= -## Cluster Deployment - -The first step is to sign up in the [Cloud -Console](https://console.cratedb.cloud/) if you haven't done so yet. -After that, you can deploy your cluster. - -Deployment steps will depend on your -{ref}`cloud provider `, or on -your local environment, if you choose the -{ref}`self-hosted ` variant of CrateDB -Cloud on Kubernetes. - -(edge-monitoring-grafana-install)= -## Install Grafana and Loki - -The first important step comes after the successful installation of -CrateDB into your chosen system. Right after you get the following -console prompt: - -:::{code} console -✓ Region is connected to CrateDB Cloud. -✓ Successfully validated installation -::: - -This means that base installation is done. You will now be asked if you -want to have Grafana installed in the system. Press `Y` to opt-in: - -:::{code} console -Optional installation of Loki and Grafana ------------------------ -! Loki and Grafana not detected. - -============================================================================= -CrateDB Edge encourages the usage of Loki and Grafana to ease support. -Would you like to install Loki and Grafana? - -============================================================================= -Install? [Yy] y -::: - -After successful installation, you will get the following output: - -:::{code} console -✓ Installed. -Loki and Grafana successfully installed. -::: - -:::{note} -If you already have a CrateDB Edge cluster deployed and didn't choose -to install Grafana and Loki initially, you can rerun the install script -to get them when needed. -::: - -(edge-monitoring-accessing-grafana)= -## Accessing Grafana UI - -You will notice that during the installation of Grafana, you are -provided with a number of useful commands that will help you access the -Grafana UI once its installation is finished. - -(edge-monitoring-grafana-password)= -### Grafana user password - -As a part of the installation process, a user account is created for -Grafana. The username is `admin` and the password can be retrieved with -the following command: - -:::{code} console -kubectl get secret --namespace crate-loki crate-grafana -o jsonpath="{.data.admin-password}" | base64 --decode ; echo -::: - -You will get a response with a password: - -:::{code} console -rpz654Q2k8D5vgcvvrRgQMZAC2gKxZJH4oQf09fB -::: - -(edge-monitoring-port-forwarding)= -### Port-forwarding to get the Grafana URL - -To get the URL of your Grafana UI, you need to issue the following -commands: - -:::{code} console -export POD_NAME=$(kubectl get pods --namespace crate-loki -l "app.kubernetes.io/name=grafana,app.kubernetes.io/instance=crate-grafana" -o jsonpath="{.items[0].metadata.name}") - -kubectl --namespace crate-loki port-forward $POD_NAME 3000 -::: - -This will forward your running Grafana instance to port `3000`. You can -then view it on that port. For this tutorial, we used Google Cloud -Engine. After issuing the command, we use the "Web preview" to see -Grafana UI on port 3000. - -![Google Cloud web preview](../../_assets/img/edge-monitoring-forwarding.png) - -:::{note} - Depending on your environment, it is possible that port 3000 will - already be occupied. If that's the case, you will see following - response: - - :::{code} console - Unable to listen on port 3000: Listeners failed to create with the following errors: - [unable to create listener: Error listen tcp4 127.0.0.1:3000: bind: address already in use unable to create listener: - Error listen tcp6 [::1]:3000: bind: cannot assign requested address] - error: unable to listen on any of the requested ports: [{3000 3000} - ::: - - When that happens, reissue the port-forwarding command with a different - port. E.g. - - :::{code} console - kubectl --namespace crate-loki port-forward $POD_NAME 3001 - ::: -::: - -(edge-monitoring-prometheus-datasource)= -## Adding the Prometheus data source - -At this point, you should be able to access the Grafana UI. After -logging in, it is necessary to add Prometheus as a data source, by -navigating to the `Configuration -> Data sources` in the left-hand menu: - -![Grafana menu](../../_assets/img/edge-monitoring-grafana-menu.png) - -You will see that out-of-the-box, the data source for Loki, is already -present. - -![Grafana data source list](../../_assets/img/edge-monitoring-datasources-list.png) - -To monitor cluster performance, you need to add another data source --Prometheus. Click the "Add data source" button in the top right to -add a new data source. Choose "Prometheus" when shown the list of -options. You will be brought to the data source configuration page. - -![Grafana Prometheus data source](../../_assets/img/edge-monitoring-prometheus-datasource.png) - -The only field that you need to fill out is "URL". The URL for -Prometheus is always: - -:::{code} console -http://cluster-monitoring-prometheus.monitoring.svc.cluster.local:9090 -::: - -After that, click "Save & test" at the bottom of the page. You should -get a response "Data source is working" - -(edge-monitoring-importing-dashboards)= -## Importing the dashboards - -Now that you have the necessary data sources, you can import the example -dashboards. Select `Dashboards -> Manage` in the menu on the left. Then, -select "Import" in the top right. - -Both of these `.json` files need to be imported: - -- [Cluster performance - dashboard](https://github.com/crate/cloud-docs/raw/main/docs/_extra/cratedb-edge-cluster-dashboard.json) -- [Logs monitoring - dashboard](https://github.com/crate/cloud-docs/raw/main/docs/_extra/cratedb-edge-logs-dashboard.json) - -(edge-monitoring-cluster-dashboard)= -## Cluster monitoring dashboard - -This dashboard utilizes metrics provided by Prometheus. It monitors the -following metrics: - -- Number of running clusters -- Number of running nodes -- Cluster health -- Number and types of opened cluster connections -- Selects & Inserts per second -- CPU usage -- Memory usage -- File system writes & reads - -![Grafana Prometheus dashboard](../../_assets/img/edge-monitoring-prometheus-dashboard.png) - -(edge-monitoring-logs-dashboard)= -## Logs monitoring dashboard - -This dashboard uses Loki to store the logs from available namespaces, -with ability to search for strings in the logs. - -![Grafana Loki dashboard](../../_assets/img/edge-monitoring-loki-dashboard.png) - -(edge-monitoring-conclusion)= -## Conclusion - -This tutorial should serve as an introduction to CrateDB Cloud on Kubernetes -monitoring using Loki & Prometheus in Grafana. When you complete it, you -should have two handy introductory dashboards to monitor your cluster's -performance and operations. - -Of course, the best dashboards for you will vary based on your use case -and needs. Because of that, we encourage you to play around with these -provided dashboards and also visit documentation [for -Loki](https://grafana.com/docs/loki/latest/) [and -Prometheus](https://grafana.com/docs/grafana/latest/datasources/prometheus/) -in Grafana which will help you to build dashboards best suited for your -needs. - -If this looks interesting to you, go to [Cloud -Console](https://console.cratedb.cloud/) and give it a try! diff --git a/docs/tutorials/edge/self-hosted-edge.md b/docs/tutorials/edge/self-hosted-edge.md deleted file mode 100644 index 96b95f8..0000000 --- a/docs/tutorials/edge/self-hosted-edge.md +++ /dev/null @@ -1,360 +0,0 @@ -(edge-self-hosted)= -# Self-hosted options - -In this section, we outline installation instructions for some -third-party supported self-hosted options, such as -[MicroK8s](https://microk8s.io/) and [K3s](https://k3s.io/). These are -third-party tools and CrateDB is not responsible for those tools. That -said, we have tested the instructions provided below for functionality. - -Users less familiar with customizing their Kubernetes stack on their own -may find any of these approaches a practical solution for easier CrateDB -Cloud on Kubernetes setup. - -(edge-tools-microk8s)= -## MicroK8s - -Below is a full walkthrough of how to get CrateDB Cloud on Kubernetes -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 Cloud -on Kubernetes. - -(edge-tools-microk8s-setup)= -### Set up MicroK8s - -Follow the instructions from the [MicroK8s -docs](https://microk8s.io/docs). For the purposes of this tutorial, we -assume a [snap](https://snapcraft.io/)-based distribution, such as -[Ubuntu](https://ubuntu.com/). 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. - -:::{code} console -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 -::: - -(edge-tools-microk8s-setup-cluster)= -### 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. - -:::{code} console -microk8s add-node -::: - -(edge-tools-microk8s-join)= -### Join nodes to cluster - -Now SSH into the two remaining nodes and run the command you received on -the first node. - -:::{code} console -root@ub11:~# microk8s join :25000/ -Contacting cluster at -Waiting for this node to finish joining the cluster... -::: - -(edge-tools-microk8s-storage)= -### Use a storage solution - -The MicroK8s setup will require a storage solution. In this case, the -tutorial shows how to do so using [Longhorn](https://longhorn.io/), a -distributed storage solution for Kubernetes. You can follow the -[Longhorn installation -instructions](https://longhorn.io/docs/1.1.1/deploy/install/install-with-kubectl/) -as described below. (Other storage solutions for Kubernetes may work as -well.) - -First the installation: - -:::{code} console -kubectl apply -f https://raw.githubusercontent.com/longhorn/longhorn/v1.1.1/deploy/longhorn.yaml -::: - -Then you need to specify the root directory: - -:::{code} console -kubectl -n longhorn-system edit deployment longhorn-driver-deployer - -- name: KUBELET_ROOT_DIR -value: /var/snap/microk8s/common/var/lib/kubelet -::: - -(edge-tools-microk8s-create-region)= -### Set up CrateDB Cloud on Kubernetes region - -At this stage, you can create a CrateDB Cloud on Kubernetes region via the CrateDB -Cloud Console. Follow the steps outlined above -{ref}`from the CrateDB sign up onwards ` to proceed. - -(edge-tools-microk8s-script)= -### Run the script - -Run the script with the following command: - -:::{code} console -wget -qO- https://console.cratedb.cloud/edge/cratedb-cloud-edge.sh > edge-installer.sh -chmod u+x edge-installer.sh -./edge-installer --dry-run -::: - -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 `` in question is the token you receive from the CrateDB -Console Cloud on Kubernetes region field in the Regions tab of the Organization -Overview. - -With this, you should be ready to use CrateDB Cloud on -Kubernetes via Microk8s. - -(edge-tools-k3s)= -## K3S - -Below is a full walkthrough of how to get CrateDB Cloud on Kubernetes -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 Cloud -on Kubernetes. - -(edge-tools-k3s-setup)= -### Set up K3S - -A simple way to bootstrap the K3S setup is with -[k3sup](https://github.com/alexellis/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: - -:::{code} console -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: - -:::{code} console -cat /var/lib/rancher/k3s/server/node-token -::: - -Note that the master node will operate both as a master and as a worker. - -(edge-tools-k3s-join)= -### Join nodes to cluster - -Next, you set up other worker nodes (as many as applicable to your use -case): - -:::{code} console -export token= -export INSTALL_K3S_VERSION="v1.19.10+k3s1" -curl -sfL https://get.k3s.io | K3S_URL="https://ub1:6443" K3S_TOKEN=$token sh - -::: - -(edge-tools-k3s-uninstall)= -### Uninstall - -If you need to uninstall, run: - -:::{code} console -/usr/local/bin/k3s-agent-uninstall.sh -::: - -(edge-tools-k3s-storage)= -### Use a storage solution - -The K3S setup for CrateDB Cloud on Kubernetes will require a storage -solution. In this case, the tutorial shows how to do so using -[Longhorn](https://longhorn.io/), a distributed storage solution for -Kubernetes. You can follow the [Longhorn installation instructions] -(https://longhorn.io/docs/1.1.1/deploy/install/install-with-kubectl/) -as described below. (Other storage solutions for Kubernetes may work as -well.) - -First the installation: - -:::{code} console -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: - -:::{code} console -kubectl -n longhorn-system edit deployment longhorn-driver-deployer - - - name: KUBELET_ROOT_DIR - value: /var/lib/rancher/k3s/agent/kubelet ..... /var/lib/kubelet -::: - -(edge-tools-k3s-setup-region)= -### Set up CrateDB Cloud on Kubernetes region - -At this stage, you can create a CrateDB Cloud on Kubernetes region via the CrateDB Cloud -Console. Follow the steps outlined above -{ref }`from the CrateDB sign up onwards ` to proceed. - -(edge-tools-k3s-script)= -### Run the script - -Run the script with the following command: - -:::{code} console -wget -qO- https://console.cratedb.cloud/edge/cratedb-cloud-edge.sh > edge-installer.sh -chmod u+x edge-installer.sh -./edge-installer --dry-run -::: - -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 `` in question is the token you receive from the CrateDB -Console Cloud on Kubernetes region field in the Regions tab of the Organization -Overview. - -With this, you should be ready to use CrateDB Cloud on Kubernetes via K3S. - -(edge-tools-custom-tls)= -## Custom TLS certificates - -By default, CrateDB Cloud on Kubernetes will issue self-signed certificates for CrateDB -instances running in your Cloud on Kubernetes region. It is also possible to use -"proper" TLS certificates if required. In the examples below, we will -configure [letsencrypt](https://letsencrypt.org/) to issue certificates -and use them with CrateDB Cloud on Kubernetes clusters. - -(edge-tools-custom-tls-issuer)= -### Create a `ClusterIssuer` - -CrateDB Cloud on Kubernetes uses an industry standard app called -[cert-manager](https://github.com/cert-manager/cert-manager/) for -managing TLS certificates. To issue valid certificates, you would need -to follow the cert-manager [tutorial for letsencrypt via the DNS -solver](https://cert-manager.io/docs/configuration/acme/dns01/). CrateDB -clusters are provisioned behind a Load Balancer, and as such the only -way to solve letsencrypt challenges is via DNS. Your configuration will -vary, but if you use `Route53` as your DNS provider, you will end up -with a configuration similar to this: - -:::{code} yaml -apiVersion: cert-manager.io/v1alpha3 -kind: ClusterIssuer -metadata: - name: letsencrypt-dns -spec: - acme: - email: administrators@yourorg.com - privateKeySecretRef: - name: letsencrypt - server: https://acme-v02.api.letsencrypt.org/directory - solvers: - - dns01: - route53: - accessKeyID: [your-access-key] - region: eu-central-1 - secretAccessKeySecretRef: - key: aws_secret_access_key - name: your_secret -::: - -(edge-tools-custom-tls-certificate)= -### Ask for a new certificate - -To ask [letsencrypt](https://letsencrypt.org/) for a new certificate, -create a `Certificate` Kubernetes resource: - -:::{code} yaml -apiVersion: cert-manager.io/v1alpha3 -kind: Certificate -metadata: - name: my-certificate - namespace: my-namespace -spec: - dnsNames: - - my-cluster-1.my.fully.qualified.domain.example.com - issuerRef: - kind: ClusterIssuer - name: letsencrypt-dns - keystores: - jks: - create: true - passwordSecretRef: - key: keystore-password - name: keystore-passwords - pkcs12: - create: true - passwordSecretRef: - key: keystore-password - name: keystore-passwords - secretName: my-target-secret-for-this-certificate -::: - -:::{note} -Note that you must do this inside of a namespace where your CrateDB will -be running. -::: - -The secret called `keystore-passwords` will be created automatically -when you create the CrateDB Cloud Project in this region. - -(edge-tools-custom-tls-replace)= -### Replace the existing certificate used by your cluster - -As your CrateDB Cloud on Kubernetes cluster comes with a self-signed certificate, you -will need to replace it. Fortunately, this is fairly straightforward, -and only requires a quick edit to the CrateDB Cluster's `StatefulSet`, -i.e.: - -:::{code} console -$ kubectl -n $YOUR_NAMESPACE edit sts crate-data-hot-$CLUSTER_ID -::: - -Then find the following section and replace the secret name with the -`secretName` specified when creating the `Certificate` entity above, -i.e.: - -:::{code} yaml -- name: keystore - secret: - defaultMode: 420 - items: - - key: keystore.jks - path: keystore.jks - secretName: my-target-secret-for-this-certificate -::: - -Once this is done, you will have to bounce each of the CrateDB pods for -the change to be picked up. Once the pods are back up, they will present -the configured certificate on both the HTTP and PGSQL ports. - -:::{note} -Note that you need to access CrateDB via a valid DNS name for this to -work, so make sure that -`my-cluster-1.my.fully.qualified.domain.example.com` correctly points to -your CrateDB instance (i.e. via an external network load balancer). -:::