From 59256333ea73d3ce75c0bc6fb969941f93dfdc69 Mon Sep 17 00:00:00 2001 From: Ewout Prangsma Date: Tue, 3 Apr 2018 12:30:14 +0200 Subject: [PATCH 1/3] Adding GettingStarted page and structuring docs for website --- README.md | 3 +- .../GettingStarted/kube-arangodb/README.md | 207 ++++++++++++++++++ .../Programs/kube-arangodb}/README.md | 0 .../kube-arangodb}/config_and_secrets.md | 0 .../kube-arangodb}/custom_resource.md | 0 .../Programs/kube-arangodb}/metrics.md | 0 .../Programs/kube-arangodb}/scaling.md | 0 .../services_and_loadbalancer.md | 0 .../Programs/kube-arangodb}/storage.md | 0 .../kube-arangodb}/storage_resource.md | 0 .../Programs/kube-arangodb}/tls.md | 0 .../Programs/kube-arangodb}/upgrading.md | 0 .../Programs/kube-arangodb}/usage.md | 0 docs/README.md | 3 +- 14 files changed, 211 insertions(+), 2 deletions(-) create mode 100644 docs/Manual/GettingStarted/kube-arangodb/README.md rename docs/{user => Manual/Programs/kube-arangodb}/README.md (100%) rename docs/{user => Manual/Programs/kube-arangodb}/config_and_secrets.md (100%) rename docs/{user => Manual/Programs/kube-arangodb}/custom_resource.md (100%) rename docs/{user => Manual/Programs/kube-arangodb}/metrics.md (100%) rename docs/{user => Manual/Programs/kube-arangodb}/scaling.md (100%) rename docs/{user => Manual/Programs/kube-arangodb}/services_and_loadbalancer.md (100%) rename docs/{user => Manual/Programs/kube-arangodb}/storage.md (100%) rename docs/{user => Manual/Programs/kube-arangodb}/storage_resource.md (100%) rename docs/{user => Manual/Programs/kube-arangodb}/tls.md (100%) rename docs/{user => Manual/Programs/kube-arangodb}/upgrading.md (100%) rename docs/{user => Manual/Programs/kube-arangodb}/usage.md (100%) diff --git a/README.md b/README.md index 8dfb31d5a..6cd76e99f 100644 --- a/README.md +++ b/README.md @@ -4,7 +4,8 @@ State: In heavy development. DO NOT USE FOR ANY PRODUCTION LIKE PURPOSE! THINGS WILL CHANGE. -- [User manual](./docs/user/README.md) +- [Getting Started](./docs/Manual/GettingStarted/kube-arangodb/README.md) +- [User manual](./docs/Manual/Programs/kube-arangodb/README.md) - [Design documents](./docs/design/README.md) ## Installation of latest release diff --git a/docs/Manual/GettingStarted/kube-arangodb/README.md b/docs/Manual/GettingStarted/kube-arangodb/README.md new file mode 100644 index 000000000..4504de641 --- /dev/null +++ b/docs/Manual/GettingStarted/kube-arangodb/README.md @@ -0,0 +1,207 @@ +# Start ArangoDB on Kubernetes in 5min + +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'll 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 `PersistenVolume's` on local storage of your nodes for optimal +storage performace. + +Note that the operator that provides `PersistentVolume's` is not needed to +run ArangoDB deployments. You can also use `PersistentVolume's` provided +by other controllers. + +In this guide we'll 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 deployment 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 `CustomResourceDefinition's` in your Kubernetes cluster: + +- `ArangoDeployment` is the resource used to deploy ArangoDB database. +- `ArangoLocalStorage` is the resource used to provision `PersistentVolume's` 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're 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 currentl 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 looks something like 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 acces) +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 +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 `Pod's` 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've choosen a different node port (31529) for this `Service` +to avoid conflicts with the port used in `single-server-service`. + +## Where to go from here diff --git a/docs/user/README.md b/docs/Manual/Programs/kube-arangodb/README.md similarity index 100% rename from docs/user/README.md rename to docs/Manual/Programs/kube-arangodb/README.md diff --git a/docs/user/config_and_secrets.md b/docs/Manual/Programs/kube-arangodb/config_and_secrets.md similarity index 100% rename from docs/user/config_and_secrets.md rename to docs/Manual/Programs/kube-arangodb/config_and_secrets.md diff --git a/docs/user/custom_resource.md b/docs/Manual/Programs/kube-arangodb/custom_resource.md similarity index 100% rename from docs/user/custom_resource.md rename to docs/Manual/Programs/kube-arangodb/custom_resource.md diff --git a/docs/user/metrics.md b/docs/Manual/Programs/kube-arangodb/metrics.md similarity index 100% rename from docs/user/metrics.md rename to docs/Manual/Programs/kube-arangodb/metrics.md diff --git a/docs/user/scaling.md b/docs/Manual/Programs/kube-arangodb/scaling.md similarity index 100% rename from docs/user/scaling.md rename to docs/Manual/Programs/kube-arangodb/scaling.md diff --git a/docs/user/services_and_loadbalancer.md b/docs/Manual/Programs/kube-arangodb/services_and_loadbalancer.md similarity index 100% rename from docs/user/services_and_loadbalancer.md rename to docs/Manual/Programs/kube-arangodb/services_and_loadbalancer.md diff --git a/docs/user/storage.md b/docs/Manual/Programs/kube-arangodb/storage.md similarity index 100% rename from docs/user/storage.md rename to docs/Manual/Programs/kube-arangodb/storage.md diff --git a/docs/user/storage_resource.md b/docs/Manual/Programs/kube-arangodb/storage_resource.md similarity index 100% rename from docs/user/storage_resource.md rename to docs/Manual/Programs/kube-arangodb/storage_resource.md diff --git a/docs/user/tls.md b/docs/Manual/Programs/kube-arangodb/tls.md similarity index 100% rename from docs/user/tls.md rename to docs/Manual/Programs/kube-arangodb/tls.md diff --git a/docs/user/upgrading.md b/docs/Manual/Programs/kube-arangodb/upgrading.md similarity index 100% rename from docs/user/upgrading.md rename to docs/Manual/Programs/kube-arangodb/upgrading.md diff --git a/docs/user/usage.md b/docs/Manual/Programs/kube-arangodb/usage.md similarity index 100% rename from docs/user/usage.md rename to docs/Manual/Programs/kube-arangodb/usage.md diff --git a/docs/README.md b/docs/README.md index de6f020dd..00f97713e 100644 --- a/docs/README.md +++ b/docs/README.md @@ -1,4 +1,5 @@ # ArangoDB operator docs -- [User manual](./user/README.md) +- [Getting Started](./Manual/GettingStarted/kube-arangodb/README.md) +- [User manual](./Manual/Programs/kube-arangodb/README.md) - [Design documents](./design/README.md) From 65d3e25b8b06b32c1391dfc262a96e95ef1648d1 Mon Sep 17 00:00:00 2001 From: Ewout Prangsma Date: Tue, 3 Apr 2018 12:32:51 +0200 Subject: [PATCH 2/3] Linked reference manual --- docs/Manual/GettingStarted/kube-arangodb/README.md | 2 ++ 1 file changed, 2 insertions(+) diff --git a/docs/Manual/GettingStarted/kube-arangodb/README.md b/docs/Manual/GettingStarted/kube-arangodb/README.md index 4504de641..089e58c10 100644 --- a/docs/Manual/GettingStarted/kube-arangodb/README.md +++ b/docs/Manual/GettingStarted/kube-arangodb/README.md @@ -205,3 +205,5 @@ Note that we've choosen 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](../../Programs/kube-arangodb/README.md) From f022162b7ae265f807fa80abb97c7c0fb47e4db5 Mon Sep 17 00:00:00 2001 From: Ewout Prangsma Date: Tue, 3 Apr 2018 15:46:23 +0200 Subject: [PATCH 3/3] Typos --- .../GettingStarted/kube-arangodb/README.md | 20 +++++++++---------- 1 file changed, 10 insertions(+), 10 deletions(-) diff --git a/docs/Manual/GettingStarted/kube-arangodb/README.md b/docs/Manual/GettingStarted/kube-arangodb/README.md index 089e58c10..9e1327e6f 100644 --- a/docs/Manual/GettingStarted/kube-arangodb/README.md +++ b/docs/Manual/GettingStarted/kube-arangodb/README.md @@ -3,8 +3,8 @@ 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. +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. @@ -17,11 +17,11 @@ 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 `PersistenVolume's` on local storage of your nodes for optimal +provide `PersistenVolumes` on local storage of your nodes for optimal storage performace. -Note that the operator that provides `PersistentVolume's` is not needed to -run ArangoDB deployments. You can also use `PersistentVolume's` provided +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. @@ -29,7 +29,7 @@ In this guide we'll 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 deployment resources +you have acces to this cluster and the rights to deploy resources at cluster level. For now, any recent Kubernetes cluster will do (e.g. `minikube`). @@ -41,10 +41,10 @@ kubectl apply -f https://raw.githubusercontent.com/arangodb/kube-arangodb//manifests/arango-deployment.yaml ``` -The first command installs two `CustomResourceDefinition's` in your Kubernetes cluster: +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 `PersistentVolume's` on local storage. +- `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. @@ -87,7 +87,7 @@ To inspect the pods created for this deployment, run: kubectl get pods --selector=arango_deployment=single-server ``` -The result will looks something like this: +The result will look similar to this: ```plain NAME READY STATUS RESTARTS AGE @@ -178,7 +178,7 @@ to inspect your cluster. Just use the correct deployment name (`cluster` instead Connecting to your cluster requires a different `Service` since the selector now has to select your `cluster` deployment and instead -of selecting all `Pod's` with role `single` it will have to select +of selecting all `Pods` with role `single` it will have to select all coordinator pods. The service looks like this: