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..9e1327e6f --- /dev/null +++ b/docs/Manual/GettingStarted/kube-arangodb/README.md @@ -0,0 +1,209 @@ +# 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 `PersistenVolumes` on local storage of your nodes for optimal +storage performace. + +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. + +## 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 +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'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 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 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 `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'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) 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)