diff --git a/docs/admin/cloudshell-manage-dashboard/managing-shells.md b/docs/admin/cloudshell-manage-dashboard/managing-shells.md index dd59c19b1d..869bdbae61 100644 --- a/docs/admin/cloudshell-manage-dashboard/managing-shells.md +++ b/docs/admin/cloudshell-manage-dashboard/managing-shells.md @@ -23,7 +23,7 @@ The **Shells** page is only displayed for system administrators in the **Global* You can use the toolbar to only display official Quali shells, sort the Shells according to **Name** or date of modification, and filter them according to Shell **Type**. ## Importing Shells -:::caution Note: +:::warning A shell update is not reversible(in other words, you cannot downgrade to an earlier shell version). Therefore, update the template version in the shell's `shell-definition.yaml` ONLY when something in the data model changes (new attributes added to `shell-definition.yaml`). Any changes in just the driver or underlying packages you can keep the template version number the same and then freely "roll back" to a previous version if the shell presents unexpected behavior. ::: **To import a new Shell into CloudShell:** @@ -72,7 +72,7 @@ This section explains how to add an attribute from the pool of global attributes ## Updating Shells Shell update overrides that existing Shell's settings with the new Shell. -:::caution Note: +:::warning A shell update is not reversible(in other words, you cannot downgrade to an earlier shell version). Therefore, update the template version in the shell's `shell-definition.yaml` ONLY when something in the data model changes (new attributes added to `shell-definition.yaml`). Any changes in just the driver or underlying packages you can keep the template version number the same and then freely "roll back" to a previous version if the shell presents unexpected behavior. ::: :::note Points to consider: diff --git a/docs/devguide/developing-shells/getting-started.md b/docs/devguide/developing-shells/getting-started.md index 3824a7b94b..a5df6cd99b 100644 --- a/docs/devguide/developing-shells/getting-started.md +++ b/docs/devguide/developing-shells/getting-started.md @@ -4,4 +4,285 @@ sidebar_position: 1 # Getting Started with Shell Development -WIP +In this section, we’ll go through the basic steps of creating a new Shell and customizing an existing one. The goal is to demonstrate the end-to-end cycle, from generating a new Shell project to creating Shell resources and running commands in CloudShell. + +Before developing shells, please familiarize yourself with CloudShell by taking [Quali U courses](http://courses.quali.com/). These courses also include installation instructions for the CloudShell SDK package that deploys a developer edition of CloudShell on which you can perform your training and development activities. + +## What is a shell? + +A Shell enables CloudShell users to interact with different sandbox elements, like physical devices and virtual appliances. A Shell models the sandbox element in CloudShell and provides commands that CloudShell users and automation processes can run on it, like Power On and Health Check. Each 2nd Gen Shell is modeled after a CloudShell standard, from which the shell inherits its default settings, attributes and driver. + +In our [community](https://github.com/orgs/QualiSystems/repositories), you can find both officially released shells and shells developed in our developer community. If you find a shell that fits your needs, you’re welcome to use it as is, or, you can customize its settings and automation, as explained in [Customizing Shells](https://help.quali.com/Online%20Help/0.0/Portal/Content/DevGuide/Shells/Customizing-Shells.htm). If you can’t find the shell you’re looking for, you’re welcome to create a new one from scratch using one of our shell standard templates and contribute it to the community for others to use it as well. + +Historically, we have had two types of shells in CloudShell, 1st Generation shells and 2nd Generation shells. While 1st Gen shells are still used, all new shells are released only as 2nd Generation shells and this developer guide focuses on this type of shells. For additional information, see [Shells Overview](https://help.quali.com/Online%20Help/0.0/Portal/Content/CSP/LAB-MNG/Features/Shells.htm). + +{{youtube}} + +## Supported versions - CloudShell v.8.0 and up + +As of version 8.0, CloudShell supports 2nd Gen Shells. This guide includes instructions on developing **2nd Gen Shells** only. + +For information on developing 1st Gen Shells, see the CloudShell Developer Guide for version 7.1. + +To learn more about the different versions of the Shells used by CloudShell and how to upgrade a 1st Gen Shell, see [Migrating 1st Gen Shells to 2nd Gen](https://help.quali.com/Online%20Help/0.0/Portal/Content/DevGuide/Reference/Converting-1G-Shells.htm). + +## Prerequisites + +- [Get CloudShell](http://info.quali.com/cloudshell-developer-edition-download): Download the latest CloudShell SDK and run it on your machine. +- [Python](https://www.python.org/downloads/): Make sure the appropriate Python version - 2.7.x and/or 3.x - (latest recommended) is installed on your machine. *Starting with CloudShell 9.3, CloudShell comes with out-of-the-box support for Python 3 for shells*. + + Python 3 automation requires Microsoft Visual C++ Redistributable 2015 x86 and x64 to be installed on the Execution Server(s). + + :::tip + CloudShell components such as Quali Server and the execution servers come with their own Python installation folders. Making changes to these folders may cause unexpected behavior in CloudShell. Therefore, if you plan on doing dev work on a machine that has CloudShell components installed, we recommend doing one of the following: + + - Configuring dedicated virtual environments for your projects out of these base installations. To do this in PyCharm, see [https://www.jetbrains.com/help/pycharm/creating-virtual-environment.html](https://www.jetbrains.com/help/pycharm/creating-virtual-environment.html). To do this via CLI, see [https://docs.python-guide.org/dev/virtualenvs/#lower-level-virtualenv](https://docs.python-guide.org/dev/virtualenvs/#lower-level-virtualenv). + - [Downloading separate installers](https://www.python.org/downloads/) for Python 2.7.18 and 3.9.9 and using these as global installations (by setting the installation folders in the machine’s PATH system variable) for any dev work being done. + ::: + +- **IDE/Text Editor**: Your preferred IDE editor. We recommend using PyCharm (which offers a free community edition) because of the tooling we’ve already created for that IDE, including a CloudShell developer plugin. + +## Installing or Updating Shellfoundry + +To create the Shell project, we’ll use [Shellfoundry](https://help.quali.com/Online%20Help/0.0/Portal/Content/DevGuide/Reference/Shellfoundry.htm), a CLI tool for generating and distributing Shells. + +:::note +Shellfoundary cannot work if there’s a proxy server present between the shellfoundry machine and the remote Quali Server machine. +::: + +**To install Shellfoundry:** + +Run the following in your local Command Line: + +```python +python -m pip install shellfoundry +``` + +For windows users, it is recommended to add the path (to the shellfoundry installation folder) to your local environment variables. For example, C:\\Python27\\Scripts. This will enable us to run the Shellfoundry commands from any folder of the Shell project. + +**To update Shellfoundry:** + +If Shellfoundry is already installed, run the following command to update: + +```python +python -m pip install shellfoundry --upgrade +``` + +For first time configuration of Shellfoundry, run the shellfoundry config, as explained in [Shellfoundry](https://help.quali.com/Online%20Help/0.0/Portal/Content/DevGuide/Reference/Shellfoundry.htm). + +## Configuring CloudShell Connection Settings + +In order to use Shellfoundry, we’ll need to first configure your CloudShell connection settings in Shellfoundry. + +**To configure CloudShell settings:** + +1. Run the following command in your command Line to see all the available configuration parameters: + + ```python + shellfoundry config + ``` + + ![Directory Structure](/Images/Devguide-shells/Shells-Getting-Started.png) + + The configuration includes some default settings that you can change. + +2. To update a default setting, run the config command with two arguments: the parameter name and the new value. + + For example, changing the username to “John”: + + ```python + shellfoundry config username John + ``` + + +Normally, you would need to set the CloudShell admin user/password and the server address. For details, see [Shellfoundry](https://help.quali.com/Online%20Help/0.0/Portal/Content/DevGuide/Reference/Shellfoundry.htm). + +## Setting the default python version for new shells + +Starting with CloudShell 9.3, the `DefaultPythonVersion` admin key allows you to control the Python version in which all new shells are created. For details, see [Advanced CloudShell Customizations](https://help.quali.com/Online%20Help/0.0/Portal/Content/Admn/Wrk-wth-Cnfg-Ky.htm). Note that this key also applies to orchestration scripts. + +You can also change this default for your shell in the shell project’s drivermetadata.xml file, but we’ll discuss that later on. + +## Creating the Shell Project + +Before developing your shell, please watch the following video to determine whether you need to create a new shell or customize an existing one: + +{{youtube}} + +**To create a new project:** + +1. Run the following command in your local Command Line: + + ```python + shellfoundry new linux-server-shell + cd linux-server-shell + ``` + + A new sub folder containing the basic Shell project’s structure and files will be created. + + Note that by default, the shell is based on Python 2. To use Python 3, create the shell with the \--python 3 tag as follows: + + ```python + shellfoundry new linux-server-shell --python 3 + ``` + +2. Navigate to the new folder. The following files have been created for you: + + ![Directory Structure](/Images/Devguide-shells/Shells-Getting-Started_1.png) + + The generated folder contains all of the basic scaffolding needed for the new Shell. We will review the Shell project’s structure in a more in-depth manner in later stages of this guide. + +3. Run the following command from the root of the project folder + + ```python + python -m pip install -r .\src\requirements.txt + ``` + + This command makes sure all of the basic package requirements for the Shell are satisfied. + + +## Testing the basic workflow + +**To test the basic workflow:** + +1. Make a minor change to the driver + +2. Install the Shell to your local CloudShell + +3. Create an instance of your Shell resource in the local CloudShell inventory + +4. ‘Hello world’ + + +### Make a minor change to the driver + +The source control for the Shell is managed under the src folder. When importing the project template, Shellfoundry already created a driver template under this folder. To make sure everything is in working order, we’ll implement an example command in the `driver.py` file. We’ll also want to add basic metadata including an alias and description. The way to do that is by editing the `drivermetadata.xml` file located in the src folder. For example, we can add a new command category under the Layout element. + +**To make changes to the driver:** + +1. Open the `driver.py` file in your preferred IDE. You’ll see that it already contains a driver for the Shell with some example commands already in place. + +2. Add a simple ‘hello world’ command to the driver: + + ```python + def say_hello(self, context, name): + """ + :param ResourceCommandContext context: the context the command runs on + :param str name: A user parameter + """ + return "hello {name} from {resource_name}".format(name=name, resource_name=context.resource.name) + ``` + +3. Open the `drivermetadata.xml` file in your preferred IDE and replace the highlighted section so that it matches the test below: + + ```xml + + + + + + + + + + + + ``` + + There is no need to get into too many details at this stage. We’ll dive more deeply into the `drivermetadata.xml` file in a later section of this guide. For now it’s sufficient to understand that we use this file to provide more CloudShell-specific information regarding how to interpret and display the driver’s commands and their parameters. + +4. Save the `driver.py` and `drivermetadata.xml` files. + + We’re now ready to install the new Shell. + + +### Install the Shell on CloudShell + +Shellfoundry provides an easy and convenient way to create the Shell package and install it on your CloudShell server. + +- To package the Shell and install it on your local CloudShell server, run the following command: + + ```python + shellfoundry install + ``` + + +### Create an instance of your Shell resource in the local CloudShell inventory + +The Shell is installed in your development CloudShell. We can now create resources of that Shell in our inventory. + +1. Log in to your CloudShell Portal. + +2. Click the **Inventory** menu. + +3. In the **Inventory** dashboard, click **Add New**, select the **LinuxServerShell**. + +4. Provide a name and an address for the shell resource, for example “HelloWorld\_Shell”. For now, since we don’t have an address of an actual server, you can provide any value for the address. + +5. Click **Create**. + +6. Click **Start discovery** to complete the operation. + + ![Shell Discovery](/Images/Devguide-shells/Shells-Getting-Started_2_624x426.png) + + +### ‘Hello world’ + +Now that we’ve added the Shell resource, we can finally add it to a blueprint and reserve it as a sandbox. + +1. In CloudShell Portal, from the main menu, click **Lab Management > Blueprints**. + +2. Create a new blueprint or open an existing one. To create a new blueprint, click the **+ Create Blueprint** link. + +3. Click the toolbar’s **Resource** button and drag the new Shell resource into the diagram. + +4. Click **Reserve** to create a new sandbox. + +5. In the **Sandbox** workspace, hover over the Shell resource and select **Commands**. The **Resource Commands** pane is displayed. + +6. To run the Say Hello command, in the **Resource Commands** pane, click the play button next to the command. + + ![Shell Discovery](/Images/Devguide-shells/Shells-Getting-Started_3_624x295.png) + + The common output is displayed in the **Output console**. + + ![Shell Discovery](/Images/Devguide-shells/Shells-Getting-Started_4_624x403.png) + + +## Development process summary + +In this tutorial we’ve covered the basic steps to develop a Shell. The process is illustrated in the below diagram: + +![Context Object](/Images/Devguide-shells/Shells-Getting-Started_5_624x481.png) + +The basic flow is: + +1. Set the CloudShell Server and user credentials in Shellfoundry. You need to do this only once as Shellfoundry remembers the settings for future sessions. + +2. Create a new Shell project by running shellfoundry new. + +3. Configure the Shell in the `shell-definitions.yaml` file located in the Shell project’s root folder. + +4. Import the Shell to the development server using `shellfoundry install`. + +5. If the shell requires the use of Python dependencies, which aren’t available in the public PyPi repository, add them to the local PyPi Server. See [PyPi Server - Managing Python Shell and Script Dependencies](https://help.quali.com/Online%20Help/0.0/Portal/Content/Admn/Pyth-Cnfg-Mds.htm). + +6. Create a resource of the Shell for testing: + + - For an inventory resource Shell: Create a Shell inventory resource in CloudShell using its Resource Template. + + - For a deployed app Shell: Define the App template in CloudShell including the deployment type and parameters, set the App model to the Shell model. + +7. Create a sandbox for testing in the development server: either add the inventory resource to the sandbox or deploy the App in the sandbox. + +8. Make incremental changes to the Shell and update the development server each time with the changes by running `shellfoundry install`. + +9. Rinse and repeat! + + +For more information on how to deploy the Shell to production, refer to the [Deploying to Production](https://help.quali.com/Online%20Help/0.0/Portal/Content/DevGuide/Shells/Deploying-to-Production.htm) section. + +## What’s next + +We’ve successfully gone through the steps of adding a basic, working Shell. In the following sections, we’ll review all of these steps in depth as well as the concepts, available options and customizations, and see how they interface with CloudShell. diff --git a/docs/intro/features/services.md b/docs/intro/features/services.md index a4157b4952..7fb74ab3a6 100644 --- a/docs/intro/features/services.md +++ b/docs/intro/features/services.md @@ -4,4 +4,37 @@ sidebar_position: 9 # Services Overview -WIP \ No newline at end of file +This article introduces services, their function in CloudShell and outlines how to configure them. + +## What is a service? + +A service is a CloudShell component that is used to model sandbox components that are not actual physical devices. It can be a public cloud-native service on AWS or Azure or a SaaS product you want to represent in the sandbox. Similar to resources, services have a data model and automation commands, but they are not managed as inventory items. This allows multiple instances of the same service to be used in a sandbox. + +## What does a service include? + +Services are based on a Shell template, which provides the service's data model and automation script. + +In addition, the service can include attributes, to be used by sandbox orchestration processes or to prompt the sandbox end user for inputs that will be used by the service's driver or script. The service's attributes can be published to prompt the sandbox end-user to provide information. + +If the Shell template provides it, the service may also include an address field to allow remote access to specific devices or web sites from within the sandbox. For example, to connect to an Amazon CDN service. + +## Service creation process + +CloudShell provides standardized Shell templates for creating services. + +:::note +Depending on your organization, the system administrator and service/blueprint designers may be the same employee. +::: + +1. Using the Shellfoundry utility, the service developer creates a Shell from the appropriate Shell template. For additional information, see the CloudShell Dev Guide's [Getting Started with Shell Development](../../devguide/developing-shells/getting-started.md). + +2. The service developer modifies the Shell's settings, including default attribute values, which inputs to publish in the diagram, and attaches service categories to expose the service to specific domains. + +3. The system administrator imports the Shell into CloudShell - as explained in [Importing Shells](../../admin/cloudshell-manage-dashboard/managing-shells.md#importing-shells). + + :::note + For 1st Gen Shells, you can optionally attach the service categories after importing the Shell into CloudShell, via **Resource Manager Client**. For additional information, see [Configuring Services](../../admin/setting-up-cloudshell/inventory-operations/configuring-services.md). + ::: + +4. The blueprint designer adds the service to the blueprint diagram from the **Apps / Services** catalog and fills in any required attribute values - see [Services in Blueprints](../../portal/blueprints/creating-blueprints/services.md). +5. End-users can now use the services in their sandboxes - see [Services in Sandboxes](../../portal/sandboxes/sandbox-workspace/services.md). \ No newline at end of file diff --git a/docs/portal/sandboxes/sandbox-workspace/extend-and-end-sandbox.md b/docs/portal/sandboxes/sandbox-workspace/extend-and-end-sandbox.md index 8c98d2044f..4a7feb8350 100644 --- a/docs/portal/sandboxes/sandbox-workspace/extend-and-end-sandbox.md +++ b/docs/portal/sandboxes/sandbox-workspace/extend-and-end-sandbox.md @@ -1,5 +1,5 @@ --- -sidebar_position: 17 +sidebar_position: 18 --- # Extend and End Sandboxes diff --git a/docs/portal/sandboxes/sandbox-workspace/labels.md b/docs/portal/sandboxes/sandbox-workspace/labels.md index a47a30f4f1..941e18a2a6 100644 --- a/docs/portal/sandboxes/sandbox-workspace/labels.md +++ b/docs/portal/sandboxes/sandbox-workspace/labels.md @@ -4,4 +4,42 @@ sidebar_position: 5 # Labels -WIP \ No newline at end of file +Labels make the sandbox more readable by visually grouping your sandbox's resources, Apps, and services according to some shared quality or characteristic, like "Spine Network", "Web Servers" or "Firewall." + +:::note Notes +- Labels are created in the blueprint and can be used in the sandbox. For additional information, see [Labels in Blueprints](../../blueprints/creating-blueprints/labels.md). +- Labels are only visible in **Diagram** view. +::: + +![](/Images/CloudShell-Portal/Lab-Management/Reservations/sandbox-labels-screenshot.png) + +## Viewing labels + +If any of the sandbox's components have labels, the **Labels Legend** is displayed at the top of the canvas, showing the labels that are currently in use. + +**To view the diagram's labels:** + +1. Hover over a component. From the context menu, select **Labels**. + + The **Labels** menu is displayed, listing the diagram's labels. + +2. Optionally use the **Search Label** field to quickly find labels. You can search for full or partial terms or phrases. + +## Applying labels + +Select an existing label and apply it to a component. + +**To apply a label to a component:** + +1. In the **Labels** menu, select a label. + +2. Click **Apply**. + + +## Removing labels + +**To remove a label from a component:** + +1. In the **Labels** menu, click the label in the list to deselect it. + +2. Click **Apply**. \ No newline at end of file diff --git a/docs/portal/sandboxes/sandbox-workspace/sandbox-list-view.md b/docs/portal/sandboxes/sandbox-workspace/sandbox-list-view.md index 2dbbfe846a..771f2fafed 100644 --- a/docs/portal/sandboxes/sandbox-workspace/sandbox-list-view.md +++ b/docs/portal/sandboxes/sandbox-workspace/sandbox-list-view.md @@ -1,5 +1,5 @@ --- -sidebar_position: 18 +sidebar_position: 19 --- # Sandbox List View diff --git a/docs/portal/sandboxes/sandbox-workspace/save-sandbox-as-blueprint.md b/docs/portal/sandboxes/sandbox-workspace/save-sandbox-as-blueprint.md new file mode 100644 index 0000000000..6a6afa98dd --- /dev/null +++ b/docs/portal/sandboxes/sandbox-workspace/save-sandbox-as-blueprint.md @@ -0,0 +1,22 @@ +--- +sidebar_position: 12 +--- + +# Save a Sandbox as a Blueprint + +This article explains how to save a sandbox as a blueprint. This option is useful if you make changes to your sandbox diagram or properties and want to save them for future use. This option is not available for completed restored sandboxes. + +:::note +CloudShell also provides the option of creating a saved sandbox. However, unlike saving a sandbox as a blueprint, saved sandboxes also save the state of both the sandbox and the Apps it contains, including configurations and operations performed on the App VMs during the sandbox. For additional information, see [Sandbox Save and Restore Overview](https://help.quali.com/Online%20Help/0.0/Portal/Content/CSP/LAB-MNG/Sndbx-Sv-Rstr-Ovrvw.htm) +::: + +**To save a sandbox as a blueprint:** + +1. Open the sandbox workspace, +2. Click the Sandbox menu and select Save As Blueprint. + + ![](/Images/CloudShell-Portal/Lab-Management/Reservations/SaveAsBlueprint.png) + + 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 diff --git a/docs/portal/sandboxes/sandbox-workspace/save-sandbox.md b/docs/portal/sandboxes/sandbox-workspace/save-sandbox.md index eddc87c1f5..2fc7f7cdb4 100644 --- a/docs/portal/sandboxes/sandbox-workspace/save-sandbox.md +++ b/docs/portal/sandboxes/sandbox-workspace/save-sandbox.md @@ -1,7 +1,7 @@ --- -sidebar_position: 12 +sidebar_position: 13 --- -# Save a Sandbox as a Blueprint +# Save a Sandbox WIP \ No newline at end of file diff --git a/docs/portal/sandboxes/sandbox-workspace/services.md b/docs/portal/sandboxes/sandbox-workspace/services.md index 6b1d03d486..c0aa7b6900 100644 --- a/docs/portal/sandboxes/sandbox-workspace/services.md +++ b/docs/portal/sandboxes/sandbox-workspace/services.md @@ -4,4 +4,111 @@ sidebar_position: 4 # Services -WIP \ No newline at end of file +This article explains how to use services in sandboxes. For additional information about CloudShell services, see [Services Overview](../../../intro/features/services.md). + + +## Find services + +**To view services:** + +1. In the Diagram view, in the toolbar, click **App / Service**. + The **Add App / Service** catalog is displayed. + +2. Browse the catalog by selecting a services folder or by using the text search. + + The list of folder items are displayed, grouped by the service families. + + ![](/Images/CloudShell-Portal/Lab-Management/Working with Services/SandboxAppServiceCatalog.png) + +## Add services + +:::note +You cannot add, edit or remove Subnet services in the sandbox. +::: + +**To add a service to the diagram:** + +1. Click the ‘**+**’ icon or drag it from the catalog into the diagram. + + ![](/Images/CloudShell-Portal/Lab-Management/Working-with-Services/Working-with-Services_3.png) + + The **Add Service** dialog box is displayed. + +2. Fill in any required fields. +3. Click **Add**. + +## Remove services + +**To remove a service from the diagram:** + +1. Select the required service. +2. Hover over the **Actions** menu, select **More Options** and then select the **Remove** option. + + ![](/Images/CloudShell-Portal/Lab-Management/Working-with-Services/Working-with-Services_4.png) + + +## Run service commands + +**To run a service command:** + +1. In an active sandbox, select the required service. +2. From the **Actions** menu, select **Commands**. + + The **Commands** pane is displayed. + +3. In the **Commands** pane, next to the required command name, click **Run** or **Deploy**. + +## Remotely connecting to a service + +This option is enabled for services that have an IP address or hostname. + +It is possible to connect remotely to a device via RDP, SSH, VNC, or Telnet using the address and user credentials specified on the service. RDP, SSH and Telnet are available by default, while VNC must be configured by the administrator. + +**To connect to a device via remote protocol:** + +1. In **Diagram** view, hover over the service. The **Actions** menu is displayed. + + In **List** view, in the required service's row, click the **Actions** menu. + +2. Select the remote connection option: + + - RDP + - SSH + - Telnet + - VNC + +3. If prompted, perform additional steps, such as selecting the Windows application to use or entering the username and password to the device. + + The device is displayed in a Windows application, or in your web browser (if the QualiX Solution Pack is installed). + + +## Activity Feed for a service in the sandbox + +The **Activity Feed** pane enables you to display system messages and command execution progress for a specific service in the sandbox. + +For information about the activity feed for a resource or App in the sandbox, see [Activity Feed for a Resource in the Sandbox](https://help.quali.com/Online%20Help/0.0/Portal/Content/CSP/LAB-MNG/Cmpnt-Actvt-Fd.htm) and [Activity Feed for an App in the sandbox](https://help.quali.com/Online%20Help/0.0/Portal/Content/CSP/LAB-MNG/App-Actns/Sndbx-Apps-Activity-Feed.htm), respectively. + +**To open a component's Activity Feed:** + +1. In the sandbox, click the component's live status icon. Alternatively, hover over the component and from the **Actions** menu, select **View Activity**. + + ![](/Images/CloudShell-Portal/Lab-Management/Working-with-Resources/Component-View-Activity.png) + + The **Activity Feed** pane is displayed, listing the last 30 entries. + + :::tip + Scroll to the bottom to display additional entries. + ::: + +2. To change the time format of the entries, click the ![](/Images/CloudShell-Portal/Lab-Management/Reservations/ActivityFeedTimeFormatButton.png) button. By default, the time elapsed is displayed for each entry. +3. To narrow down your search for entries, use the search and filtering options. Click the ![](/Images/CloudShell-Portal/Lab-Management/Reservations/ActivityFeedButton.png) button to show the filters. + + Note that the search and filters apply to all entries in the Activity Feed, not just the last 30. + + - **Search feed** field: search for entries that include a word, phrase or regex. For regex, start with a backtick - \`. For example, `` `resour*``. + - **Error** option: display errors that occurred in the sandbox + - **Has output** option: display entries that have an output + - **Component** drop down list: display entries that are related to a specific resource, App or service in the sandbox. The value Component displays entries for all components. + - **Event type** drop down list: display entries of a specific type. Values are: **Event type** (all entries), **Command**, **Resource**, **Service** and **Sandbox**. + +For more detailed information about a particular error, see [Activity Feed Pane](https://help.quali.com/Online%20Help/0.0/Portal/Content/CSP/LAB-MNG/Sndbx-View-Actvty-Fd.htm). \ No newline at end of file diff --git a/docs/portal/sandboxes/sandbox-workspace/show-physical-connections.md b/docs/portal/sandboxes/sandbox-workspace/show-physical-connections.md index 451e692268..05da87baad 100644 --- a/docs/portal/sandboxes/sandbox-workspace/show-physical-connections.md +++ b/docs/portal/sandboxes/sandbox-workspace/show-physical-connections.md @@ -1,5 +1,5 @@ --- -sidebar_position: 14 +sidebar_position: 15 --- # Show Physical Connections diff --git a/docs/portal/sandboxes/sandbox-workspace/show-physical-layer.md b/docs/portal/sandboxes/sandbox-workspace/show-physical-layer.md index a5ea6342b1..7324643715 100644 --- a/docs/portal/sandboxes/sandbox-workspace/show-physical-layer.md +++ b/docs/portal/sandboxes/sandbox-workspace/show-physical-layer.md @@ -1,5 +1,5 @@ --- -sidebar_position: 13 +sidebar_position: 14 --- # Show the Physical Layer diff --git a/docs/portal/sandboxes/sandbox-workspace/system-messages/_category_.json b/docs/portal/sandboxes/sandbox-workspace/system-messages/_category_.json index f36f88c7e8..1533fbf8b9 100644 --- a/docs/portal/sandboxes/sandbox-workspace/system-messages/_category_.json +++ b/docs/portal/sandboxes/sandbox-workspace/system-messages/_category_.json @@ -1,6 +1,6 @@ { "label": "Viewing System Messages", - "position": 16, + "position": 17, "link": { "type": "generated-index", "description": "CloudShell Portal displays system messages in the following places: Indication Messages, Outout Console Window, Activity Feed Pane, Activity Details Window." diff --git a/docs/portal/sandboxes/sandbox-workspace/view-sandbox-metadata.md b/docs/portal/sandboxes/sandbox-workspace/view-sandbox-metadata.md index 59a5197223..d96bb2e920 100644 --- a/docs/portal/sandboxes/sandbox-workspace/view-sandbox-metadata.md +++ b/docs/portal/sandboxes/sandbox-workspace/view-sandbox-metadata.md @@ -1,5 +1,5 @@ --- -sidebar_position: 15 +sidebar_position: 16 --- # Show Sandbox Metadata diff --git a/docs/portal/sandboxes/saved-sandboxes/delete-saved-sandbox.md b/docs/portal/sandboxes/saved-sandboxes/delete-saved-sandbox.md index e816131000..acdfb61f9c 100644 --- a/docs/portal/sandboxes/saved-sandboxes/delete-saved-sandbox.md +++ b/docs/portal/sandboxes/saved-sandboxes/delete-saved-sandbox.md @@ -4,4 +4,25 @@ sidebar_position: 2 # Delete a Saved Sandbox -WIP +*Deleting a saved sandbox is part of the Save and Restore paid add-on. Contact your account manager to purchase a license.* + +When deleting a saved sandbox, CloudShell deletes all artifacts associated with the saved sandbox. A saved sandbox is deleted from CloudShell only when all these artifacts are successfully deleted. Note that BI data related to the saved sandbox is note removed from CloudShell and can be displayed in custom Insight dashboards. For additional information about Save and Restore, see [Sandbox Save and Restore Overview](../sandbox-save-and-restore-overview.md). + +:::note +In order to delete a saved sandbox that is associated with an active or pending sandbox, you must first end or delete the sandbox. To find all active/pending sandboxes that are associated with a saved sandbox, see [Show Restored Sandboxes](./show-restored-sandboxes.md). +::: + +**To delete a saved sandbox:** + +1. In the **Saved Sandboxes** dashboard, click the **Actions** button at the end of the row and select **Delete**. + + A "Deletion in progress" message is displayed next to the name of the saved sandbox. + + CloudShell deletes the sandbox, its components and VM artifacts both from CloudShell and the cloud providers that host the sandbox's VMs. Note that this may take some time since some aspects of this process take place outside of CloudShell. + + +## Deletion failure + +If deleting a saved sandbox fails, CloudShell will keep the saved sandbox in the **Saved Sandboxes** dashboard and mark it as “Deletion failed". Such a sandbox cannot be restored, since some of its components may have already been deleted. You are advised to try again to delete the saved sandbox. + +To display a detailed error log of the deletion process, click on the **Deletion failed** button. diff --git a/docs/portal/sandboxes/saved-sandboxes/restore-saved-sandbox.md b/docs/portal/sandboxes/saved-sandboxes/restore-saved-sandbox.md index 24bd8cf69c..d9cf72721d 100644 --- a/docs/portal/sandboxes/saved-sandboxes/restore-saved-sandbox.md +++ b/docs/portal/sandboxes/saved-sandboxes/restore-saved-sandbox.md @@ -4,4 +4,77 @@ sidebar_position: 1 # Restore a Saved Sandbox -WIP +*Restoring a sandbox is part of the Save and Restore paid add-on. Contact your account manager to purchase a license. For additional information about this add-on, see the [Sandbox Save and Restore Overview](../sandbox-save-and-restore-overview.md)* + +In CloudShell, you can restore a saved sandbox to the exact state of the sandbox when it was saved. The saved sandbox is an independent copy of the original sandbox, and can be restored to multiple sandboxes. + +The restore script is available out-of-the-box. It is a part of the setup process and when restoring a sandbox, it actually replaces the setup script. To customize the restore script, see the CloudShell Dev Guide's [Extending the OOB Restore Orchestration Script](https://help.quali.com/Online%20Help/0.0/Portal/Content/DevGuide/Orch-Scripts/CloudShell-OOB-Orch.htm#Extendin2). + +Note: Save and Restore does not apply to persistent environments. + + +## Restoring a saved sandbox + +**To restore a saved sandbox:** + +1. In the **Saved Sandboxes** dashboard, click the **Actions** button at the end of the row and select **Restore**. + + The **Restore** dialog box is displayed. + + ![](/Images/CloudShell-Portal/Lab-Management/Environments/RestoreSandboxSimple.PNG) + +2. In the **Schedule** field, you can set the required restored sandbox duration or specify the explicit start and/or end time. Use the Calendar button to set future dates. + +3. You can view and edit the **Name** of the restored sandbox. By default, the restored sandbox name is the name of the saved sandbox. + +4. You can view the name of the **Saved Sandbox**. This field is not editable. +5. To specify additional options, click the **Advanced Form** ![](/Images/CloudShell-Portal/Lab-Management/Reservations/AdvancedFormTab_20x20.png) button. + + The advanced form enables you to configure the email notifications, permitted users, and other options. + + ![](/Images/CloudShell-Portal/Lab-Management/Environments/RestoreSandboxAdvanced.PNG) + + 1. Optionally enter a **Description**. Otherwise, the description of the restored saved sandbox will use the saved sandbox description. + 2. To define a sandbox owner, click **Owner** and select the required user. By default, the user who initiated the restore action is set as the sandbox owner. + 3. Instead of changing the owner of the restored sandbox, you can permit additional users to use the sandbox. Click the **Permitted Users** section and select the users you wish to add. + 4. You can configure CloudShell to send email notifications to the owner of the restored sandbox and permitted users. + + :::note + This capability requires the administrator to activate the email notifications feature using the `ReservationEmail` configuration keys. + ::: + + 1. Click the **Email Notifications** field. + + The **Email Notifications** area expands. + + ![](/Images/CloudShell-Portal/Lab-Management/Reservations/ReservePaneEmailNotificaions.png) + + 2. Configure the email notification settings. + - **On start** - Sends notification as the restore saved sandbox starts. + - **On setup complete** - Sends notification when the sandbox setup completes. + - **Before end** - Sends notification before the Teardown process begins. The exact time is decided by the user. + - **On end** - Sends notification when the sandbox ends. + 5. If the original blueprint had inputs, they are displayed here. Values are taken from the saved sandbox and are not-editable. +6. Click **Restore**. + + If any resource is unavailable for the scheduled time slot, the Conflicts dialog box is displayed, proposing an alternative time slot, as described in [Dealing with conflicts](https://help.quali.com/Online%20Help/0.0/Portal/Content/CSP/LAB-MNG/Sndbx-Crt.htm#Dealing). + + The saved sandbox is restored to the state when the sandbox was saved. Once the sandbox is restored, the sandbox state changes to **Active**. + + CloudShell restores the saved sandbox, its elements and configurations, as well as the states of the sandbox and its elements. + + +## Sandbox restore logic + +Currently, CloudShell Save and Restore applies only to sandboxes with vCenter/OpenStack-based virtual components, physical resources and CloudShell services. Apps of other cloud providers are not supported and therefore, you cannot save and restore a sandbox which contains any of these elements. + +The elements of the saved sandbox that are restored directly reflect the elements that were saved when you saved the sandbox. For information on the save logic, see [Sandbox save logic](https://help.quali.com/Online%20Help/0.0/Portal/Content/CSP/LAB-MNG/Sndbx-Sv.htm#Save2). + +There are, however, a number of important points that you should consider when restoring a saved sandbox: + +- Resources in the saved sandbox are added to the sandbox, assuming they are available for the reservation's timeslot. +- Apps that were not deployed in the original sandbox will be deployed, using their defined deployment paths. Since clones are not created for undeployed Apps when saving the sandbox, CloudShell will need to deploy the Apps using their respective deployment paths, in the same way a regular App is deployed during sandbox setup. +- All L1/L2 connections are established in the restored sandbox, regardless of their state (connected/disconnected) in the original sandbox. +- Since new VMs are created in the restored sandbox, the IP and MAC addresses of the VMs may differ from the original sandbox. You may need to adjust the Restore script as a result of this change. +- If the original sandbox contained any virtual traffic generator VMs loaded with a test configuration, the test configuration will need to be reloaded either automatically by the Restore script or manually after the sandbox is restored. +- If the original sandbox contained any **VLAN Auto** services, the VLAN IDs allocated in the restored sandbox may differ. diff --git a/docs/portal/sandboxes/saved-sandboxes/show-restored-sandboxes.md b/docs/portal/sandboxes/saved-sandboxes/show-restored-sandboxes.md index ab31550faf..2af972ead9 100644 --- a/docs/portal/sandboxes/saved-sandboxes/show-restored-sandboxes.md +++ b/docs/portal/sandboxes/saved-sandboxes/show-restored-sandboxes.md @@ -4,4 +4,16 @@ sidebar_position: 3 # Show Restored Sandboxes -WIP +This article explains how to show a list of active and pending sandboxes that were restored from a specific saved sandbox. + +This is useful, for example, if you need to delete a saved sandbox that is associated with an active or pending sandbox, as you must first end or delete the sandbox. + +**To show a saved sandbox's restored sandboxes:** + +1. In the Saved Sandboxes dashboard, click the Actions button at the end of the row and select Show Restored Sandboxes. + + The Sandboxes dashboard is displayed, listing the associated sandboxes. + + :::tip + Alternatively, you can copy the saved sandbox's ID and paste it in the Sandboxes dashboard's search field in the top left corner of the screen. + :::