From c94ff26dc2dfb2111033954a5e7cd655c06ad82d Mon Sep 17 00:00:00 2001 From: "QUALISYSTEMS\\nahum-t" Date: Mon, 27 Jul 2026 12:04:12 +0300 Subject: [PATCH] Track 3 Tier 3: fill remaining stale how-to gaps - Config keys: AbstractResolutionStrategy, NetworkRouteResolverStrategy (Legacy/Optimistic, off by default, 2026.1) - TestShell API: persistent reservations via UpdateReservationEndTime(reservationId, isPersistent, endTime) - Type-ahead Owner/Permitted-Users pickers in the Reserve dialog for large domains - PostgreSQL database support (Beta) in system requirements / DB selection - Assembly Lab: save-as-blueprint preserves routes with non-resource endpoints Grounded in server code + integration tests; adversarially verified. Co-Authored-By: Claude Opus 4.8 (1M context) --- .../abstract-resources.md | 32 +++++++++++++++++ ...vity-management-and-route-configuration.md | 35 +++++++++++++++++++ .../testshell-api.md | 28 +++++++++++++++ .../select-database-type/index.md | 4 +++ .../cs-system-requirements/database-prereq.md | 15 +++++++- docs/portal/blueprints/blueprint-catalog.md | 4 +++ docs/portal/sandboxes/creating-sandboxes.md | 4 +++ .../save-sandbox-as-blueprint.md | 6 +++- 8 files changed, 126 insertions(+), 2 deletions(-) diff --git a/docs/admin/setting-up-cloudshell/cloudshell-configuration-options/customer-configuration-keys-repository/abstract-resources.md b/docs/admin/setting-up-cloudshell/cloudshell-configuration-options/customer-configuration-keys-repository/abstract-resources.md index 73aab174be..773b91fa9b 100644 --- a/docs/admin/setting-up-cloudshell/cloudshell-configuration-options/customer-configuration-keys-repository/abstract-resources.md +++ b/docs/admin/setting-up-cloudshell/cloudshell-configuration-options/customer-configuration-keys-repository/abstract-resources.md @@ -62,4 +62,36 @@ sidebar_position: 1 2021.1 and above + + +## Abstract resource resolution strategy +When CloudShell reserves a sandbox, it resolves each abstract resource requirement to a concrete resource. By default (`Legacy`), all abstract resolution runs under a single global lock, so concurrent reservation requests are handled one at a time. Setting the strategy to `Optimistic` enables an opt-in solver that resolves abstract requirements outside that global lock and validates the result before committing, improving throughput when many reservations run concurrently. On `Legacy`, resolution behavior is unchanged. After changing this key, restart the CloudShell Server for it to take effect. + + + + + + + + + + + + + + + + + + + + + + + + + + + +
Key``
Possible valuesLegacy/Optimistic
Where to add/change`customer.config` CloudShell Server installation directory (requires a CloudShell Server service restart)
Default valueLegacy
Affected CloudShell ComponentCloudShell Server
Version2026.1 and above
\ No newline at end of file diff --git a/docs/admin/setting-up-cloudshell/cloudshell-configuration-options/customer-configuration-keys-repository/connectivity-management-and-route-configuration.md b/docs/admin/setting-up-cloudshell/cloudshell-configuration-options/customer-configuration-keys-repository/connectivity-management-and-route-configuration.md index f377266df2..571d881176 100644 --- a/docs/admin/setting-up-cloudshell/cloudshell-configuration-options/customer-configuration-keys-repository/connectivity-management-and-route-configuration.md +++ b/docs/admin/setting-up-cloudshell/cloudshell-configuration-options/customer-configuration-keys-repository/connectivity-management-and-route-configuration.md @@ -64,6 +64,41 @@ sidebar_position: 4 +## Select the network route resolution strategy + +By default, CloudShell resolves network routes under a single, server-wide lock, so concurrent route resolutions run one at a time. Setting this key to `Optimistic` enables an opt-in resolver that performs the route-resolution work outside that global lock and commits the result using optimistic concurrency (it validates and, if another reservation claimed a needed resource in the meantime, retries). This allows multiple route resolutions to proceed in parallel, which can increase route-resolution throughput when many reservations resolve routes at the same time. The default `Legacy` strategy preserves the original single-lock behavior. Any unrecognized value falls back to `Legacy`. + +Changing this key requires a restart of the CloudShell Server. + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
Key``
Possible valuesLegacy/Optimistic
Where to add/change`customer.config` CloudShell Server installation directory
Default valueLegacy
Affected CloudShell ComponentCloudShell Server
Version2026.1 and above
+ ## Enable regular users to change their email address diff --git a/docs/api-guide/shell-dev-blueprint-design-api/testshell-api.md b/docs/api-guide/shell-dev-blueprint-design-api/testshell-api.md index e5956c0d8d..1493bc144a 100644 --- a/docs/api-guide/shell-dev-blueprint-design-api/testshell-api.md +++ b/docs/api-guide/shell-dev-blueprint-design-api/testshell-api.md @@ -50,4 +50,32 @@ Once the scenario is created, it can be run automatically. - Some actions that are possible in Resource Manager and in CloudShell Portal are not supported in TestShell API. For example, you cannot create and edit a blueprint using TestShell API. There are other solutions for that, such as creating and editing a sandbox and then saving it as a blueprint or importing a Quali package. - Many operations have two versions, a "single” version and a "bulk” version. For example, it is possible to create a single resource using the "CreateResource" method or to create many resources at once using the "CreateResources” operation. This is not always the fastest way performance-wise, but it is sometime easier to write and edit. The bulk operation usually gets a matrix as an input, and sometimes has special rules (such as the fact you cannot have the sub-resource creation line before the resource line). - Any function that requires a resource full path can also get the resource name without the folders it is located in. +::: + +## Working with persistent reservations + +In addition to standard timed reservations, TestShell API can work with **persistent reservations** (persistent sandboxes). A persistent sandbox does not have a fixed end time and remains reserved until you explicitly end it or convert it back to a timed reservation. + +Persistence is controlled through the **`UpdateReservationEndTime`** method rather than a dedicated create method. The method takes the following parameters: + +- **`reservationId`** – The ID of the reservation to update. +- **`isPersistent`** – A `Yes`/`No` value that sets whether the sandbox is persistent. +- **`endTime`** – The new end time for the reservation. + +### Making a reservation persistent + +To convert an existing timed reservation into a persistent one, call `UpdateReservationEndTime` with `isPersistent` set to `Yes`. Since a persistent sandbox has no fixed end time, the `endTime` value is not applied and can be left empty. + +Note the following behavior: + +- A sandbox that is already persistent cannot be set to persistent again. Attempting to do so returns an error, because a persistent sandbox's end time cannot be changed. + +### Converting a persistent reservation back to a timed reservation + +To turn a persistent sandbox back into a standard timed reservation, call `UpdateReservationEndTime` with `isPersistent` set to `No` and provide a valid `endTime`. The end time must be later than the current time; otherwise the call fails. + +After this operation, the reservation is no longer persistent and ends at the specified end time. + +:::note +The `CreateReservation` and `CreateImmediateReservation` methods do not include a persistence flag. To make a sandbox persistent, first create the reservation and then update it with `UpdateReservationEndTime` as described above. The exact method availability may depend on your CloudShell version. ::: \ No newline at end of file diff --git a/docs/install-configure/cloudshell-suite/complete-install/install-cloudshell/select-database-type/index.md b/docs/install-configure/cloudshell-suite/complete-install/install-cloudshell/select-database-type/index.md index 6501a7c044..9a36070450 100644 --- a/docs/install-configure/cloudshell-suite/complete-install/install-cloudshell/select-database-type/index.md +++ b/docs/install-configure/cloudshell-suite/complete-install/install-cloudshell/select-database-type/index.md @@ -24,6 +24,10 @@ For more information, see [New Job Scheduling Architecture](../../../new-jss-ins :::tip For high load systems, we recommend using an SQL Server that is hosted on a separate machine (not Quali Server). ::: + + :::note PostgreSQL (Beta) + Starting with CloudShell 2025.1, PostgreSQL is available as an alternative relational database backend to SQL Server, **in Beta (evaluation only)**. Contact Quali Support for evaluation access. For details, see [Database Prerequisites](../../../../cs-system-requirements/database-prereq.md#postgresql-database-support-beta). + ::: 3. Select the MongoDB to use (create on-the-fly on the Quali Server or use an external MongoDB instance/cluster). CloudShell officially supports Mongo 4.2 and above (Community and Enterprise editions). diff --git a/docs/install-configure/cs-system-requirements/database-prereq.md b/docs/install-configure/cs-system-requirements/database-prereq.md index 07e29208e2..89b1b85978 100644 --- a/docs/install-configure/cs-system-requirements/database-prereq.md +++ b/docs/install-configure/cs-system-requirements/database-prereq.md @@ -4,7 +4,7 @@ sidebar_position: 5 # Database Prerequisites -CloudShell applications can work with MS SQL database. +CloudShell applications work with Microsoft SQL Server as the primary relational database backend. Starting with CloudShell 2025.1, **PostgreSQL is also available as an alternative relational database backend, in Beta**. For details, see [PostgreSQL database support (Beta)](#postgresql-database-support-beta) below. ## MongoDB database permissions and installation requirements @@ -92,6 +92,19 @@ Installation instructions: Quali Server, SQL server or SQL Express, and the CloudShell applications can be installed on the same machine, or on separate machines in the same network. +## PostgreSQL database support (Beta) + +:::note Beta +Starting with CloudShell 2025.1, PostgreSQL is supported as an alternative relational database backend, **in Beta (evaluation only)**. It is intended for evaluation and is not yet recommended for production deployments. Microsoft SQL Server remains the default, fully supported relational database backend. +::: + +To evaluate CloudShell on PostgreSQL, or to migrate an existing CloudShell SQL Server database to PostgreSQL, **contact Quali Support for evaluation access**. Quali Support will provide the required components, supported-version details, and setup and migration guidance for your CloudShell version. + +Notes: + +- PostgreSQL replaces only the SQL Server relational backend. CloudShell still uses MongoDB for the data described in [Select the Database Type](../cloudshell-suite/complete-install/install-cloudshell/select-database-type/index.md), regardless of whether the relational backend is SQL Server or PostgreSQL. +- Because this feature is in Beta, the exact supported PostgreSQL versions and configuration steps depend on your CloudShell version and are provided by Quali Support as part of evaluation access. + ## Additional requirements - The **Distributed Transaction Coordinator** service must be running on the database server with specific configurations, as detailed in the Troubleshooting Guide: diff --git a/docs/portal/blueprints/blueprint-catalog.md b/docs/portal/blueprints/blueprint-catalog.md index f68ca53296..c59d07fda5 100644 --- a/docs/portal/blueprints/blueprint-catalog.md +++ b/docs/portal/blueprints/blueprint-catalog.md @@ -168,6 +168,10 @@ Blueprints of type ‘view’ cannot be reserved. 3. Instead of changing the owner of the sandbox, you can permit additional users to use the sandbox. Click the Permitted Users section and select the users you wish to add. + :::note + In the Owner and Permitted Users pickers, the list of users is scoped to your current domain. When the domain has a large number of users, the picker loads users incrementally instead of loading them all up front - start typing a user name to search for and add users that are not shown in the initial list. + ::: + 4. To prevent users from ending the sandbox before its scheduled end time, enable Termination Protection. This option ensures your sandbox isn't ended accidentally or prematurely. And when you are ready to manually end the sandbox, disable the option in the sandbox's properties window and then end it. 5. You can configure CloudShell to send email notifications to the owner of the sandbox and permitted users. diff --git a/docs/portal/sandboxes/creating-sandboxes.md b/docs/portal/sandboxes/creating-sandboxes.md index d79f172952..bc2275268d 100644 --- a/docs/portal/sandboxes/creating-sandboxes.md +++ b/docs/portal/sandboxes/creating-sandboxes.md @@ -65,6 +65,10 @@ Blueprints of type ‘view’ cannot be reserved. 3. Instead of changing the owner of the sandbox, you can permit additional users to use the sandbox. Click the **Permitted Users** section and select the users you wish to add. + :::note + In the **Owner** and **Permitted Users** pickers, the list of users is scoped to your current domain. When the domain has a large number of users, the picker loads users incrementally instead of loading them all up front - start typing a user name to search for and add users that are not shown in the initial list. + ::: + 4. To prevent users from ending the sandbox before its scheduled end time, enable **Termination Protection**. This option ensures your sandbox isn't ended accidentally or prematurely. And when you are ready to manually end the sandbox, disable the option in the sandbox's properties window and then end it. 5. You can configure CloudShell to send email notifications to the owner of the sandbox and permitted users. diff --git a/docs/portal/sandboxes/sandbox-workspace/save-sandbox-as-blueprint.md b/docs/portal/sandboxes/sandbox-workspace/save-sandbox-as-blueprint.md index 70b576ac17..c9854a56a6 100644 --- a/docs/portal/sandboxes/sandbox-workspace/save-sandbox-as-blueprint.md +++ b/docs/portal/sandboxes/sandbox-workspace/save-sandbox-as-blueprint.md @@ -19,4 +19,8 @@ CloudShell also provides the option of creating a saved sandbox. However, unlike The new blueprint's properties page is displayed. -3. Make the necessary changes and click **Update** at the bottom right of the page. \ No newline at end of file +3. Make the necessary changes and click **Update** at the bottom right of the page. + +:::note +When you save the sandbox as a blueprint, connections (routes) whose endpoint is not a resource — for example, a route to an abstract or otherwise non-resource endpoint — are preserved in the resulting blueprint. Previously, such routes could prevent the sandbox from being saved. +::: \ No newline at end of file