Hawkin
/
arangodb
mirror of https://gitee.com/bigwinds/arangodb
1
0
Fork 0
Code Issues Projects Releases Wiki Activity

Doc - kube-arangodb docs integration (#5014)

This commit is contained in:
sleto-it 2018-04-05 12:57:24 +02:00 committed by GitHub
parent 7fe3134307
commit eb0b48c52b
No known key found for this signature in database
GPG Key ID: 4AEE18F83AFDEB23
20 changed files with 939 additions and 7 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

41
Documentation/Books/Manual/Deployment/Kubernetes/ConfigAndSecrets.md Normal file
View File

@ -0,0 +1,41 @@
<!-- don't edit here, its from https://@github.com/arangodb/kube-arangodb.git / docs/Manual/ -->
# Configuration & secrets
An ArangoDB cluster has lots of configuration options.
Some will be supported directly in the ArangoDB Operator,
others will have to specified separately.
## Built-in options
All built-in options are passed to ArangoDB servers via commandline
arguments configured in the Pod-spec.
## Other configuration options
All commandline options of `arangod` (and `arangosync`) are available
by adding options to the `spec.<group>.args` list of a group
of servers.
These arguments are added to th commandline created for these servers.
## Secrets
The ArangoDB cluster needs several secrets such as JWT tokens
TLS certificates and so on.
All these secrets are stored as Kubernetes Secrets and passed to
the applicable Pods as files, mapped into the Pods filesystem.
The name of the secret is specified in the custom resource.
For example:
```yaml
apiVersion: "cluster.arangodb.com/v1alpha"
kind: "Cluster"
metadata:
name: "example-arangodb-cluster"
spec:
mode: Cluster
auth:
jwtSecretName: <name-of-JWT-token-secret>
```

294
Documentation/Books/Manual/Deployment/Kubernetes/DeploymentResource.md Normal file
View File

@ -0,0 +1,294 @@
<!-- don't edit here, its from https://@github.com/arangodb/kube-arangodb.git / docs/Manual/ -->
# ArangoLocalStorage Custom Resource
The ArangoDB Deployment Operator creates and maintains ArangoDB deployments
in a Kubernetes cluster, given a deployment specification.
This deployment specification is a `CustomResource` following
a `CustomResourceDefinition` created by the operator.
Example minimal deployment definition of an ArangoDB database cluster:
```yaml
apiVersion: "database.arangodb.com/v1alpha"
kind: "ArangoDeployment"
metadata:
name: "example-arangodb-cluster"
spec:
mode: Cluster
```
Example more elaborate deployment definition:
```yaml
apiVersion: "database.arangodb.com/v1alpha"
kind: "ArangoDeployment"
metadata:
name: "example-arangodb-cluster"
spec:
mode: Cluster
environment: Production
agents:
count: 3
args:
- --log.level=debug
resources:
requests:
storage: 8Gi
storageClassName: ssd
dbservers:
count: 5
resources:
requests:
storage: 80Gi
storageClassName: ssd
coordinators:
count: 3
image: "arangodb/arangodb:3.3.4"
```
## Specification reference
Below you'll find all settings of the `ArangoDeployment` custom resource.
Several settings are for various groups of servers. These are indicated
with `<group>` where `<group>` can be any of:
- `agents` for all agents of a `Cluster` or `ResilientSingle` pair.
- `dbservers` for all dbservers of a `Cluster`.
- `coordinators` for all coordinators of a `Cluster`.
- `single` for all single servers of a `Single` instance or `ResilientSingle` pair.
- `syncmasters` for all syncmasters of a `Cluster`.
- `syncworkers` for all syncworkers of a `Cluster`.
### `spec.mode: string`
This setting specifies the type of deployment you want to create.
Possible values are:
- `Cluster` (default) Full cluster. Defaults to 3 agents, 3 dbservers & 3 coordinators.
- `ResilientSingle` Resilient single pair. Defaults to 3 agents and 2 single servers.
- `Single` Single server only (note this does not provide high availability or reliability).
This setting cannot be changed after the deployment has been created.
### `spec.environment: string`
This setting specifies the type of environment in which the deployment is created.
Possible values are:
- `Development` (default) This value optimizes the deployment for development
use. It is possible to run a deployment on a small number of nodes (e.g. minikube).
- `Production` This value optimizes the deployment for production use.
It puts required affinity constraints on all pods to avoid agents & dbservers
from running on the same machine.
### `spec.image: string`
This setting specifies the docker image to use for all ArangoDB servers.
In a `development` environment this setting defaults to `arangodb/arangodb:latest`.
For `production` environments this is a required setting without a default value.
It is highly recommend to use explicit version (not `latest`) for production
environments.
### `spec.imagePullPolicy: string`
This setting specifies the pull policy for the docker image to use for all ArangoDB servers.
Possible values are:
- `IfNotPresent` (default) to pull only when the image is not found on the node.
- `Always` to always pull the image before using it.
### `spec.storageEngine: string`
This setting specifies the type of storage engine used for all servers
in the cluster.
Possible values are:
- `MMFiles` To use the MMFiles storage engine.
- `RocksDB` (default) To use the RocksDB storage engine.
This setting cannot be changed after the cluster has been created.
### `spec.rocksdb.encryption.keySecretName`
This setting specifies the name of a kubernetes `Secret` that contains
an encryption key used for encrypting all data stored by ArangoDB servers.
When an encryption key is used, encryption of the data in the cluster is enabled,
without it encryption is disabled.
The default value is empty.
This requires the Enterprise version.
The encryption key cannot be changed after the cluster has been created.
The secret specified by this setting, must have a data field named 'key' containing
an encryption key that is exactly 32 bytes long.
### `spec.auth.jwtSecretName: string`
This setting specifies the name of a kubernetes `Secret` that contains
the JWT token used for accessing all ArangoDB servers.
When no name is specified, it defaults to `<deployment-name>-jwt`.
To disable authentication, set this value to `None`.
If you specify a name of a `Secret`, that secret must have the token
in a data field named `token`.
If you specify a name of a `Secret` that does not exist, a random token is created
and stored in a `Secret` with given name.
Changing a JWT token results in stopping the entire cluster
and restarting it.
### `spec.tls.caSecretName: string`
This setting specifies the name of a kubernetes `Secret` that contains
a standard CA certificate + private key used to sign certificates for individual
ArangoDB servers.
When no name is specified, it defaults to `<deployment-name>-ca`.
To disable authentication, set this value to `None`.
If you specify a name of a `Secret` that does not exist, a self-signed CA certificate + key is created
and stored in a `Secret` with given name.
The specified `Secret`, must contain the following data fields:
- `ca.crt` PEM encoded public key of the CA certificate
- `ca.key` PEM encoded private key of the CA certificate
### `spec.tls.altNames: []string`
This setting specifies a list of alternate names that will be added to all generated
certificates. These names can be DNS names or email addresses.
The default value is empty.
### `spec.tls.ttl: duration`
This setting specifies the time to live of all generated
server certificates.
The default value is `2160h` (about 3 month).
When the server certificate is about to expire, it will be automatically replaced
by a new one and the affected server will be restarted.
Note: The time to live of the CA certificate (when created automatically)
will be set to 10 years.
### `spec.sync.enabled: bool`
This setting enables/disables support for data center 2 data center
replication in the cluster. When enabled, the cluster will contain
a number of `syncmaster` & `syncworker` servers.
The default value is `false`.
### `spec.sync.image: string`
This setting specifies the docker image to use for all ArangoSync servers.
When not specified, the `spec.image` value is used.
### `spec.sync.imagePullPolicy: string`
This setting specifies the pull policy for the docker image to use for all ArangoSync servers.
For possible values, see `spec.imagePullPolicy`.
When not specified, the `spec.imagePullPolicy` value is used.
### `spec.sync.auth.jwtSecretName: string`
This setting specifies the name of a kubernetes `Secret` that contains
the JWT token used for accessing all ArangoSync master servers.
When not specified, the `spec.auth.jwtSecretName` value is used.
If you specify a name of a `Secret` that does not exist, a random token is created
and stored in a `Secret` with given name.
### `spec.sync.auth.clientCASecretName: string`
This setting specifies the name of a kubernetes `Secret` that contains
a PEM encoded CA certificate used for client certificate verification
in all ArangoSync master servers.
This is a required setting when `spec.sync.enabled` is `true`.
The default value is empty.
### `spec.sync.mq.type: string`
This setting sets the type of message queue used by ArangoSync.
Possible values are:
- `Direct` (default) for direct HTTP connections between the 2 data centers.
### `spec.sync.tls.caSecretName: string`
This setting specifies the name of a kubernetes `Secret` that contains
a standard CA certificate + private key used to sign certificates for individual
ArangoSync master servers.
When no name is specified, it defaults to `<deployment-name>-sync-ca`.
If you specify a name of a `Secret` that does not exist, a self-signed CA certificate + key is created
and stored in a `Secret` with given name.
The specified `Secret`, must contain the following data fields:
- `ca.crt` PEM encoded public key of the CA certificate
- `ca.key` PEM encoded private key of the CA certificate
### `spec.sync.tls.altNames: []string`
This setting specifies a list of alternate names that will be added to all generated
certificates. These names can be DNS names or email addresses.
The default value is empty.
### `spec.sync.monitoring.tokenSecretName: string`
This setting specifies the name of a kubernetes `Secret` that contains
the bearer token used for accessing all monitoring endpoints of all ArangoSync
servers.
When not specified, no monitoring token is used.
The default value is empty.
### `spec.ipv6.forbidden: bool`
This setting prevents the use of IPv6 addresses by ArangoDB servers.
The default is `false`.
### `spec.<group>.count: number`
This setting specifies the number of servers to start for the given group.
For the agent group, this value must be a positive, odd number.
The default value is `3` for all groups except `single` (there the default is `1`
for `spec.mode: single` and `2` for `spec.mode: resilientsingle`).
For the `syncworkers` group, it is highly recommended to use the same number
as for the `dbservers` group.
### `spec.<group>.args: [string]`
This setting specifies additional commandline arguments passed to all servers of this group.
The default value is an empty array.
### `spec.<group>.resources.requests.cpu: cpuUnit`
This setting specifies the amount of CPU requested by server of this group.
See https://kubernetes.io/docs/concepts/configuration/manage-compute-resources-container/ for details.
### `spec.<group>.resources.requests.memory: memoryUnit`
This setting specifies the amount of memory requested by server of this group.
See https://kubernetes.io/docs/concepts/configuration/manage-compute-resources-container/ for details.
### `spec.<group>.resources.requests.storage: storageUnit`
This setting specifies the amount of storage required for each server of this group.
The default value is `8Gi`.
This setting is not available for group `coordinators`, `syncmasters` & `syncworkers`
because servers in these groups do not need persistent storage.
### `spec.<group>.storageClassName: string`
This setting specifies the `storageClass` for the `PersistentVolume`s created
for each server of this group.
This setting is not available for group `coordinators`, `syncmasters` & `syncworkers`
because servers in these groups do not need persistent storage.

4
Documentation/Books/Manual/Deployment/Kubernetes/Metrics.md Normal file
View File

@ -0,0 +1,4 @@
<!-- don't edit here, its from https://@github.com/arangodb/kube-arangodb.git / docs/Manual/ -->
# Metrics
TBD

7
Documentation/Books/Manual/Deployment/Kubernetes/README.md Normal file
View File

@ -0,0 +1,7 @@
<!-- don't edit here, its from https://@github.com/arangodb/kube-arangodb.git / docs/Manual/ -->
# 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.

22
Documentation/Books/Manual/Deployment/Kubernetes/Scaling.md Normal file
View File

@ -0,0 +1,22 @@
<!-- don't edit here, its from https://@github.com/arangodb/kube-arangodb.git / docs/Manual/ -->
# Scaling
The ArangoDB Kubernetes Operator supports up and down scaling of
the number of dbservers & coordinators.
Currently it is not possible to change the number of
agents of a cluster.
The scale up or down, change the number of servers in the custom
resource.
E.g. change `spec.dbservers.count` from `3` to `4`.
Then apply the updated resource using:
```bash
kubectl apply -f yourCustomResourceFile.yaml
```
Inspect the status of the custom resource to monitor
the progress of the scaling operation.

75
Documentation/Books/Manual/Deployment/Kubernetes/ServicesAndLoadBalancer.md Normal file
View File

@ -0,0 +1,75 @@
<!-- don't edit here, its from https://@github.com/arangodb/kube-arangodb.git / docs/Manual/ -->
# Services and load balancer
The ArangoDB Kubernetes Operator will create services that can be used to
reach the ArangoDB servers from inside the Kubernetes cluster.
To use the ArangoDB servers from outside the Kubernetes cluster
you have to add another service as explained below.
## Services
### Single server
For a single server deployment, the operator creates a single
`Service` named `<cluster-name>`. This service has a normal cluster IP
address.
### Full cluster
For a full cluster deployment, the operator creates two `Services`.
- `<cluster-name>_servers` a headless `Service` intended to provide
DNS names for all pods created by the operator.
It selects all ArangoDB & ArangoSync servers in the cluster.
- `<cluster-name>` a normal `Service` that selects only the coordinators
of the cluster. This `Service` is configured with `ClientIP` session
affinity. This is needed for cursor requests, since they are bound to
a specific coordinator.
When the coordinators are asked to provide endpoints of the cluster
(e.g. when calling `client.SynchronizeEndpoints()` in the go driver)
the DNS names of the individual `Pods` will be returned
(`<pod>.<cluster-name>_servers.<namespace>.svc`)
### Full cluster with DC2DC
For a full cluster with datacenter replication deployment,
the same `Services` are created as for a Full cluster, with the following
additions:
- `<cluster-name>_sync` a normal `Service` that selects only the syncmasters
of the cluster.
## Load balancer
To reach the ArangoDB servers from outside the Kubernetes cluster, you
have to deploy additional services.
You can use `LoadBalancer` or `NodePort` services, depending on your
Kubernetes deployment.
This service should select:
- `arangodb_cluster_name: <cluster-name>`
- `role: coordinator`
For example:
```yaml
kind: Service
apiVersion: v1
metadata:
name: arangodb-cluster-exposed
spec:
selector:
arangodb_cluster_name: arangodb-cluster
role: coordinator
type: NodePort
ports:
- protocol: TCP
port: 8529
targetPort: 8529
nodePort: 30529
```

76
Documentation/Books/Manual/Deployment/Kubernetes/Storage.md Normal file
View File

@ -0,0 +1,76 @@
<!-- don't edit here, its from https://@github.com/arangodb/kube-arangodb.git / docs/Manual/ -->
# Storage
An ArangoDB cluster relies heavily on fast persistent storage.
The ArangoDB Kubernetes Operator uses `PersistentVolumeClaims` to deliver
the storage to Pods that need them.
## Storage configuration
In the cluster resource, one can specify the type of storage
used by groups of servers using the `spec.<group>.storageClassName`
setting.
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.
## Local storage
For optimal performance, ArangoDB should be configured with locally attached
SSD storage.
To accomplish this, one must create `PersistentVolumes` 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.
Note that each volume must have a capacity that is equal to or higher than the
capacity needed for each server.
To select the correct node, add a required node-affinity annotation as shown
in the example below.
```yaml
apiVersion: v1
kind: PersistentVolume
metadata:
name: volume-agent-1
annotations:
"volume.alpha.kubernetes.io/node-affinity": '{
"requiredDuringSchedulingIgnoredDuringExecution": {
"nodeSelectorTerms": [
{ "matchExpressions": [
{ "key": "kubernetes.io/hostname",
"operator": "In",
"values": ["node-1"]
}
]}
]}
}'
spec:
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
to bind volumes on their first use as shown in the example below.
This ensures that the Kubernetes scheduler takes all constraints on a `Pod`
that into consideration before binding the volume to a claim.
```yaml
kind: StorageClass
apiVersion: storage.k8s.io/v1
metadata:
name: local-ssd
provisioner: kubernetes.io/no-provisioner
volumeBindingMode: WaitForFirstConsumer
```

63
Documentation/Books/Manual/Deployment/Kubernetes/StorageResource.md Normal file
View File

@ -0,0 +1,63 @@
<!-- don't edit here, its from https://@github.com/arangodb/kube-arangodb.git / docs/Manual/ -->
# ArangoLocalStorage Custom Resource
The ArangoDB Storage Operator creates and maintains ArangoDB
storage resources in a Kubernetes cluster, given a storage specification.
This storage specification is a `CustomResource` following
a `CustomResourceDefinition` created by the operator.
Example minimal storage definition:
```yaml
apiVersion: "storage.arangodb.com/v1alpha"
kind: "ArangoLocalStorage"
metadata:
name: "example-arangodb-storage"
spec:
storageClass:
name: my-local-ssd
localPath:
- /mnt/big-ssd-disk
```
This definition results in:
- a `StorageClass` called `my-local-ssd`
- the dynamic provisioning of PersistentVolume's with
a local volume on a node where the local volume starts
in a sub-directory of `/mnt/big-ssd-disk`.
- the dynamic cleanup of PersistentVolume's (created by
the operator) after one is released.
The provisioned volumes will have a capacity that matches
the requested capacity of volume claims.
## Specification reference
Below you'll find all settings of the `ArangoLocalStorage` custom resource.
### `spec.storageClass.name: string`
This setting specifies the name of the storage class that
created `PersistentVolume` will use.
If empty, this field defaults to the name of the `ArangoLocalStorage`
object.
If a `StorageClass` with given name does not yet exist, it
will be created.
### `spec.storageClass.isDefault: bool`
This setting specifies if the created `StorageClass` will
be marked as default storage class. (default is `false`)
### `spec.localPath: stringList`
This setting specifies one of more local directories
(on the nodes) used to create persistent volumes in.
### `spec.nodeSelector: nodeSelector`
This setting specifies which nodes the operator will
provision persistent volumes on.

45
Documentation/Books/Manual/Deployment/Kubernetes/Tls.md Normal file
View File

@ -0,0 +1,45 @@
<!-- don't edit here, its from https://@github.com/arangodb/kube-arangodb.git / docs/Manual/ -->
# TLS
The ArangoDB Kubernetes Operator will by default create ArangoDB deployments
that use secure TLS connections.
It uses a single CA certificate (stored in a Kubernetes secret) and
one certificate per ArangoDB server (stored in a Kubernetes secret per server).
To disable TLS, set `spec.tls.caSecretName` to `None`.
## Install CA certificate
If the CA certificate is self-signed, it will not be trusted by browsers,
until you install it in the local operating system or browser.
This process differs per operating system.
To do so, you first have to fetch the CA certificate from its Kubernetes
secret.
```bash
kubectl get secret <deploy-name>-ca --template='{{index .data "ca.crt"}}' | base64 -D > ca.crt
```
### Windows
TODO
### MacOS
To install a CA certificate in MacOS, run:
```bash
sudo /usr/bin/security add-trusted-cert -d -r trustRoot -k /Library/Keychains/System.keychain ca.crt
```
To uninstall a CA certificate in MacOS, run:
```bash
sudo /usr/bin/security remove-trusted-cert -d ca.crt
```
### Linux
TODO

21
Documentation/Books/Manual/Deployment/Kubernetes/Upgrading.md Normal file
View File

@ -0,0 +1,21 @@
<!-- don't edit here, its from https://@github.com/arangodb/kube-arangodb.git / docs/Manual/ -->
# Upgrading
The ArangoDB Kubernetes Operator supports upgrading an ArangoDB from
one version to the next.
To upgrade a cluster, change the version by changing
the `spec.image` setting and the apply the updated
custom resource using:
```bash
kubectl apply -f yourCustomResourceFile.yaml
```
To update the ArangoDB Kubernetes Operator itself to a new version,
update the image version of the deployment resource
and apply it using:
```bash
kubectl apply -f examples/yourUpdatedDeployment.yaml
```

51
Documentation/Books/Manual/Deployment/Kubernetes/Usage.md Normal file
View File

@ -0,0 +1,51 @@
<!-- don't edit here, its from https://@github.com/arangodb/kube-arangodb.git / docs/Manual/ -->
# Using the ArangoDB Kubernetes Operator
## Installation
The ArangoDB Kubernetes Operator needs to be installed in your Kubernetes
cluster first. To do so, clone this repository and run:
```bash
kubectl apply -f manifests/crd.yaml
kubectl apply -f manifests/arango-deployment.yaml
```
To use `ArangoLocalStorage`, also run:
```bash
kubectl apply -f manifests/arango-storage.yaml
```
## Cluster creation
Once the operator is running, you can create your ArangoDB cluster
by creating a custom resource and deploying it.
For example:
```bash
kubectl apply -f examples/simple-cluster.yaml
```
## Cluster removal
To remove an existing cluster, delete the custom
resource. The operator will then delete all created resources.
For example:
```bash
kubectl delete -f examples/simple-cluster.yaml
```
## Operator removal
To remove the entire ArangoDB Kubernetes Operator, remove all
clusters first and then remove the operator by running:
```bash
kubectl delete -f manifests/arango-deployment.yaml
# If `ArangoLocalStorage` is installed
kubectl delete -f manifests/arango-storage.yaml
```

0
Documentation/Books/Manual/Programs/Starter/options.md → Documentation/Books/Manual/Programs/Starter/Options.md
View File

2
Documentation/Books/Manual/Programs/Starter/README.md
View File

@ -5,4 +5,4 @@ This chapter documents the _ArangoDB Starter_.
The _ArangoDB Starter_ is a tool that can help you deploy ArangoDB in an easy way (either in single-instance, active/passive or Cluster mode).
For a Tutorial, please refer to [this](../../GettingStarted/Starter/README.md) section.
For a Tutorial, please refer to [this](../../Tutorials/Starter/README.md) section.

0
Documentation/Books/Manual/Programs/Starter/security.md → Documentation/Books/Manual/Programs/Starter/Security.md
View File

18
Documentation/Books/Manual/SUMMARY.md
View File

@ -16,9 +16,11 @@
* [Next Steps](GettingStarted/NextSteps.md)
* [Tutorials](Tutorials/README.md)
# https://@github.com/arangodb-helper/arangodb.git;arangodb;docs/Manual;;/
* [ArangoDB Starter](GettingStarted/Starter/README.md)
* [ArangoDB Starter](Tutorials/Starter/README.md)
# https://@github.com/arangodb/arangosync.git;arangosync;docs/Manual;;/
* [Datacenter to datacenter Replication](GettingStarted/DC2DC/README.md)
* [Datacenter to datacenter Replication](Tutorials/DC2DC/README.md)
# https://@github.com/arangodb/kube-arangodb.git;kube-arangodb;docs/Manual;;/
* [Kubernetes](Tutorials/Kubernetes/README.md)
* [ArangoDB Programs](Programs/README.md)
# https://@github.com//arangodb-helper/arangodb.git;arangodb;docs/Manual;;/
* [ArangoDB Starter](Programs/Starter/README.md)
@ -177,6 +179,18 @@
* [ArangoSync Master](Deployment/DC2DC/ArangoSyncMaster.md)
* [ArangoSync Workers](Deployment/DC2DC/ArangoSyncWorkers.md)
* [Prometheus & Grafana](Deployment/DC2DC/PrometheusGrafana.md)
# https://@github.com/arangodb/kube-arangodb.git;kube-arangodb;docs/Manual;;/
* [Kubernetes](Deployment/Kubernetes/README.md)
* [Using the Operator](Deployment/Kubernetes/Usage.md)
* [Deployment Resource](Deployment/Kubernetes/DeploymentResource.md)
* [ArangoDB Configuration & Secrets](Deployment/Kubernetes/ConfigAndSecrets.md)
* [Metrics](Deployment/Kubernetes/Metrics.md)
* [Scaling](Deployment/Kubernetes/Scaling.md)
* [Services & Load balancer](Deployment/Kubernetes/ServicesAndLoadBalancer.md)
* [Storage](Deployment/Kubernetes/Storage.md)
* [Storage Resource](Deployment/Kubernetes/StorageResource.md)
* [TLS](Deployment/Kubernetes/Tls.md)
* [Upgrading](Deployment/Kubernetes/Upgrading.md)
* [Administration](Administration/README.md)
* [Web Interface](Administration/WebInterface/README.md)
* [Dashboard](Administration/WebInterface/Dashboard.md)

BIN
Documentation/Books/Manual/Scalability/DC2DC/dc2dc.png
View File

Binary file not shown.
Side by Side Swipe Overlay

Before

Width:  |  Height:  |  Size: 183 KiB

After

Width:  |  Height:  |  Size: 183 KiB

0
Documentation/Books/Manual/GettingStarted/DC2DC/README.md → Documentation/Books/Manual/Tutorials/DC2DC/README.md
View File

210
Documentation/Books/Manual/Tutorials/Kubernetes/README.md Normal file
View File

@ -0,0 +1,210 @@
<!-- don't edit here, its from https://@github.com/arangodb/kube-arangodb.git / docs/Manual/ -->
# Start ArangoDB on Kubernetes in 5 minutes
Starting an ArangoDB database (either single server or full blown cluster)
on Kubernetes involves a lot of resources.
The servers needs to run in `Pods`, you need `Secrets` for authentication,
TLS certificates and `Services` to enable communication with the database.
Use `kube-arangodb`, the ArangoDB Kubernetes Operator to greatly simplify
this process.
In this guide, we will explain what the ArangoDB Kubernetes Operator is,
how to install it and how use it to deploy your first ArangoDB database
in a Kubernetes cluster.
## What is `kube-arangodb`
`kube-arangodb` is a set of two operators that you deploy in your Kubernetes
cluster to (1) manage deployments of the ArangoDB database and (2)
provide `PersistentVolumes` on local storage of your nodes for optimal
storage performance.
Note that the operator that provides `PersistentVolumes` is not needed to
run ArangoDB deployments. You can also use `PersistentVolumes` provided
by other controllers.
In this guide we will focus on the `ArangoDeployment` operator.
## Installing `kube-arangodb`
To install `kube-arangodb` in your Kubernetes cluster, make sure
you have access to this cluster and the rights to deploy resources
at cluster level.
For now, any recent Kubernetes cluster will do (e.g. `minikube`).
Then run (replace `<version>` with the version of the operator that you want to install):
```bash
kubectl apply -f https://raw.githubusercontent.com/arangodb/kube-arangodb/<version>/manifests/crd.yaml
kubectl apply -f https://raw.githubusercontent.com/arangodb/kube-arangodb/<version>/manifests/arango-deployment.yaml
```
The first command installs two `CustomResourceDefinitions` in your Kubernetes cluster:
- `ArangoDeployment` is the resource used to deploy ArangoDB database.
- `ArangoLocalStorage` is the resource used to provision `PersistentVolumes` on local storage.
The second command installs a `Deployment` that runs the operator that controls
`ArangoDeployment` resources.
## Deploying your first ArangoDB database
The first database we are going to deploy is a single server database.
Create a file called `single-server.yaml` with the following content.
```yaml
apiVersion: "database.arangodb.com/v1alpha"
kind: "ArangoDeployment"
metadata:
name: "single-server"
spec:
mode: Single
```
Now insert this resource in your Kubernetes cluster using:
```bash
kubectl apply -f single-server.yaml
```
The `ArangoDeployment` operator in `kube-arangodb` will now inspect the
resource you just deployed and start the process to run a single server database.
To inspect the current status of your deployment, run:
```bash
kubectl describe ArangoDeployment single-server
# or shorter
kubectl describe arango single-server
```
To inspect the pods created for this deployment, run:
```bash
kubectl get pods --selector=arango_deployment=single-server
```
The result will look similar to this:
```plain
NAME READY STATUS RESTARTS AGE
single-server-sngl-cjtdxrgl-fe06f0 1/1 Running 0 1m
```
Once the pod reports that it is has a `Running` status and is ready,
your database s available.
## Connecting to your database
The single server database you deployed in the previous chapter is now
available, but only from within the Kubernetes cluster.
To make the database available outside your Kubernetes cluster (e.g. for browser access)
you must deploy an additional `Service`.
There are several possible types of `Service` to choose from.
We are going to use the `NodePort` type to expose the database on port 30529 of
every node of your Kubernetes cluster.
Create a file called `single-server-service.yaml` with the following content.
```yaml
kind: Service
apiVersion: v1
metadata:
name: single-server-service
spec:
selector:
app: arangodb
arango_deployment: single-server
role: single
type: NodePort
ports:
- protocol: TCP
port: 8529
targetPort: 8529
nodePort: 30529
```
Deploy the `Service` into your Kubernetes cluster using:
```bash
kubectl apply -f single-server-service.yaml
```
Now you can connect your browser to `https://<node name>:30529/`,
where `<node name>` is the name or IP address of any of the nodes
of your Kubernetes cluster.
Your browser will show a warning about an unknown certificate.
Accept the certificate for now.
Then login using username `root` and an empty password.
If you want to delete your single server ArangoDB database, just run:
```bash
kubectl delete ArangoDeployment single-server
```
## Deploying a full blown ArangoDB cluster database
The deployment of a full blown cluster is very similar to deploying
a single server database. The difference is in the `mode` field of
the `ArangoDeployment` specification.
Create a file called `cluster.yaml` with the following content.
```yaml
apiVersion: "database.arangodb.com/v1alpha"
kind: "ArangoDeployment"
metadata:
name: "cluster"
spec:
mode: Cluster
```
Now insert this resource in your Kubernetes cluster using:
```bash
kubectl apply -f cluster.yaml
```
The same commands used in the single server deployment can be used
to inspect your cluster. Just use the correct deployment name (`cluster` instead of `single-server`).
Connecting to your cluster requires a different `Service` since the
selector now has to select your `cluster` deployment and instead
of selecting all `Pods` with role `single` it will have to select
all coordinator pods.
The service looks like this:
```yaml
kind: Service
apiVersion: v1
metadata:
name: cluster-service
spec:
selector:
app: arangodb
arango_deployment: cluster
role: coordinator
type: NodePort
ports:
- protocol: TCP
port: 8529
targetPort: 8529
nodePort: 31529
```
Note that we have chosen a different node port (31529) for this `Service`
to avoid conflicts with the port used in `single-server-service`.
## Where to go from here
- [ArangoDB Kubernetes Operator](../../Deployment/Kubernetes/README.md)

11
Documentation/Books/Manual/Tutorials/README.md
View File

@ -1,2 +1,11 @@
Tutorials
=========
=========
- [ArangoDB Starter](Starter/README.md):
Starting an ArangoDB Cluster or database the easy way
- [Datacenter to datacenter Replication](DC2DC/README.md):
A tutorial about the ArangoSync DC2DC solution
- [Kubernetes](Kubernetes/README.md):
Start ArangoDB on Kubernetes in 5 minutes

6
Documentation/Books/Manual/GettingStarted/Starter/README.md → Documentation/Books/Manual/Tutorials/Starter/README.md
View File

@ -52,7 +52,7 @@ the console, the starter uses the next few ports above the starter
port. That is, if one uses port 8528 for the starter, the coordinator
will use 8529 (=8528+1), the dbserver 8530 (=8528+2), and the agent 8531
(=8528+3). You can change the default starter port with the `--starter.port`
[option](../../Programs/Starter/options.md).
[option](../../Programs/Starter/Options.md).
Additional servers can be added in the same way.
@ -271,6 +271,6 @@ Make sure to match the arguments given to start the starter (`--starter.port` &
## More information
- [Options](../../Programs/Starter/options.md) contains a list of all commandline options supported by the starter.
- [Security](../../Programs/Starter/security.md) contains instructions of how to create certificates & tokens needed
- [Options](../../Programs/Starter/Options.md) contains a list of all commandline options supported by the starter.
- [Security](../../Programs/Starter/Security.md) contains instructions of how to create certificates & tokens needed
to secure an ArangoDB deployment.