diff --git a/site/content/arangodb/3.12/develop/http-api/administration.md b/site/content/arangodb/3.12/develop/http-api/administration.md index 57effdb398..5c279b0d2b 100644 --- a/site/content/arangodb/3.12/develop/http-api/administration.md +++ b/site/content/arangodb/3.12/develop/http-api/administration.md @@ -1257,6 +1257,108 @@ x-content-type-options: nosniff ``` {{< /details >}} +### Get the deployment ID + +Introduced in: v3.12.6 + +```openapi +paths: + /_db/{database-name}/_admin/deployment/id: + get: + operationId: getDeploymentId + description: | + Get the unique identifier of this ArangoDB deployment. + parameters: + - name: database-name + in: path + required: true + example: _system + description: | + The name of a database. Which database you use doesn't matter as long + as the user account you authenticate with has at least read access + to this database. + schema: + type: string + responses: + '200': + description: | + The deployment ID has been retrieved successfully. + content: + application/json: + schema: + type: object + required: + - id + properties: + id: + description: | + The UUID that uniquely identifies the deployment. + type: string + format: uuid + '401': + description: | + The user account has insufficient permissions for the selected database. + content: + application/json: + schema: + type: object + required: + - error + - code + - errorNum + - errorMessage + properties: + error: + description: | + A flag indicating that an error occurred. + type: boolean + example: true + code: + description: | + The HTTP response status code. + type: integer + example: 401 + errorNum: + description: | + The ArangoDB error number for the error that occurred. + type: integer + errorMessage: + description: | + A descriptive error message. + type: string + tags: + - Administration +``` + +**Examples** + +{{< comment >}} +Example not generated because it the deployment ID would change on every run. +{{< /comment >}} + +```bash +curl --header 'accept: application/json' --dump - http://localhost:8529/_admin/deployment/id +``` + +{{< details summary="Show output" >}} +```bash +HTTP/1.1 200 OK +X-Arango-Queue-Time-Seconds: 0.000000 +Strict-Transport-Security: max-age=31536000 ; includeSubDomains +Expires: 0 +Pragma: no-cache +Cache-Control: no-cache, no-store, must-revalidate, pre-check=0, post-check=0, max-age=0, s-maxage=0 +Content-Security-Policy: frame-ancestors 'self'; form-action 'self'; +X-Content-Type-Options: nosniff +Server: ArangoDB +Connection: Keep-Alive +Content-Type: application/json; charset=utf-8 +Content-Length: 45 + +{"id":"6172616e-676f-4000-0000-9396df268f7f"} +``` +{{< /details >}} + ## Shutdown ### Start the shutdown sequence diff --git a/site/content/arangodb/3.12/develop/javascript-api/@arangodb/db-object.md b/site/content/arangodb/3.12/develop/javascript-api/@arangodb/db-object.md index bcc82a55e1..d5bf818473 100644 --- a/site/content/arangodb/3.12/develop/javascript-api/@arangodb/db-object.md +++ b/site/content/arangodb/3.12/develop/javascript-api/@arangodb/db-object.md @@ -1282,4 +1282,4 @@ Sets a license. - `force` (boolean, _optional_): Whether to change the license even if it expires sooner than the current one. Default: `false`. -Also see [Apply a license](../../../operations/administration/license-management.md#apply-a-license). +Also see [Apply a license key](../../../operations/administration/license-management.md#apply-a-license-key). diff --git a/site/content/arangodb/3.12/operations/administration/license-management.md b/site/content/arangodb/3.12/operations/administration/license-management.md index ae55860b72..03b1ffd9b7 100644 --- a/site/content/arangodb/3.12/operations/administration/license-management.md +++ b/site/content/arangodb/3.12/operations/administration/license-management.md @@ -3,25 +3,134 @@ title: Enterprise Edition License Management menuTitle: License Management weight: 20 description: >- - How to apply a license and check the licensing status of an ArangoDB deployment + How to activate a deployment, obtain and apply a license key, and check the + licensing status of an ArangoDB deployment --- The Enterprise Edition of ArangoDB requires a license so that you can use ArangoDB for commercial purposes and have a dataset size over 100 GiB. See [ArangoDB Editions](../../features/_index.md#arangodb-editions) for details. -How to set a license key and to retrieve information about the current license -via different interfaces is described below. +There are different license management flows: -{{< info >}} -If you use the ArangoDB Kubernetes Operator (including the Data Platform), -check the [kube-arangodb documentation](https://arangodb.github.io/kube-arangodb/docs/how-to/set_license.html) -for more details on how to set a license key in a Kubernetes-managed deployment. -{{< /info >}} +- **Activate a deployment** (from v3.12.6 onward):\ + Customers receive license credentials composed of a client ID and a client secret. + You can use a command-line tool to activate deployments with these credentials, + either one-off or continuously. + + An activation is generally valid for two weeks and it is recommended to + renew the activation weekly. + + {{< info >}} + If you use the ArangoDB Kubernetes Operator (including the Data Platform), + check the [kube-arangodb documentation](https://arangodb.github.io/kube-arangodb/docs/how-to/set_license.html) + for more details on how to set a license key in a Kubernetes-managed deployment. + {{< /info >}} + +- **Apply a license key**:\ + Up to v3.12.5, customers received a license key directly and it was typically + valid for one year. From v3.12.6 onward, customers receive license credentials + instead. You can use a command-line tool to generate a license key using these + credentials, and the license key generally expires every two weeks. + + You can also activate a deployment instead of generating a license key, but + this requires an internet connection. For air-gapped environments for example, + the license key flow is required and the license key has a longer validity. + +How to activate a deployment or apply a license key to it, as well as how to +retrieve information about the current license via different interfaces is +described below. + +## Activate a deployment + +1. Download the Arango Data Platform CLI tool `arangodb_operator_platform` from + . + It is available for Linux, macOS, and Windows for the x86-64 as well as 64-bit ARM + architecture (e.g. `arangodb_operator_platform_linux_amd64`). + + It is recommended to rename the downloaded executable to + `arangodb_operator_platform` (with an `.exe` extension on Windows) and add it to + the `PATH` environment variable to make it available as a command in the system. + +2. Activate a deployment once using the Platform CLI tool. Point it to a running + ArangoDB deployment (running on `http://localhost:8529` in this example) and + supply the license credentials: + + ```sh + arangodb_operator_platform license activate --arango.endpoint http://localhost:8529 --license.client.id "your-corp" --license.client.secret "..." + ``` + + Unless authentication is disabled for the deployment, you need to additionally + supply either ArangoDB user credentials or a JWT session token and specify the + authentication method (case-sensitive): + + ```sh + # User credentials + arangodb_operator_platform license activate --arango.authentication Basic --arango.basic.username "root" --arango.basic.password "" ... + + # JWT session token + arangodb_operator_platform license activate --arango.authentication Token --arango.token "eyJh..." ... + ``` + +3. You can specify an activation interval to keep the Platform CLI tool running + and have it re-activate the deployment automatically, e.g. once a week: + + ```sh + arangodb_operator_platform license activate --license.interval 168h ... + ``` + +## Generate a license key + +1. Download the Arango Data Platform CLI tool `arangodb_operator_platform` from + . + It is available for Linux, macOS, and Windows for the x86-64 as well as 64-bit ARM + architecture (e.g. `arangodb_operator_platform_linux_amd64`). + + It is recommended to rename the downloaded executable to + `arangodb_operator_platform` (with an `.exe` extension on Windows) and add it to + the `PATH` environment variable to make it available as a command in the system. + +2. Create an inventory file using the Platform CLI tool. Point it to a running + ArangoDB deployment (running on `http://localhost:8529` in this example): + + ```sh + arangodb_operator_platform license inventory --arango.endpoint="http://localhost:8529" inventory.json + ``` + + Unless authentication is disabled for the deployment, you need to additionally + supply either ArangoDB user credentials or a JWT session token and specify the + authentication method (case-sensitive): + + ```sh + # User credentials + arangodb_operator_platform license inventory --arango.authentication Basic --arango.basic.username "root" --arango.basic.password "" ... + + # JWT session token + arangodb_operator_platform license inventory --arango.authentication Token --arango.token "eyJh..." ... + ``` + +3. Determine the ID of the ArangoDB deployment. You can find it in the inventory file + or call the [`GET /_admin/deployment/id` endpoint](../../develop/http-api/administration.md#get-the-deployment-id): + + ```sh + # User credentials + curl -uroot: http://localhost:8529/_admin/deployment/id + + # JWT session token + curl -H "Authorization: Bearer eyJh..." http://localhost:8529/_admin/deployment/id + + # Example result: + # {"id":"6172616e-676f-4000-0000-05c958168340"} + ``` + +4. Generate the license key using the deployment ID, the inventory file, and the + license credentials, and write it to a file: -## Apply a license + ```sh + arangodb_operator_platform license generate --deployment.id "6172616e-676f-4000-0000-05c958168340" --inventory inventory.json --license.client.id "your-corp" --license.client.secret "..." 2> license_key.txt + ``` -To use the Enterprise Edition, set the license key like so: +## Apply a license key {{< tabs "interfaces" >}} @@ -32,6 +141,7 @@ To use the Enterprise Edition, set the license key like so: 4. Expand the **PUT /_admin/license** sub-panel. 5. Click the **Try it out** button. 6. Paste the license key into the text area below the **Request body** label. + Make sure the key is wrapped in double quotes. 7. Make sure the license key is surrounded by double quote marks. 8. Click the **Execute** button. 9. Scroll down to **Server response** to check the result. diff --git a/site/content/arangodb/3.12/release-notes/version-3.12/api-changes-in-3-12.md b/site/content/arangodb/3.12/release-notes/version-3.12/api-changes-in-3-12.md index 16456aaa60..7c4681dd46 100644 --- a/site/content/arangodb/3.12/release-notes/version-3.12/api-changes-in-3-12.md +++ b/site/content/arangodb/3.12/release-notes/version-3.12/api-changes-in-3-12.md @@ -338,6 +338,15 @@ documentation. Also see [Authentication with access tokens](#authentication-with-access-tokens) for related API changes. +#### Deployment ID + +Introduced in: v3.12.6 + +Licenses are now bound to specific deployments. Each deployment has a unique +identifier that you can retrieve via a new +[`GET /_admin/deployment/id` endpoint](../../develop/http-api/administration.md#get-the-deployment-id) +in the HTTP API. + ### Endpoints augmented #### View API diff --git a/site/content/arangodb/3.12/release-notes/version-3.12/incompatible-changes-in-3-12.md b/site/content/arangodb/3.12/release-notes/version-3.12/incompatible-changes-in-3-12.md index 1fe5a31d18..ef6c6782af 100644 --- a/site/content/arangodb/3.12/release-notes/version-3.12/incompatible-changes-in-3-12.md +++ b/site/content/arangodb/3.12/release-notes/version-3.12/incompatible-changes-in-3-12.md @@ -994,6 +994,23 @@ more data, less file descriptors are used. - `segmentsBytesMax` increased from `5368709120` (5 GiB) to `8589934592` (8 GiB) - `segmentsBytesFloor` increased from `2097152` (2 MiB) to `25165824` (24 MiB) +## License management changes + +Introduced in: v3.12.6 + +Enterprise Edition license keys are now longer issued directly. Customers receive +license credentials instead. You can use a command-line tool to either activate +deployments or generate license keys using these credentials. An internet +connection is required for both. A generated key can subsequently be applied to +an air-gapped deployment without internet access. + +The activation and license keys are now typically short-lived and need to be +renewed every two weeks. Old license keys remain valid until their regular +expiration. + +See [Enterprise Edition License Management](../../operations/administration/license-management.md) +for details. + ## Added and removed consolidation options for inverted indexs and `arangosearch` Views Introduced in: v3.12.7 diff --git a/site/content/arangodb/3.12/release-notes/version-3.12/whats-new-in-3-12.md b/site/content/arangodb/3.12/release-notes/version-3.12/whats-new-in-3-12.md index e550246d34..ae6cc65e89 100644 --- a/site/content/arangodb/3.12/release-notes/version-3.12/whats-new-in-3-12.md +++ b/site/content/arangodb/3.12/release-notes/version-3.12/whats-new-in-3-12.md @@ -2509,6 +2509,27 @@ environment variable `NAME`. If there is an environment variable called `PID` or `TEMP_BASE_DIR`, then `@PID@` or `@TEMP_BASE_DIR@` is substituted with the value of the respective environment variable. +### License management changes + +Introduced: v3.12.6 + +The Enterprise Edition requires a license and customers used to receive a +license key directly. Going forward, customers receive license credentials +instead. You can use a command-line tool to either activate deployments or +generate license keys using these credentials. + +The activation and license keys are now typically short-lived and need to be +renewed every two weeks. Old license keys remain valid until their regular +expiration. + +Licenses are now bound to specific deployments. Each deployment has a unique +identifier that you can retrieve via a new +[`GET /_admin/deployment/id` endpoint](../../develop/http-api/administration.md#get-the-deployment-id) +in the HTTP API. + +See [Enterprise Edition License Management](../../operations/administration/license-management.md) +for details. + ### New consolidation algorithm for inverted indexes and `arangosearch` Views Introduced in: v3.12.7 diff --git a/site/content/arangodb/4.0/develop/http-api/administration.md b/site/content/arangodb/4.0/develop/http-api/administration.md index 57effdb398..5c279b0d2b 100644 --- a/site/content/arangodb/4.0/develop/http-api/administration.md +++ b/site/content/arangodb/4.0/develop/http-api/administration.md @@ -1257,6 +1257,108 @@ x-content-type-options: nosniff ``` {{< /details >}} +### Get the deployment ID + +Introduced in: v3.12.6 + +```openapi +paths: + /_db/{database-name}/_admin/deployment/id: + get: + operationId: getDeploymentId + description: | + Get the unique identifier of this ArangoDB deployment. + parameters: + - name: database-name + in: path + required: true + example: _system + description: | + The name of a database. Which database you use doesn't matter as long + as the user account you authenticate with has at least read access + to this database. + schema: + type: string + responses: + '200': + description: | + The deployment ID has been retrieved successfully. + content: + application/json: + schema: + type: object + required: + - id + properties: + id: + description: | + The UUID that uniquely identifies the deployment. + type: string + format: uuid + '401': + description: | + The user account has insufficient permissions for the selected database. + content: + application/json: + schema: + type: object + required: + - error + - code + - errorNum + - errorMessage + properties: + error: + description: | + A flag indicating that an error occurred. + type: boolean + example: true + code: + description: | + The HTTP response status code. + type: integer + example: 401 + errorNum: + description: | + The ArangoDB error number for the error that occurred. + type: integer + errorMessage: + description: | + A descriptive error message. + type: string + tags: + - Administration +``` + +**Examples** + +{{< comment >}} +Example not generated because it the deployment ID would change on every run. +{{< /comment >}} + +```bash +curl --header 'accept: application/json' --dump - http://localhost:8529/_admin/deployment/id +``` + +{{< details summary="Show output" >}} +```bash +HTTP/1.1 200 OK +X-Arango-Queue-Time-Seconds: 0.000000 +Strict-Transport-Security: max-age=31536000 ; includeSubDomains +Expires: 0 +Pragma: no-cache +Cache-Control: no-cache, no-store, must-revalidate, pre-check=0, post-check=0, max-age=0, s-maxage=0 +Content-Security-Policy: frame-ancestors 'self'; form-action 'self'; +X-Content-Type-Options: nosniff +Server: ArangoDB +Connection: Keep-Alive +Content-Type: application/json; charset=utf-8 +Content-Length: 45 + +{"id":"6172616e-676f-4000-0000-9396df268f7f"} +``` +{{< /details >}} + ## Shutdown ### Start the shutdown sequence diff --git a/site/content/arangodb/4.0/develop/javascript-api/@arangodb/db-object.md b/site/content/arangodb/4.0/develop/javascript-api/@arangodb/db-object.md index d9d2dc1af7..5a198c6f40 100644 --- a/site/content/arangodb/4.0/develop/javascript-api/@arangodb/db-object.md +++ b/site/content/arangodb/4.0/develop/javascript-api/@arangodb/db-object.md @@ -1265,4 +1265,4 @@ Sets a license. - `force` (boolean, _optional_): Whether to change the license even if it expires sooner than the current one. Default: `false`. -Also see [Apply a license](../../../operations/administration/license-management.md#apply-a-license). +Also see [Apply a license key](../../../operations/administration/license-management.md#apply-a-license-key). diff --git a/site/content/arangodb/4.0/operations/administration/license-management.md b/site/content/arangodb/4.0/operations/administration/license-management.md index 8fda54572c..33853f5034 100644 --- a/site/content/arangodb/4.0/operations/administration/license-management.md +++ b/site/content/arangodb/4.0/operations/administration/license-management.md @@ -3,7 +3,8 @@ title: Enterprise Edition License Management menuTitle: License Management weight: 20 description: >- - How to apply a license and check the licensing status of an ArangoDB deployment + How to activate a deployment, obtain and apply a license key, and check the + licensing status of an ArangoDB deployment aliases: - ../upgrading/community-to-enterprise-upgrade # 3.12 -> 4.0 --- @@ -12,18 +13,126 @@ ArangoDB for commercial purposes and have a dataset size over 100 GiB. See [ArangoDB Editions](../../features/_index.md#arangodb-editions) for details. -How to set a license key and to retrieve information about the current license -via different interfaces is described below. +There are different license management flows: -{{< info >}} -If you use the ArangoDB Kubernetes Operator (including the Data Platform), -check the [kube-arangodb documentation](https://arangodb.github.io/kube-arangodb/docs/how-to/set_license.html) -for more details on how to set a license key in a Kubernetes-managed deployment. -{{< /info >}} +- **Activate a deployment** (from v3.12.6 onward):\ + Customers receive license credentials composed of a client ID and a client secret. + You can use a command-line tool to activate deployments with these credentials, + either one-off or continuously. + + An activation is generally valid for two weeks and it is recommended to + renew the activation weekly. + + {{< info >}} + If you use the ArangoDB Kubernetes Operator (including the Data Platform), + check the [kube-arangodb documentation](https://arangodb.github.io/kube-arangodb/docs/how-to/set_license.html) + for more details on how to set a license key in a Kubernetes-managed deployment. + {{< /info >}} + +- **Apply a license key**:\ + Up to v3.12.5, customers received a license key directly and it was typically + valid for one year. From v3.12.6 onward, customers receive license credentials + instead. You can use a command-line tool to generate a license key using these + credentials, and the license key generally expires every two weeks. + + You can also activate a deployment instead of generating a license key, but + this requires an internet connection. For air-gapped environments for example, + the license key flow is required and the license key has a longer validity. + +How to activate a deployment or apply a license key to it, as well as how to +retrieve information about the current license via different interfaces is +described below. + +## Activate a deployment + +1. Download the Arango Data Platform CLI tool `arangodb_operator_platform` from + . + It is available for Linux, macOS, and Windows for the x86-64 as well as 64-bit ARM + architecture (e.g. `arangodb_operator_platform_linux_amd64`). + + It is recommended to rename the downloaded executable to + `arangodb_operator_platform` (with an `.exe` extension on Windows) and add it to + the `PATH` environment variable to make it available as a command in the system. + +2. Activate a deployment once using the Platform CLI tool. Point it to a running + ArangoDB deployment (running on `http://localhost:8529` in this example) and + supply the license credentials: + + ```sh + arangodb_operator_platform license activate --arango.endpoint http://localhost:8529 --license.client.id "your-corp" --license.client.secret "..." + ``` + + Unless authentication is disabled for the deployment, you need to additionally + supply either ArangoDB user credentials or a JWT session token and specify the + authentication method (case-sensitive): + + ```sh + # User credentials + arangodb_operator_platform license activate --arango.authentication Basic --arango.basic.username "root" --arango.basic.password "" ... + + # JWT session token + arangodb_operator_platform license activate --arango.authentication Token --arango.token "eyJh..." ... + ``` + +3. You can specify an activation interval to keep the Platform CLI tool running + and have it re-activate the deployment automatically, e.g. once a week: + + ```sh + arangodb_operator_platform license activate --license.interval 168h ... + ``` + +## Generate a license key + +1. Download the Arango Data Platform CLI tool `arangodb_operator_platform` from + . + It is available for Linux, macOS, and Windows for the x86-64 as well as 64-bit ARM + architecture (e.g. `arangodb_operator_platform_linux_amd64`). + + It is recommended to rename the downloaded executable to + `arangodb_operator_platform` (with an `.exe` extension on Windows) and add it to + the `PATH` environment variable to make it available as a command in the system. + +2. Create an inventory file using the Platform CLI tool. Point it to a running + ArangoDB deployment (running on `http://localhost:8529` in this example): + + ```sh + arangodb_operator_platform license inventory --arango.endpoint="http://localhost:8529" inventory.json + ``` + + Unless authentication is disabled for the deployment, you need to additionally + supply either ArangoDB user credentials or a JWT session token and specify the + authentication method (case-sensitive): + + ```sh + # User credentials + arangodb_operator_platform license inventory --arango.authentication Basic --arango.basic.username "root" --arango.basic.password "" ... + + # JWT session token + arangodb_operator_platform license inventory --arango.authentication Token --arango.token "eyJh..." ... + ``` + +3. Determine the ID of the ArangoDB deployment. You can find it in the inventory file + or call the [`GET /_admin/deployment/id` endpoint](../../develop/http-api/administration.md#get-the-deployment-id): + + ```sh + # User credentials + curl -uroot: http://localhost:8529/_admin/deployment/id + + # JWT session token + curl -H "Authorization: Bearer eyJh..." http://localhost:8529/_admin/deployment/id + + # Example result: + # {"id":"6172616e-676f-4000-0000-05c958168340"} + ``` + +4. Generate the license key using the deployment ID, the inventory file, and the + license credentials, and write it to a file: -## Apply a license + ```sh + arangodb_operator_platform license generate --deployment.id "6172616e-676f-4000-0000-05c958168340" --inventory inventory.json --license.client.id "your-corp" --license.client.secret "..." 2> license_key.txt + ``` -To use the Enterprise Edition, set the license key like so: +## Apply a license key {{< tabs "interfaces" >}} @@ -34,6 +143,7 @@ To use the Enterprise Edition, set the license key like so: 4. Expand the **PUT /_admin/license** sub-panel. 5. Click the **Try it out** button. 6. Paste the license key into the text area below the **Request body** label. + Make sure the key is wrapped in double quotes. 7. Make sure the license key is surrounded by double quote marks. 8. Click the **Execute** button. 9. Scroll down to **Server response** to check the result. diff --git a/site/content/arangodb/4.0/release-notes/version-3.12/api-changes-in-3-12.md b/site/content/arangodb/4.0/release-notes/version-3.12/api-changes-in-3-12.md index 16456aaa60..7c4681dd46 100644 --- a/site/content/arangodb/4.0/release-notes/version-3.12/api-changes-in-3-12.md +++ b/site/content/arangodb/4.0/release-notes/version-3.12/api-changes-in-3-12.md @@ -338,6 +338,15 @@ documentation. Also see [Authentication with access tokens](#authentication-with-access-tokens) for related API changes. +#### Deployment ID + +Introduced in: v3.12.6 + +Licenses are now bound to specific deployments. Each deployment has a unique +identifier that you can retrieve via a new +[`GET /_admin/deployment/id` endpoint](../../develop/http-api/administration.md#get-the-deployment-id) +in the HTTP API. + ### Endpoints augmented #### View API diff --git a/site/content/arangodb/4.0/release-notes/version-3.12/incompatible-changes-in-3-12.md b/site/content/arangodb/4.0/release-notes/version-3.12/incompatible-changes-in-3-12.md index 1fe5a31d18..ef6c6782af 100644 --- a/site/content/arangodb/4.0/release-notes/version-3.12/incompatible-changes-in-3-12.md +++ b/site/content/arangodb/4.0/release-notes/version-3.12/incompatible-changes-in-3-12.md @@ -994,6 +994,23 @@ more data, less file descriptors are used. - `segmentsBytesMax` increased from `5368709120` (5 GiB) to `8589934592` (8 GiB) - `segmentsBytesFloor` increased from `2097152` (2 MiB) to `25165824` (24 MiB) +## License management changes + +Introduced in: v3.12.6 + +Enterprise Edition license keys are now longer issued directly. Customers receive +license credentials instead. You can use a command-line tool to either activate +deployments or generate license keys using these credentials. An internet +connection is required for both. A generated key can subsequently be applied to +an air-gapped deployment without internet access. + +The activation and license keys are now typically short-lived and need to be +renewed every two weeks. Old license keys remain valid until their regular +expiration. + +See [Enterprise Edition License Management](../../operations/administration/license-management.md) +for details. + ## Added and removed consolidation options for inverted indexs and `arangosearch` Views Introduced in: v3.12.7 diff --git a/site/content/arangodb/4.0/release-notes/version-3.12/whats-new-in-3-12.md b/site/content/arangodb/4.0/release-notes/version-3.12/whats-new-in-3-12.md index e550246d34..ae6cc65e89 100644 --- a/site/content/arangodb/4.0/release-notes/version-3.12/whats-new-in-3-12.md +++ b/site/content/arangodb/4.0/release-notes/version-3.12/whats-new-in-3-12.md @@ -2509,6 +2509,27 @@ environment variable `NAME`. If there is an environment variable called `PID` or `TEMP_BASE_DIR`, then `@PID@` or `@TEMP_BASE_DIR@` is substituted with the value of the respective environment variable. +### License management changes + +Introduced: v3.12.6 + +The Enterprise Edition requires a license and customers used to receive a +license key directly. Going forward, customers receive license credentials +instead. You can use a command-line tool to either activate deployments or +generate license keys using these credentials. + +The activation and license keys are now typically short-lived and need to be +renewed every two weeks. Old license keys remain valid until their regular +expiration. + +Licenses are now bound to specific deployments. Each deployment has a unique +identifier that you can retrieve via a new +[`GET /_admin/deployment/id` endpoint](../../develop/http-api/administration.md#get-the-deployment-id) +in the HTTP API. + +See [Enterprise Edition License Management](../../operations/administration/license-management.md) +for details. + ### New consolidation algorithm for inverted indexes and `arangosearch` Views Introduced in: v3.12.7 diff --git a/site/content/data-platform/_index.md b/site/content/data-platform/_index.md index 82ab7ea1d2..f21e9731c9 100644 --- a/site/content/data-platform/_index.md +++ b/site/content/data-platform/_index.md @@ -5,6 +5,8 @@ weight: 1 description: >- The Arango Data Platform brings everything ArangoDB offers together to a single solution that you can deploy on-prem or use as a managed service +aliases: + - data-platform/get-started --- {{< tip >}} The Arango Data Platform is available as a pre-release. To get @@ -12,11 +14,12 @@ exclusive early access, [get in touch](https://arango.ai/contact-us/) with the Arango team. {{< /tip >}} -The Arango Data Platform is a **Kubernetes-native** technical infrastructure that acts as the umbrella -for hosting the entire ArangoDB offering of products. Built from the ground up for -cloud-native orchestration, the platform leverages the power of Kubernetes to make it easy -to deploy, scale, and operate the core ArangoDB database system along with any additional -AI solutions for GraphRAG, graph machine learning, data explorations, and more. You can +The Arango Data Platform is a **Kubernetes-native** technical infrastructure that +acts as the umbrella for hosting the entire ArangoDB offering of products. +Built from the ground up for cloud-native orchestration, the platform leverages +the power of Kubernetes to make it easy to deploy, scale, and operate the core +ArangoDB database system along with additional services and AI solutions for +GraphRAG, graph machine learning, data explorations, and more. You can run it on-premises or in the cloud yourself on top of Kubernetes to access all of the platform features with enterprise-grade automation and reliability. @@ -67,12 +70,39 @@ What you get with the AI Suite: The AI Suite requires a separate license. {{< /tip >}} +## Deployment options + +### Use the Arango Data Platform as a managed service + +You can request the Arango Data Platform as a managed service for the +[Arango Managed Platform (AMP)](../../amp/_index.md). + +[Get in touch](https://arango.ai/contact-us/) with the Arango team to learn more. + +### Self-host the Arango Data Platform + +You can set up and run the Arango Data Platform on-premises or in the cloud and +manage this deployment yourself. + +For a guide how to set up the Data Platform yourself, see +[Install the Arango Data Platform](installation.md). + +{{< info >}} +**Kubernetes-Native**: The Arango Data Platform is built specifically for Kubernetes +environments and relies on the official [ArangoDB Kubernetes Operator](https://arangodb.github.io/kube-arangodb/) +to provide automated deployment, scaling, and management capabilities. +{{< /info >}} + +## Recommended resources + {{< cards >}} +{{< comment >}} {{% card title="Get started with the Arango Data Platform" link="get-started/" %}} Deploy the core ArangoDB database system with Kubernetes orchestration. Optionally add AI Suite to turn data into an AI-powered knowledge engine. {{% /card %}} +{{< /comment >}} {{% card title="Features and Architecture" link="features/" %}} Explore the Kubernetes-native architecture, unified interface, and enterprise-grade capabilities of the Arango Data Platform. diff --git a/site/content/data-platform/get-started.md b/site/content/data-platform/get-started.md index c2f1795e1b..5143d1af1c 100644 --- a/site/content/data-platform/get-started.md +++ b/site/content/data-platform/get-started.md @@ -3,8 +3,8 @@ title: Get Started with the Arango Data Platform (v3.0) menuTitle: Get Started weight: 10 description: >- - The Arango Data Platform brings everything ArangoDB offers together to a single - solution that you can deploy on-prem or use as a managed service + Try out the Data Platform +draft: true --- {{< tip >}} The Arango Data Platform is available as a pre-release. To get @@ -12,198 +12,3 @@ exclusive early access, [get in touch](https://arango.ai/contact-us/) with the Arango team. {{< /tip >}} -The Arango Data Platform is a technical infrastructure that acts as the umbrella -for hosting the entire ArangoDB offering of products. The Platform makes it easy -to deploy and operate the core ArangoDB database system along with any additional -ArangoDB products for machine learning, data explorations, and more. You can -run it on-premises or in the cloud yourself on top of Kubernetes to access all -of the platform features. - -## Use the Arango Data Platform as a managed service - -You can request the Arango Data Platform as a managed service for the -[Arango Managed Platform (AMP)](../../amp/_index.md). -[Get in touch](https://arango.ai/contact-us/) with the Arango team to learn more. - -## Self-host the Arango Data Platform - -You can set up and run the Arango Data Platform on-premises or in the cloud and -manage this deployment yourself. - -{{< info >}} -**Kubernetes-Native**: The Arango Data Platform is built specifically for Kubernetes -environments and relies on the official [ArangoDB Kubernetes Operator](https://arangodb.github.io/kube-arangodb/) -to provide automated deployment, scaling, and management capabilities. -{{< /info >}} - -### Requirements for self-hosting - -- **Early access to the Arango Data Platform**: - [Get in touch](https://arango.ai/contact-us/) with the Arango team to get - exclusive early access to the pre-release of the Arango Data Platform & AI Suite. - -- **Kubernetes**: Orchestrates the selected services that comprise the - Arango Data Platform, running them in containers for safety and scalability. - - Set up a [Kubernetes](https://kubernetes.io/) cluster if you don't have one - available yet. - -- **kubectl**: A command line tool for communicating with a Kubernetes cluster's - control plane. - - Install [kubectl](https://kubernetes.io/docs/tasks/tools/#kubectl) for applying - specifications such as for creating the ArangoDB Core deployment, as well as - for checking pods, logs, etc. - -- **Helm**: A package manager for Kubernetes. - - You need to have [helm](https://helm.sh/docs/intro/install/) installed in order - to install the required certificate manager and the ArangoDB Kubernetes Operator - as part of the Platform setup. - -- **Container registry**: A repository for storing and accessing container images. - - You need to have a container registry for installing the images of the Platform - services. It can be a local registry. - -{{< comment >}} -- **Licenses**: If you want to use any paid features, you need to purchase the - respective packages. -{{< /comment >}} - -### Setup - -1. Obtain a zip package of the Arango Data Platform for the offline installation. - It includes helm charts, manifests, and blobs of the container image layers. - You also receive a package configuration file from the Arango team. - -2. Create a Kubernetes namespace for ArangoDB and a secret with your - Enterprise Edition license key. Substitute `` with the actual - license string: - - ```sh - kubectl create namespace arangodb - - kubectl create secret generic arango-license-key \ - --namespace arangodb \ - --from-literal=token-v2="" - ``` - -3. Install the certificate manager. You can check - for the available releases. - - ```sh - VERSION_CERT='1.18.2' # Use a newer version if available - helm repo add jetstack https://charts.jetstack.io - helm repo update - - helm upgrade --install cert-manager \ - --namespace cert-manager --create-namespace \ - --version "v${VERSION_CERT}" \ - jetstack/cert-manager \ - --set crds.enabled=true - ``` - -4. Install the [ArangoDB Kubernetes Operator](https://arangodb.github.io/kube-arangodb/) `kube-arangodb` with helm, - with options to enable webhooks, certificates, and the gateway feature. - - ```sh - VERSION_OPERATOR='1.3.0' # Use a newer version if available - - helm upgrade --install operator \ - --namespace arangodb \ - "https://github.com/arangodb/kube-arangodb/releases/download/${VERSION_OPERATOR}/kube-arangodb-enterprise-${VERSION_OPERATOR}.tgz" \ - --set "webhooks.enabled=true" \ - --set "certificate.enabled=true" \ - --set "operator.args[0]=--deployment.feature.gateway=true" \ - --set "operator.features.platform=true" \ - --set "operator.features.ml=true" \ - --set "operator.architectures={amd64}" # or {arm64} for ARM-based CPUs - ``` - -5. Create an `ArangoDeployment` specification for the ArangoDB Core. See the - [ArangoDeployment Custom Resource Overview](https://arangodb.github.io/kube-arangodb/docs/deployment-resource-reference.html) - and the linked reference. - - You need to enable the gateway feature by setting `spec.gateway.enabled` and - `spec.gateway.dynamic` to `true` in the specification. You also need to set - `spec.license` to the secret created earlier. Example for an ArangoDB cluster - deployment using version 3.12.5 with three DB-Servers and two Coordinators: - - ```yaml - apiVersion: "database.arangodb.com/v1" - kind: "ArangoDeployment" - metadata: - name: "platform-example" - spec: - mode: Cluster - image: "arangodb/enterprise:3.12.5" - gateway: - enabled: true - dynamic: true - gateways: - count: 1 - dbservers: - count: 3 - coordinators: - count: 2 - license: - secretName: arango-license-key - # ... - ``` - -6. Download the Arango Data Platform CLI tool `arangodb_operator_platform` from - . - It is available for Linux and macOS, for the x86-64 as well as 64-bit ARM - architecture (e.g. `arangodb_operator_platform_linux_amd64`). - - It is recommended to rename the downloaded executable to - `arangodb_operator_platform` and add it to the `PATH` environment variable - to make it available as a command in the system. - - The Platform CLI tool simplifies the further setup and later management of - the Platform's Kubernetes services. - -7. Import the zip package of the Arango Data Platform into the container registry. - Replace `platform.zip` with the file path of the offline installation package. - Replace `gcr.io/my-reg` with the address of your registry. - - ```sh - arangodb_operator_platform package import \ - --registry-docker-credentials \ - gcr.io/my-reg \ - ./platform.zip \ - platform.imported.yaml - ``` - -8. Install the package using the package configuration you received from the - Arango team (`platform.yaml`) and the configuration generated by the - previous command (`platform.imported.yaml`). These configurations are merged, - allowing for targeted upgrades and user-defined overrides. - - The package installation creates and enables various services, including - the unified web interface of the Platform. - - ```sh - arangodb_operator_platform --context arangodb package install \ - --platform.name platform-example \ - ./platform.yaml \ - ./platform.imported.yaml - ``` - -## Interfaces - -The Arango Data Platform uses a gateway to make all its services available via a -single port at the external address of the deployment. For a local deployment, -the base URL is `https://127.0.0.1:8529`. - -### Unified web interface - -You can access the Arango Data Platform web interface with a browser by appending -`/ui/` to the base URL, e.g. `https://127.0.0.1:8529/ui/`. - -### ArangoDB Core - -The HTTP API of the ArangoDB Core database system is available at the base URL. -For example, the URL of the Cursor API for submitting AQL queries (against the `_system` database) is -`https://127.0.0.1:8529/_db/_system/_api/cursor`. diff --git a/site/content/data-platform/installation.md b/site/content/data-platform/installation.md new file mode 100644 index 0000000000..2bdbde3db0 --- /dev/null +++ b/site/content/data-platform/installation.md @@ -0,0 +1,305 @@ +--- +title: Install the Arango Data Platform (v3.0) +menuTitle: Installation +weight: 13 +description: >- + How to set up the Data Platform on-premises, on hardware with internet access +--- +{{< tip >}} +The Arango Data Platform is available as a pre-release. To get +exclusive early access, [get in touch](https://arango.ai/contact-us/) with +the Arango team. +{{< /tip >}} + +## Requirements for self-hosting + +- **Early access to the Arango Data Platform**: + [Get in touch](https://arango.ai/contact-us/) with the Arango team to get + exclusive early access to the pre-release of the Arango Data Platform & AI Suite. + +- **Kubernetes**: Orchestrates the selected services that comprise the + Arango Data Platform, running them in containers for safety and scalability. + + Set up a [Kubernetes](https://kubernetes.io/) cluster if you don't have one + available yet. + +- **kubectl**: A command line tool for communicating with a Kubernetes cluster's + control plane. + + Install [kubectl](https://kubernetes.io/docs/tasks/tools/#kubectl) for applying + specifications such as for creating the ArangoDB Core deployment, as well as + for checking pods, logs, etc. + +- **Helm**: A package manager for Kubernetes. + + You need to have [helm](https://helm.sh/docs/intro/install/) installed in order + to install the required certificate manager and the ArangoDB Kubernetes Operator + as part of the Platform setup. + +- **Container registry**: A repository for storing and accessing container images. + + For offline installation such as for air-gapped environments, you need to have + a container registry that available in your environment. It can be a local + registry. It is needed for important and installing the images of the + Platform Suite. + +{{< comment >}} +- **Licenses**: If you want to use any paid features, you need to purchase the + respective packages. +{{< /comment >}} + +## On-premises setup + +#### Step 1: Get the installation files and information + +You receive a package configuration file and license credentials from the +Arango team. + +The Data Platform **package configuration** is a YAML file that defines which +services to install and their configurations. + +The **license credentials** are composed of a client ID and client secret that +you need to activate a deployment online or to generate license keys for +offline deployments (e.g. air-gapped). + +In case of an installation on hardware with internet access, everything needed +to install the services of the Platform Suite is downloaded during the setup. + +The internet access needs to be persistent for the license activation and +continuous renewal of the license. + +#### Step 2: Create a namespace + +Ensure `kubectl` is properly configured and can communicate with your +Kubernetes cluster, e.g. by running the following commands: + +```sh +kubectl cluster-info +kubectl get nodes +``` + +Create a Kubernetes namespace for ArangoDB and the Platform Suite resources. +The namespace used throughout this guide is called `arangodb`, but you can use +a different name. + +```sh +kubectl create namespace arangodb +``` + +#### Step 3: Create a secret for the license + +Create a Kubernetes secret with your license credentials. + +Substitute `` and `` +with the actual license credentials: + +```sh +kubectl create secret generic arango-license-key \ + --namespace arangodb \ + --from-literal=license-client-id="" \ + --from-literal=license-client-secret="" +``` + +You may run the following command to verify that the secret was created: + +```sh +kubectl get secret arango-license-key -n arangodb +``` + +Expected output: + +``` +NAME TYPE DATA AGE +arango-license-key Opaque 2 10s +``` + +#### Step 4: Install the certificate manager + +Install the certificate manager via the Jetstack Helm repository. + +The `cert-manager` creates and renews TLS certificates for WebHooks in the +ArangoDB Kubernetes Operator. + +You can check +for the available releases. + +```sh +VERSION_CERT='1.19.2' # Use a newer version if available + +helm repo add jetstack https://charts.jetstack.io +helm repo update + +helm upgrade --install cert-manager \ + --namespace cert-manager --create-namespace \ + --version "v${VERSION_CERT}" \ + jetstack/cert-manager \ + --set crds.enabled=true +``` + +You may use the following commands to wait for `cert-manager` to be ready and +verify that it is running: + +```sh +kubectl wait --for=condition=ready pod -l app.kubernetes.io/instance=cert-manager -n cert-manager --timeout=120s +kubectl get pods -n cert-manager +``` + +Expected output (`x` stands for varying letter or digit): + +``` +NAME READY STATUS RESTARTS AGE +cert-manager-xxxxxxxxxx-xxxxx 1/1 Running 0 20s +cert-manager-cainjector-xxxxxxxxxx-xxxxx 1/1 Running 0 20s +cert-manager-webhook-xxxxxxxxx-xxxxx 1/1 Running 0 20s +``` + +#### Step 5: Install the Operator + +Install the [ArangoDB Kubernetes Operator](https://arangodb.github.io/kube-arangodb/) +(`kube-arangodb`) with Helm. It is the core component that manages ArangoDB +deployments and the Data Platform. It watches for custom resources and creates +the necessary Kubernetes resources. + +You can find the latest release on GitHub: + + +Make sure set the the options as shown below to enable webhooks, certificates, +the gateway feature, and machine learning: + +```sh +VERSION_OPERATOR='1.3.3' # Use a newer version if available + +helm upgrade --install operator \ + --namespace arangodb \ + "https://github.com/arangodb/kube-arangodb/releases/download/${VERSION_OPERATOR}/kube-arangodb-enterprise-${VERSION_OPERATOR}.tgz" \ + --set "webhooks.enabled=true" \ + --set "certificate.enabled=true" \ + --set "operator.args[0]=--deployment.feature.gateway=true" \ + --set "operator.features.platform=true" \ + --set "operator.features.ml=true" \ + --set "operator.architectures={amd64}" # or {arm64} for ARM-based CPUs +``` + +You may use the following commands to wait for the operator to be ready and +verify it is running: + +```bash +kubectl wait --for=condition=ready pod -l app.kubernetes.io/name=kube-arangodb-enterprise -n arangodb --timeout=120s + +kubectl get deployment -n arangodb -l app.kubernetes.io/name=kube-arangodb-enterprise +kubectl get pods -n arangodb -l app.kubernetes.io/name=kube-arangodb-enterprise +``` + +Expected output (`x` stands for varying letter or digit): + +``` +NAME READY UP-TO-DATE AVAILABLE AGE +arango-operator-operator 1/1 1 1 45s + +NAME READY STATUS RESTARTS AGE +arango-operator-operator-xxxxxxxxxx-xxxxx 2/2 Running 0 45s +``` + +#### Step 6: Create a deployment + +Create an `ArangoDeployment` specification for ArangoDB. See the +[ArangoDeployment Custom Resource Overview](https://arangodb.github.io/kube-arangodb/docs/deployment-resource-reference.html) +and the linked reference. + +You need to enable the gateway feature by setting `spec.gateway.enabled` and +`spec.gateway.dynamic` to `true` in the specification. You also need to set +`spec.license` to the secret created earlier. Example for an ArangoDB cluster +deployment using version 3.12.7 with three DB-Servers and two Coordinators: + +```yaml +apiVersion: "database.arangodb.com/v1" +kind: "ArangoDeployment" +metadata: + name: "deployment-example" +spec: + mode: Cluster + image: "arangodb/enterprise:3.12.7" + gateway: + enabled: true + dynamic: true + gateways: + count: 1 + dbservers: + count: 3 + coordinators: + count: 2 + license: + secretName: arango-license-key + # ... +``` + +You can save the specification as a YAML file, e.g. `deployment.yaml`. + +Apply the specification and wait for the pods to be ready: + +```sh +kubectl apply -f deployment.yaml + +kubectl get pods --namespace arangodb --watch # Ctrl+C to stop watching +``` + +Given the above specification, you should eventually see pods with the following +names with a status of `Running`: +- `deployment-example-agnt-*` (3 Agents) +- `deployment-example-crdn-*` (2 Coordinators) +- `deployment-example-prmr-*` (3 DB-Servers) +- `deployment-example-gway-*` (1 Gateway) + +#### Step 7: Get the Data Platform CLI tool + +Download the Arango Data Platform CLI tool `arangodb_operator_platform` from +. +It is available for Linux, macOS, and Windows for the x86-64 as well as 64-bit ARM +architecture (e.g. `arangodb_operator_platform_linux_amd64`). + +It is recommended to rename the downloaded executable to +`arangodb_operator_platform` (with an `.exe` extension on Windows) and add it to +the `PATH` environment variable to make it available as a command in the system. + +The Platform CLI tool simplifies the further setup and later management of +the Platform's Kubernetes services. + +#### Step 8: Install the Data Platform package + +Install the package using the package configuration you received from the +Arango team (`platform.yaml`). + +The package installation creates and enables various services, including +the unified web interface of the Data Platform. + +Substitute `` and `` +with the actual license credentials and `./platform.yaml` with the path to the +package configuration file. + +```sh +arangodb_operator_platform --context arangodb package install \ + --license.client.id "" \ + --license.client.secret "" \ + --platform.name deployment-example \ + ./platform.yaml +``` + +It can take a while to run this command because it downloads the Platform Suite, +and in case of the AI Data Platform, also the AI Suite. + +## Interfaces + +The Arango Data Platform uses a gateway to make all its services available via a +single port at the external address of the deployment. For a local deployment, +the base URL is `https://127.0.0.1:8529`. + +### Unified web interface + +You can access the Arango Data Platform web interface with a browser by appending +`/ui/` to the base URL, e.g. `https://127.0.0.1:8529/ui/`. + +### ArangoDB Core + +The HTTP API of the ArangoDB Core database system is available at the base URL. +For example, the URL of the Cursor API for submitting AQL queries (against the +`_system` database) is `https://127.0.0.1:8529/_db/_system/_api/cursor`. diff --git a/site/content/data-platform/release-notes.md b/site/content/data-platform/release-notes.md index 70abf3625c..5ee1009e7c 100644 --- a/site/content/data-platform/release-notes.md +++ b/site/content/data-platform/release-notes.md @@ -73,9 +73,9 @@ ArangoDB Enterprise Edition v3.12.5. For AI Suite features in this release, see ### Arango Data Platform -The Arango Data Platform is a Kubernetes-native technical infrastructure that -brings together the entire ArangoDB offering into a unified solution. -See [Get Started with the Arango Data Platform](get-started.md). +The [Arango Data Platform](_index.md) is a Kubernetes-native technical +infrastructure that brings together the entire ArangoDB offering into a +unified solution. What's included: @@ -91,6 +91,6 @@ What's included: - **Unified web interface**: Single interface for accessing all Platform services and components. -The Platform can be extended with the [AI Suite](../ai-suite/_index.md) for +The Data Platform can be extended with the [AI Suite](../ai-suite/_index.md) for advanced capabilities like GraphRAG, GraphML, Graph Analytics, AQLizer, and more (requires separate license).