From b8bf87e054757dd7db461f38fe68d470a666f20c Mon Sep 17 00:00:00 2001 From: sleto-it <31849787+sleto-it@users.noreply.github.com> Date: Wed, 20 Jun 2018 18:01:32 +0200 Subject: [PATCH] Doc - Kube tutorial backport (#5637) --- .../DeploymentReplicationResource.md | 6 +- .../Kubernetes/DeploymentResource.md | 17 ++ Documentation/Books/Manual/SUMMARY.md | 4 + .../Manual/Tutorials/Kubernetes/DC2DC.md | 138 ++++++++++++++ .../Manual/Tutorials/Kubernetes/README.md | 171 ++++++++++++++++++ .../Books/Manual/Tutorials/README.md | 8 + 6 files changed, 341 insertions(+), 3 deletions(-) create mode 100644 Documentation/Books/Manual/Tutorials/Kubernetes/DC2DC.md create mode 100644 Documentation/Books/Manual/Tutorials/Kubernetes/README.md create mode 100644 Documentation/Books/Manual/Tutorials/README.md diff --git a/Documentation/Books/Manual/Deployment/Kubernetes/DeploymentReplicationResource.md b/Documentation/Books/Manual/Deployment/Kubernetes/DeploymentReplicationResource.md index 2d79744d77..7cc1f60ce4 100644 --- a/Documentation/Books/Manual/Deployment/Kubernetes/DeploymentReplicationResource.md +++ b/Documentation/Books/Manual/Deployment/Kubernetes/DeploymentReplicationResource.md @@ -40,7 +40,7 @@ metadata: name: "replication-from-a-to-b" spec: source: - endpoint: ["https://163.172.149.229:31888", "https://51.15.225.110:31888", "https://51.15.229.133:31888"] + masterEndpoint: ["https://163.172.149.229:31888", "https://51.15.225.110:31888", "https://51.15.229.133:31888"] auth: keyfileSecretName: cluster-a-sync-auth tls: @@ -68,7 +68,7 @@ with sync enabled. This cluster configured as the replication source. -### `spec.source.endpoint: []string` +### `spec.source.masterEndpoint: []string` This setting specifies zero or more master endpoint URL's of the source cluster. @@ -109,7 +109,7 @@ with sync enabled. This cluster configured as the replication destination. -### `spec.destination.endpoint: []string` +### `spec.destination.masterEndpoint: []string` This setting specifies zero or more master endpoint URL's of the destination cluster. diff --git a/Documentation/Books/Manual/Deployment/Kubernetes/DeploymentResource.md b/Documentation/Books/Manual/Deployment/Kubernetes/DeploymentResource.md index 4038627cec..587ea186b4 100644 --- a/Documentation/Books/Manual/Deployment/Kubernetes/DeploymentResource.md +++ b/Documentation/Books/Manual/Deployment/Kubernetes/DeploymentResource.md @@ -108,6 +108,23 @@ Possible values are: This setting cannot be changed after the cluster has been created. +### `spec.downtimeAllowed: bool` + +This setting is used to allow automatic reconciliation actions that yield +some downtime of the ArangoDB deployment. +When this setting is set to `false` (the default), no automatic action that +may result in downtime is allowed. +If the need for such an action is detected, an event is added to the `ArangoDeployment`. + +Once this setting is set to `true`, the automatic action is executed. + +Operations that may result in downtime are: + +- Rotating TLS CA certificate + +Note: It is still possible that there is some downtime when the Kubernetes +cluster is down, or in a bad state, irrespective of the value of this setting. + ### `spec.rocksdb.encryption.keySecretName` This setting specifies the name of a kubernetes `Secret` that contains diff --git a/Documentation/Books/Manual/SUMMARY.md b/Documentation/Books/Manual/SUMMARY.md index c93aa28f21..29c1c68f52 100644 --- a/Documentation/Books/Manual/SUMMARY.md +++ b/Documentation/Books/Manual/SUMMARY.md @@ -11,6 +11,10 @@ * [Accessing the Web Interface](GettingStarted/WebInterface.md) * [Coming from SQL](GettingStarted/ComingFromSql.md) # +* [Tutorials](Tutorials/README.md) + * [Kubernetes](Tutorials/Kubernetes/README.md) + * [Datacenter to datacenter Replication on Kubernetes](Tutorials/Kubernetes/DC2DC.md) +# * [Highlights](Highlights.md) # * [Scalability](Scalability/README.md) diff --git a/Documentation/Books/Manual/Tutorials/Kubernetes/DC2DC.md b/Documentation/Books/Manual/Tutorials/Kubernetes/DC2DC.md new file mode 100644 index 0000000000..8c77ae6df3 --- /dev/null +++ b/Documentation/Books/Manual/Tutorials/Kubernetes/DC2DC.md @@ -0,0 +1,138 @@ + +# Start ArangoDB Cluster to Cluster Synchronization on Kubernetes + +This tutorial guides you through the steps needed to configure +an ArangoDB datacenter to datacenter replication between two ArangoDB +clusters running in Kubernetes. + +## Requirements + +1. This tutorial assumes that you have 2 ArangoDB clusters running in 2 different Kubernetes clusters. +1. Both Kubernetes clusters are equipped with support for `Services` of type `LoadBalancer`. +1. You can create (global) DNS names for configured `Services` with low propagation times. E.g. use Cloudflare. +1. You have 4 DNS names available: + - One for the database in the source ArangoDB cluster. E.g. `src-db.mycompany.com` + - One for the ArangoDB syncmasters in the source ArangoDB cluster. E.g. `src-sync.mycompany.com` + - One for the database in the destination ArangoDB cluster. E.g. `dst-db.mycompany.com` + - One for the ArangoDB syncmasters in the destination ArangoDB cluster. E.g. `dst-sync.mycompany.com` + +## Step 1: Enable Datacenter Replication Support on source ArangoDB cluster + +Set your current Kubernetes context to the Kubernetes source cluster. + +Edit the `ArangoDeployment` of the source ArangoDB clusters. + +Set: + +- `spec.tls.altNames` to `["src-db.mycompany.com"]` (can include more names / IP addresses) +- `spec.sync.enabled` to `true` +- `spec.sync.externalAccess.masterEndpoint` to `["https://src-sync.mycompany.com:8629"]` +- `spec.sync.externalAccess.accessPackageSecretNames` to `["src-accesspackage"]` + +## Step 2: Extract access-package from source ArangoDB cluster + +Run: + +```bash +kubectl get secret src-accesspackage --template='{{index .data "accessPackage.yaml"}}' | \ + base64 -D > accessPackage.yaml +``` + +## Step 3: Configure source DNS names + +Run: + +```bash +kubectl get service +``` + +Find the IP address contained in the `LoadBalancer` column for the following `Services`: + +- `-ea` Use this IP address for the `src-db.mycompany.com` DNS name. +- `-sync` Use this IP address for the `src-sync.mycompany.com` DNS name. + +The process for configuring DNS names is specific to each DNS provider. + +## Step 4: Enable Datacenter Replication Support on destination ArangoDB cluster + +Set your current Kubernetes context to the Kubernetes destination cluster. + +Edit the `ArangoDeployment` of the source ArangoDB clusters. + +Set: + +- `spec.tls.altNames` to `["dst-db.mycompany.com"]` (can include more names / IP addresses) +- `spec.sync.enabled` to `true` +- `spec.sync.externalAccess.masterEndpoint` to `["https://dst-sync.mycompany.com:8629"]` + +## Step 5: Import access package in destination cluster + +Run: + +```bash +kubectl apply -f accessPackage.yaml +``` + +Note: This imports two `Secrets`, containing TLS information about the source cluster, +into the destination cluster + +## Step 6: Configure destination DNS names + +Run: + +```bash +kubectl get service +``` + +Find the IP address contained in the `LoadBalancer` column for the following `Services`: + +- `-ea` Use this IP address for the `dst-db.mycompany.com` DNS name. +- `-sync` Use this IP address for the `dst-sync.mycompany.com` DNS name. + +The process for configuring DNS names is specific to each DNS provider. + +## Step 7: Create an `ArangoDeploymentReplication` resource + +Create a yaml file (e.g. called `src-to-dst-repl.yaml`) with the following content: + +```yaml +apiVersion: "replication.database.arangodb.com/v1alpha" +kind: "ArangoDeploymentReplication" +metadata: + name: "replication-src-to-dst" +spec: + source: + masterEndpoint: ["https://src-sync.mycompany.com:8629"] + auth: + keyfileSecretName: src-accesspackage-auth + tls: + caSecretName: src-accesspackage-ca + destination: + deploymentName: +``` + +## Step 8: Wait for DNS names to propagate + +Wait until the DNS names configured in step 3 and 6 resolve to their configured +IP addresses. + +Depending on your DNS provides this can take a few minutes up to 24 hours. + +## Step 9: Activate replication + +Run: + +```bash +kubectl apply -f src-to-dst-repl.yaml +``` + +Replication from the source cluster to the destination cluster will now be configured. + +Check the status of the replication by inspecting the status of the `ArangoDeploymentReplication` resource using: + +```bash +kubectl describe ArangoDeploymentReplication replication-src-to-dst +``` + +As soon as the replication is configured, the `Add collection` button in the `Collections` +page of the web UI (of the destination cluster) will be grayed out. diff --git a/Documentation/Books/Manual/Tutorials/Kubernetes/README.md b/Documentation/Books/Manual/Tutorials/Kubernetes/README.md new file mode 100644 index 0000000000..42a75d4be2 --- /dev/null +++ b/Documentation/Books/Manual/Tutorials/Kubernetes/README.md @@ -0,0 +1,171 @@ + +# 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 +# Optional +kubectl apply -f https://raw.githubusercontent.com/arangodb/kube-arangodb//manifests/arango-storage.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. + +The optional third command installs a `Deployment` that runs the operator that +provides `PersistentVolumes` on local disks of the cluster nodes. +Use this when running on bare-metal or if there is no provisioner for fast +storage in your Kubernetes cluster. + +## 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 from within the Kubernetes cluster as well as outside it. + +Access to the database from outside the Kubernetes cluster is provided +using an external-access service. +By default this service is of type `LoadBalancer`. If this type of service +is not supported by your Kubernetes cluster, it will be replaced by +a service of type `NodePort` after a minute. + +To see the type of service that has been created, run: + +```bash +kubectl get service single-server-ea +``` + +When the service is of the `LoadBalancer` type, use the IP address +listed in the `EXTERNAL-IP` column with port 8529. +When the service is of the `NodePort` type, use the IP address +of any of the nodes of the cluster, combine with the high (>30000) port listed in the `PORT(S)` column. + +Now you can connect your browser to `https://:/`. + +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`). + +## 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 new file mode 100644 index 0000000000..ac9286147a --- /dev/null +++ b/Documentation/Books/Manual/Tutorials/README.md @@ -0,0 +1,8 @@ +Tutorials +========= + +- [Kubernetes](Kubernetes/README.md): + Start ArangoDB on Kubernetes in 5 minutes + +- [Kubernetes](Kubernetes/DC2DC.md): + DC2DC on Kubernetes