New license management using credentials to activate deployments or generate license keys

Author: Simran-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
+
+<small>Introduced in: v3.12.6</small>
+
+```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

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).

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
+   <https://github.com/arangodb/kube-arangodb/releases>.
+   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
+   <https://github.com/arangodb/kube-arangodb/releases>.
+   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.

site/content/arangodb/3.12/release-notes/version-3.12/api-changes-in-3-12.md

@@ -336,6 +336,15 @@ documentation.
 Also see [Authentication with access tokens](#authentication-with-access-tokens)
 for related API changes.
 
+#### Deployment ID
+
+<small>Introduced in: v3.12.6</small>
+
+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

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
+
+<small>Introduced in: v3.12.6</small>
+
+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.
+
 ## HTTP RESTful API
 
 ### JavaScript-based traversal using `/_api/traversal` removed

site/content/arangodb/3.12/release-notes/version-3.12/whats-new-in-3-12.md

@@ -2452,6 +2452,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
+
+<small>Introduced: v3.12.6</small>
+
+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.
+
 ## Client tools
 
 ### Protocol aliases for endpoints