diff --git a/README.md b/README.md index 3c50ee352..0ea0dbf78 100644 --- a/README.md +++ b/README.md @@ -6,7 +6,7 @@ ArangoDB Kubernetes Operator helps to run ArangoDB deployments on Kubernetes clusters. To get started, follow the Installation instructions below and/or -read the [tutorial](./docs/Manual/Tutorials/Kubernetes/README.md). +read the [tutorial](https://www.arangodb.com/docs/stable/tutorials-kubernetes.html). ## State diff --git a/docs/Manual/Deployment/Kubernetes/Authentication.md b/docs/Manual/Deployment/Kubernetes/Authentication.md deleted file mode 100644 index b20d1e67d..000000000 --- a/docs/Manual/Deployment/Kubernetes/Authentication.md +++ /dev/null @@ -1,18 +0,0 @@ -# Authentication - -The ArangoDB Kubernetes Operator will by default create ArangoDB deployments -that require authentication to access the database. - -It uses a single JWT secret (stored in a Kubernetes secret) -to provide *super-user* access between all servers of the deployment -as well as access from the ArangoDB Operator to the deployment. - -To disable authentication, set `spec.auth.jwtSecretName` to `None`. - -Initially the deployment is accessible through the web user-interface and -APIs, using the user `root` with an empty password. -Make sure to change this password immediately after starting the deployment! - -## See also - -- [Secure connections (TLS)](./Tls.md) diff --git a/docs/Manual/Deployment/Kubernetes/BackupPolicyResource.md b/docs/Manual/Deployment/Kubernetes/BackupPolicyResource.md deleted file mode 100644 index 3aebd2be2..000000000 --- a/docs/Manual/Deployment/Kubernetes/BackupPolicyResource.md +++ /dev/null @@ -1,157 +0,0 @@ -# ArangoBackupPolicy Custom Resource - -The ArangoBackupPolicy represents schedule definition for creating ArangoBackup Custom Resources by operator. -This deployment specification is a `CustomResource` following -a `CustomResourceDefinition` created by the operator. - -## Examples: - -### Create schedule for all deployments - - -```yaml -apiVersion: "backup.arangodb.com/v1alpha" -kind: "ArangoBackupPolicy" -metadata: - name: "example-arangodb-backup-policy" -spec: - schedule: "*/15 * * * *" -``` - -Action: - -Create an ArangoBackup Custom Resource for each ArangoBackup every 15 minutes - -### Create schedule for selected deployments - - -```yaml -apiVersion: "backup.arangodb.com/v1alpha" -kind: "ArangoBackupPolicy" -metadata: - name: "example-arangodb-backup-policy" -spec: - schedule: "*/15 * * * *" - selector: - matchLabels: - labelName: "labelValue" -``` - -Action: - -Create an ArangoBackup Custom Resource for selected ArangoBackup every 15 minutes - -### Create schedule for all deployments and upload - - -```yaml -apiVersion: "backup.arangodb.com/v1alpha" -kind: "ArangoBackupPolicy" -metadata: - name: "example-arangodb-backup-policy" -spec: - schedule: "*/15 * * * * " - template: - upload: - repositoryURL: "s3:/..." - credentialsSecretName: "secret-name" -``` - -Create an ArangoBackup Custom Resource for each ArangoBackup every 15 minutes and upload to repositoryURL - -## ArangoBackup Custom Resource Spec: - -```yaml -apiVersion: "backup.arangodb.com/v1alpha" -kind: "ArangoBackupPolicy" -metadata: - name: "example-arangodb-backup-policy" -spec: - schedule: "*/15 * * * * " - selector: - matchLabels: - labelName: "labelValue" - matchExpressions: [] - template: - options: - timeout: 3 - force: true - upload: - repositoryURL: "s3:/..." - credentialsSecretName: "secret-name" -status: - scheduled: "time" - message: "message" -``` - -## `spec: Object` - -Spec of the ArangoBackupPolicy Custom Resource - -Required: true - -Default: {} - -### `spec.schedule: String` - -Schedule definition. Parser from https://godoc.org/github.com/robfig/cron - -Required: true - -Default: "" - -### `spec.selector: Object` - -Selector definition for selecting matching ArangoBackup Custom Resources. Parser from https://godoc.org/k8s.io/apimachinery/pkg/apis/meta/v1#LabelSelector - -Required: false - -Default: {} - -### `spec.template: ArangoBackupTemplate` - -Template for the ArangoBackup Custom Resource - -Required: false - -Default: {} - -### `spec.template.options: ArangoBackup - spec.options` - -ArangoBackup options - -Required: false - -Default: {} - -### `spec.template.upload: ArangoBackup - spec.upload` - -ArangoBackup upload configuration - -Required: false - -Default: {} - -## `status: Object` - -Status of the ArangoBackupPolicy Custom Resource managed by operator - -Required: true - -Default: {} - -### `status.scheduled: TimeStamp` - -Next scheduled time in UTC - -Required: true - -Default: "" - -### `status.message: String` - -Message from the operator in case of failure - schedule not valid, ArangoBackupPolicy not valid - -Required: false - -Default: "" \ No newline at end of file diff --git a/docs/Manual/Deployment/Kubernetes/BackupResource.md b/docs/Manual/Deployment/Kubernetes/BackupResource.md deleted file mode 100644 index ae254f688..000000000 --- a/docs/Manual/Deployment/Kubernetes/BackupResource.md +++ /dev/null @@ -1,457 +0,0 @@ -# ArangoBackup Custom Resource - -The ArangoBackup Operator creates and maintains ArangoBackups -in a Kubernetes cluster, given a Backup specification. -This deployment specification is a `CustomResource` following -a `CustomResourceDefinition` created by the operator. - -## Examples: - -### Create simple Backup - -```yaml -apiVersion: "backup.arangodb.com/v1alpha" -kind: "ArangoBackup" -metadata: - name: "example-arangodb-backup" - namespace: "arangodb" -spec: - deployment: - name: "my-deployment" -``` - -Action: - -Create Backup on ArangoDeployment named `my-deployment` - -### Create and upload Backup - - -```yaml -apiVersion: "backup.arangodb.com/v1alpha" -kind: "ArangoBackup" -metadata: - name: "example-arangodb-backup" - namespace: "arangodb" -spec: - deployment: - name: "my-deployment" - upload: - repositoryURL: "S3://test/kube-test" - credentialsSecretName: "my-s3-rclone-credentials" -``` - -Action: - -Create Backup on ArangoDeployment named `my-deployment` and upload it to `S3://test/kube-test`. - - -### Download Backup - - -```yaml -apiVersion: "backup.arangodb.com/v1alpha" -kind: "ArangoBackup" -metadata: - name: "example-arangodb-backup" - namespace: "arangodb" -spec: - deployment: - name: "my-deployment" - download: - repositoryURL: "S3://test/kube-test" - credentialsSecretName: "my-s3-rclone-credentials" - id: "backup-id" -``` - -Download Backup with id `backup-id` from `S3://test/kube-test` on ArangoDeployment named `my-deployment` - -### Restore - -Information about restoring can be found in [ArangoDeployment](./DeploymentResource.md). - -## Advertised fields - -List of custom columns in CRD specification for Kubectl: -- `.spec.policyName` - optional name of the policy -- `.spec.deployment.name` - name of the deployment -- `.status.state` - current ArangoBackup Custom Resource state -- `.status.message` - additional message for current state - -## ArangoBackup Custom Resource Spec: - -```yaml -apiVersion: "backup.arangodb.com/v1alpha" -kind: "ArangoBackup" -metadata: - name: "example-arangodb-backup" - namespace: "arangodb" -spec: - policyName: "my-policy" - deployment: - name: "my-deployment" - options: - timeout: 3 - force: true - download: - repositoryURL: "s3:/..." - credentialsSecretName: "secret-name" - id: "backup-id" - upload: - repositoryURL: "s3:/..." - credentialsSecretName: "secret-name" -status: - state: "Ready" - time: "time" - message: "Message details" - - progress: - jobID: "id" - progress: "10%" - backup: - id: "id" - version: "3.6.0-dev" - forced: true - uploaded: true - downloaded: true - createdAt: "time" - sizeInBytes: 1 - numberOfDBServers: 3 - available: true -``` - -## `spec: Object` - -Spec of the ArangoBackup Custom Resource. - -Required: true - -Default: {} - -### `spec.deployment: Object` - -ArangoDeployment specification. - -Field is immutable. - -Required: true - -Default: {} - -#### `spec.deployment.name: String` - -Name of the ArangoDeployment Custom Resource within same namespace as ArangoBackup Custom Resource. - -Field is immutable. - -Required: true - -Default: "" - -#### `spec.policyName: String` - -Name of the ArangoBackupPolicy which created this Custom Resource - -Field is immutable. - -Required: false - -Default: "" - -### `spec.options: Object` - -Backup options. - -Field is immutable. - -Required: false - -Default: {} - -#### `spec.options.timeout: float` - -Timeout for Backup creation request in seconds. - -Field is immutable. - -Required: false - -Default: 30 - -#### `spec.options.allowInconsistent: bool` - -AllowInconsistent flag for Backup creation request. -If this value is set to true, backup is taken even if we are not able to acquire lock. - -Field is immutable. - -Required: false - -Default: false - -### `spec.download: Object` - -Backup download settings. - -Field is immutable. - -Required: false - -Default: {} - -#### `spec.download.repositoryURL: string` - -Field is immutable. Protocol needs to be defined in `spec.download.credentialsSecretName` if protocol is other than local. - -Mode protocols can be found at [rclone.org](https://rclone.org/). - -Format: `:/` - -Examples: -- `s3://my-bucket/test` -- `azure://test` - -Required: true - -Default: "" - -#### `spec.download.credentialsSecretName: string` - -Field is immutable. Name of the secret used while accessing repository - -Secret structure: - -```yaml -apiVersion: v1 -data: - token: -kind: Secret -metadata: - name: -type: Opaque -``` - -`JSON Token` options are described on the [Rclone](https://rclone.org/) page. -We can define more than one protocols at same time in one secret. - -This field is defined in json format: - -```json -{ - "": { - "type":"", - ...parameters - } -} -``` - -AWS S3 example - based on [Rclone S3](https://rclone.org/s3/) documentation and interactive process: - -```json -{ - "S3": { - "type": "s3", # Choose s3 type - "provider": "AWS", # Choose one of the providers - "env_auth": "false", # Define credentials in next step instead of using ENV - "access_key_id": "xxx", - "secret_access_key": "xxx", - "region": "eu-west-2", # Choose region - "acl": "private", # Set permissions on newly created remote object - } -} -``` - -and you can from now use `S3://bucket/path`. - -Required: false - -Default: "" - -#### `spec.download.id: string` - -ID of the ArangoBackup to be downloaded. - -Field is immutable. - -Required: true - -Default: "" - -### `spec.upload: Object` - -Backup upload settings. - -This field can be removed and created again with different values. This operation will trigger upload again. -Fields in Custom Resource Spec Upload are immutable. - -Required: false - -Default: {} - -#### `spec.upload.repositoryURL: string` - -Same structure as `spec.download.repositoryURL`. - -Required: true - -Default: "" - -#### `spec.upload.credentialsSecretName: string` - -Same structure as `spec.download.credentialsSecretName`. - -Required: false - -Default: "" - -## `status: Object` - -Status of the ArangoBackup Custom Resource. This field is managed by subresource and only by operator - -Required: true - -Default: {} - -### `status.state: enum` - -State of the ArangoBackup object. - -Required: true - -Default: "" - -Possible states: -- "" - default state, changed to "Pending" -- "Pending" - state in which Custom Resource is queued. If Backup is possible changed to "Scheduled" -- "Scheduled" - state which will start create/download process -- "Download" - state in which download request will be created on ArangoDB -- "DownloadError" - state when download failed -- "Downloading" - state for downloading progress -- "Create" - state for creation, field available set to true -- "Upload" - state in which upload request will be created on ArangoDB -- "Uploading" - state for uploading progress -- "UploadError" - state when uploading failed -- "Ready" - state when Backup is finished -- "Deleted" - state when Backup was once in ready, but has been deleted -- "Failed" - state for failure -- "Unavailable" - state when Backup is not available on the ArangoDB. It can happen in case of upgrades, node restarts etc. - -### `status.time: timestamp` - -Time in UTC when state of the ArangoBackup Custom Resource changed. - -Required: true - -Default: "" - -### `status.message: string` - -State message of the ArangoBackup Custom Resource. - -Required: false - -Default: "" - -### `status.progress: object` - -Progress info of the uploading and downloading process. - -Required: false - -Default: {} - -#### `status.progress.jobID: string` - -ArangoDB job ID for uploading or downloading. - -Required: true - -Default: "" - -#### `status.progress.progress: string` - -ArangoDeployment job progress. - -Required: true - -Default: "0%" - - -### `status.backup: object` - -ArangoBackup details. - -Required: true - -Default: {} - -#### `status.backup.id: string` - -ArangoBackup ID. - -Required: true - -Default: "" - -#### `status.backup.version: string` - -ArangoBackup version. - -Required: true - -Default: "" - -#### `status.backup.potentiallyInconsistent: bool` - -ArangoBackup potentially inconsistent flag. - -Required: false - -Default: false - -#### `status.backup.uploaded: bool` - -Determines if ArangoBackup has been uploaded. - -Required: false - -Default: false - -#### `status.backup.downloaded: bool` - -Determines if ArangoBackup has been downloaded. - -Required: false - -Default: false - -#### `status.backup.createdAt: TimeStamp` - -ArangoBackup Custom Resource creation time in UTC. - -Required: true - -Default: now() - -#### `status.backup.sizeInBytes: uint64` - -Size of the Backup in ArangoDB. - -Required: true - -Default: 0 - -#### `status.backup.numberOfDBServers: uint` - -Cluster size of the Backup in ArangoDB. - -Required: true - -Default: 0 - -### `status.available: bool` - -Determines if we can restore from ArangoBackup. - -Required: true - -Default: false \ No newline at end of file diff --git a/docs/Manual/Deployment/Kubernetes/ConfigAndSecrets.md b/docs/Manual/Deployment/Kubernetes/ConfigAndSecrets.md deleted file mode 100644 index 702451839..000000000 --- a/docs/Manual/Deployment/Kubernetes/ConfigAndSecrets.md +++ /dev/null @@ -1,40 +0,0 @@ -# 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/docs/Manual/Deployment/Kubernetes/Dashboards.md b/docs/Manual/Deployment/Kubernetes/Dashboards.md deleted file mode 100644 index 277597a2e..000000000 --- a/docs/Manual/Deployment/Kubernetes/Dashboards.md +++ /dev/null @@ -1,73 +0,0 @@ -# Operator Dashboards - -The ArangoDB Kubernetes Operator can create a dashboard for each type of -resource it supports. These dashboards are intended to give an overview of -the created resources, their state and instructions on how to modify those resources. - -The dashboards do not provide direct means to modify the resources. -All modifications are done using `kubectl` commands (which are provided by the dashboards) -so the standard security of your Kubernetes cluster is not bypassed. - -## Exposing the dashboards - -For each resource type (deployment, deployment replication & local storage) operator -a `Service` is created that serves the dashboard internally in the Kubernetes cluster. -To expose a dashboard outside the Kubernetes cluster, run a `kubecty expose` -command like this: - -```bash -kubectl expose service --type=LoadBalancer \ - --port=8528 --target-port=8528 \ - --name= --namespace= -``` - -Replace `` with: - -- `arango-deployment-operator` for the ArangoDeployment operator dashboard. -- `arango-deployment-replication-operator` for the ArangoDeploymentReplication - operator dashboard. -- `arango-storage-operator` for the ArangoLocalStorage operator dashboard. - (use 'kube-system' namespace) - -Replace `` with the name of the namespace that the operator is in. -This will often be `default`. - -This will create an additional `Service` of type `LoadBalancer` that copies -the selector from the existing `Service`. -If your Kubernetes cluster does not support loadbalancers, -use `--type=NodePort` instead. - -Run the following command to inspect your new service and look for the -loadbalancer IP/host address (or nodeport). - -```bash -kubectl get service --namespace= -``` - -This will result in something like this: - -```bash -$ kubectl get service arango-storage-operator-lb --namespace=kube-system -NAME TYPE CLUSTER-IP EXTERNAL-IP PORT(S) AGE -arango-storage-operator-lb LoadBalancer 10.103.30.24 192.168.31.11 8528:30655/TCP 1d -``` - -## Authentication - -While the dashboards do not provide any means to directly modify resources, -they still show sensitive information (e.g. TLS certificates). -Therefore the dashboards require a username+password for authentications. - -The username+password pair is configured in a generic Kubernetes `Secret` named `arangodb-operator-dashboard`, found in the namespace where the operator runs. - -To create such a secret, run this: - -```bash -kubectl create secret generic \ - arangodb-operator-dashboard --namespace= \ - --from-literal=username= \ - --from-literal=password= -``` - -Until such a `Secret` is found, the operator will respond with a status `401` -to any request related to the dashboard. diff --git a/docs/Manual/Deployment/Kubernetes/DeploymentReplicationResource.md b/docs/Manual/Deployment/Kubernetes/DeploymentReplicationResource.md deleted file mode 100644 index f0538d287..000000000 --- a/docs/Manual/Deployment/Kubernetes/DeploymentReplicationResource.md +++ /dev/null @@ -1,207 +0,0 @@ -# ArangoDeploymentReplication Custom Resource - -The ArangoDB Replication Operator creates and maintains ArangoDB -`arangosync` configurations in a Kubernetes cluster, given a replication specification. -This replication specification is a `CustomResource` following -a `CustomResourceDefinition` created by the operator. - -Example minimal replication definition for 2 ArangoDB cluster with sync in the same Kubernetes cluster: - -```yaml -apiVersion: "replication.database.arangodb.com/v1alpha" -kind: "ArangoDeploymentReplication" -metadata: - name: "replication-from-a-to-b" -spec: - source: - deploymentName: cluster-a - auth: - keyfileSecretName: cluster-a-sync-auth - destination: - deploymentName: cluster-b -``` - -This definition results in: - -- the arangosync `SyncMaster` in deployment `cluster-b` is called to configure a synchronization - from the syncmasters in `cluster-a` to the syncmasters in `cluster-b`, - using the client authentication certificate stored in `Secret` `cluster-a-sync-auth`. - To access `cluster-a`, the JWT secret found in the deployment of `cluster-a` is used. - To access `cluster-b`, the JWT secret found in the deployment of `cluster-b` is used. - -Example replication definition for replicating from a source that is outside the current Kubernetes cluster -to a destination that is in the same Kubernetes cluster: - -```yaml -apiVersion: "replication.database.arangodb.com/v1alpha" -kind: "ArangoDeploymentReplication" -metadata: - name: "replication-from-a-to-b" -spec: - source: - 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: - caSecretName: cluster-a-sync-ca - destination: - deploymentName: cluster-b -``` - -This definition results in: - -- the arangosync `SyncMaster` in deployment `cluster-b` is called to configure a synchronization - from the syncmasters located at the given list of endpoint URLs to the syncmasters `cluster-b`, - using the client authentication certificate stored in `Secret` `cluster-a-sync-auth`. - To access `cluster-a`, the keyfile (containing a client authentication certificate) is used. - To access `cluster-b`, the JWT secret found in the deployment of `cluster-b` is used. - -## Specification reference - -Below you'll find all settings of the `ArangoDeploymentReplication` custom resource. - -### `spec.source.deploymentName: string` - -This setting specifies the name of an `ArangoDeployment` resource that runs a cluster -with sync enabled. - -This cluster configured as the replication source. - -### `spec.source.masterEndpoint: []string` - -This setting specifies zero or more master endpoint URLs of the source cluster. - -Use this setting if the source cluster is not running inside a Kubernetes cluster -that is reachable from the Kubernetes cluster the `ArangoDeploymentReplication` resource is deployed in. - -Specifying this setting and `spec.source.deploymentName` at the same time is not allowed. - -### `spec.source.auth.keyfileSecretName: string` - -This setting specifies the name of a `Secret` containing a client authentication certificate called `tls.keyfile` used to authenticate -with the SyncMaster at the specified source. - -If `spec.source.auth.userSecretName` has not been set, -the client authentication certificate found in the secret with this name is also used to configure -the synchronization and fetch the synchronization status. - -This setting is required. - -### `spec.source.auth.userSecretName: string` - -This setting specifies the name of a `Secret` containing a `username` & `password` used to authenticate -with the SyncMaster at the specified source in order to configure synchronization and fetch synchronization status. - -The user identified by the username must have write access in the `_system` database of the source ArangoDB cluster. - -### `spec.source.tls.caSecretName: string` - -This setting specifies the name of a `Secret` containing a TLS CA certificate `ca.crt` used to verify -the TLS connection created by the SyncMaster at the specified source. - -This setting is required, unless `spec.source.deploymentName` has been set. - -### `spec.destination.deploymentName: string` - -This setting specifies the name of an `ArangoDeployment` resource that runs a cluster -with sync enabled. - -This cluster configured as the replication destination. - -### `spec.destination.masterEndpoint: []string` - -This setting specifies zero or more master endpoint URLs of the destination cluster. - -Use this setting if the destination cluster is not running inside a Kubernetes cluster -that is reachable from the Kubernetes cluster the `ArangoDeploymentReplication` resource is deployed in. - -Specifying this setting and `spec.destination.deploymentName` at the same time is not allowed. - -### `spec.destination.auth.keyfileSecretName: string` - -This setting specifies the name of a `Secret` containing a client authentication certificate called `tls.keyfile` used to authenticate -with the SyncMaster at the specified destination. - -If `spec.destination.auth.userSecretName` has not been set, -the client authentication certificate found in the secret with this name is also used to configure -the synchronization and fetch the synchronization status. - -This setting is required, unless `spec.destination.deploymentName` or `spec.destination.auth.userSecretName` has been set. - -Specifying this setting and `spec.destination.userSecretName` at the same time is not allowed. - -### `spec.destination.auth.userSecretName: string` - -This setting specifies the name of a `Secret` containing a `username` & `password` used to authenticate -with the SyncMaster at the specified destination in order to configure synchronization and fetch synchronization status. - -The user identified by the username must have write access in the `_system` database of the destination ArangoDB cluster. - -Specifying this setting and `spec.destination.keyfileSecretName` at the same time is not allowed. - -### `spec.destination.tls.caSecretName: string` - -This setting specifies the name of a `Secret` containing a TLS CA certificate `ca.crt` used to verify -the TLS connection created by the SyncMaster at the specified destination. - -This setting is required, unless `spec.destination.deploymentName` has been set. - -## Authentication details - -The authentication settings in a `ArangoDeploymentReplication` resource are used for two distinct purposes. - -The first use is the authentication of the syncmasters at the destination with the syncmasters at the source. -This is always done using a client authentication certificate which is found in a `tls.keyfile` field -in a secret identified by `spec.source.auth.keyfileSecretName`. - -The second use is the authentication of the ArangoDB Replication operator with the syncmasters at the source -or destination. These connections are made to configure synchronization, stop configuration and fetch the status -of the configuration. -The method used for this authentication is derived as follows (where `X` is either `source` or `destination`): - -- If `spec.X.userSecretName` is set, the username + password found in the `Secret` identified by this name is used. -- If `spec.X.keyfileSecretName` is set, the client authentication certificate (keyfile) found in the `Secret` identifier by this name is used. -- If `spec.X.deploymentName` is set, the JWT secret found in the deployment is used. - -## Creating client authentication certificate keyfiles - -The client authentication certificates needed for the `Secrets` identified by `spec.source.auth.keyfileSecretName` & `spec.destination.auth.keyfileSecretName` -are normal ArangoDB keyfiles that can be created by the `arangosync create client-auth keyfile` command. -In order to do so, you must have access to the client authentication CA of the source/destination. - -If the client authentication CA at the source/destination also contains a private key (`ca.key`), the ArangoDeployment operator -can be used to create such a keyfile for you, without the need to have `arangosync` installed locally. -Read the following paragraphs for instructions on how to do that. - -## Creating and using access packages - -An access package is a YAML file that contains: - -- A client authentication certificate, wrapped in a `Secret` in a `tls.keyfile` data field. -- A TLS certificate authority public key, wrapped in a `Secret` in a `ca.crt` data field. - -The format of the access package is such that it can be inserted into a Kubernetes cluster using the standard `kubectl` tool. - -To create an access package that can be used to authenticate with the ArangoDB SyncMasters of an `ArangoDeployment`, -add a name of a non-existing `Secret` to the `spec.sync.externalAccess.accessPackageSecretNames` field of the `ArangoDeployment`. -In response, a `Secret` is created in that Kubernetes cluster, with the given name, that contains a `accessPackage.yaml` data field -that contains a Kubernetes resource specification that can be inserted into the other Kubernetes cluster. - -The process for creating and using an access package for authentication at the source cluster is as follows: - -- Edit the `ArangoDeployment` resource of the source cluster, set `spec.sync.externalAccess.accessPackageSecretNames` to `["my-access-package"]` -- Wait for the `ArangoDeployment` operator to create a `Secret` named `my-access-package`. -- Extract the access package from the Kubernetes source cluster using: - -```bash -kubectl get secret my-access-package --template='{{index .data "accessPackage.yaml"}}' | base64 -D > accessPackage.yaml -``` - -- Insert the secrets found in the access package in the Kubernetes destination cluster using: - -```bash -kubectl apply -f accessPackage.yaml -``` - -As a result, the destination Kubernetes cluster will have 2 additional `Secrets`. One contains a client authentication certificate -formatted as a keyfile. Another contains the public key of the TLS CA certificate of the source cluster. diff --git a/docs/Manual/Deployment/Kubernetes/DeploymentResource.md b/docs/Manual/Deployment/Kubernetes/DeploymentResource.md deleted file mode 100644 index b1eb1a419..000000000 --- a/docs/Manual/Deployment/Kubernetes/DeploymentResource.md +++ /dev/null @@ -1,583 +0,0 @@ -# ArangoDeployment 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 `ActiveFailover` 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 `ActiveFailover` 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. -- `ActiveFailover` Active-failover 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.imagePullSecrets: []string` - -This setting specifies the list of image pull secrets for the docker image to use for all ArangoDB servers. - -### `spec.annotations: map[string]string` - -This setting set specified annotations to all ArangoDeployment owned resources (pods, services, PVC's, PDB's). - -### `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.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 -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.networkAttachedVolumes: bool` - -The default of this option is `false`. If set to `true`, and the -deployed ArangoDB version is new enough (>= 3.4.8 for 3.4 and >= 3.5.1 -for 3.5), a `ResignLeaderShip` operation -will be triggered when a dbserver pod is evicted (rather than a -`CleanOutServer` operation). Furthermore, the pod will simply be -redeployed on a different node, rather than cleaned and retired and -replaced by a new member. You must only set this option to `true` if -your persistent volumes are "movable" in the sense that they can be -mounted from a different k8s node, like in the case of network attached -volumes. If your persistent volumes are tied to a specific pod, you -must leave this option on `false`. - -### `spec.externalAccess.type: string` - -This setting specifies the type of `Service` that will be created to provide -access to the ArangoDB deployment from outside the Kubernetes cluster. -Possible values are: - -- `None` To limit access to application running inside the Kubernetes cluster. -- `LoadBalancer` To create a `Service` of type `LoadBalancer` for the ArangoDB deployment. -- `NodePort` To create a `Service` of type `NodePort` for the ArangoDB deployment. -- `Auto` (default) To create a `Service` of type `LoadBalancer` and fallback to a `Service` or type `NodePort` when the - `LoadBalancer` is not assigned an IP address. - -### `spec.externalAccess.loadBalancerIP: string` - -This setting specifies the IP used to for the LoadBalancer to expose the ArangoDB deployment on. -This setting is used when `spec.externalAccess.type` is set to `LoadBalancer` or `Auto`. - -If you do not specify this setting, an IP will be chosen automatically by the load-balancer provisioner. - -### `spec.externalAccess.loadBalancerSourceRanges: []string` - -If specified and supported by the platform (cloud provider), this will restrict traffic through the cloud-provider -load-balancer will be restricted to the specified client IPs. This field will be ignored if the -cloud-provider does not support the feature. - -More info: https://kubernetes.io/docs/tasks/access-application-cluster/configure-cloud-provider-firewall/ - -### `spec.externalAccess.nodePort: int` - -This setting specifies the port used to expose the ArangoDB deployment on. -This setting is used when `spec.externalAccess.type` is set to `NodePort` or `Auto`. - -If you do not specify this setting, a random port will be chosen automatically. - -### `spec.externalAccess.advertisedEndpoint: string` - -This setting specifies the advertised endpoint for all coordinators. - -### `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.externalAccess.type: string` - -This setting specifies the type of `Service` that will be created to provide -access to the ArangoSync syncMasters from outside the Kubernetes cluster. -Possible values are: - -- `None` To limit access to applications running inside the Kubernetes cluster. -- `LoadBalancer` To create a `Service` of type `LoadBalancer` for the ArangoSync SyncMasters. -- `NodePort` To create a `Service` of type `NodePort` for the ArangoSync SyncMasters. -- `Auto` (default) To create a `Service` of type `LoadBalancer` and fallback to a `Service` or type `NodePort` when the - `LoadBalancer` is not assigned an IP address. - -Note that when you specify a value of `None`, a `Service` will still be created, but of type `ClusterIP`. - -### `spec.sync.externalAccess.loadBalancerIP: string` - -This setting specifies the IP used for the LoadBalancer to expose the ArangoSync SyncMasters on. -This setting is used when `spec.sync.externalAccess.type` is set to `LoadBalancer` or `Auto`. - -If you do not specify this setting, an IP will be chosen automatically by the load-balancer provisioner. - -### `spec.sync.externalAccess.nodePort: int` - -This setting specifies the port used to expose the ArangoSync SyncMasters on. -This setting is used when `spec.sync.externalAccess.type` is set to `NodePort` or `Auto`. - -If you do not specify this setting, a random port will be chosen automatically. - -### `spec.sync.externalAccess.loadBalancerSourceRanges: []string` - -If specified and supported by the platform (cloud provider), this will restrict traffic through the cloud-provider -load-balancer will be restricted to the specified client IPs. This field will be ignored if the -cloud-provider does not support the feature. - -More info: https://kubernetes.io/docs/tasks/access-application-cluster/configure-cloud-provider-firewall/ - - -### `spec.sync.externalAccess.masterEndpoint: []string` - -This setting specifies the master endpoint(s) advertised by the ArangoSync SyncMasters. -If not set, this setting defaults to: - -- If `spec.sync.externalAccess.loadBalancerIP` is set, it defaults to `https://:<8629>`. -- Otherwise it defaults to `https://:<8629>`. - -### `spec.sync.externalAccess.accessPackageSecretNames: []string` - -This setting specifies the names of zero of more `Secrets` that will be created by the deployment -operator containing "access packages". An access package contains those `Secrets` that are needed -to access the SyncMasters of this `ArangoDeployment`. - -By removing a name from this setting, the corresponding `Secret` is also deleted. -Note that to remove all access packages, leave an empty array in place (`[]`). -Completely removing the setting results in not modifying the list. - -See [the `ArangoDeploymentReplication` specification](./DeploymentReplicationResource.md) for more information -on access packages. - -### `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.disableIPv6: bool` - -This setting prevents the use of IPv6 addresses by ArangoDB servers. -The default is `false`. - -This setting cannot be changed after the deployment has been created. - -### `spec.restoreFrom: string` - -This setting specifies a `ArangoBackup` resource name the cluster should be restored from. - -After a restore or failure to do so, the status of the deployment contains information about the -restore operation in the `restore` key. - -It will contain some of the following fields: -- _requestedFrom_: name of the `ArangoBackup` used to restore from. -- _message_: optional message explaining why the restore failed. -- _state_: state indicating if the restore was successful or not. Possible values: `Restoring`, `Restored`, `RestoreFailed` - -If the `restoreFrom` key is removed from the spec, the `restore` key is deleted as well. - -A new restore attempt is made if and only if either in the status restore is not set or if spec.restoreFrom and status.requestedFrom are different. - -### `spec.license.secretName: string` - -This setting specifies the name of a kubernetes `Secret` that contains -the license key token used for enterprise images. This value is not used for -the community edition. - -### `spec.bootstrap.passwordSecretNames.root: string` - -This setting specifies a secret name for the credentials of the root user. - -When a deployment is created the operator will setup the root user account -according to the credentials given by the secret. If the secret doesn't exist -the operator creates a secret with a random password. - -There are two magic values for the secret name: -- `None` specifies no action. This disables root password randomization. This is the default value. (Thus the root password is empty - not recommended) -- `Auto` specifies automatic name generation, which is `-root-password`. - -### `spec.metrics.enabled: bool` - -If this is set to `true`, the operator runs a sidecar container for -every DBserver pod and every coordinator pod. The sidecar container runs -the ArangoDB-exporter and exposes metrics of the corresponding `arangod` -instance in Prometheus format on port 9101 under path `/metrics`. You -also have to specify a string for `spec.metrics.image`, which is the -Docker image name of the `arangodb-exporter`. At the time of this -writing you should use `arangodb/arangodb-exporter:0.1.6`. See [this -repository](https://github.com/arangodb-helper/arangodb-exporter) for -the latest version. If the image name is left empty, the same image as -for the main deployment is used. Note however, that current ArangoDB -releases (<= 3.4.5) do not ship the exporter in their image. This is -going to change in the future. - -In addition to the sidecar containers the operator will deploy a service -to access the exporter ports (from within the k8s cluster), and a -resource of type `ServiceMonitor`, provided the corresponding custom -resource definition is deployed in the k8s cluster. If you are running -Prometheus in the same k8s cluster with the Prometheus operator, this -will be the case. The `ServiceMonitor` will have the following labels -set: - - - `app: arangodb` - - `arango_deployment: YOUR_DEPLOYMENT_NAME` - - `context: metrics` - - `metrics: prometheus` - -This makes it possible that you configure your Prometheus deployment to -automatically start monitoring on the available Prometheus feeds. To -this end, you must configure the `serviceMonitorSelector` in the specs -of your Prometheus deployment to match these labels. For example: - -```yaml - serviceMonitorSelector: - matchLabels: - metrics: prometheus -``` - -would automatically select all pods of all ArangoDB cluster deployments -which have metrics enabled. - -### `spec.metrics.image: string` - -See above, this is the name of the Docker image for the ArangoDB -exporter to expose metrics. If empty, the same image as for the main -deployment is used. - -### `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: ActiveFailover`). - -For the `syncworkers` group, it is highly recommended to use the same number -as for the `dbservers` group. - -### `spec..minCount: number` - -Specifies a minimum for the count of servers. If set, a specification is invalid if `count < minCount`. - -### `spec..maxCount: number` - -Specifies a maximum for the count of servers. If set, a specification is invalid if `count > maxCount`. - -### `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: ResourceRequirements` - -This setting specifies the resources required by pods of this group. This includes requests and limits. - -See https://kubernetes.io/docs/concepts/configuration/manage-compute-resources-container/ for details. - -### `spec..volumeClaimTemplate.Spec: PersistentVolumeClaimSpec` - -Specifies a volumeClaimTemplate used by operator to create to volume claims for pods of this group. -This setting is not available for group `coordinators`, `syncmasters` & `syncworkers`. - -The default value describes a volume with `8Gi` storage, `ReadWriteOnce` access mode and volume mode set to `PersistentVolumeFilesystem`. - -If this field is not set and `spec..resources.requests.storage` is set, then a default volume claim -with size as specified by `spec..resources.requests.storage` will be created. In that case `storage` -and `iops` is not forwarded to the pods resource requirements. - -### `spec..serviceAccountName: string` - -This setting specifies the `serviceAccountName` for the `Pods` created -for each server of this group. If empty, it defaults to using the -`default` service account. - -Using an alternative `ServiceAccount` is typically used to separate access rights. -The ArangoDB deployments need some very minimal access rights. With the -deployment of the operator, we grant the following rights for the `default` -service account: - -``` -rules: -- apiGroups: - - "" - resources: - - pods - verbs: - - get -``` - -If you are using a different service account, please grant these rights -to that service account. - -### `spec..annotations: map[string]string` - -This setting set annotations overrides for pods in this group. Annotations are merged with `spec.annotations`. - -### `spec..priorityClassName: string` - -Priority class name for pods of this group. Will be forwarded to the pod spec. [Kubernetes documentation](https://kubernetes.io/docs/concepts/configuration/pod-priority-preemption/) - -### `spec..probes.livenessProbeDisabled: bool` - -If set to true, the operator does not generate a liveness probe for new pods belonging to this group. - -### `spec..probes.readinessProbeDisabled: bool` - -If set to true, the operator does not generate a readiness probe for new pods belonging to this group. - -### `spec..tolerations: []Toleration` - -This setting specifies the `tolerations` for the `Pod`s created -for each server of this group. - -By default, suitable tolerations are set for the following keys with the `NoExecute` effect: - -- `node.kubernetes.io/not-ready` -- `node.kubernetes.io/unreachable` -- `node.alpha.kubernetes.io/unreachable` (will be removed in future version) - -For more information on tolerations, consult the [Kubernetes documentation](https://kubernetes.io/docs/concepts/configuration/taint-and-toleration/). - -### `spec..nodeSelector: map[string]string` - -This setting specifies a set of labels to be used as `nodeSelector` for Pods of this node. - -For more information on node selectors, consult the [Kubernetes documentation](https://kubernetes.io/docs/concepts/configuration/assign-pod-node/). - -## Deprecated Fields - -### `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. - -Please use VolumeClaimTemplate from now on. This field is not considered if -VolumeClaimTemplate is set. Note however, that the information in requests -is completely handed over to the pod in this case. - -### `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. - -Please use VolumeClaimTemplate from now on. This field is not considered if -VolumeClaimTemplate is set. Note however, that the information in requests -is completely handed over to the pod in this case. diff --git a/docs/Manual/Deployment/Kubernetes/Drain.md b/docs/Manual/Deployment/Kubernetes/Drain.md deleted file mode 100644 index a17a87a2f..000000000 --- a/docs/Manual/Deployment/Kubernetes/Drain.md +++ /dev/null @@ -1,455 +0,0 @@ -# Draining Kubernetes nodes - -{% hint 'danger' %} -If Kubernetes nodes with ArangoDB pods on them are drained without care -data loss can occur! The recommended procedure is described below. -{% endhint %} - -For maintenance work in k8s it is sometimes necessary to drain a k8s node, -which means removing all pods from it. Kubernetes offers a standard API -for this and our operator supports this - to the best of its ability. - -Draining nodes is easy enough for stateless services, which can simply be -re-launched on any other node. However, for a stateful service this -operation is more difficult, and as a consequence more costly and there -are certain risks involved, if the operation is not done carefully -enough. To put it simply, the operator must first move all the data -stored on the node (which could be in a locally attached disk) to -another machine, before it can shut down the pod gracefully. Moving data -takes time, and even after the move, the distributed system ArangoDB has -to recover from this change, for example by ensuring data synchronicity -between the replicas in their new location. - -Therefore, a systematic drain of all k8s nodes in sequence has to follow -a careful procedure, in particular to ensure that ArangoDB is ready to -move to the next step. This is necessary to avoid catastrophic data -loss, and is simply the price one pays for running a stateful service. - -## Anatomy of a drain procedure in k8s: the grace period - -When a `kubectl drain` operation is triggered for a node, k8s first -checks if there are any pods with local data on disk. Our ArangoDB pods have -this property (the _Coordinators_ do use `EmptyDir` volumes, and _Agents_ -and _DBServers_ could have persistent volumes which are actually stored on -a locally attached disk), so one has to override this with the -`--delete-local-data=true` option. - -Furthermore, quite often, the node will contain pods which are managed -by a `DaemonSet` (which is not the case for ArangoDB), which makes it -necessary to override this check with the `--ignore-daemonsets=true` -option. - -Finally, it is checked if the node has any pods which are not managed by -anything, either by k8s itself (`ReplicationController`, `ReplicaSet`, -`Job`, `DaemonSet` or `StatefulSet`) or by an operator. If this is the -case, the drain operation will be refused, unless one uses the option -`--force=true`. Since the ArangoDB operator manages our pods, we do not -have to use this option for ArangoDB, but you might have to use it for -other pods. - -If all these checks have been overcome, k8s proceeds as follows: All -pods are notified about this event and are put into a `Terminating` -state. During this time, they have a chance to take action, or indeed -the operator managing them has. In particular, although the pods get -termination notices, they can keep running until the operator has -removed all _finalizers_. This gives the operator a chance to sort out -things, for example in our case to move data away from the pod. - -However, there is a limit to this tolerance by k8s, and that is the -grace period. If the grace period has passed but the pod has not -actually terminated, then it is killed the hard way. If this happens, -the operator has no chance but to remove the pod, drop its persistent -volume claim and persistent volume. This will obviously lead to a -failure incident in ArangoDB and must be handled by fail-over management. -Therefore, **this event should be avoided**. - -## Things to check in ArangoDB before a node drain - -There are basically two things one should check in an ArangoDB cluster -before a node drain operation can be started: - - 1. All cluster nodes are up and running and healthy. - 2. For all collections and shards all configured replicas are in sync. - -{% hint 'warning' %} -If any cluster node is unhealthy, there is an increased risk that the -system does not have enough resources to cope with a failure situation. - -If any shard replicas are not currently in sync, then there is a serious -risk that the cluster is currently not as resilient as expected. -{% endhint %} - -One possibility to verify these two things is via the ArangoDB web interface. -Node health can be monitored in the _Overview_ tab under _NODES_: - -![Cluster Health Screen](./HealthyCluster.png) - -**Check that all nodes are green** and that there is **no node error** in the -top right corner. - -As to the shards being in sync, see the _Shards_ tab under _NODES_: - -![Shard Screen](./ShardsInSync.png) - -**Check that all collections have a green check mark** on the right side. -If any collection does not have such a check mark, you can click on the -collection and see the details about shards. Please keep in -mind that this has to be done **for each database** separately! - -Obviously, this might be tedious and calls for automation. Therefore, there -are APIs for this. The first one is [Cluster Health](https://www.arangodb.com/docs/stable/http/cluster-health.html): - -``` -POST /_admin/cluster/health -``` - -… which returns a JSON document looking like this: - -```JSON -{ - "Health": { - "CRDN-rxtu5pku": { - "Endpoint": "ssl://my-arangodb-cluster-coordinator-rxtu5pku.my-arangodb-cluster-int.default.svc:8529", - "LastAckedTime": "2019-02-20T08:09:22Z", - "SyncTime": "2019-02-20T08:09:21Z", - "Version": "3.4.2-1", - "Engine": "rocksdb", - "ShortName": "Coordinator0002", - "Timestamp": "2019-02-20T08:09:22Z", - "Status": "GOOD", - "SyncStatus": "SERVING", - "Host": "my-arangodb-cluster-coordinator-rxtu5pku.my-arangodb-cluster-int.default.svc", - "Role": "Coordinator", - "CanBeDeleted": false - }, - "PRMR-wbsq47rz": { - "LastAckedTime": "2019-02-21T09:14:24Z", - "Endpoint": "ssl://my-arangodb-cluster-dbserver-wbsq47rz.my-arangodb-cluster-int.default.svc:8529", - "SyncTime": "2019-02-21T09:14:24Z", - "Version": "3.4.2-1", - "Host": "my-arangodb-cluster-dbserver-wbsq47rz.my-arangodb-cluster-int.default.svc", - "Timestamp": "2019-02-21T09:14:24Z", - "Status": "GOOD", - "SyncStatus": "SERVING", - "Engine": "rocksdb", - "ShortName": "DBServer0006", - "Role": "DBServer", - "CanBeDeleted": false - }, - "AGNT-wrqmwpuw": { - "Endpoint": "ssl://my-arangodb-cluster-agent-wrqmwpuw.my-arangodb-cluster-int.default.svc:8529", - "Role": "Agent", - "CanBeDeleted": false, - "Version": "3.4.2-1", - "Engine": "rocksdb", - "Leader": "AGNT-oqohp3od", - "Status": "GOOD", - "LastAckedTime": 0.312 - }, - ... [some more entries, one for each instance] - }, - "ClusterId": "210a0536-fd28-46de-b77f-e8882d6d7078", - "error": false, - "code": 200 -} -``` - -Check that each instance has a `Status` field with the value `"GOOD"`. -Here is a shell command which makes this check easy, using the -[`jq` JSON pretty printer](https://stedolan.github.io/jq/): - -```bash -curl -k https://arangodb.9hoeffer.de:8529/_admin/cluster/health --user root: | jq . | grep '"Status"' | grep -v '"GOOD"' -``` - -For the shards being in sync there is the -[Cluster Inventory](https://www.arangodb.com/docs/stable/http/replications-replication-dump.html#return-cluster-inventory-of-collections-and-indexes) -API call: - -``` -POST /_db/_system/_api/replication/clusterInventory -``` - -… which returns a JSON body like this: - -```JSON -{ - "collections": [ - { - "parameters": { - "cacheEnabled": false, - "deleted": false, - "globallyUniqueId": "c2010061/", - "id": "2010061", - "isSmart": false, - "isSystem": false, - "keyOptions": { - "allowUserKeys": true, - "type": "traditional" - }, - "name": "c", - "numberOfShards": 6, - "planId": "2010061", - "replicationFactor": 2, - "shardKeys": [ - "_key" - ], - "shardingStrategy": "hash", - "shards": { - "s2010066": [ - "PRMR-vzeebvwf", - "PRMR-e6hbjob1" - ], - "s2010062": [ - "PRMR-e6hbjob1", - "PRMR-vzeebvwf" - ], - "s2010065": [ - "PRMR-e6hbjob1", - "PRMR-vzeebvwf" - ], - "s2010067": [ - "PRMR-vzeebvwf", - "PRMR-e6hbjob1" - ], - "s2010064": [ - "PRMR-vzeebvwf", - "PRMR-e6hbjob1" - ], - "s2010063": [ - "PRMR-e6hbjob1", - "PRMR-vzeebvwf" - ] - }, - "status": 3, - "type": 2, - "waitForSync": false - }, - "indexes": [], - "planVersion": 132, - "isReady": true, - "allInSync": true - }, - ... [more collections following] - ], - "views": [], - "tick": "38139421", - "state": "unused" -} -``` - -Check that for all collections the attributes `"isReady"` and `"allInSync"` -both have the value `true`. Note that it is necessary to do this for all -databases! - -Here is a shell command which makes this check easy: - -```bash -curl -k https://arangodb.9hoeffer.de:8529/_db/_system/_api/replication/clusterInventory --user root: | jq . | grep '"isReady"\|"allInSync"' | sort | uniq -c -``` - -If all these checks are performed and are okay, then it is safe to -continue with the clean out and drain procedure as described below. - -{% hint 'danger' %} -If there are some collections with `replicationFactor` set to -1, the system is not resilient and cannot tolerate the failure of even a -single server! One can still perform a drain operation in this case, but -if anything goes wrong, in particular if the grace period is chosen too -short and a pod is killed the hard way, data loss can happen. -{% endhint %} - -If all `replicationFactor`s of all collections are at least 2, then the -system can tolerate the failure of a single _DBserver_. If you have set -the `Environment` to `Production` in the specs of the ArangoDB -deployment, you will only ever have one _DBserver_ on each k8s node and -therefore the drain operation is relatively safe, even if the grace -period is chosen too small. - -Furthermore, we recommend to have one k8s node more than _DBservers_ in -you cluster, such that the deployment of a replacement _DBServer_ can -happen quickly and not only after the maintenance work on the drained -node has been completed. However, with the necessary care described -below, the procedure should also work without this. - -Finally, one should **not run a rolling upgrade or restart operation** -at the time of a node drain. - -## Clean out a DBserver manually - -In this step we clean out a _DBServer_ manually, **before issuing the -`kubectl drain` command**. Previously, we have denoted this step as optional, -but for safety reasons, we consider it mandatory now, since it is near -impossible to choose the grace period long enough in a reliable way. - -Furthermore, if this step is not performed, we must choose -the grace period long enough to avoid any risk, as explained in the -previous section. However, this has a disadvantage which has nothing to -do with ArangoDB: We have observed, that some k8s internal services like -`fluentd` and some DNS services will always wait for the full grace -period to finish a node drain. Therefore, the node drain operation will -always take as long as the grace period. Since we have to choose this -grace period long enough for ArangoDB to move all data on the _DBServer_ -pod away to some other node, this can take a considerable amount of -time, depending on the size of the data you keep in ArangoDB. - -Therefore it is more time-efficient to perform the clean-out operation -beforehand. One can observe completion and as soon as it is completed -successfully, we can then issue the drain command with a relatively -small grace period and still have a nearly risk-free procedure. - -To clean out a _DBServer_ manually, we have to use this API: - -``` -POST /_admin/cluster/cleanOutServer -``` - -… and send as body a JSON document like this: - -```JSON -{"server":"DBServer0006"} -``` - -The value of the `"server"` attribute should be the name of the DBserver -which is the one in the pod which resides on the node that shall be -drained next. This uses the UI short name (`ShortName` in the -`/_admin/cluster/health` API), alternatively one can use the -internal name, which corresponds to the pod name. In our example, the -pod name is: - -``` -my-arangodb-cluster-prmr-wbsq47rz-5676ed -``` - -… where `my-arangodb-cluster` is the ArangoDB deployment name, therefore -the internal name of the _DBserver_ is `PRMR-wbsq47rz`. Note that `PRMR` -must be all capitals since pod names are always all lower case. So, we -could use the body: - -```JSON -{"server":"PRMR-wbsq47rz"} -``` - -You can use this command line to achieve this: - -```bash -curl -k https://arangodb.9hoeffer.de:8529/_admin/cluster/cleanOutServer --user root: -d '{"server":"PRMR-wbsq47rz"}' -``` - -The API call will return immediately with a body like this: - -```JSON -{"error":false,"id":"38029195","code":202} -``` - -The given `id` in this response can be used to query the outcome or -completion status of the clean out server job with this API: - -``` -GET /_admin/cluster/queryAgencyJob?id=38029195 -``` - -… which will return a body like this: - -```JSON -{ - "error": false, - "id": "38029195", - "status": "Pending", - "job": { - "timeCreated": "2019-02-21T10:42:14.727Z", - "server": "PRMR-wbsq47rz", - "timeStarted": "2019-02-21T10:42:15Z", - "type": "cleanOutServer", - "creator": "CRDN-rxtu5pku", - "jobId": "38029195" - }, - "code": 200 -} -``` - -Use this command line to check progress: - -```bash -curl -k https://arangodb.9hoeffer.de:8529/_admin/cluster/queryAgencyJob?id=38029195 --user root: -``` - -It indicates that the job is still ongoing (`"Pending"`). As soon as -the job has completed, the answer will be: - -```JSON -{ - "error": false, - "id": "38029195", - "status": "Finished", - "job": { - "timeCreated": "2019-02-21T10:42:14.727Z", - "server": "PRMR-e6hbjob1", - "jobId": "38029195", - "timeStarted": "2019-02-21T10:42:15Z", - "timeFinished": "2019-02-21T10:45:39Z", - "type": "cleanOutServer", - "creator": "CRDN-rxtu5pku" - }, - "code": 200 -} -``` - -From this moment on the _DBserver_ can no longer be used to move -shards to. At the same time, it will no longer hold any data of the -cluster. - -Now the drain operation involving a node with this pod on it is -completely risk-free, even with a small grace period. - -## Performing the drain - -After all above [checks before a node drain](#things-to-check-in-arangodb-before-a-node-drain) -and the [manual clean out of the DBServer](#clean-out-a-dbserver-manually) -have been done successfully, it is safe to perform the drain operation, similar to this command: - -```bash -kubectl drain gke-draintest-default-pool-394fe601-glts --delete-local-data --ignore-daemonsets --grace-period=300 -``` - -As described above, the options `--delete-local-data` for ArangoDB and -`--ignore-daemonsets` for other services have been added. A `--grace-period` of -300 seconds has been chosen because for this example we are confident that all the data on our _DBServer_ pod -can be moved to a different server within 5 minutes. Note that this is -**not saying** that 300 seconds will always be enough. Regardless of how -much data is stored in the pod, your mileage may vary, moving a terabyte -of data can take considerably longer! - -If the highly recommended step of -[cleaning out a DBserver manually](#clean-out-a-dbserver-manually) -has been performed beforehand, the grace period can easily be reduced to 60 -seconds - at least from the perspective of ArangoDB, since the server is already -cleaned out, so it can be dropped readily and there is still no risk. - -At the same time, this guarantees now that the drain is completed -approximately within a minute. - -## Things to check after a node drain - -After a node has been drained, there will usually be one of the -_DBservers_ gone from the cluster. As a replacement, another _DBServer_ has -been deployed on a different node, if there is a different node -available. If not, the replacement can only be deployed when the -maintenance work on the drained node has been completed and it is -uncordoned again. In this latter case, one should wait until the node is -back up and the replacement pod has been deployed there. - -After that, one should perform the same checks as described in -[things to check before a node drain](#things-to-check-in-arangodb-before-a-node-drain) -above. - -Finally, it is likely that the shard distribution in the "new" cluster -is not balanced out. In particular, the new _DBSserver_ is not automatically -used to store shards. We recommend to -[re-balance](https://www.arangodb.com/docs/stable/administration-cluster.html#movingrebalancing-shards) the shard distribution, -either manually by moving shards or by using the _Rebalance Shards_ -button in the _Shards_ tab under _NODES_ in the web UI. This redistribution can take -some time again and progress can be monitored in the UI. - -After all this has been done, **another round of checks should be done** -before proceeding to drain the next node. diff --git a/docs/Manual/Deployment/Kubernetes/DriverConfiguration.md b/docs/Manual/Deployment/Kubernetes/DriverConfiguration.md deleted file mode 100644 index 7c7de9e1b..000000000 --- a/docs/Manual/Deployment/Kubernetes/DriverConfiguration.md +++ /dev/null @@ -1,134 +0,0 @@ -# Configuring your driver for ArangoDB access - -In this chapter you'll learn how to configure a driver for accessing -an ArangoDB deployment in Kubernetes. - -The exact methods to configure a driver are specific to that driver. - -## Database endpoint(s) - -The endpoint(s) (or URLs) to communicate with is the most important -parameter your need to configure in your driver. - -Finding the right endpoints depend on wether your client application is running in -the same Kubernetes cluster as the ArangoDB deployment or not. - -### Client application in same Kubernetes cluster - -If your client application is running in the same Kubernetes cluster as -the ArangoDB deployment, you should configure your driver to use the -following endpoint: - -```text -https://..svc:8529 -``` - -Only if your deployment has set `spec.tls.caSecretName` to `None`, should -you use `http` instead of `https`. - -### Client application outside Kubernetes cluster - -If your client application is running outside the Kubernetes cluster in which -the ArangoDB deployment is running, your driver endpoint depends on the -external-access configuration of your ArangoDB deployment. - -If the external-access of the ArangoDB deployment is of type `LoadBalancer`, -then use the IP address of that `LoadBalancer` like this: - -```text -https://:8529 -``` - -If the external-access of the ArangoDB deployment is of type `NodePort`, -then use the IP address(es) of the `Nodes` of the Kubernetes cluster, -combined with the `NodePort` that is used by the external-access service. - -For example: - -```text -https://:30123 -``` - -You can find the type of external-access by inspecting the external-access `Service`. -To do so, run the following command: - -```bash -kubectl get service -n -ea -``` - -The output looks like this: - -```bash -NAME TYPE CLUSTER-IP EXTERNAL-IP PORT(S) AGE SELECTOR -example-simple-cluster-ea LoadBalancer 10.106.175.38 192.168.10.208 8529:31890/TCP 1s app=arangodb,arango_deployment=example-simple-cluster,role=coordinator -``` - -In this case the external-access is of type `LoadBalancer` with a load-balancer IP address -of `192.168.10.208`. -This results in an endpoint of `https://192.168.10.208:8529`. - -## TLS settings - -As mentioned before the ArangoDB deployment managed by the ArangoDB operator -will use a secure (TLS) connection unless you set `spec.tls.caSecretName` to `None` -in your `ArangoDeployment`. - -When using a secure connection, you can choose to verify the server certificates -provides by the ArangoDB servers or not. - -If you want to verify these certificates, configure your driver with the CA certificate -found in a Kubernetes `Secret` found in the same namespace as the `ArangoDeployment`. - -The name of this `Secret` is stored in the `spec.tls.caSecretName` setting of -the `ArangoDeployment`. If you don't set this setting explicitly, it will be -set automatically. - -Then fetch the CA secret using the following command (or use a Kubernetes client library to fetch it): - -```bash -kubectl get secret -n --template='{{index .data "ca.crt"}}' | base64 -D > ca.crt -``` - -This results in a file called `ca.crt` containing a PEM encoded, x509 CA certificate. - -## Query requests - -For most client requests made by a driver, it does not matter if there is any -kind of load-balancer between your client application and the ArangoDB -deployment. - -{% hint 'info' %} -Note that even a simple `Service` of type `ClusterIP` already behaves as a -load-balancer. -{% endhint %} - -The exception to this is cursor-related requests made to an ArangoDB `Cluster` -deployment. The coordinator that handles an initial query request (that results -in a `Cursor`) will save some in-memory state in that coordinator, if the result -of the query is too big to be transfer back in the response of the initial -request. - -Follow-up requests have to be made to fetch the remaining data. These follow-up -requests must be handled by the same coordinator to which the initial request -was made. As soon as there is a load-balancer between your client application -and the ArangoDB cluster, it is uncertain which coordinator will receive the -follow-up request. - -ArangoDB will transparently forward any mismatched requests to the correct -coordinator, so the requests can be answered correctly without any additional -configuration. However, this incurs a small latency penalty due to the extra -request across the internal network. - -To prevent this uncertainty client-side, make sure to run your client -application in the same Kubernetes cluster and synchronize your endpoints before -making the initial query request. This will result in the use (by the driver) of -internal DNS names of all coordinators. A follow-up request can then be sent to -exactly the same coordinator. - -If your client application is running outside the Kubernetes cluster the easiest -way to work around it is by making sure that the query results are small enough -to be returned by a single request. When that is not feasible, it is also -possible to resolve this when the internal DNS names of your Kubernetes cluster -are exposed to your client application and the resulting IP addresses are -routable from your client application. To expose internal DNS names of your -Kubernetes cluster, your can use [CoreDNS](https://coredns.io). diff --git a/docs/Manual/Deployment/Kubernetes/HealthyCluster.png b/docs/Manual/Deployment/Kubernetes/HealthyCluster.png deleted file mode 100644 index 2670e5bd2..000000000 Binary files a/docs/Manual/Deployment/Kubernetes/HealthyCluster.png and /dev/null differ diff --git a/docs/Manual/Deployment/Kubernetes/Helm.md b/docs/Manual/Deployment/Kubernetes/Helm.md deleted file mode 100644 index c4c6b501b..000000000 --- a/docs/Manual/Deployment/Kubernetes/Helm.md +++ /dev/null @@ -1,154 +0,0 @@ -# Using the ArangoDB Kubernetes Operator with Helm - -[`Helm`](https://www.helm.sh/) is a package manager for Kubernetes, which enables -you to install various packages (include the ArangoDB Kubernetes Operator) -into your Kubernetes cluster. - -The benefit of `helm` (in the context of the ArangoDB Kubernetes Operator) -is that it allows for a lot of flexibility in how you install the operator. -For example you can install the operator in a namespace other than -`default`. - -## Charts - -The ArangoDB Kubernetes Operator is contained in two `helm` charts: - -- `kube-arangodb` which contains the operator for the `ArangoDeployment`, `ArangoLocalStorage` - and `ArangoDeploymentReplication` resource types. -- `kube-arangodb-crd` which contains the CRD for the `ArangoDeployment` and `ArangoDeploymentReplication` resource types. - - -## Configurable values for ArangoDB Kubernetes Operator - -The following values can be configured when installing the -ArangoDB Kubernetes Operator with `helm`. - -Values are passed to `helm` using an `--set==` argument passed -to the `helm install` or `helm upgrade` command. - -### `operator.image` - -Image used for the ArangoDB Operator. - -Default: `arangodb/kube-arangodb:latest` - -### `operator.imagePullPolicy` - -Image pull policy for Operator images. - -Default: `IfNotPresent` - -### `operator.imagePullSecrets` - -List of the Image Pull Secrets for Operator images. - -Default: `[]string` - -### `operator.service.type` - -Type of the Operator service. - -Default: `ClusterIP` - -### `operator.annotations` - -Annotations passed to the Operator Deployment definition. - -Default: `[]string` - -### `operator.resources.limits.cpu` - -CPU limits for operator pods. - -Default: `1` - -### `operator.resources.limits.memory` - -Memory limits for operator pods. - -Default: `256Mi` - -### `operator.resources.requested.cpu` - -Requested CPI by Operator pods. - -Default: `250m` - -### `operator.resources.requested.memory` - -Requested memory for operator pods. - -Default: `256Mi` - -### `operator.replicaCount` - -Replication count for Operator deployment. - -Default: `2` - -### `operator.updateStrategy` - -Update strategy for operator pod. - -Default: `Recreate` - -### `operator.features.deployment` - -Define if ArangoDeployment Operator should be enabled. - -Default: `true` - -### `operator.features.deploymentReplications` - -Define if ArangoDeploymentReplications Operator should be enabled. - -Default: `true` - -### `operator.features.storage` - -Define if ArangoLocalStorage Operator should be enabled. - -Default: `false` - -### `operator.features.backup` - -Define if ArangoBackup Operator should be enabled. - -Default: `false` - -### `rbac.enabled` - -Define if RBAC should be enabled. - -Default: `true` - -## Alternate namespaces - -The `kube-arangodb` chart supports deployment into a non-default namespace. - -To install the `kube-arangodb` chart is a non-default namespace, use the `--namespace` -argument like this. - -```bash -helm install --namespace=mynamespace kube-arangodb.tgz -``` - -Note that since the operators claim exclusive access to a namespace, you can -install the `kube-arangodb` chart in a namespace once. -You can install the `kube-arangodb` chart in multiple namespaces. To do so, run: - -```bash -helm install --namespace=namespace1 kube-arangodb.tgz -helm install --namespace=namespace2 kube-arangodb.tgz -``` - -The `kube-arangodb-storage` chart is always installed in the `kube-system` namespace. - -## Common problems - -### Error: no available release name found - -This error is given by `helm install ...` in some cases where it has -insufficient permissions to install charts. - -For various ways to work around this problem go to [this Stackoverflow article](https://stackoverflow.com/questions/43499971/helm-error-no-available-release-name-found). diff --git a/docs/Manual/Deployment/Kubernetes/Metrics.md b/docs/Manual/Deployment/Kubernetes/Metrics.md deleted file mode 100644 index 2b1ec822e..000000000 --- a/docs/Manual/Deployment/Kubernetes/Metrics.md +++ /dev/null @@ -1,15 +0,0 @@ -# Metrics - -The ArangoDB Kubernetes Operator (`kube-arangodb`) exposes metrics of -its operations in a format that is compatible with [Prometheus](https://prometheus.io). - -The metrics are exposed through HTTPS on port `8528` under path `/metrics`. - -Look at [examples/metrics](https://github.com/arangodb/kube-arangodb/tree/master/examples/metrics) -for examples of `Services` and `ServiceMonitors` you can use to integrate -with Prometheus through the [Prometheus-Operator by CoreOS](https://github.com/coreos/prometheus-operator). - -Furthermore, the operator can run sidecar containers for ArangoDB -deployments of type Cluster which expose metrics in Prometheus format. -Use the attribute `spec.metrics` to set this up see the [spec -reference](./DeploymentResource.md) for details. diff --git a/docs/Manual/Deployment/Kubernetes/README.md b/docs/Manual/Deployment/Kubernetes/README.md deleted file mode 100644 index f22499ece..000000000 --- a/docs/Manual/Deployment/Kubernetes/README.md +++ /dev/null @@ -1,23 +0,0 @@ -# ArangoDB Kubernetes Operator - -The ArangoDB Kubernetes Operator (`kube-arangodb`) is a set of operators -that you deploy in your Kubernetes cluster to: - -- Manage deployments of the ArangoDB database -- Provide `PersistentVolumes` on local storage of your nodes for optimal storage performance. -- Configure ArangoDB Datacenter to Datacenter replication - -Each of these uses involves a different custom resource. - -- Use an [`ArangoDeployment` resource](./DeploymentResource.md) to - create an ArangoDB database deployment. -- Use an [`ArangoBackup` resource](./BackupResource.md) to - create an ArangoDB backup. -- Use an [`ArangoLocalStorage` resource](./StorageResource.md) to - provide local `PersistentVolumes` for optimal I/O performance. -- Use an [`ArangoDeploymentReplication` resource](./DeploymentReplicationResource.md) to - configure ArangoDB Datacenter to Datacenter replication. - -Continue with [Using the ArangoDB Kubernetes Operator](./Usage.md) -to learn how to install the ArangoDB Kubernetes operator and create -your first deployment. \ No newline at end of file diff --git a/docs/Manual/Deployment/Kubernetes/Scaling.md b/docs/Manual/Deployment/Kubernetes/Scaling.md deleted file mode 100644 index 37bee7c15..000000000 --- a/docs/Manual/Deployment/Kubernetes/Scaling.md +++ /dev/null @@ -1,21 +0,0 @@ -# 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/docs/Manual/Deployment/Kubernetes/ServicesAndLoadBalancer.md b/docs/Manual/Deployment/Kubernetes/ServicesAndLoadBalancer.md deleted file mode 100644 index 381e508bb..000000000 --- a/docs/Manual/Deployment/Kubernetes/ServicesAndLoadBalancer.md +++ /dev/null @@ -1,125 +0,0 @@ -# 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. - -By default, the ArangoDB Kubernetes Operator will also create an additional -service to reach the ArangoDB deployment from outside the Kubernetes cluster. - -For exposing the ArangoDB deployment to the outside, there are 2 options: - -- Using a `NodePort` service. This will expose the deployment on a specific port (above 30.000) - on all nodes of the Kubernetes cluster. -- Using a `LoadBalancer` service. This will expose the deployment on a load-balancer - that is provisioned by the Kubernetes cluster. - -The `LoadBalancer` option is the most convenient, but not all Kubernetes clusters -are able to provision a load-balancer. Therefore we offer a third (and default) option: `Auto`. -In this option, the ArangoDB Kubernetes Operator tries to create a `LoadBalancer` -service. It then waits for up to a minute for the Kubernetes cluster to provision -a load-balancer for it. If that has not happened after a minute, the service -is replaced by a service of type `NodePort`. - -To inspect the created service, run: - -```bash -kubectl get services -ea -``` - -To use the ArangoDB servers from outside the Kubernetes cluster -you have to add another service as explained below. - -## Services - -If you do not want the ArangoDB Kubernetes Operator to create an external-access -service for you, set `spec.externalAccess.Type` to `None`. - -If you want to create external access services manually, follow the instructions below. - -### 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`. - -- `-int` 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 -(`.-int..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 - -If you want full control of the `Services` needed to access the ArangoDB deployment -from outside your Kubernetes cluster, set `spec.externalAccess.type` of the `ArangoDeployment` to `None` -and create a `Service` as specified below. - -Create a `Service` of type `LoadBalancer` or `NodePort`, depending on your -Kubernetes deployment. - -This service should select: - -- `arango_deployment: ` -- `role: coordinator` - -The following example yields a service of type `LoadBalancer` with a specific -load balancer IP address. -With this service, the ArangoDB cluster can now be reached on `https://1.2.3.4:8529`. - -```yaml -kind: Service -apiVersion: v1 -metadata: - name: arangodb-cluster-exposed -spec: - selector: - arango_deployment: arangodb-cluster - role: coordinator - type: LoadBalancer - loadBalancerIP: 1.2.3.4 - ports: - - protocol: TCP - port: 8529 - targetPort: 8529 -``` - -The following example yields a service of type `NodePort` with the ArangoDB -cluster exposed on port 30529 of all nodes of the Kubernetes cluster. - -```yaml -kind: Service -apiVersion: v1 -metadata: - name: arangodb-cluster-exposed -spec: - selector: - arango_deployment: arangodb-cluster - role: coordinator - type: NodePort - ports: - - protocol: TCP - port: 8529 - targetPort: 8529 - nodePort: 30529 -``` diff --git a/docs/Manual/Deployment/Kubernetes/ShardsInSync.png b/docs/Manual/Deployment/Kubernetes/ShardsInSync.png deleted file mode 100644 index f013ba30a..000000000 Binary files a/docs/Manual/Deployment/Kubernetes/ShardsInSync.png and /dev/null differ diff --git a/docs/Manual/Deployment/Kubernetes/Storage.md b/docs/Manual/Deployment/Kubernetes/Storage.md deleted file mode 100644 index 2b4b6b687..000000000 --- a/docs/Manual/Deployment/Kubernetes/Storage.md +++ /dev/null @@ -1,133 +0,0 @@ -# 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 `ArangoDeployment` resource, one can specify the type of storage -used by groups of servers using the `spec..storageClassName` -setting. - -This is an example of a `Cluster` deployment that stores its agent & dbserver -data on `PersistentVolumes` that use the `my-local-ssd` `StorageClass` - -```yaml -apiVersion: "database.arangodb.com/v1alpha" -kind: "ArangoDeployment" -metadata: - name: "cluster-using-local-ssh" -spec: - mode: Cluster - agents: - storageClassName: my-local-ssd - dbservers: - storageClassName: my-local-ssd -``` - -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. - -This is an example of a `Cluster` deployment that requests volumes of 80GB -for every dbserver, resulting in a total storage capacity of 240GB (with 3 dbservers). - -```yaml -apiVersion: "database.arangodb.com/v1alpha" -kind: "ArangoDeployment" -metadata: - name: "cluster-using-local-ssh" -spec: - mode: Cluster - dbservers: - resources: - requests: - storage: 80Gi -``` - -## Local storage - -For optimal performance, ArangoDB should be configured with locally attached -SSD storage. - -The easiest way to accomplish this is to deploy an -[`ArangoLocalStorage` resource](./StorageResource.md). -The ArangoDB Storage Operator will use it to provide `PersistentVolumes` for you. - -This is an example of an `ArangoLocalStorage` resource that will result in -`PersistentVolumes` created on any node of the Kubernetes cluster -under the directory `/mnt/big-ssd-disk`. - -```yaml -apiVersion: "storage.arangodb.com/v1alpha" -kind: "ArangoLocalStorage" -metadata: - name: "example-arangodb-storage" -spec: - storageClass: - name: my-local-ssd - localPath: - - /mnt/big-ssd-disk -``` - -Note that using local storage required `VolumeScheduling` to be enabled in your -Kubernetes cluster. ON Kubernetes 1.10 this is enabled by default, on version -1.9 you have to enable it with a `--feature-gate` setting. - -### Manually creating `PersistentVolumes` - -The alternative is to create `PersistentVolumes` manually, 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/docs/Manual/Deployment/Kubernetes/StorageResource.md b/docs/Manual/Deployment/Kubernetes/StorageResource.md deleted file mode 100644 index e6a005290..000000000 --- a/docs/Manual/Deployment/Kubernetes/StorageResource.md +++ /dev/null @@ -1,62 +0,0 @@ -# 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/docs/Manual/Deployment/Kubernetes/Tls.md b/docs/Manual/Deployment/Kubernetes/Tls.md deleted file mode 100644 index 480422853..000000000 --- a/docs/Manual/Deployment/Kubernetes/Tls.md +++ /dev/null @@ -1,54 +0,0 @@ -# Secure connections (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 - -To install a CA certificate in Windows, follow the -[procedure described here](http://wiki.cacert.org/HowTo/InstallCAcertRoots). - -### 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 - -To install a CA certificate in Linux, on Ubuntu, run: - -```bash -sudo cp ca.crt /usr/local/share/ca-certificates/.crt -sudo update-ca-certificates -``` - -## See also - -- [Authentication](./Authentication.md) diff --git a/docs/Manual/Deployment/Kubernetes/Troubleshooting.md b/docs/Manual/Deployment/Kubernetes/Troubleshooting.md deleted file mode 100644 index 4bfda279c..000000000 --- a/docs/Manual/Deployment/Kubernetes/Troubleshooting.md +++ /dev/null @@ -1,115 +0,0 @@ -# Troubleshooting - -While Kubernetes and the ArangoDB Kubernetes operator will automatically -resolve a lot of issues, there are always cases where human attention -is needed. - -This chapter gives your tips & tricks to help you troubleshoot deployments. - -## Where to look - -In Kubernetes all resources can be inspected using `kubectl` using either -the `get` or `describe` command. - -To get all details of the resource (both specification & status), -run the following command: - -```bash -kubectl get -n -o yaml -``` - -For example, to get the entire specification and status -of an `ArangoDeployment` resource named `my-arangodb` in the `default` namespace, -run: - -```bash -kubectl get ArangoDeployment my-arango -n default -o yaml -# or shorter -kubectl get arango my-arango -o yaml -``` - -Several types of resources (including all ArangoDB custom resources) support -events. These events show what happened to the resource over time. - -To show the events (and most important resource data) of a resource, -run the following command: - -```bash -kubectl describe -n -``` - -## Getting logs - -Another invaluable source of information is the log of containers being run -in Kubernetes. -These logs are accessible through the `Pods` that group these containers. - -To fetch the logs of the default container running in a `Pod`, run: - -```bash -kubectl logs -n -# or with follow option to keep inspecting logs while they are written -kubectl logs -n -f -``` - -To inspect the logs of a specific container in `Pod`, add `-c `. -You can find the names of the containers in the `Pod`, using `kubectl describe pod ...`. - -{% hint 'info' %} -Note that the ArangoDB operators are being deployed themselves as a Kubernetes `Deployment` -with 2 replicas. This means that you will have to fetch the logs of 2 `Pods` running -those replicas. -{% endhint %} - -## What if - -### The `Pods` of a deployment stay in `Pending` state - -There are two common causes for this. - -1) The `Pods` cannot be scheduled because there are not enough nodes available. - This is usually only the case with a `spec.environment` setting that has a value of `Production`. - - Solution: -Add more nodes. - -1) There are no `PersistentVolumes` available to be bound to the `PersistentVolumeClaims` - created by the operator. - - Solution: -Use `kubectl get persistentvolumes` to inspect the available `PersistentVolumes` -and if needed, use the [`ArangoLocalStorage` operator](./StorageResource.md) to provision `PersistentVolumes`. - -### When restarting a `Node`, the `Pods` scheduled on that node remain in `Terminating` state - -When a `Node` no longer makes regular calls to the Kubernetes API server, it is -marked as not available. Depending on specific settings in your `Pods`, Kubernetes -will at some point decide to terminate the `Pod`. As long as the `Node` is not -completely removed from the Kubernetes API server, Kubernetes will try to use -the `Node` itself to terminate the `Pod`. - -The `ArangoDeployment` operator recognizes this condition and will try to replace those -`Pods` with `Pods` on different nodes. The exact behavior differs per type of server. - -### What happens when a `Node` with local data is broken - -When a `Node` with `PersistentVolumes` hosted on that `Node` is broken and -cannot be repaired, the data in those `PersistentVolumes` is lost. - -If an `ArangoDeployment` of type `Single` was using one of those `PersistentVolumes` -the database is lost and must be restored from a backup. - -If an `ArangoDeployment` of type `ActiveFailover` or `Cluster` was using one of -those `PersistentVolumes`, it depends on the type of server that was using the volume. - -- If an `Agent` was using the volume, it can be repaired as long as 2 other agents are still healthy. -- If a `DBServer` was using the volume, and the replication factor of all database - collections is 2 or higher, and the remaining dbservers are still healthy, - the cluster will duplicate the remaining replicas to - bring the number of replicas back to the original number. -- If a `DBServer` was using the volume, and the replication factor of a database - collection is 1 and happens to be stored on that dbserver, the data is lost. -- If a single server of an `ActiveFailover` deployment was using the volume, and the - other single server is still healthy, the other single server will become leader. - After replacing the failed single server, the new follower will synchronize with - the leader. diff --git a/docs/Manual/Deployment/Kubernetes/Upgrading.md b/docs/Manual/Deployment/Kubernetes/Upgrading.md deleted file mode 100644 index 90e9b7e73..000000000 --- a/docs/Manual/Deployment/Kubernetes/Upgrading.md +++ /dev/null @@ -1,41 +0,0 @@ -# Upgrading - -The ArangoDB Kubernetes Operator supports upgrading an ArangoDB from -one version to the next. - -## Upgrade an ArangoDB deployment - -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 -``` - -The ArangoDB operator will perform an sequential upgrade -of all servers in your deployment. Only one server is upgraded -at a time. - -For patch level upgrades (e.g. 3.3.9 to 3.3.10) each server -is stopped and restarted with the new version. - -For minor level upgrades (e.g. 3.3.9 to 3.4.0) each server -is stopped, then the new version is started with `--database.auto-upgrade` -and once that is finish the new version is started with the normal arguments. - -The process for major level upgrades depends on the specific version. - -## Upgrade the operator itself - -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 -``` - -## See also - -- [Scaling](./Scaling.md) \ No newline at end of file diff --git a/docs/Manual/Deployment/Kubernetes/Usage.md b/docs/Manual/Deployment/Kubernetes/Usage.md deleted file mode 100644 index 12b2d2944..000000000 --- a/docs/Manual/Deployment/Kubernetes/Usage.md +++ /dev/null @@ -1,116 +0,0 @@ -# Using the ArangoDB Kubernetes Operator - -## Installation - -The ArangoDB Kubernetes Operator needs to be installed in your Kubernetes -cluster first. - -If you have `Helm` available, we recommend installation using `Helm`. - -### Installation with Helm - -To install the ArangoDB Kubernetes Operator with [`helm`](https://www.helm.sh/), -run (replace `` with the version of the operator that you want to install): - -```bash -export URLPREFIX=https://github.com/arangodb/kube-arangodb/releases/download/ -helm install $URLPREFIX/kube-arangodb-crd.tgz -helm install $URLPREFIX/kube-arangodb.tgz -``` - -This installs operators for the `ArangoDeployment` and `ArangoDeploymentReplication` -resource types. - -If you want to avoid the installation of the operator for the `ArangoDeploymentReplication` -resource type, add `--set=DeploymentReplication.Create=false` to the `helm install` -command. - -To use `ArangoLocalStorage` resources, also run: - -```bash -helm install $URLPREFIX/kube-arangodb-storage.tgz -``` - -For more information on installing with `Helm` and how to customize an installation, -see [Using the ArangoDB Kubernetes Operator with Helm](./Helm.md). - -### Installation with Kubectl - -To install the ArangoDB Kubernetes Operator without `Helm`, -run (replace `` with the version of the operator that you want to install): - -```bash -export URLPREFIX=https://raw.githubusercontent.com/arangodb/kube-arangodb//manifests -kubectl apply -f $URLPREFIX/arango-crd.yaml -kubectl apply -f $URLPREFIX/arango-deployment.yaml -``` - -To use `ArangoLocalStorage` resources, also run: - -```bash -kubectl apply -f $URLPREFIX/arango-storage.yaml -``` - -To use `ArangoDeploymentReplication` resources, also run: - -```bash -kubectl apply -f $URLPREFIX/arango-deployment-replication.yaml -``` - -You can find the latest release of the ArangoDB Kubernetes Operator -[in the kube-arangodb repository](https://github.com/arangodb/kube-arangodb/releases/latest). - -## ArangoDB deployment creation - -Once the operator is running, you can create your ArangoDB database deployment -by creating a `ArangoDeployment` custom resource and deploying it into your -Kubernetes cluster. - -For example (all examples can be found [in the kube-arangodb repository](https://github.com/arangodb/kube-arangodb/tree/master/examples)): - -```bash -kubectl apply -f examples/simple-cluster.yaml -``` - -## Deployment removal - -To remove an existing ArangoDB deployment, delete the custom -resource. The operator will then delete all created resources. - -For example: - -```bash -kubectl delete -f examples/simple-cluster.yaml -``` - -**Note that this will also delete all data in your ArangoDB deployment!** - -If you want to keep your data, make sure to create a backup before removing the deployment. - -## Operator removal - -To remove the entire ArangoDB Kubernetes Operator, remove all -clusters first and then remove the operator by running: - -```bash -helm delete -# If `ArangoLocalStorage` operator is installed -helm delete -``` - -or when you used `kubectl` to install the operator, run: - -```bash -kubectl delete deployment arango-deployment-operator -# If `ArangoLocalStorage` operator is installed -kubectl delete deployment -n kube-system arango-storage-operator -# If `ArangoDeploymentReplication` operator is installed -kubectl delete deployment arango-deployment-replication-operator -``` - -## See also - -- [Driver configuration](./DriverConfiguration.md) -- [Scaling](./Scaling.md) -- [Upgrading](./Upgrading.md) -- [Using the ArangoDB Kubernetes Operator with Helm](./Helm.md) \ No newline at end of file diff --git a/docs/Manual/Tutorials/Kubernetes/AKS.md b/docs/Manual/Tutorials/Kubernetes/AKS.md deleted file mode 100644 index 3aec03c54..000000000 --- a/docs/Manual/Tutorials/Kubernetes/AKS.md +++ /dev/null @@ -1,104 +0,0 @@ -# Start ArangoDB on Azure Kubernetes Service (AKS) - -## Requirements - -* [kubectl](https://kubernetes.io/docs/tasks/tools/install-kubectl/) (**version >= 1.10**) -* [helm](https://www.helm.sh/) -* [Azure CLI](https://docs.microsoft.com/en-us/cli/azure/install-azure-cli-apt?view=azure-cli-latest) - -## Deploy cluster - -* In Azure dashboard choose **Create a resource** -* Choose **Kubernetes Service** - -## Cluster basics (version >=1.10) - -![basics](./aks-create-basics.png) - -## Cluster authentication (Enable RBAC) - -![basics](./aks-create-auth.png) - -## Wait for cluster to be created - -![basics](./aks-create-valid.png) - -## Move to control using `kubectl` - -- Login to Azure using CLI - - ``` - $ az login - [ - { - "cloudName": "AzureCloud", - "id": "...", - "isDefault": true, - "name": "ArangoDB-INC", - "state": "Enabled", - "tenantId": "...", - "user": { - "name": "xxx@arangodb.com", - "type": "user" - } - } - ] - ``` - -- Get AKS credentials to merge with local config, using resource group and - cluster names used for above deployment - - ``` - $ az aks get-credentials --resource-group clifton --name ArangoDB - ``` - -- Verify successful merge - - ``` - $ kubectl get svc - NAME TYPE CLUSTER-IP EXTERNAL-IP PORT(S) AGE - kubernetes ClusterIP 10.0.0.1 443/TCP 38m - ``` - -- Initialize `helm` - - ``` - $ kubectl create serviceaccount --namespace kube-system tiller - serviceaccount/tiller created - ``` - - ``` - $ kubectl create clusterrolebinding tiller-cluster-rule \ - --clusterrole=cluster-admin --serviceaccount=kube-system:tiller - clusterrolebinding.rbac.authorization.k8s.io/tiller-cluster-rule created - ``` - - ``` - $ helm init --service-account tiller - $HELM_HOME has been configured at /home/xxx/.helm. - ... - Happy Helming! - - Tiller (the Helm server-side component) has been - installed into your Kubernetes Cluster. - ``` - -- Deploy ArangoDB operator - - ``` - $ helm install \ - github.com/arangodb/kube-arangodb/releases/download/X.X.X/kube-arangodb.tgz - NAME: orderly-hydra - LAST DEPLOYED: Wed Oct 31 15:11:37 2018 - NAMESPACE: default - STATUS: DEPLOYED - ... - See https://www.arangodb.com/docs/stable/tutorials-kubernetes.html - for how to get started. - ``` - -- Deploy ArangoDB cluster - - ``` - $ kubectl apply -f https://raw.githubusercontent.com/arangodb/kube-arangodb/master/examples/simple-cluster.yaml - ``` diff --git a/docs/Manual/Tutorials/Kubernetes/DC2DC.md b/docs/Manual/Tutorials/Kubernetes/DC2DC.md deleted file mode 100644 index 760d1e2f9..000000000 --- a/docs/Manual/Tutorials/Kubernetes/DC2DC.md +++ /dev/null @@ -1,142 +0,0 @@ -# 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. - -{% hint 'info' %} -This feature is only available in the -[**Enterprise Edition**](https://www.arangodb.com/why-arangodb/arangodb-enterprise/) -{% endhint %} - -## 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/docs/Manual/Tutorials/Kubernetes/EKS.md b/docs/Manual/Tutorials/Kubernetes/EKS.md deleted file mode 100644 index d3c6952af..000000000 --- a/docs/Manual/Tutorials/Kubernetes/EKS.md +++ /dev/null @@ -1,187 +0,0 @@ -# Start ArangoDB on Amazon Elastic Kubernetes Service (EKS) - -## Requirements: - -* [kubectl](https://kubernetes.io/docs/tasks/tools/install-kubectl/) (**version >= 1.10**) -* [helm](https://www.helm.sh/) -* [AWS IAM authenticator](https://github.com/kubernetes-sigs/aws-iam-authenticator) -* [AWS CLI](https://docs.aws.amazon.com/cli/latest/userguide/installing.html) (**version >= 1.16**) - -``` -$ aws --version - aws-cli/1.16.43 Python/2.7.15rc1 Linux/4.15.0-36-generic botocore/1.12.33 -``` - -## Create a Kubernetes cluster - -![clusters](eks-clusters.png) - -## Wait for cluster to be `ACTIVE` -![cluster-active](eks-cluster-active.png) - -## Continue with aws client - -### Configure AWS client - -Refer to the [AWS documentation](https://docs.aws.amazon.com/cli/latest/userguide/cli-chap-getting-started.html) -to accordingly fill in the below with your credentials. -Pay special attention to the correct region information to find your cluster next. - -``` -$ aws configure - AWS Access Key ID [None]: AKIAIOSFODNN7EXAMPLE - AWS Secret Access Key [None]: wJalrXUtnFEMI/K7MDENG/bPxRfiCYEXAMPLEKEY - Default region name [None]: us-west-2 - Default output format [None]: json -``` - -Verify that you can see your cluster listed, when authenticated -``` -$ aws eks list-clusters -{ - "clusters": [ - "ArangoDB" - ] -} -``` - -You should be able to verify the `ACTIVE` state of your cluster -``` -$ aws eks describe-cluster --name ArangoDB --query cluster.status - "ACTIVE" -``` - -### Integrate kubernetes configuration locally - -It's time to integrate the cluster into your local kubernetes configurations - -``` -$ aws eks update-kubeconfig --name ArangoDB - Added new context arn:aws:eks:us-west-2:XXXXXXXXXXX:cluster/ArangoDB to ... - -``` - -At this point, we are ready to use kubectl to communicate with the cluster. -``` -$ kubectl get service - NAME TYPE CLUSTER-IP EXTERNAL-IP PORT(S) AGE - kubernetes ClusterIP 10.100.0.1 443/TCP 23h -``` - -``` -$ kubectl get nodes - No resources found. -``` - -### Create worker Stack - -On Amazon EKS, we need to launch worker nodes, as the cluster has none. -Open Amazon's [cloud formation console](https://console.aws.amazon.com/cloudformation/) -and choose `Create Stack` by specifying this S3 template URL: - -``` -https://amazon-eks.s3-us-west-2.amazonaws.com/cloudformation/2018-08-30/amazon-eks-nodegroup.yaml -``` - -![formation-template](eks-create-template.png) - -### Worker stack details - -Pay good attention to details here. If your input is not complete, your worker -nodes are either not spawned or you won't be able to integrate the workers -into your kubernetes cluster. - -**Stack name**: Choose a name for your stack. For example ArangoDB-stack - -**ClusterName**: **Important!!!** Use the same name as above, refer to `aws eks list-clusters`. - -**ClusterControlPlaneSecurityGroup**: Choose the same SecurityGroups value as above, when you create your EKS Cluster. - -**NodeGroupName**: Enter a name for your node group for example `ArangoDB-node-group` - -**NodeAutoScalingGroupMinSize**: Minimum number of nodes to which you may scale your workers. - -**NodeAutoScalingGroupMaxSize**: Nomen est omen. - -**NodeInstanceType**: Choose an instance type for your worker nodes. For this test we went with the default `t2.medium` instances. - -**NodeImageId**: Dependent on the region, there are two image Ids for boxes with and without GPU support. - -| Region | without GPU | with GPU | -|-----------|-----------------------|-----------------------| -| us-west-2 | ami-0a54c984b9f908c81 | ami-0440e4f6b9713faf6 | -| us-east-1 | ami-0440e4f6b9713faf6 | ami-058bfb8c236caae89 | -| eu-west-1 | ami-0c7a4976cb6fafd3a | ami-0706dc8a5eed2eed9 | - -**KeyName**: SSH key pair, which may be used to ssh into the nodes. This is required input. - -**VpcId**: The same VPCId, which you get using `aws eks describe-cluster --name --query cluster.resourcesVpcConfig.vpcId` - -**Subnets**: Choose the subnets that you created in Create your Amazon EKS Cluster VPC. - -### Review your stack and submit -![create-review](eks-create-review.png) - -### Wait for stack to get ready -![eks-stack](eks-stack.png) - -### Note down `NodeInstanceRole` -Once stack is ready, navigate at the bottom to the Outputs pane and note down the `NodeInstanceRole` -![eks-stack](eks-stack-ready.png) - -### Integrate worker stack as Kubernetes nodes - -* Download the configuration map here: -``` -$ curl -O https://amazon-eks.s3-us-west-2.amazonaws.com/cloudformation/2018-08-30/aws-auth-cm.yaml -``` -* Modify `data|mapRoles|rolearn` to match the `NoteInstanceRole`, you acquired after your node stack was finished - -* Deploy node integration -``` -$ kubectl apply -f aws-auth-cm.yaml -``` - -### Wait for nodes to join the cluster and get ready -Monitor `kubectl get nodes` and watch your nodes to be ready -``` -$ kubectl get nodes - NAME STATUS ROLES AGE VERSION - ip-172-31-20-103.us-west-2.compute.internal Ready 1d v1.10.3 - ip-172-31-38-160.us-west-2.compute.internal Ready 1d v1.10.3 - ip-172-31-45-199.us-west-2.compute.internal Ready 1d v1.10.3 -``` - -### Setup `helm` -* Create service account for `tiller` -``` -$ kubectl create serviceaccount --namespace kube-system tiller - serviceaccount/tiller created -``` -* Allow `tiller` to modify the cluster -``` -$ kubectl create clusterrolebinding tiller-cluster-rule \ - --clusterrole=cluster-admin --serviceaccount=kube-system:tiller - clusterrolebinding.rbac.authorization.k8s.io/tiller-cluster-rule created -``` -* Initialize `helm` -``` -$ helm init --service-account tiller - $HELM_HOME has been configured at ~/.helm. - ... - Happy Helming! -``` - -### Deploy ArangoDB cluster -``` -$ kubectl apply -f https://raw.githubusercontent.com/arangodb/kube-arangodb/master/examples/simple-cluster.yaml -``` - -### Wait for cluster to become ready -Get `LoadBalancer` address from below command to access your coordinator. -``` -$ kubectl get svc -``` - -### Secure ArangoDB cluster -Do not forget to immediately assign a secure database `root` password once on coordinator diff --git a/docs/Manual/Tutorials/Kubernetes/GKE.md b/docs/Manual/Tutorials/Kubernetes/GKE.md deleted file mode 100644 index 52f1813fb..000000000 --- a/docs/Manual/Tutorials/Kubernetes/GKE.md +++ /dev/null @@ -1,77 +0,0 @@ -# Start ArangoDB on Google Kubernetes Engine (GKE) - -In this guide you'll learn how to run ArangoDB on Google Kubernetes Engine (GKE). - -## Create a Kubernetes cluster - -In order to run ArangoDB on GKE you first need to create a Kubernetes cluster. - -To do so, go to the GKE console. -You'll find a list of existing clusters (initially empty). - -![clusters](./gke-clusters.png) - -Click on `CREATE CLUSTER`. - -In the form that follows, enter information as seen in the screenshot below. - -![create a cluster](./gke-create-cluster.png) - -We have successfully ran clusters with 4 `1 vCPU` nodes or 3 `2 vCPU` nodes. -Smaller node configurations will likely lead to unschedulable `Pods`. - -Once you click `Create`, you'll return to the list of clusters and your -new cluster will be listed there. - -![with new cluster](./gke-clusters-added.png) - -It will take a few minutes for the cluster to be created. - -Once you're cluster is ready, a `Connect` button will appear in the list. - -![cluster is ready](./gke-clusters-ready.png) - -## Getting access to your Kubernetes cluster - -Once your cluster is ready you must get access to it. -The standard `Connect` button provided by GKE will give you access with only limited -permissions. Since the Kubernetes operator also requires some cluster wide -permissions, you need "administrator" permissions. - -To get these permissions, do the following. - -Click on `Connect` next to your cluster. -The following popup will appear. - -![connect to cluster](./gke-connect-to-cluster.png) - -Click on `Run in Cloud Shell`. - -It will take some time to launch a shell (in your browser). - -Once ready, run the `gcloud` command that is already prepare in your commandline. - -You should now be able to access your cluster using `kubectl`. - -To verify try a command like: - -```bash -kubectl get pods --all-namespaces -``` - -## Installing `kube-arangodb` - -You can now install the ArangoDB Kubernetes operator in your Kubernetes cluster -on GKE. - -To do so, follow the [Installing kube-arangodb](./README.md#installing-kube-arangodb) instructions. - -## Deploying your first ArangoDB database - -Once the ArangoDB Kubernetes operator has been installed and its `Pods` are in the `Ready` -state, you can launch your first ArangoDB deployment in your Kubernetes cluster -on GKE. - -To do so, follow the [Deploying your first ArangoDB database](./README.md#deploying-your-first-arangodb-database) instructions. - -Note that GKE supports `Services` of type `LoadBalancer`. diff --git a/docs/Manual/Tutorials/Kubernetes/README.md b/docs/Manual/Tutorials/Kubernetes/README.md deleted file mode 100644 index 2d177790e..000000000 --- a/docs/Manual/Tutorials/Kubernetes/README.md +++ /dev/null @@ -1,193 +0,0 @@ -# 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 need 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. - -First, you obviously need a Kubernetes cluster and the right credentials -to access it. If you already have this, you can immediately skip to the -next section. Since different cloud providers differ slightly in their -Kubernetes offering, we have put together detailed tutorials for those -platforms we officially support, follow the link for detailed setup -instructions: - - - [Amazon Elastic Kubernetes Service (EKS)](EKS.md) - - [Google Kubernetes Engine (GKE)](GKE.md) - - [Microsoft Azure Kubernetes Service (AKS)](AKS.md) - -Note that in particular the details of Role Based Access Control (RBAC) -matter. - -## 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/arango-crd.yaml -kubectl apply -f https://raw.githubusercontent.com/arangodb/kube-arangodb//manifests/arango-deployment.yaml -# To use `ArangoLocalStorage`, also run -kubectl apply -f https://raw.githubusercontent.com/arangodb/kube-arangodb//manifests/arango-storage.yaml -# To use `ArangoDeploymentReplication`, also run -kubectl apply -f https://raw.githubusercontent.com/arangodb/kube-arangodb//manifests/arango-deployment-replication.yaml -``` - -The first command installs two `CustomResourceDefinitions` in your Kubernetes cluster: - -- `ArangoDeployment` is the resource used to deploy ArangoDB database. -- `ArangoDeploymentReplication` is the resource used to deploy ArangoDB DC2DC - replications. - -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. Furthermore, this also installs a -new custom resource definition: - -- `ArangoLocalStorage` is the resource used to provision `PersistentVolumes` on local storage. - -The optional fourth command installs a `Deployment` that runs the -operator that takes care of DC2DC replications. - -## 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/docs/Manual/Tutorials/Kubernetes/aks-create-auth.png b/docs/Manual/Tutorials/Kubernetes/aks-create-auth.png deleted file mode 100644 index 0f6746f8b..000000000 Binary files a/docs/Manual/Tutorials/Kubernetes/aks-create-auth.png and /dev/null differ diff --git a/docs/Manual/Tutorials/Kubernetes/aks-create-basics.png b/docs/Manual/Tutorials/Kubernetes/aks-create-basics.png deleted file mode 100644 index e2b644500..000000000 Binary files a/docs/Manual/Tutorials/Kubernetes/aks-create-basics.png and /dev/null differ diff --git a/docs/Manual/Tutorials/Kubernetes/aks-create-valid.png b/docs/Manual/Tutorials/Kubernetes/aks-create-valid.png deleted file mode 100644 index 9af3d6acb..000000000 Binary files a/docs/Manual/Tutorials/Kubernetes/aks-create-valid.png and /dev/null differ diff --git a/docs/Manual/Tutorials/Kubernetes/eks-cluster-active.png b/docs/Manual/Tutorials/Kubernetes/eks-cluster-active.png deleted file mode 100644 index 0f433bafa..000000000 Binary files a/docs/Manual/Tutorials/Kubernetes/eks-cluster-active.png and /dev/null differ diff --git a/docs/Manual/Tutorials/Kubernetes/eks-clusters.png b/docs/Manual/Tutorials/Kubernetes/eks-clusters.png deleted file mode 100644 index 006308cea..000000000 Binary files a/docs/Manual/Tutorials/Kubernetes/eks-clusters.png and /dev/null differ diff --git a/docs/Manual/Tutorials/Kubernetes/eks-create-review.png b/docs/Manual/Tutorials/Kubernetes/eks-create-review.png deleted file mode 100644 index c4ff95be7..000000000 Binary files a/docs/Manual/Tutorials/Kubernetes/eks-create-review.png and /dev/null differ diff --git a/docs/Manual/Tutorials/Kubernetes/eks-create-template.png b/docs/Manual/Tutorials/Kubernetes/eks-create-template.png deleted file mode 100644 index 2a62b9ce9..000000000 Binary files a/docs/Manual/Tutorials/Kubernetes/eks-create-template.png and /dev/null differ diff --git a/docs/Manual/Tutorials/Kubernetes/eks-stack-ready.png b/docs/Manual/Tutorials/Kubernetes/eks-stack-ready.png deleted file mode 100644 index 511bef48f..000000000 Binary files a/docs/Manual/Tutorials/Kubernetes/eks-stack-ready.png and /dev/null differ diff --git a/docs/Manual/Tutorials/Kubernetes/eks-stack.png b/docs/Manual/Tutorials/Kubernetes/eks-stack.png deleted file mode 100644 index 3cc192bb8..000000000 Binary files a/docs/Manual/Tutorials/Kubernetes/eks-stack.png and /dev/null differ diff --git a/docs/Manual/Tutorials/Kubernetes/gke-clusters-added.png b/docs/Manual/Tutorials/Kubernetes/gke-clusters-added.png deleted file mode 100644 index 845a44495..000000000 Binary files a/docs/Manual/Tutorials/Kubernetes/gke-clusters-added.png and /dev/null differ diff --git a/docs/Manual/Tutorials/Kubernetes/gke-clusters-ready.png b/docs/Manual/Tutorials/Kubernetes/gke-clusters-ready.png deleted file mode 100644 index 7ecf21fd8..000000000 Binary files a/docs/Manual/Tutorials/Kubernetes/gke-clusters-ready.png and /dev/null differ diff --git a/docs/Manual/Tutorials/Kubernetes/gke-clusters.png b/docs/Manual/Tutorials/Kubernetes/gke-clusters.png deleted file mode 100644 index dd9a033bf..000000000 Binary files a/docs/Manual/Tutorials/Kubernetes/gke-clusters.png and /dev/null differ diff --git a/docs/Manual/Tutorials/Kubernetes/gke-connect-to-cluster.png b/docs/Manual/Tutorials/Kubernetes/gke-connect-to-cluster.png deleted file mode 100644 index 80c824f50..000000000 Binary files a/docs/Manual/Tutorials/Kubernetes/gke-connect-to-cluster.png and /dev/null differ diff --git a/docs/Manual/Tutorials/Kubernetes/gke-create-cluster.png b/docs/Manual/Tutorials/Kubernetes/gke-create-cluster.png deleted file mode 100644 index 2108d5981..000000000 Binary files a/docs/Manual/Tutorials/Kubernetes/gke-create-cluster.png and /dev/null differ diff --git a/docs/README.md b/docs/README.md index 5ac45532c..bff3a892a 100644 --- a/docs/README.md +++ b/docs/README.md @@ -1,17 +1,5 @@ # ArangoDB Kubernetes Operator -- [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) - - [Backup Resource](./Manual/Deployment/Kubernetes/BackupResource.md) - - [BackupPolicy Resource](./Manual/Deployment/Kubernetes/BackupPolicyResource.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) +- [Tutorial](https://www.arangodb.com/docs/stable/tutorials-kubernetes.html) +- [Documentation](https://www.arangodb.com/docs/stable/deployment-kubernetes.html) - [Design documents](./design/README.md) diff --git a/docs/Manual/Tutorials/Kubernetes/bare-metal.md b/docs/bare-metal.md similarity index 93% rename from docs/Manual/Tutorials/Kubernetes/bare-metal.md rename to docs/bare-metal.md index 1b00a3002..05f670682 100644 --- a/docs/Manual/Tutorials/Kubernetes/bare-metal.md +++ b/docs/bare-metal.md @@ -3,27 +3,32 @@ A not of warning for lack of a better word upfront: Kubernetes is awesome and powerful. As with awesome and powerful things, there is infinite ways of setting up a k8s cluster. With great flexibility -comes great complexity. There are inifinite ways of hitting barriers. +comes great complexity. There are infinite ways of hitting barriers. This guide is a walk through for, again in lack of a better word, -a reasonable and flexibel setup to get to an ArangoDB cluster setup on -a baremetal kubernetes setup. +a reasonable and flexible setup to get to an ArangoDB cluster setup on +a bare metal kubernetes setup. ## BEWARE: Do not use this setup for production! -This guide does not involve setting up dedicated master nodes or high availability for Kubernetes, but uses for sake of simplicity a single untainted master. This is the very definition of a test environment. +This guide does not involve setting up dedicated master nodes or high +availability for Kubernetes, but uses for sake of simplicity a single untainted +master. This is the very definition of a test environment. -If you are interested in running a high available Kubernetes setup, please refer to: [Creating Highly Available Clusters with kubeadm](https://kubernetes.io/docs/setup/independent/high-availability/) +If you are interested in running a high available Kubernetes setup, please +refer to: [Creating Highly Available Clusters with kubeadm](https://kubernetes.io/docs/setup/independent/high-availability/) ## Requirements -Let there be 3 Linux boxes, `kube01 (192.168.10.61)`, `kube02 (192.168.10.62)` and `kube03 (192.168.10.3)`, with `kubeadm` and `kubectl` installed and off we go: +Let there be 3 Linux boxes, `kube01 (192.168.10.61)`, `kube02 (192.168.10.62)` +and `kube03 (192.168.10.3)`, with `kubeadm` and `kubectl` installed and off we go: * `kubeadm`, `kubectl` version `>=1.10` -## Initialise the master node +## Initialize the master node -The master node is outstanding in that it handles the API server and some other vital infrastructure +The master node is outstanding in that it handles the API server and some other +vital infrastructure ``` sudo kubeadm init --pod-network-cidr=10.244.0.0/16 @@ -106,7 +111,9 @@ sudo chown $(id -u):$(id -g) $HOME/.kube/config ## Deploy a pod network -For this guide, we go with **flannel**, as it is an easy way of setting up a layer 3 network, which uses the Kubernetes API and just works anywhere, where a network between the involved machines works: +For this guide, we go with **flannel**, as it is an easy way of setting up a +layer 3 network, which uses the Kubernetes API and just works anywhere, where a +network between the involved machines works: ``` kubectl apply -f \ @@ -126,7 +133,8 @@ kubectl apply -f \ ## Join remaining nodes -Run the above join commands on the nodes `kube02` and `kube03`. Below is the output on `kube02` for the setup for this guide: +Run the above join commands on the nodes `kube02` and `kube03`. Below is the +output on `kube02` for the setup for this guide: ``` sudo kubeadm join 192.168.10.61:6443 --token blcr1y.49wloegyaugice8a --discovery-token-ca-cert-hash sha256:0505933664d28054a62298c68dc91e9b2b5cf01ecfa2228f3c8fa2412b7a78c8 @@ -327,7 +335,8 @@ You can now deploy ArangoDeployment & ArangoDeploymentReplication resources. See https://www.arangodb.com/docs/stable/tutorials-kubernetes.html for how to get started. ``` -- As unlike cloud k8s offerings no file volume infrastructure exists, we need to still deploy the storage operator chart: +- As unlike cloud k8s offerings no file volume infrastructure exists, we need + to still deploy the storage operator chart: ``` helm install \ @@ -424,13 +433,15 @@ kubectl get services kubernetes ClusterIP 10.96.0.1 443/TCP 69m ``` -- In this case, according to the access service, `example-simple-cluster-ea`, the cluster's coordinators are reachable here: +- In this case, according to the access service, `example-simple-cluster-ea`, + the cluster's coordinators are reachable here: https://kube01:30551, https://kube02:30551 and https://kube03:30551 ## LoadBalancing -For this guide we like to use the `metallb` load balancer, which can be easiy installed as a simple layer 2 load balancer: +For this guide we like to use the `metallb` load balancer, which can be easiy +installed as a simple layer 2 load balancer: - install the `metalllb` controller: @@ -452,13 +463,16 @@ kubectl apply -f \ deployment.apps/controller created ``` -- Deploy network range configurator. Assuming that the range for the IP addresses, which are granted to `metalllb` for load balancing is 192.168.10.224/28, download the [exmample layer2 configurator](https://raw.githubusercontent.com/google/metallb/v0.7.3/manifests/example-layer2-config.yaml). +- Deploy network range configurator. Assuming that the range for the IP addresses, + which are granted to `metalllb` for load balancing is 192.168.10.224/28, + download the [exmample layer2 configurator](https://raw.githubusercontent.com/google/metallb/v0.7.3/manifests/example-layer2-config.yaml). ``` wget https://raw.githubusercontent.com/google/metallb/v0.7.3/manifests/example-layer2-config.yaml ``` -- Edit the `example-layer2-config.yaml` file to use the according addresses. Do this with great care, as YAML files are indention sensitive. +- Edit the `example-layer2-config.yaml` file to use the according addresses. + Do this with great care, as YAML files are indention sensitive. ``` apiVersion: v1 @@ -493,7 +507,7 @@ kubectl delete service example-simple-cluster-ea service "example-simple-cluster-ea" deleted ``` -- watch, how the service goes from `Nodeport` to `LoadBalancer` the output above +- watch, how the service goes from `Nodeport` to `LoadBalancer` the output above ``` kubectl get services diff --git a/docs/design/acceptance_test.md b/docs/design/acceptance_test.md index 090bc73a2..5967035dc 100644 --- a/docs/design/acceptance_test.md +++ b/docs/design/acceptance_test.md @@ -32,7 +32,7 @@ Deploy the following ArangoDB operators: - `ArangoDeploymentReplication` operator - `ArangoLocalStorage` operator -To do so, follow the [instructions in the manual](../Manual/Deployment/Kubernetes/Usage.md). +To do so, follow the [instructions in the documentation](https://www.arangodb.com/docs/stable/deployment-kubernetes-usage.html). ### `PersistentVolume` provider