Improving documentation

docs/Manual/Deployment/Kubernetes/Authentication.md

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

docs/Manual/Deployment/Kubernetes/DriverConfiguration.md

@@ -0,0 +1,128 @@
+# Configuring your driver for ArangoDB access
+
+In this chapter you'll learn how to configure a driver for accessing
+an ArangoDB deployment in Kubernetes.
+
+The exact methods to configure a driver are specific to that driver.
+
+## Database endpoint(s)
+
+The endpoint(s) (or URLs) to communicate with is the most important
+parameter your need to configure in your driver.
+
+Finding the right endpoints depend on wether your client application is running in
+the same Kubernetes cluster as the ArangoDB deployment or not.
+
+### Client application in same Kubernetes cluster
+
+If your client application is running in the same Kubernetes cluster as
+the ArangoDB deployment, you should configure your driver to use the
+following endpoint:
+
+```text
+https://<deployment-name>.<namespace>.svc:8529
+```
+
+Only if your deployment has set `spec.tls.caSecretName` to `None`, should
+you use `http` instead of `https`.
+
+### Client application outside Kubernetes cluster
+
+If your client application is running outside the Kubernetes cluster in which
+the ArangoDB deployment is running, your driver endpoint depends on the
+external-access configuration of your ArangoDB deployment.
+
+If the external-access of the ArangoDB deployment is of type `LoadBalancer`,
+then use the IP address of that `LoadBalancer` like this:
+
+```text
+https://<load-balancer-ip>:8529
+```
+
+If the external-access of the ArangoDB deployment is of type `NodePort`,
+then use the IP address(es) of the `Nodes` of the Kubernetes cluster,
+combined with the `NodePort` that is used by the external-access service.
+
+For example:
+
+```text
+https://<kubernetes-node-1-ip>:30123
+```
+
+You can find the type of external-access by inspecting the external-access `Service`.
+To do so, run the following command:
+
+```bash
+kubectl get service -n <namespace-of-deployment> <deployment-name>-ea
+```
+
+The output looks like this:
+
+```bash
+NAME                         TYPE           CLUSTER-IP       EXTERNAL-IP      PORT(S)          AGE       SELECTOR
+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
+```
+
+In this case the external-access is of type `LoadBalancer` with a load-balancer IP address
+of `192.168.10.208`.
+This results in an endpoint of `https://192.168.10.208:8529`.
+
+## TLS settings
+
+As mentioned before the ArangoDB deployment managed by the ArangoDB operator
+will use a secure (TLS) connection unless you set `spec.tls.caSecretName` to `None`
+in your `ArangoDeployment`.
+
+When using a secure connection, you can choose to verify the server certificates
+provides by the ArangoDB servers or not.
+
+If you want to verify these certificates, configure your driver with the CA certificate
+found in a Kubernetes `Secret` found in the same namespace as the `ArangoDeployment`.
+
+The name of this `Secret` is stored in the `spec.tls.caSecretName` setting of
+the `ArangoDeployment`. If you don't set this setting explicitly, it will be
+set automatically.
+
+Then fetch the CA secret using the following command (or use a Kubernetes client library to fetch it):
+
+```bash
+kubectl get secret -n <namespace> <secret-name> --template='{{index .data "ca.crt"}}' | base64 -D > ca.crt
+```
+
+This results in a file called `ca.crt` containing a PEM encoded, x509 CA certificate.
+
+## Query requests
+
+For most client requests made by a driver, it does not matter if there is any kind
+of load-balancer between your client application and the ArangoDB deployment.
+
+{% hint 'info' %}
+Note that even a simple `Service` of type `ClusterIP` already behaves as a load-balancer.
+{% endhint %}
+
+The exception to this is cursor related requests made to an ArangoDB `Cluster` deployment.
+The coordinator that handles an initial query request (that results in a `Cursor`)
+will save some in-memory state in that coordinator, if the result of the query
+is too big to be transfer back in the response of the initial request.
+
+Follow-up requests have to be made to fetch the remaining data.
+These follow-up requests must be handled by the same coordinator to which the initial
+request was made.
+
+As soon as there is a load-balancer between your client application and the ArangoDB cluster,
+it is uncertain which coordinator will actually handle the follow-up request.
+
+To resolve this uncertainty, make sure to run your client application in the same
+Kubernetes cluster and synchronize your endpoints before making the
+initial query request.
+This will result in the use (by the driver) of internal DNS names of all coordinators.
+A follow-up request can then be sent to exactly the same coordinator.
+
+If your client application is running outside the Kubernetes cluster this is much harder
+to solve.
+The easiest way to work around it, is by making sure that the query results are small
+enough.
+When that is not feasible, it is also possible to resolve this
+when the internal DNS names of your Kubernetes cluster are exposed to your client application
+and the resuling IP addresses are routeable from your client application.
+To expose internal DNS names of your Kubernetes cluster, your can use [CoreDNS](https://coredns.io).

docs/Manual/Deployment/Kubernetes/README.md

@@ -1,6 +1,21 @@
 # ArangoDB Kubernetes Operator
 
-The ArangoDB Kubernetes Operator (`kube-arangodb`) is a set of two operators
-that you deploy in your Kubernetes cluster to manage deployments of the
-ArangoDB database and provide `PersistentVolumes` on local storage of your
-nodes for optimal storage performance.
+The ArangoDB Kubernetes Operator (`kube-arangodb`) is a set of operators
+that you deploy in your Kubernetes cluster to:
+
+- Manage deployments of the ArangoDB database
+- Provide `PersistentVolumes` on local storage of your nodes for optimal storage performance.
+- Configure ArangoDB Datacenter to Datacenter replication
+
+Each of these uses involves a different custom resource.
+
+- Use an [`ArangoDeployment` resource](./DeploymentResource.md) to
+  create an ArangoDB database deployment.
+- Use an [`ArangoLocalStorage` resource](./StorageResource.md) to
+  provide local `PersistentVolumes` for optimal I/O performance.
+- Use an [`ArangoDeploymentReplication` resource](./DeploymentReplicationResource.md) to
+  configure ArangoDB Datacenter to Datacenter replication.
+
+Continue with [Using the ArangoDB Kubernetes Operator](./Usage.md)
+to learn how to install the ArangoDB Kubernetes operator and create
+your first deployment.

docs/Manual/Deployment/Kubernetes/Storage.md

@@ -10,13 +10,45 @@ In the `ArangoDeployment` resource, one can specify the type of storage
 used by groups of servers using the `spec.<group>.storageClassName`
 setting.
 
+This is an example of a `Cluster` deployment that stores its agent & dbserver
+data on `PersistentVolumes` that use the `my-local-ssd` `StorageClass`
+
+```yaml
+apiVersion: "database.arangodb.com/v1alpha"
+kind: "ArangoDeployment"
+metadata:
+  name: "cluster-using-local-ssh"
+spec:
+  mode: Cluster
+  agents:
+    storageClassName: my-local-ssd
+  dbservers:
+    storageClassName: my-local-ssd
+```
+
 The amount of storage needed is configured using the
 `spec.<group>.resources.requests.storage` setting.
 
 Note that configuring storage is done per group of servers.
 It is not possible to configure storage per individual
 server.
 
+This is an example of a `Cluster` deployment that requests volumes of 80GB
+for every dbserver, resulting in a total storage capacity of 240GB (with 3 dbservers).
+
+```yaml
+apiVersion: "database.arangodb.com/v1alpha"
+kind: "ArangoDeployment"
+metadata:
+  name: "cluster-using-local-ssh"
+spec:
+  mode: Cluster
+  dbservers:
+    resources:
+      requests:
+        storage: 80Gi
+```
+
 ## Local storage
 
 For optimal performance, ArangoDB should be configured with locally attached
@@ -26,6 +58,28 @@ The easiest way to accomplish this is to deploy an
 [`ArangoLocalStorage` resource](./StorageResource.md).
 The ArangoDB Storage Operator will use it to provide `PersistentVolumes` for you.
 
+This is an example of an `ArangoLocalStorage` resource that will result in
+`PersistentVolumes` created on any node of the Kubernetes cluster
+under the directory `/mnt/big-ssd-disk`.
+
+```yaml
+apiVersion: "storage.arangodb.com/v1alpha"
+kind: "ArangoLocalStorage"
+metadata:
+  name: "example-arangodb-storage"
+spec:
+  storageClass:
+    name: my-local-ssd
+  localPath:
+  - /mnt/big-ssd-disk
+```
+
+Note that using local storage required `VolumeScheduling` to be enabled in your
+Kubernetes cluster. ON Kubernetes 1.10 this is enabled by default, on version
+1.9 you have to enable it with a `--feature-gate` setting.
+
+### Manually creating `PersistentVolumes`
+
 The alternative is to create `PersistentVolumes` manually, for all servers that
 need persistent storage (single, agents & dbservers).
 E.g. for a `Cluster` with 3 agents and 5 dbservers, you must create 8 volumes.
@@ -54,14 +108,14 @@ metadata:
                  ]}
               }'
 spec:
