Skip to content

Commit 29c97f1

Browse files
ewoutpewoutp
committed
Improving documentation
1 parent 1aa8ce3 commit 29c97f1

File tree

4 files changed

+198
-14
lines changed

4 files changed

+198
-14
lines changed

‎docs/Manual/Deployment/Kubernetes/DriverConfiguration.md‎

Lines changed: 128 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,128 @@
1+
# Configuring your driver for ArangoDB access
2+
3+
In this chapter you'll learn how to configure a driver for accessing
4+
an ArangoDB deployment in Kubernetes.
5+
6+
The exact methods to configure a driver are specific to that driver.
7+
8+
## Database endpoint(s)
9+
10+
The endpoint(s) (or URLs) to communicate with is the most important
11+
parameter your need to configure in your driver.
12+
13+
Finding the right endpoints depend on wether your client application is running in
14+
the same Kubernetes cluster as the ArangoDB deployment or not.
15+
16+
### Client application in same Kubernetes cluster
17+
18+
If your client application is running in the same Kubernetes cluster as
19+
the ArangoDB deployment, you should configure your driver to use the
20+
following endpoint:
21+
22+
```text
23+
https://<deployment-name>.<namespace>.svc:8529
24+
```
25+
26+
Only if your deployment has set `spec.tls.caSecretName` to `None`, should
27+
you use `http` instead of `https`.
28+
29+
### Client application outside Kubernetes cluster
30+
31+
If your client application is running outside the Kubernetes cluster in which
32+
the ArangoDB deployment is running, your driver endpoint depends on the
33+
external-access configuration of your ArangoDB deployment.
34+
35+
If the external-access of the ArangoDB deployment is of type `LoadBalancer`,
36+
then use the IP address of that `LoadBalancer` like this:
37+
38+
```text
39+
https://<load-balancer-ip>:8529
40+
```
41+
42+
If the external-access of the ArangoDB deployment is of type `NodePort`,
43+
then use the IP address(es) of the `Nodes` of the Kubernetes cluster,
44+
combined with the `NodePort` that is used by the external-access service.
45+
46+
For example:
47+
48+
```text
49+
https://<kubernetes-node-1-ip>:30123
50+
```
51+
52+
You can find the type of external-access by inspecting the external-access `Service`.
53+
To do so, run the following command:
54+
55+
```bash
56+
kubectl get service -n <namespace-of-deployment> <deployment-name>-ea
57+
```
58+
59+
The output looks like this:
60+
61+
```bash
62+
NAME TYPE CLUSTER-IP EXTERNAL-IP PORT(S) AGE SELECTOR
63+
example-simple-cluster-ea LoadBalancer 10.106.175.38 192.168.10.208 8529:31890/TCP 1s app=arangodb,arango_deployment=example-simple-cluster,role=coordinator
64+
```
65+
66+
In this case the external-access is of type `LoadBalancer` with a load-balancer IP address
67+
of `192.168.10.208`.
68+
This results in an endpoint of `https://192.168.10.208:8529`.
69+
70+
## TLS settings
71+
72+
As mentioned before the ArangoDB deployment managed by the ArangoDB operator
73+
will use a secure (TLS) connection unless you set `spec.tls.caSecretName` to `None`
74+
in your `ArangoDeployment`.
75+
76+
When using a secure connection, you can choose to verify the server certificates
77+
provides by the ArangoDB servers or not.
78+
79+
If you want to verify these certificates, configure your driver with the CA certificate
80+
found in a Kubernetes `Secret` found in the same namespace as the `ArangoDeployment`.
81+
82+
The name of this `Secret` is stored in the `spec.tls.caSecretName` setting of
83+
the `ArangoDeployment`. If you don't set this setting explicitly, it will be
84+
set automatically.
85+
86+
Then fetch the CA secret using the following command (or use a Kubernetes client library to fetch it):
87+
88+
```bash
89+
kubectl get secret -n <namespace> <secret-name> --template='{{index .data "ca.crt"}}' | base64 -D > ca.crt
90+
```
91+
92+
This results in a file called `ca.crt` containing a PEM encoded, x509 CA certificate.
93+
94+
## Query requests
95+
96+
For most client requests made by a driver, it does not matter if there is any kind
97+
of load-balancer between your client application and the ArangoDB deployment.
98+
99+
{% hint 'info' %}
100+
Note that even a simple `Service` of type `ClusterIP` already behaves as a load-balancer.
101+
{% endhint %}
102+
103+
The exception to this is cursor related requests made to an ArangoDB `Cluster` deployment.
104+
The coordinator that handles an initial query request (that results in a `Cursor`)
105+
will save some in-memory state in that coordinator, if the result of the query
106+
is to big to be transfer back in the response of the initial request.
107+
108+
Follow-up requests have to be made to fetch the remaining data.
109+
These follow-up requests must be handled by the same coordinator to which the initial
110+
request was made.
111+
112+
As soon as there is a load-balancer between your client application and the ArangoDB cluster,
113+
it is uncertain which coordinator will actually handle the follow-up request.
114+
115+
To resolve this uncertainty, make sure to run your client application in the same
116+
Kubernetes cluster and synchronize your endpoints before making the
117+
initial query request.
118+
This will result in the use (by the driver) of internal DNS names of all coordinators.
119+
A follow-up request can then be send to exaclty the same coordinator.
120+
121+
If your client application is running outside the Kubernetes cluster this is much harder
122+
to solve.
123+
The easiest way to work around it, is by making sure that the query results are small
124+
enough.
125+
When that is not feasible, it is also possible to resolve this
126+
when the internal DNS names of your Kubernetes cluster are exposed to your client application
127+
and the resuling IP addresses are routeable from your client application.
128+
To expose internal DNS names of your Kubernetes cluster, your can use [CoreDNS](https://coredns.io).

‎docs/Manual/Deployment/Kubernetes/README.md‎

Lines changed: 19 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -1,6 +1,21 @@
11
# ArangoDB Kubernetes Operator
22

3-
The ArangoDB Kubernetes Operator (`kube-arangodb`) is a set of two operators
4-
that you deploy in your Kubernetes cluster to manage deployments of the
5-
ArangoDB database and provide `PersistentVolumes` on local storage of your
6-
nodes for optimal storage performance.
3+
The ArangoDB Kubernetes Operator (`kube-arangodb`) is a set of operators
4+
that you deploy in your Kubernetes cluster to:
5+
6+
- Manage deployments of the ArangoDB database
7+
- Provide `PersistentVolumes` on local storage of your nodes for optimal storage performance.
8+
- Configure ArangoDB Datacenter to Datacenter replication
9+
10+
Each of these uses involves a different custom resource.
11+
12+
- Use an [`ArangoDeployment` resource](./DeploymentResource.md) to
13+
create an ArangoDB database deployment.
14+
- Use an [`ArangoLocalStorage` resource](./StorageResource.md) to
15+
provide local `PersistentVolumes` for optimal I/O performance.
16+
- Use an [`ArangoDeploymentReplication` resource](./DeploymentReplicationResource.md) to
17+
configure ArangoDB Datacenter to Datacenter replication.
18+
19+
Continue with [Using the ArangoDB Kubernetes Operator](./Usage.md)
20+
to learn how to install the ArangoDB Kubernetes operator and create
21+
your first deployment.

‎docs/Manual/Deployment/Kubernetes/Upgrading.md‎

Lines changed: 21 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -3,6 +3,8 @@
33
The ArangoDB Kubernetes Operator supports upgrading an ArangoDB from
44
one version to the next.
55

6+
## Upgrade an ArangoDB deployment
7+
68
To upgrade a cluster, change the version by changing
79
the `spec.image` setting and the apply the updated
810
custom resource using:
@@ -11,10 +13,29 @@ custom resource using:
1113
kubectl apply -f yourCustomResourceFile.yaml
1214
```
1315

16+
The ArangoDB operator will perform an sequential upgrade
17+
of all servers in your deployment. Only one server is upgraded
18+
at a time.
19+
20+
For patch level upgrades (e.g. 3.3.9 to 3.3.10) each server
21+
is stopped and restarted with the new version.
22+
23+
For minor level upgrades (e.g. 3.3.9 to 3.4.0) each server
24+
is stopped, then the new version is started with `--database.auto-upgrade`
25+
and once that is finish the new version is started with the normal arguments.
26+
27+
The process for major level upgrades depends on the specific version.
28+
29+
## Upgrade the operator itself
30+
1431
To update the ArangoDB Kubernetes Operator itself to a new version,
1532
update the image version of the deployment resource
1633
and apply it using:
1734

1835
```bash
1936
kubectl apply -f examples/yourUpdatedDeployment.yaml
2037
```
38+
39+
## See also
40+
41+
- [Scaling](./Scaling.md)

‎docs/Manual/Deployment/Kubernetes/Usage.md‎

Lines changed: 30 additions & 10 deletions
Original file line numberDiff line numberDiff line change
@@ -8,33 +8,41 @@ cluster first.
88
To do so, run (replace `<version>` with the version of the operator that you want to install):
99

1010
```bash
11-
kubectl apply -f https://raw.githubusercontent.com/arangodb/kube-arangodb/<version>/manifests/crd.yaml
12-
kubectl apply -f https://raw.githubusercontent.com/arangodb/kube-arangodb/<version>/manifests/arango-deployment.yaml
11+
export URLPREFIX=https://raw.githubusercontent.com/arangodb/kube-arangodb/<version>/manifests
12+
kubectl apply -f $URLPREFIX/crd.yaml
13+
kubectl apply -f $URLPREFIX/arango-deployment.yaml
1314
```
1415

15-
To use `ArangoLocalStorage`, also run:
16+
To use `ArangoLocalStorage` resources, also run:
1617

1718
```bash
18-
kubectl apply -f https://raw.githubusercontent.com/arangodb/kube-arangodb/<version>/manifests/arango-storage.yaml
19+
kubectl apply -f $URLPREFIX/arango-storage.yaml
20+
```
21+
22+
To use `ArangoDeploymentReplication` resources, also run:
23+
24+
```bash
25+
kubectl apply -f $URLPREFIX/arango-deployment-replication.yaml
1926
```
2027

2128
You can find the latest release of the ArangoDB Kubernetes Operator
2229
[in the kube-arangodb repository](https://github.com/arangodb/kube-arangodb/releases/latest).
2330

24-
## Cluster creation
31+
## ArangoDB deployment creation
2532

26-
Once the operator is running, you can create your ArangoDB cluster
27-
by creating a custom resource and deploying it.
33+
Once the operator is running, you can create your ArangoDB database deployment
34+
by creating a `ArangoDeployment` custom resource and deploying it into your
35+
Kubernetes cluster.
2836

2937
For example (all examples can be found [in the kube-arangodb repository](https://github.com/arangodb/kube-arangodb/tree/master/examples)):
3038

3139
```bash
3240
kubectl apply -f examples/simple-cluster.yaml
3341
```
3442

35-
## Cluster removal
43+
## Deployment removal
3644

37-
To remove an existing cluster, delete the custom
45+
To remove an existing ArangoDB deployment, delete the custom
3846
resource. The operator will then delete all created resources.
3947

4048
For example:
@@ -43,13 +51,25 @@ For example:
4351
kubectl delete -f examples/simple-cluster.yaml
4452
```
4553

54+
**Note that this will also delete all data in your ArangoDB deployment!**
55+
56+
If you want to keep your data, make sure to create a backup before removing the deployment.
57+
4658
## Operator removal
4759

4860
To remove the entire ArangoDB Kubernetes Operator, remove all
4961
clusters first and then remove the operator by running:
5062

5163
```bash
5264
kubectl delete deployment arango-deployment-operator
53-
# If `ArangoLocalStorage` is installed
65+
# If `ArangoLocalStorage` operator is installed
5466
kubectl delete deployment -n kube-system arango-storage-operator
67+
# If `ArangoDeploymentReplication` operator is installed
68+
kubectl delete deployment arango-deployment-replication-operator
5569
```
70+
71+
## See also
72+
73+
- [Driver configuration](./DriverConfiguration.md)
74+
- [Scaling](./Scaling.md)
75+
- [Upgrading](./Upgrading.md)

0 commit comments

Comments
 (0)