Skip to content

Commit 16ada24

Browse files
ewoutpewoutp
committed
Merge branch 'master' of github.com:arangodb/kube-arangodb
2 parents 0b48d62 + e34089a commit 16ada24

File tree

8 files changed

+403
-25
lines changed

8 files changed

+403
-25
lines changed

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

+18
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,18 @@
1+
# Authentication
2+
3+
The ArangoDB Kubernetes Operator will by default create ArangoDB deployments
4+
that require authentication to access the database.
5+
6+
It uses a single JWT secret (stored in a Kubernetes secret)
7+
to provide *super-user* access between all servers of the deployment
8+
as well as access from the ArangoDB Operator to the deployment.
9+
10+
To disable authentication, set `spec.auth.jwtSecretName` to `None`.
11+
12+
Initially the deployment is accessible through the web user-interface and
13+
API's, using the user `root` with an empty password.
14+
Make sure to change this password immediately after starting the deployment!
15+
16+
## See also
17+
18+
- [Secure connections (TLS)](./Tls.md)

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

+128
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 too 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 sent to exactly 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

+19-4
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/Storage.md

+62-8
Original file line numberDiff line numberDiff line change
@@ -10,13 +10,45 @@ In the `ArangoDeployment` resource, one can specify the type of storage
1010
used by groups of servers using the `spec.<group>.storageClassName`
1111
setting.
1212

13+
This is an example of a `Cluster` deployment that stores its agent & dbserver
14+
data on `PersistentVolumes` that use the `my-local-ssd` `StorageClass`
15+
16+
```yaml
17+
apiVersion: "database.arangodb.com/v1alpha"
18+
kind: "ArangoDeployment"
19+
metadata:
20+
name: "cluster-using-local-ssh"
21+
spec:
22+
mode: Cluster
23+
agents:
24+
storageClassName: my-local-ssd
25+
dbservers:
26+
storageClassName: my-local-ssd
27+
```
28+
1329
The amount of storage needed is configured using the
1430
`spec.<group>.resources.requests.storage` setting.
1531

1632
Note that configuring storage is done per group of servers.
1733
It is not possible to configure storage per individual
1834
server.
1935

36+
This is an example of a `Cluster` deployment that requests volumes of 80GB
37+
for every dbserver, resulting in a total storage capacity of 240GB (with 3 dbservers).
38+
39+
```yaml
40+
apiVersion: "database.arangodb.com/v1alpha"
41+
kind: "ArangoDeployment"
42+
metadata:
43+
name: "cluster-using-local-ssh"
44+
spec:
45+
mode: Cluster
46+
dbservers:
47+
resources:
48+
requests:
49+
storage: 80Gi
50+
```
51+
2052
## Local storage
2153

2254
For optimal performance, ArangoDB should be configured with locally attached
@@ -26,6 +58,28 @@ The easiest way to accomplish this is to deploy an
2658
[`ArangoLocalStorage` resource](./StorageResource.md).
2759
The ArangoDB Storage Operator will use it to provide `PersistentVolumes` for you.
2860

61+
This is an example of an `ArangoLocalStorage` resource that will result in
62+
`PersistentVolumes` created on any node of the Kubernetes cluster
63+
under the directory `/mnt/big-ssd-disk`.
64+
65+
```yaml
66+
apiVersion: "storage.arangodb.com/v1alpha"
67+
kind: "ArangoLocalStorage"
68+
metadata:
69+
name: "example-arangodb-storage"
70+
spec:
71+
storageClass:
72+
name: my-local-ssd
73+
localPath:
74+
- /mnt/big-ssd-disk
75+
```
76+
77+
Note that using local storage required `VolumeScheduling` to be enabled in your
78+
Kubernetes cluster. ON Kubernetes 1.10 this is enabled by default, on version
79+
1.9 you have to enable it with a `--feature-gate` setting.
80+
81+
### Manually creating `PersistentVolumes`
82+
2983
The alternative is to create `PersistentVolumes` manually, for all servers that
3084
need persistent storage (single, agents & dbservers).
3185
E.g. for a `Cluster` with 3 agents and 5 dbservers, you must create 8 volumes.
@@ -54,14 +108,14 @@ metadata:
54108
]}
55109
}'
56110
spec:
57-
capacity:
58-
storage: 100Gi
59-
accessModes:
60-
- ReadWriteOnce
61-
persistentVolumeReclaimPolicy: Delete
62-
storageClassName: local-ssd
63-
local:
64-
path: /mnt/disks/ssd1
111+
capacity:
112+
storage: 100Gi
113+
accessModes:
114+
- ReadWriteOnce
115+
persistentVolumeReclaimPolicy: Delete
116+
storageClassName: local-ssd
117+
local:
118+
path: /mnt/disks/ssd1
65119
```
66120

67121
For Kubernetes 1.9 and up, you should create a `StorageClass` which is configured

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

+13-3
Original file line numberDiff line numberDiff line change
@@ -1,4 +1,4 @@
1-
# TLS
1+
# Secure connections (TLS)
22

33
The ArangoDB Kubernetes Operator will by default create ArangoDB deployments
44
that use secure TLS connections.
@@ -23,7 +23,8 @@ kubectl get secret <deploy-name>-ca --template='{{index .data "ca.crt"}}' | base
2323

2424
### Windows
2525

26-
TODO
26+
To install a CA certificate in Windows, follow the
27+
[procedure described here](http://wiki.cacert.org/HowTo/InstallCAcertRoots).
2728

2829
### MacOS
2930

@@ -41,4 +42,13 @@ sudo /usr/bin/security remove-trusted-cert -d ca.crt
4142

4243
### Linux
4344

44-
TODO
45+
To install a CA certificate in Linux, on Ubuntu, run:
46+
47+
```bash
48+
sudo cp ca.crt /usr/local/share/ca-certificates/<some-name>.crt
49+
sudo update-ca-certificates
50+
```
51+
52+
## See also
53+
54+
- [Authentication](./Authentication.md)

0 commit comments

Comments
 (0)