/
introduction.md
277 lines (218 loc) · 11.5 KB
/
introduction.md
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
(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 <edge-providers>`
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 <quick-start>` 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.
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.
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.
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 <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.
(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:
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.
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 <edge-create-org>`. 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 <edge-config>` 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.