-    capacity:
-      storage: 100Gi
-    accessModes:
-    - ReadWriteOnce
-    persistentVolumeReclaimPolicy: Delete
-    storageClassName: local-ssd
-    local:
-      path: /mnt/disks/ssd1
+  capacity:
+    storage: 100Gi
+  accessModes:
+  - ReadWriteOnce
+  persistentVolumeReclaimPolicy: Delete
+  storageClassName: local-ssd
+  local:
+    path: /mnt/disks/ssd1
 ```
 
 For Kubernetes 1.9 and up, you should create a `StorageClass` which is configured

docs/Manual/Deployment/Kubernetes/Tls.md

@@ -1,4 +1,4 @@
-# TLS
+# Secure connections (TLS)
 
 The ArangoDB Kubernetes Operator will by default create ArangoDB deployments
 that use secure TLS connections.
@@ -23,7 +23,8 @@ kubectl get secret <deploy-name>-ca --template='{{index .data "ca.crt"}}' | base
 
 ### Windows
 
-TODO
+To install a CA certificate in Windows, follow the
+[procedure described here](http://wiki.cacert.org/HowTo/InstallCAcertRoots).
 
 ### MacOS
 
@@ -41,4 +42,13 @@ sudo /usr/bin/security remove-trusted-cert -d ca.crt
 
 ### Linux
 
-TODO
+To install a CA certificate in Linux, on Ubuntu, run:
+
+```bash
+sudo cp ca.crt /usr/local/share/ca-certificates/<some-name>.crt
+sudo update-ca-certificates
+```
+
+## See also
+
+- [Authentication](./Authentication.md)