diff --git a/README.md b/README.md index 22edbb39b..42ec5f93e 100644 --- a/README.md +++ b/README.md @@ -4,9 +4,7 @@ State: In heavy development. DO NOT USE FOR ANY PRODUCTION LIKE PURPOSE! THINGS WILL CHANGE. -- [Getting Started](./docs/Manual/GettingStarted/Kubernetes/README.md) -- [User manual](./docs/Manual/Deployment/Kubernetes/README.md) -- [Design documents](./docs/design/README.md) +[Documentation](./docs/README.md) ## Installation of latest release diff --git a/docs/Manual/Deployment/Kubernetes/config_and_secrets.md b/docs/Manual/Deployment/Kubernetes/ConfigAndSecrets.md similarity index 94% rename from docs/Manual/Deployment/Kubernetes/config_and_secrets.md rename to docs/Manual/Deployment/Kubernetes/ConfigAndSecrets.md index c381afc37..702451839 100644 --- a/docs/Manual/Deployment/Kubernetes/config_and_secrets.md +++ b/docs/Manual/Deployment/Kubernetes/ConfigAndSecrets.md @@ -1,7 +1,7 @@ # Configuration & secrets An ArangoDB cluster has lots of configuration options. -Some will be supported directly in the ArangoDB operator, +Some will be supported directly in the ArangoDB Operator, others will have to specified separately. ## Built-in options diff --git a/docs/Manual/Deployment/Kubernetes/deployment_resource.md b/docs/Manual/Deployment/Kubernetes/DeploymentResource.md similarity index 98% rename from docs/Manual/Deployment/Kubernetes/deployment_resource.md rename to docs/Manual/Deployment/Kubernetes/DeploymentResource.md index 069ba56d3..5809c75b2 100644 --- a/docs/Manual/Deployment/Kubernetes/deployment_resource.md +++ b/docs/Manual/Deployment/Kubernetes/DeploymentResource.md @@ -1,6 +1,6 @@ # ArangoLocalStorage Custom Resource -The ArangoDB Deployment operator creates and maintains ArangoDB deployments +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. @@ -102,7 +102,7 @@ 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. +- `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. diff --git a/docs/Manual/Deployment/Kubernetes/metrics.md b/docs/Manual/Deployment/Kubernetes/Metrics.md similarity index 100% rename from docs/Manual/Deployment/Kubernetes/metrics.md rename to docs/Manual/Deployment/Kubernetes/Metrics.md diff --git a/docs/Manual/Deployment/Kubernetes/README.md b/docs/Manual/Deployment/Kubernetes/README.md index c6d9ab6ec..28849d67c 100644 --- a/docs/Manual/Deployment/Kubernetes/README.md +++ b/docs/Manual/Deployment/Kubernetes/README.md @@ -1,12 +1,6 @@ -# ArangoDB operator user manual +# ArangoDB Kubernetes Operator -- [Using the operator](./usage.md) -- [Deployment Resource](./deployment_resource.md) -- [ArangoDB configuration & secrets](./config_and_secrets.md) -- [Metrics](./metrics.md) -- [Scaling](./scaling.md) -- [Services & Load balancer](./services_and_loadbalancer.md) -- [Storage](./storage.md) -- [Storage Resource](./storage_resource.md) -- [TLS](./tls.md) -- [Upgrading](./upgrading.md) +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/docs/Manual/Deployment/Kubernetes/scaling.md b/docs/Manual/Deployment/Kubernetes/Scaling.md similarity index 87% rename from docs/Manual/Deployment/Kubernetes/scaling.md rename to docs/Manual/Deployment/Kubernetes/Scaling.md index 7ed4d2077..37bee7c15 100644 --- a/docs/Manual/Deployment/Kubernetes/scaling.md +++ b/docs/Manual/Deployment/Kubernetes/Scaling.md @@ -1,6 +1,6 @@ # Scaling -The ArangoDB operator supports up and down scaling of +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 diff --git a/docs/Manual/Deployment/Kubernetes/services_and_loadbalancer.md b/docs/Manual/Deployment/Kubernetes/ServicesAndLoadBalancer.md similarity index 96% rename from docs/Manual/Deployment/Kubernetes/services_and_loadbalancer.md rename to docs/Manual/Deployment/Kubernetes/ServicesAndLoadBalancer.md index 303ef92d6..e6191ac0a 100644 --- a/docs/Manual/Deployment/Kubernetes/services_and_loadbalancer.md +++ b/docs/Manual/Deployment/Kubernetes/ServicesAndLoadBalancer.md @@ -1,6 +1,6 @@ # Services and load balancer -The ArangoDB operator will create services that can be used to +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 diff --git a/docs/Manual/Deployment/Kubernetes/storage.md b/docs/Manual/Deployment/Kubernetes/Storage.md similarity index 96% rename from docs/Manual/Deployment/Kubernetes/storage.md rename to docs/Manual/Deployment/Kubernetes/Storage.md index 88add04cb..15db3def2 100644 --- a/docs/Manual/Deployment/Kubernetes/storage.md +++ b/docs/Manual/Deployment/Kubernetes/Storage.md @@ -1,7 +1,7 @@ # Storage An ArangoDB cluster relies heavily on fast persistent storage. -The ArangoDB operator uses `PersistenVolumeClaims` to deliver +The ArangoDB Kubernetes Operator uses `PersistentVolumeClaims` to deliver the storage to Pods that need them. ## Storage configuration diff --git a/docs/Manual/Deployment/Kubernetes/storage_resource.md b/docs/Manual/Deployment/Kubernetes/StorageResource.md similarity index 96% rename from docs/Manual/Deployment/Kubernetes/storage_resource.md rename to docs/Manual/Deployment/Kubernetes/StorageResource.md index ce68d459e..e6a005290 100644 --- a/docs/Manual/Deployment/Kubernetes/storage_resource.md +++ b/docs/Manual/Deployment/Kubernetes/StorageResource.md @@ -1,6 +1,6 @@ # ArangoLocalStorage Custom Resource -The ArangoDB Storage operator creates and maintains ArangoDB +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. diff --git a/docs/Manual/Deployment/Kubernetes/tls.md b/docs/Manual/Deployment/Kubernetes/Tls.md similarity index 89% rename from docs/Manual/Deployment/Kubernetes/tls.md rename to docs/Manual/Deployment/Kubernetes/Tls.md index d769cba39..127c664fd 100644 --- a/docs/Manual/Deployment/Kubernetes/tls.md +++ b/docs/Manual/Deployment/Kubernetes/Tls.md @@ -1,7 +1,7 @@ # TLS -The ArangoDB operator will by default create ArangoDB deployments that use -secure TLS connections. +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). diff --git a/docs/Manual/Deployment/Kubernetes/upgrading.md b/docs/Manual/Deployment/Kubernetes/Upgrading.md similarity index 72% rename from docs/Manual/Deployment/Kubernetes/upgrading.md rename to docs/Manual/Deployment/Kubernetes/Upgrading.md index 68c414748..56fe7989a 100644 --- a/docs/Manual/Deployment/Kubernetes/upgrading.md +++ b/docs/Manual/Deployment/Kubernetes/Upgrading.md @@ -1,6 +1,6 @@ # Upgrading -The ArangoDB operator supports upgrading an ArangoDB from +The ArangoDB Kubernetes Operator supports upgrading an ArangoDB from one version to the next. To upgrade a cluster, change the version by changing @@ -11,7 +11,7 @@ custom resource using: kubectl apply -f yourCustomResourceFile.yaml ``` -To update the ArangoDB operator itself to a new version, +To update the ArangoDB Kubernetes Operator itself to a new version, update the image version of the deployment resource and apply it using: diff --git a/docs/Manual/Deployment/Kubernetes/usage.md b/docs/Manual/Deployment/Kubernetes/Usage.md similarity index 83% rename from docs/Manual/Deployment/Kubernetes/usage.md rename to docs/Manual/Deployment/Kubernetes/Usage.md index 8d3e78752..01930c479 100644 --- a/docs/Manual/Deployment/Kubernetes/usage.md +++ b/docs/Manual/Deployment/Kubernetes/Usage.md @@ -1,8 +1,8 @@ -# Using the ArangoDB operator +# Using the ArangoDB Kubernetes Operator ## Installation -The ArangoDB operator needs to be installed in your Kubernetes +The ArangoDB Kubernetes Operator needs to be installed in your Kubernetes cluster first. To do so, clone this repository and run: ```bash @@ -40,7 +40,7 @@ kubectl delete -f examples/simple-cluster.yaml ## Operator removal -To remove the entire ArangoDB operator, remove all +To remove the entire ArangoDB Kubernetes Operator, remove all clusters first and then remove the operator by running: ```bash diff --git a/docs/Manual/GettingStarted/Kubernetes/README.md b/docs/Manual/Tutorials/Kubernetes/README.md similarity index 87% rename from docs/Manual/GettingStarted/Kubernetes/README.md rename to docs/Manual/Tutorials/Kubernetes/README.md index 8e7326928..5a37b2c17 100644 --- a/docs/Manual/GettingStarted/Kubernetes/README.md +++ b/docs/Manual/Tutorials/Kubernetes/README.md @@ -1,4 +1,4 @@ -# Start ArangoDB on Kubernetes in 5min +# 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. @@ -6,10 +6,10 @@ 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 +Use `kube-arangodb`, the ArangoDB Kubernetes Operator to greatly simplify this process. -In this guide, we'll explain what the ArangoDB Kubernetes operator is, +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. @@ -17,19 +17,19 @@ in a Kubernetes cluster. `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 `PersistenVolumes` on local storage of your nodes for optimal -storage performace. +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'll focus on the `ArangoDeployment` operator. +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 acces to this cluster and the rights to deploy resources +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`). @@ -51,7 +51,7 @@ The second command installs a `Deployment` that runs the operator that controls ## Deploying your first ArangoDB database -The first database we're going to deploy is a single server 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. @@ -73,7 +73,7 @@ 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 currentl status of your deployment, run: +To inspect the current status of your deployment, run: ```bash kubectl describe ArangoDeployment single-server @@ -102,11 +102,11 @@ your database s available. 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 acces) +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're going to use the `NodePort` type to expose the database on port 30529 of +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. @@ -201,9 +201,9 @@ spec: nodePort: 31529 ``` -Note that we've choosen a different node port (31529) for this `Service` +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 -- [Reference manual](../../Deployment/Kubernetes/README.md) +- [ArangoDB Kubernetes Operator](../../Deployment/Kubernetes/README.md) diff --git a/docs/README.md b/docs/README.md index b4a4484a8..7c4580ccf 100644 --- a/docs/README.md +++ b/docs/README.md @@ -1,5 +1,15 @@ -# ArangoDB operator docs +# ArangoDB Kubernetes Operator -- [Getting Started](./Manual/GettingStarted/Kubernetes/README.md) -- [User manual](./Manual/Programs/Kubernetes/README.md) +- [Getting Started](./Manual/Tutorials/Kubernetes/README.md) +- [User manual](./Manual/Deployment/Kubernetes/README.md) + - [Using the Operator](./Manual/Deployment/Kubernetes/Usage.md) + - [Deployment Resource](./Manual/Deployment/Kubernetes/DeploymentResource.md) + - [ArangoDB configuration & secrets](./Manual/Deployment/Kubernetes/ConfigAndSecrets.md) + - [Metrics](./Manual/Deployment/Kubernetes/Metrics.md) + - [Scaling](./Manual/Deployment/Kubernetes/Scaling.md) + - [Services & Load balancer](./Manual/Deployment/Kubernetes/ServicesAndLoadBalancer.md) + - [Storage](./Manual/Deployment/Kubernetes/Storage.md) + - [Storage Resource](./Manual/Deployment/Kubernetes/StorageResource.md) + - [TLS](./Manual/Deployment/Kubernetes/Tls.md) + - [Upgrading](./Manual/Deployment/Kubernetes/Upgrading.md) - [Design documents](./design/README.md)