diff --git a/antora-playbook.yml b/antora-playbook.yml index ea9c91fc8..2596a71aa 100644 --- a/antora-playbook.yml +++ b/antora-playbook.yml @@ -12,6 +12,9 @@ content: - url: . branches: HEAD start_path: docs + - url: https://github.com/hazelcast/hazelcast-mono + branches: [master] + start_path: docs/rest ui: bundle: url: https://github.com/hazelcast/hazelcast-docs-ui/releases/latest/download/ui-bundle.zip #../hazelcast-docs-ui/build/ui-bundle.zip @@ -32,4 +35,5 @@ asciidoc: ucd: User Code Deployment extensions: - ./docs-tabs-library/tabs-block.js - - asciidoctor-kroki \ No newline at end of file + - asciidoctor-kroki + - ./lib/swagger-ui-block-macro.js \ No newline at end of file diff --git a/docs/modules/clients/partials/rest-deprecation.adoc b/docs/modules/clients/partials/rest-deprecation.adoc index 8b0a1cafe..34dcdd81f 100644 --- a/docs/modules/clients/partials/rest-deprecation.adoc +++ b/docs/modules/clients/partials/rest-deprecation.adoc @@ -1,5 +1,5 @@ [CAUTION] -.Deprecation Notice for the REST API +.Deprecation Notice for the Community Edition REST API ==== -The REST API has been deprecated and will be removed as of Hazelcast version 7.0. An improved version of this feature is under development. +The Community Edition REST API has been deprecated and will be removed as of Hazelcast version 7.0. An improved version of this feature is under development. For more info, see xref:maintain-cluster:enterprise-rest-api.adoc[REST API] ==== \ No newline at end of file diff --git a/docs/modules/cp-subsystem/pages/cp-subsystem.adoc b/docs/modules/cp-subsystem/pages/cp-subsystem.adoc index f0400e778..bcf81dbcd 100644 --- a/docs/modules/cp-subsystem/pages/cp-subsystem.adoc +++ b/docs/modules/cp-subsystem/pages/cp-subsystem.adoc @@ -273,3 +273,69 @@ group is not available anymore, no management tasks can be performed on the CP Subsystem. For instance, a new CP group cannot be created. In this case, the only solution is to wipe-out the whole CP Subsystem state by performing a force-reset. See xref:management.adoc#cp-subsystem-management-apis[CP Subsystem Management]. + +== Kubernetes + +IMPORTANT: We strongly encourage using xref:kubernetes:deploying-in-kubernetes.adoc#hazelcast-platform-operator-for-kubernetesopenshift[Hazelcast Platform Operator,window=_blank] for deployments into Kubernetes. If you choose to use Helm, use the official +`hazelcast/hazelcast-enterprise` xref:kubernetes:deploying-in-kubernetes.adoc#helm-chart[Helm Chart,window=_blank] +and configure within the limitations described in this section. + +Deployment of CP within Kubernetes is supported from Hazelcast Enterprise 5.5 and covers the +following scenarios when using xref:kubernetes:deploying-in-kubernetes.adoc#hazelcast-platform-operator-for-kubernetesopenshift[Hazelcast Platform Operator,window=_blank] or our `hazelcast/hazelcast-enterprise` xref:kubernetes:deploying-in-kubernetes.adoc#helm-chart[Helm Chart,window=_blank]. + +- Deployment: see xref:kubernetes:deploying-in-kubernetes.adoc[Deploying in Kubernetes,window=_blank]. +- Pause: scaling of pods to `0` +- Resume: scaling of pods back to the same number of pods defined at the point of _Deployment_ +- Rolling Update +- Spurious pod restarts + +We support 3, 5- and 7-CP member deployments under the constraints discussed in this section. + +The method by which deployment, pause, resume and rolling update are performed will vary according +to the way that CP was deployed. See xref:kubernetes:deploying-in-kubernetes.adoc[Deploying in Kubernetes,window=_blank] +for more information. + +[NOTE] +==== +* CP is only supported on Kubernetes with CP xref:cp-subsystem:configuration.adoc#persistence[persistence enabled,window=_blank]. +Hazelcast Enterprise is therefore a requirement. + +* The current limitation on CP in Kubernetes is that we do not support dynamic scaling of the cluster. +The number of members defined at the time of deployment is static and the CP members and CP group size +are expected to be equal to the total number of members (the cluster size) at the time of deployment. +Explicit removal and promotion of a CP member is not supported: Kubernetes has the responsibility of +restarting CP members should they be terminated. These restrictions will be removed in a subsequent +release of Hazelcast Enterprise. +==== + +We recommend setting xref:cp-subsystem:configuration.adoc#data-load-timeout-seconds[data-load-timeout-seconds,window=_blank] +to a value that spans the duration from when the first pod is running to when last pod is running and has completed its CP +intialisation procedure. This is particularly important if you intend to perform _resume_ scenarios. Currently the only way to determine when a CP member has completed its initialisation is to consult the logs. Therefore, we recommend the following to determine a reasonable value for `data-load-timeout-seconds`: + +1. Load CP with an amount of data that is representative of your production use case +2. Pause the cluster +3. Resume the cluster and determine the duration in seconds between when first pod in the `StatefulSet` running and when the last pod in the `StatefulSet` is running and outputted an `INFO` level log message that matches the pattern `CP restore completed...in` as described shortly. + +If you are using a log aggregation service and want to filter key startup events within CP, you can use the `INFO` level patterns emitted by `CPPersistenceServiceImpl` as detailed below. + +[cols="1,1,1"] +|=== +|Phrase|Example Match|Description + +|`CP restore starting...in` +|`CP restore starting...in /data/cp-data/0e667605-c650-42b7-9625-376a213008a6; Timeout(s): 120` +| Point at which the entire CP restoration process started. + +|`CP restore completed...in` +|`CP restore completed...in /data/cp-data/0e667605-c650-42b7-9625-376a213008a6; Took(ms): 50387` +| Point at which the entire CP restoration process completed, including notifying other CP members that the member has rejoined and the loading of its persisted data. + +|`CP restore starting(CPGroupId` +|`CP restore starting(CPGroupId{name='METADATA', seed=0, groupId=0})...in /data/persistence/cp/212561fb-c2d5-442a-a4e0-a863fdf7074b/METADATA@0@0` +| Point at which a particular CP Group's data started loading. + +|`CP restore completed(CPGroupId` +|`CP restore completed(CPGroupId{name='METADATA', seed=0, groupId=0})...in /data/persistence/cp/212561fb-c2d5-442a-a4e0-a863fdf7074b/METADATA@0@0; Took(ms): 29` +| Point at which a particular CP Group's data completed loading. + +|=== diff --git a/docs/modules/deploy/pages/versioning-compatibility.adoc b/docs/modules/deploy/pages/versioning-compatibility.adoc index e1ea8d08c..a751b2618 100644 --- a/docs/modules/deploy/pages/versioning-compatibility.adoc +++ b/docs/modules/deploy/pages/versioning-compatibility.adoc @@ -303,23 +303,13 @@ The following table lists the compatibilities between client and Platform/IMDG v |Go 0.x.y | -* Platform 5.x.y -* IMDG 4.x.y +* IMDG 3.6.x through 3.12.x |CLC 5.x.y | * Platform 5.x.y * IMDG 4.x.y -|CLC 1.x.y -| -* Platform 5.x.y -* IMDG 4.x.y - -|CLC 0.x.y -| -* Platform 5.x.y -* IMDG 4.x.y |=== diff --git a/docs/modules/maintain-cluster/images/rest-api-swagger-clicking-execute-button.png b/docs/modules/maintain-cluster/images/rest-api-swagger-clicking-execute-button.png new file mode 100644 index 000000000..254b49fb2 Binary files /dev/null and b/docs/modules/maintain-cluster/images/rest-api-swagger-clicking-execute-button.png differ diff --git a/docs/modules/maintain-cluster/images/rest-api-swagger-clicking-try-it-out-button.png b/docs/modules/maintain-cluster/images/rest-api-swagger-clicking-try-it-out-button.png new file mode 100644 index 000000000..927e58449 Binary files /dev/null and b/docs/modules/maintain-cluster/images/rest-api-swagger-clicking-try-it-out-button.png differ diff --git a/docs/modules/maintain-cluster/images/rest-api-swagger-expanding-an-endpoint.png b/docs/modules/maintain-cluster/images/rest-api-swagger-expanding-an-endpoint.png new file mode 100644 index 000000000..9af759712 Binary files /dev/null and b/docs/modules/maintain-cluster/images/rest-api-swagger-expanding-an-endpoint.png differ diff --git a/docs/modules/maintain-cluster/images/rest-api-swagger-listed-endpoints.png b/docs/modules/maintain-cluster/images/rest-api-swagger-listed-endpoints.png new file mode 100644 index 000000000..267028536 Binary files /dev/null and b/docs/modules/maintain-cluster/images/rest-api-swagger-listed-endpoints.png differ diff --git a/docs/modules/maintain-cluster/pages/enterprise-rest-api.adoc b/docs/modules/maintain-cluster/pages/enterprise-rest-api.adoc new file mode 100644 index 000000000..a09e7d6a6 --- /dev/null +++ b/docs/modules/maintain-cluster/pages/enterprise-rest-api.adoc @@ -0,0 +1,476 @@ += REST API +[[enterprise-rest-api]] +:page-enterprise: true + +Hazelcast provides a REST API that allows you to access your data +structures and cluster using the HTTP/HTTPS protocols. + +You can interact with the API using various tools and platforms such as cURL, REST clients (like Postman and Insomnia), or programming languages with HTTP request libraries or built-in support. The REST API also comes with a Swagger UI that offers an easy navigation and testing the API calls. See <>. + +In this section, we use cURL to provide the request examples. + +NOTE: REST API is only available in the {enterprise-product-name} Edition. +Hazelcast also offered a Community Edition REST API, but this has been deprecated and will be removed as of Hazelcast version 7.0. For more info, see xref:rest-api.adoc[Community Edition REST API]. + +== Enabling REST API + +REST service is **disabled** in the configuration by default; enable it as shown in the following configuration. + +NOTE: If you are using Hazelcast's xref:getting-started:editions.adoc#slim-distribution[slim distribution], you must add `hazelcast-enterprise-rest-{full-version}.jar` to your member's classpath to use the REST API. If you are working with the full distribution, this additional step is not needed. + +[tabs] +==== +XML:: ++ +-- +[source,xml] +---- + + + ... + + +---- +-- + +YAML:: ++ +[source,yaml] +---- +hazelcast: + rest: + enabled: true +---- +==== + +== Changing Default Port + +`8443` is the default port for REST API. To change it to another port, update the `rest` configuration as shown in the following example. + +[tabs] +==== +XML:: ++ +-- +[source,xml] +---- + + + 8080 + + +---- +-- + +YAML:: ++ +[source,yaml] +---- +hazelcast: + rest: + enabled: true + port: 8080 +---- +==== + +== Authentication + +You must secure the communication with REST API by configuring its authentication and access control. + +=== Configuring Authentication + +REST supports simple authentication based on username, password and user roles; see xref:security:simple-authentication.adoc[Simple Authentication]. To configure the simple authentication in the REST API, complete the following steps: + +* **#Enable REST API:#** +You need to enable the REST API. + +* **#Define A Security Realm:#** +You need to define the security realm within the rest configuration. + +* **#Enable Security:#** +You need to enable the security to use REST API. + +* **#Configure Rest Realm:#** +You need to introduce a REST realm as the authentication mechanism. This realm will handle user authentication using a simple method based on username and password. + +* **#Setup Users and Roles:#** +You should identify users and their roles within the REST realm. + +* **#Configure AccessControlService:#** +To configure `AccessControlService`, you should provide a factory class that creates an instance of the service. `AccessControlService` delegates authentication to the configured security realm. You can either create a custom factory class, or use the default implementation. For the default implementation, you can use `DefaultAccessControlServiceFactory`, to produce `DefaultAccessControlService`. Authorization decisions in this service are based on three predefined roles: `reader`, who can make requests via GET endpoints only; `writer`, who can make requests including GET, POST, and DELETE; and `admin`, who can make all requests and access admin-specific endpoints. + +The following configuration example includes all the steps listed above. + +[tabs] +==== +XML:: ++ +-- +[source,xml] +---- + + + restRealm + + + + + + + + admin + + + + <1> + com.hazelcast.internal.rest.access.DefaultAccessControlServiceFactory + + + + + +---- +-- + +YAML:: ++ +[source,yaml] +---- +hazelcast: + rest: + enabled: true + security-realm: restRealm + security: + enabled: true + realms: + - name: restRealm + authentication: + simple: + users: + - username: 'restuser' + password: 'restpassword' + roles: + - admin + access-control-service: <1> + factory-class-name: com.hazelcast.internal.rest.access.DefaultAccessControlServiceFactory +---- +==== +<1> To configure `AccessControlService`, you should provide a factory class that creates an instance of the service. `AccessControlService` delegates authentication to the configured security realm. You can either create a custom factory class, or use the default implementation. For the default implementation, you can use `DefaultAccessControlServiceFactory`, to produce `DefaultAccessControlService`. Authorization decisions in this service are based on three predefined roles: `reader`, who can make requests via GET endpoints only; `writer`, who can make requests including GET, POST, and DELETE; and `admin`, who can make all requests and access admin-specific endpoints. + +NOTE: Besides the simple authentication, you can also use other authentication types such as LDAP. See xref:security:security-realms.adoc#authentication-configuration[Authentication Configuration] on how to configure different types within a security realm. + +=== Authentication Process + +To authenticate to the REST API, the REST client must obtain a token. See the <> for details. The token request requires a username and password and the role(s) assigned to the user are included in the token as claims. You can use the token until it expires. You use the token at the `Authorization` header for each subsequent REST API call so that the call is authorized appropriately. If a valid token is not included in the header, the API will respond with a `401 Unauthorized` error. + +== HTTPS Support + +You can configure TLS/SSL in the REST API. We use Spring Boot underneath to enable Spring web services, and all the TLS/SSL related options correspond to the underlying Spring Boot TLS/SSL support capabilities. + +The TLS/SSL configuration of the REST server is completely different from Hazelcast TLS/SSL configuration which has different configuration settings. +The configuration settings are available to set up TLS/SSL as shown in +the below declarative example: + +[tabs] +==== +XML:: ++ +-- +[source,xml] +---- + + + + NEED + TLS_RSA_WITH_AES_128_CBC_SHA, TLS_RSA_WITH_AES_128_CBC_SHA256 + myKeyAlias + myKeyPassword + /path/to/keystore + myKeyStorePassword + JKS + SUN + /path/to/truststore + myTrustStorePassword + JKS + SUN + TLSv1.2, TLSv1.3 + TLS + /path/to/certificate + /path/to/certificate-key + /path/to/trust-certificate + /path/to/trust-certificate-key + + + +---- +-- + +YAML:: ++ +[source,yaml] +---- +hazelcast: + rest: + enabled: true + ssl: + enabled: true + client-auth: NEED + ciphers: TLS_RSA_WITH_AES_128_CBC_SHA, TLS_RSA_WITH_AES_128_CBC_SHA256 + enabled-protocols: TLSv1.2, TLSv1.3 + key-alias: myKeyAlias + key-password: myKeyPassword + key-store: /path/to/keystore + key-store-password: myKeyStorePassword + key-store-type: JKS + key-store-provider: SUN + trust-store: /path/to/truststore + trust-store-password: myTrustStorePassword + trust-store-type: JKS + trust-store-provider: SUN + protocol: TLS + certificate: /path/to/certificate + certificate-key: /path/to/certificate-key + trust-certificate: /path/to/trust-certificate + trust-certificate-key: /path/to/trust-certificate-key +---- +==== + +== JWT Based Authorization + +After a successful authentication by making request to the token endpoint (see <>), you will receive a short-living JWT token with assigned role names as a claim for authorization checks in subsequent REST calls. + +Token issued by one member is not trusted by other members. + +Tokens are valid for 15 minutes by default. You can update the expiry duration using the `token-validity-seconds` configuration element as shown in the following example. + +[tabs] +==== +XML:: ++ +-- +[source,xml] +---- + + + 300 + + +---- +-- + +YAML:: ++ +[source,yaml] +---- +hazelcast: + rest: + enabled: true + token-validity-seconds: 300 +---- +==== + +[#obtaining-a-token] +== Obtaining a Token + +To obtain a token, you send a `POST` request to the token endpoint at `/hazelcast/rest/api/v1/token`. The request must include JSON-formatted `username` and `password` which you <>. If the authentication is successful, you get a response which contains a valid token for the expiry duration. + +Example request using cURL: + +[source,shell] +---- +curl -X 'POST' \ + 'http://localhost:8443/hazelcast/rest/api/v1/token' \ + -H 'Content-Type: application/json' \ + -d '{ + "username": "restuser", + "password": "restpassword" +}' +---- + +It returns the following response if successful: + +[source,json] +---- +{ + "token": "" +} +---- + +It returns the following response if the provided credentials are incorrect: + +[source,json] +---- +{ + "statusCode": 401, + "message": "Username/password provided don't match the expected values." +} +---- + +== Accessing the Swagger UI + +Hazelcast REST API's Swagger UI provides information about each endpoint, including required parameters, request and response structures and types, potential response codes, and example responses. You can use this UI to easily navigate and test different API calls directly from the interface. To access it: + +. Enable the REST API. +. Start a Hazelcast member. +. Go to `http://:/swagger-ui/index.html` where and are the running member's IP address/hostname and port, respectively. + +The following is an example view: + +image::rest-api-swagger-listed-endpoints.png[] + +On the Swagger page, each endpoint is listed with a caret icon on the right side. Click the caret icon to expand the details for an endpoint. For this example, let's expand the `GET /hazelcast/rest/api/v1/cluster` endpoint. + +image::rest-api-swagger-expanding-an-endpoint.png[] + +After expanding the endpoint, let's proceed to send a request. Click the `Try it out` button, enter the parameters (if any). There are no parameters for this example. + +image::rest-api-swagger-clicking-execute-button.png[] + +Click the `Execute` button to send the request. You can see the response in the **Server response** section as shown below. You can also see the executed cURL command in the **Curl** section. + +image::rest-api-swagger-clicking-try-it-out-button.png[] + +== GET/POST/DELETE HTTP Request Examples + +All the requests in the REST API can return one of the following response types. + +* Successful void/boolean response which does not have a body. + +* Successful response which returns data in JSON format. For example: + +[source,json] +---- +{ + "nodeState": "ACTIVE", + "clusterState": "ACTIVE", + "numberOfMembers": 1 +} +---- + +* Error response in JSON format. For example: + +[source,json] +---- +{ + "statusCode": 400, + "message": "Please provide a valid value." +} +---- + +=== Retrieving Cluster Status + +You can send a `GET` request to the endpoint at `/hazelcast/rest/api/v1/cluster` to retrieve the status of your cluster. + +Example request using cURL: + +[source,shell] +---- +curl -X 'GET' \ + 'http://localhost:8443/hazelcast/rest/api/v1/cluster' \ + -H 'Authorization: Bearer ' +---- + +It returns the following response if successful: + +[source,json] +---- +{ + "members": [ + { + "address": "[192.168.0.24]:5701", + "liteMember": false, + "localMember": true, + "uuid": "3d8b9c35-a35f-461a-9e7f-d64e3f1f0f03", + "memberVersion": "5.5.0" + } + ], + "clientCount": 0, + "allConnectionCount": 0, + "state": "ACTIVE", + "version": "5.5" +} +---- + +=== Retrieving Cluster State + +You can send a `GET` request to the endpoint at `/hazelcast/rest/api/v1/cluster/state` to retrieve the state of your cluster. + +Example request using cURL: + +[source,shell] +---- +curl -X 'GET' \ + 'http://localhost:8443/hazelcast/rest/api/v1/cluster/state' \ + -H 'Authorization: Bearer ' +---- + +It returns the following response if successful: + +[source,json] +---- +{ + "state": "ACTIVE" +} +---- + +=== Changing Cluster State + +You can send a `POST` request to the endpoint at `/hazelcast/rest/api/v1/cluster/state` to change the state of your cluster. You must provide the new state within the request body in the JSON format. Valid states are `ACTIVE`, `NO_MIGRATION`, `FROZEN`, `PASSIVE`. + +Example request using cURL: + +[source,shell] +---- +curl -X 'POST' \ + 'http://localhost:8443/hazelcast/rest/api/v1/cluster/state' \ + -H 'Authorization: Bearer Bearer ' \ + -H 'Content-Type: application/json' \ + -d '{ + "state": "PASSIVE" +}' +---- + +* It returns 200 response without body if successful. +* It returns 400 response if provided state is not a valid cluster state. For example: + +[source,json] +---- +{ + "statusCode": 400, + "message": "FOOBAR is not a valid ClusterState. Please provide one of the valid values: [ACTIVE, NO_MIGRATION, FROZEN, PASSIVE]" +} +---- + +=== Destroying a CP Group + +You can send a `DELETE` request to the endpoint at `/hazelcast/rest/api/v1/cp/groups/{group-name}` to unconditionally destroy the given active CP group. + +Example request using cURL: + +[source,shell] +---- +curl -X 'DELETE' \ + 'http://localhost:8443/hazelcast/rest/api/v1/cp/groups/my-group' \ + -H 'Authorization: Bearer Bearer ' +---- + +* It returns 200 response without body if successful. +* It returns 400 response if you try to destroy METADATA group. For example: + +[source,json] +---- +{ + "statusCode": 400, + "message": "Meta data CP group [METADATA] cannot be destroyed!" +} +---- + +* It returns 500 response if CP subsystem is not enabled: + +[source,json] +---- +{ + "statusCode": 500, + "message": "CP Subsystem is not enabled!" +} +---- diff --git a/docs/modules/maintain-cluster/pages/rest-api-swagger.adoc b/docs/modules/maintain-cluster/pages/rest-api-swagger.adoc new file mode 100644 index 000000000..1a35ad223 --- /dev/null +++ b/docs/modules/maintain-cluster/pages/rest-api-swagger.adoc @@ -0,0 +1,5 @@ += Swagger UI for REST API +:page-enterprise: true +:page-layout: swagger + +swagger_ui::{attachmentsdir}/api-docs.yaml[] diff --git a/docs/modules/maintain-cluster/pages/rest-api.adoc b/docs/modules/maintain-cluster/pages/rest-api.adoc index 9b9a89cc1..b37535594 100644 --- a/docs/modules/maintain-cluster/pages/rest-api.adoc +++ b/docs/modules/maintain-cluster/pages/rest-api.adoc @@ -1,4 +1,4 @@ -= REST API += {open-source-product-name} REST API [[rest-api]] include::clients:partial$rest-deprecation.adoc[] diff --git a/docs/modules/maintain-cluster/pages/shutdown.adoc b/docs/modules/maintain-cluster/pages/shutdown.adoc index aa65c6ee9..6a45c9d69 100644 --- a/docs/modules/maintain-cluster/pages/shutdown.adoc +++ b/docs/modules/maintain-cluster/pages/shutdown.adoc @@ -21,7 +21,7 @@ bin/hz-cluster-admin -a
-c -o shutdown REST API:: + -- -include::clients:partial$rest-deprecation.adoc[] +CAUTION: The REST API has been deprecated and will be removed as of Hazelcast version 7.0. An improved version of this feature is under development. NOTE: To use the REST API to shut down a cluster, you must first xref:clients:rest.adoc[enable it]. diff --git a/docs/modules/maintain-cluster/partials/nav.adoc b/docs/modules/maintain-cluster/partials/nav.adoc index 37435ce09..fdc4602ef 100644 --- a/docs/modules/maintain-cluster/partials/nav.adoc +++ b/docs/modules/maintain-cluster/partials/nav.adoc @@ -5,5 +5,6 @@ ** xref:maintain-cluster:member-attributes.adoc[Filtering Members with Attributes] ** xref:maintain-cluster:lite-members.adoc[Lite Members] ** xref:maintain-cluster:shutdown.adoc[Shutting Down] -** xref:maintain-cluster:rest-api.adoc[REST API] +** xref:maintain-cluster:enterprise-rest-api.adoc[REST API] +*** xref:maintain-cluster:rest-api.adoc[Community Edition REST API] ** xref:management:cluster-utilities.adoc[Cluster Utilities] diff --git a/docs/modules/migrate/pages/data-migration-tool.adoc b/docs/modules/migrate/pages/data-migration-tool.adoc index d17f4ad6a..80eb90663 100644 --- a/docs/modules/migrate/pages/data-migration-tool.adoc +++ b/docs/modules/migrate/pages/data-migration-tool.adoc @@ -40,7 +40,7 @@ At a high-level, the migration process is as follows: == Get the DMT -You can download the DMT from https://viridian.hazelcast.com/[Hazelcast {hazelcast-cloud}^] or the https://hazelcast.com/[Hazelcast web site^]. +You can download the DMT from https://cloud.hazelcast.com/[Hazelcast {hazelcast-cloud}^] or the https://hazelcast.com/[Hazelcast web site^]. Once downloaded, extract the DMT package to a location in your folder structure. The DMT package includes the following: diff --git a/docs/modules/tiered-storage/pages/overview.adoc b/docs/modules/tiered-storage/pages/overview.adoc index f25b998ae..93fa880c1 100644 --- a/docs/modules/tiered-storage/pages/overview.adoc +++ b/docs/modules/tiered-storage/pages/overview.adoc @@ -38,6 +38,12 @@ This means that, if an entry is on the disk, it is relocated to the memory insid As more and more entries are relocated to the in-memory region of the HybridLog, the memory space occupied by the unreachable entries on disk is reclaimed. This reclamation is done by a compactor running synchronously with IMap operations on the same partition. +After a cluster restart, Tiered Storage ensures seamless restoration of data within +the configured maps from files stored on the designated device. +This data restoration requires graceful shutdowns using the `HazelcastInstance.shutdown()` method, while the cluster is in the `PASSIVE` state; +see xref:maintain-cluster:shutdown.adoc#graceful-shutdown[Graceful Shutdown] and xref:maintain-cluster:cluster-member-states.adoc#cluster-states[Cluster States]. +Failure to do so may lead to restart failures. The maps backed by Tiered Storage maintain consistent state synchronization, seamlessly restoring data from files upon restart. + == Supported Devices Hazelcast supports only non-volatile memory express (NVMe) local SSD devices for Tiered Storage. @@ -47,8 +53,6 @@ While HDDs and some network storage options work with the same file abstraction - Tiered Storage currently only supports Hazelcast IMap data structure. -- Data recovery from persisted data is not supported. When a Hazelcast member has Tiered Storage enabled and it fails or shuts down, you cannot use the local Tiered Storage device files for data recovery. - - Time-to-live (TTL) expiration is not supported by maps backed by Tiered Storage. This means that methods, such as `IMap.put`, throw `UnsupportedOperationException` if a TTL value is provided. If the default TTL setting is present in the map configuration, `InvalidConfigurationException` is thrown during the member startup. diff --git a/lib/swagger-ui-block-macro.js b/lib/swagger-ui-block-macro.js new file mode 100644 index 000000000..6cca736ef --- /dev/null +++ b/lib/swagger-ui-block-macro.js @@ -0,0 +1,20 @@ +const buildSwaggerUi = ({ specUrl }) => ` + + +` + +function blockSwaggerUiMacro ({ file }) { + return function () { + this.process((parent, specUrl) => { + specUrl = `${specUrl}` + const contentScripts = buildSwaggerUi({ specUrl }) + return this.createBlock(parent, 'pass', contentScripts) + }) + } +} + +function register (registry, context) { + registry.blockMacro('swagger_ui', blockSwaggerUiMacro(context)) +} + +module.exports.register = register diff --git a/package.json b/package.json index a4c97dbe0..7136b85dd 100644 --- a/package.json +++ b/package.json @@ -14,10 +14,14 @@ "devDependencies": { "@antora/cli": "^3.1.1", "@antora/site-generator": "^3.1.1", + "@asciidoctor/core": "^2.0.0", + "@djencks/antora-aggregate-collector": "^0.1.0-beta.1", "@jcahills/antora-link-checker": "^1.0.1", + "asciidoctor-kroki": "^0.10.0", "ngrok": "^3.3.0", - "serve": "^11.3.2", - "@asciidoctor/core": "^2.0.0", - "asciidoctor-kroki": "^0.10.0" + "serve": "^11.3.2" + }, + "dependencies": { + "redoc": "^2.1.4" } }