From eb0b48c52b8ce5daf7497b23ddc3a4b2875022f0 Mon Sep 17 00:00:00 2001 From: sleto-it <31849787+sleto-it@users.noreply.github.com> Date: Thu, 5 Apr 2018 12:57:24 +0200 Subject: [PATCH] Doc - kube-arangodb docs integration (#5014) --- .../Deployment/Kubernetes/ConfigAndSecrets.md | 41 +++ .../Kubernetes/DeploymentResource.md | 294 ++++++++++++++++++ .../Manual/Deployment/Kubernetes/Metrics.md | 4 + .../Manual/Deployment/Kubernetes/README.md | 7 + .../Manual/Deployment/Kubernetes/Scaling.md | 22 ++ .../Kubernetes/ServicesAndLoadBalancer.md | 75 +++++ .../Manual/Deployment/Kubernetes/Storage.md | 76 +++++ .../Deployment/Kubernetes/StorageResource.md | 63 ++++ .../Books/Manual/Deployment/Kubernetes/Tls.md | 45 +++ .../Manual/Deployment/Kubernetes/Upgrading.md | 21 ++ .../Manual/Deployment/Kubernetes/Usage.md | 51 +++ .../Starter/{options.md => Options.md} | 0 .../Books/Manual/Programs/Starter/README.md | 2 +- .../Starter/{security.md => Security.md} | 0 Documentation/Books/Manual/SUMMARY.md | 18 +- .../Books/Manual/Scalability/DC2DC/dc2dc.png | Bin 187241 -> 187335 bytes .../DC2DC/README.md | 0 .../Manual/Tutorials/Kubernetes/README.md | 210 +++++++++++++ .../Books/Manual/Tutorials/README.md | 11 +- .../Starter/README.md | 6 +- 20 files changed, 939 insertions(+), 7 deletions(-) create mode 100644 Documentation/Books/Manual/Deployment/Kubernetes/ConfigAndSecrets.md create mode 100644 Documentation/Books/Manual/Deployment/Kubernetes/DeploymentResource.md create mode 100644 Documentation/Books/Manual/Deployment/Kubernetes/Metrics.md create mode 100644 Documentation/Books/Manual/Deployment/Kubernetes/README.md create mode 100644 Documentation/Books/Manual/Deployment/Kubernetes/Scaling.md create mode 100644 Documentation/Books/Manual/Deployment/Kubernetes/ServicesAndLoadBalancer.md create mode 100644 Documentation/Books/Manual/Deployment/Kubernetes/Storage.md create mode 100644 Documentation/Books/Manual/Deployment/Kubernetes/StorageResource.md create mode 100644 Documentation/Books/Manual/Deployment/Kubernetes/Tls.md create mode 100644 Documentation/Books/Manual/Deployment/Kubernetes/Upgrading.md create mode 100644 Documentation/Books/Manual/Deployment/Kubernetes/Usage.md rename Documentation/Books/Manual/Programs/Starter/{options.md => Options.md} (100%) rename Documentation/Books/Manual/Programs/Starter/{security.md => Security.md} (100%) rename Documentation/Books/Manual/{GettingStarted => Tutorials}/DC2DC/README.md (100%) create mode 100644 Documentation/Books/Manual/Tutorials/Kubernetes/README.md rename Documentation/Books/Manual/{GettingStarted => Tutorials}/Starter/README.md (98%) diff --git a/Documentation/Books/Manual/Deployment/Kubernetes/ConfigAndSecrets.md b/Documentation/Books/Manual/Deployment/Kubernetes/ConfigAndSecrets.md new file mode 100644 index 0000000000..a7ff858d51 --- /dev/null +++ b/Documentation/Books/Manual/Deployment/Kubernetes/ConfigAndSecrets.md @@ -0,0 +1,41 @@ + +# 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..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: +``` diff --git a/Documentation/Books/Manual/Deployment/Kubernetes/DeploymentResource.md b/Documentation/Books/Manual/Deployment/Kubernetes/DeploymentResource.md new file mode 100644 index 0000000000..d1bd0a9bee --- /dev/null +++ b/Documentation/Books/Manual/Deployment/Kubernetes/DeploymentResource.md @@ -0,0 +1,294 @@ + +# 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 `` where `` 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 `-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 `-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 `-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..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..args: [string]` + +This setting specifies additional commandline arguments passed to all servers of this group. +The default value is an empty array. + +### `spec..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..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..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..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. diff --git a/Documentation/Books/Manual/Deployment/Kubernetes/Metrics.md b/Documentation/Books/Manual/Deployment/Kubernetes/Metrics.md new file mode 100644 index 0000000000..42682fc24e --- /dev/null +++ b/Documentation/Books/Manual/Deployment/Kubernetes/Metrics.md @@ -0,0 +1,4 @@ + +# Metrics + +TBD diff --git a/Documentation/Books/Manual/Deployment/Kubernetes/README.md b/Documentation/Books/Manual/Deployment/Kubernetes/README.md new file mode 100644 index 0000000000..12e10aa103 --- /dev/null +++ b/Documentation/Books/Manual/Deployment/Kubernetes/README.md @@ -0,0 +1,7 @@ + +# 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. diff --git a/Documentation/Books/Manual/Deployment/Kubernetes/Scaling.md b/Documentation/Books/Manual/Deployment/Kubernetes/Scaling.md new file mode 100644 index 0000000000..a509879e03 --- /dev/null +++ b/Documentation/Books/Manual/Deployment/Kubernetes/Scaling.md @@ -0,0 +1,22 @@ + +# 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. diff --git a/Documentation/Books/Manual/Deployment/Kubernetes/ServicesAndLoadBalancer.md b/Documentation/Books/Manual/Deployment/Kubernetes/ServicesAndLoadBalancer.md new file mode 100644 index 0000000000..fb8bd4420c --- /dev/null +++ b/Documentation/Books/Manual/Deployment/Kubernetes/ServicesAndLoadBalancer.md @@ -0,0 +1,75 @@ + +# 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 ``. This service has a normal cluster IP +address. + +### Full cluster + +For a full cluster deployment, the operator creates two `Services`. + +- `_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. + +- `` 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 +(`._servers..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: + +- `_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: ` +- `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 +``` diff --git a/Documentation/Books/Manual/Deployment/Kubernetes/Storage.md b/Documentation/Books/Manual/Deployment/Kubernetes/Storage.md new file mode 100644 index 0000000000..dfc9fa679d --- /dev/null +++ b/Documentation/Books/Manual/Deployment/Kubernetes/Storage.md @@ -0,0 +1,76 @@ + +# 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..storageClassName` +setting. + +The amount of storage needed is configured using the +`spec..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 +``` diff --git a/Documentation/Books/Manual/Deployment/Kubernetes/StorageResource.md b/Documentation/Books/Manual/Deployment/Kubernetes/StorageResource.md new file mode 100644 index 0000000000..08eb00b320 --- /dev/null +++ b/Documentation/Books/Manual/Deployment/Kubernetes/StorageResource.md @@ -0,0 +1,63 @@ + +# 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. diff --git a/Documentation/Books/Manual/Deployment/Kubernetes/Tls.md b/Documentation/Books/Manual/Deployment/Kubernetes/Tls.md new file mode 100644 index 0000000000..3314cc4018 --- /dev/null +++ b/Documentation/Books/Manual/Deployment/Kubernetes/Tls.md @@ -0,0 +1,45 @@ + +# 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 -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 diff --git a/Documentation/Books/Manual/Deployment/Kubernetes/Upgrading.md b/Documentation/Books/Manual/Deployment/Kubernetes/Upgrading.md new file mode 100644 index 0000000000..980eb8a660 --- /dev/null +++ b/Documentation/Books/Manual/Deployment/Kubernetes/Upgrading.md @@ -0,0 +1,21 @@ + +# 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 +``` diff --git a/Documentation/Books/Manual/Deployment/Kubernetes/Usage.md b/Documentation/Books/Manual/Deployment/Kubernetes/Usage.md new file mode 100644 index 0000000000..13d1088369 --- /dev/null +++ b/Documentation/Books/Manual/Deployment/Kubernetes/Usage.md @@ -0,0 +1,51 @@ + +# 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 +``` diff --git a/Documentation/Books/Manual/Programs/Starter/options.md b/Documentation/Books/Manual/Programs/Starter/Options.md similarity index 100% rename from Documentation/Books/Manual/Programs/Starter/options.md rename to Documentation/Books/Manual/Programs/Starter/Options.md diff --git a/Documentation/Books/Manual/Programs/Starter/README.md b/Documentation/Books/Manual/Programs/Starter/README.md index ca7b398196..3b2ae4a5dc 100644 --- a/Documentation/Books/Manual/Programs/Starter/README.md +++ b/Documentation/Books/Manual/Programs/Starter/README.md @@ -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. diff --git a/Documentation/Books/Manual/Programs/Starter/security.md b/Documentation/Books/Manual/Programs/Starter/Security.md similarity index 100% rename from Documentation/Books/Manual/Programs/Starter/security.md rename to Documentation/Books/Manual/Programs/Starter/Security.md diff --git a/Documentation/Books/Manual/SUMMARY.md b/Documentation/Books/Manual/SUMMARY.md index f4a953d389..8c061404c4 100644 --- a/Documentation/Books/Manual/SUMMARY.md +++ b/Documentation/Books/Manual/SUMMARY.md @@ -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) diff --git a/Documentation/Books/Manual/Scalability/DC2DC/dc2dc.png b/Documentation/Books/Manual/Scalability/DC2DC/dc2dc.png index ca27ab52f2c5e1d49001cf1bb6b71e57f4f73857..b2e55c55f886962d92208abbab22de3b19c7d83c 100644 GIT binary patch delta 108 zcmaF4jr;g^?l>DoU0sEg{5 +# 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 `` with the version of the operator that you want to install): + +```bash +kubectl apply -f https://raw.githubusercontent.com/arangodb/kube-arangodb//manifests/crd.yaml +kubectl apply -f https://raw.githubusercontent.com/arangodb/kube-arangodb//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://:30529/`, +where `` 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) diff --git a/Documentation/Books/Manual/Tutorials/README.md b/Documentation/Books/Manual/Tutorials/README.md index f08b66f9f0..601a054263 100644 --- a/Documentation/Books/Manual/Tutorials/README.md +++ b/Documentation/Books/Manual/Tutorials/README.md @@ -1,2 +1,11 @@ Tutorials -========= \ No newline at end of file +========= + +- [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 diff --git a/Documentation/Books/Manual/GettingStarted/Starter/README.md b/Documentation/Books/Manual/Tutorials/Starter/README.md similarity index 98% rename from Documentation/Books/Manual/GettingStarted/Starter/README.md rename to Documentation/Books/Manual/Tutorials/Starter/README.md index a075d8d467..b8e714fbf2 100644 --- a/Documentation/Books/Manual/GettingStarted/Starter/README.md +++ b/Documentation/Books/Manual/Tutorials/Starter/README.md @@ -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.