Release date: December 2020
Shell version: 1.0.0
Document version: 1.0
- Overview
- Downloading the Shell
- Importing and Configuring the Shell
- Updating Python Dependencies for Shells
- Typical Workflows
- References
- Release Notes
A shell integrates a device model, application or other technology with CloudShell. A shell consists of a data model that defines how the device or service and its properties are modeled in CloudShell, alongside automation that enables interaction with the device or service via CloudShell.
CloudShell Cloud Providers shells provide the ability to provision Apps on a virtualization platform or a service provider platform.
The Apps can be modeled on a variety of types of services, depending on the Cloud Provider, including VMs, Containers, or Emulated instances.
Amazon AWS Cloud Provider Shell 2G provides you with app deployment and management capabilities on AWS EC2. These include:
- Pyhon 3.7 support
- Capability to deploy, manage and tear down AWS infrastructure as part of CloudShell sandboxes, including virtual networks, subnets, EC2 instances and security groups
- Option to deploy to existing shared VPC
- Enable source destination checks
For details, see the Add an AWS Cloud Provider Resource CloudShell Help article. For more information on AWS, see the vendor's official product documentation.
Amazon AWS Cloud Provider Shell 2G is based on the Cloud Provider Standard version 1.0.0.
For detailed information about the shell’s structure and attributes, see the Cloud Provider Standard in GitHub.
Release: Amazon AWS Cloud Provider Shell 2G
▪ CloudShell version 9.3 and above
Note: If your CloudShell version does not support this shell, you should consider upgrading to a later version of CloudShell or contact customer support.
The shell's data model includes all shell metadata, families, and attributes.
The attribute names and types that are derived from the standard are listed in the following section of the Cloud Provider Shell Standard:
Common Cloud Provider Attributes
The following table describes attributes that are unique to this shell and are not documented in the Shell Standard:
| Attribute Name | Data Type | Description |
|---|---|---|
| REGION | Lookup | The public cloud region to be used by this cloud provider resource. |
| AWS MGMT SG ID | string | The Management VPC's security group. Use the SG1id output when configuring the Management VPC for the region. For example, "sg-71240198". This value is used by the Setup process to configure the communication between the Management VPC's instances and the Sandbox instances. |
| AWS MGMT VPC ID | string | ID of the Management VPC. Used by the Setup process to set up the VPC and subnet for the sandbox. Use the ManagementVPCID output when configuring the Management VPC for the region. For example “vpc-633fb904”. |
| KEYPAIRS LOCATION | string | The name of an S3 bucket in which PEM files will be located. Each active Sandbox will have a PEM file under a designated folder. Use the S3Name output when configuring the Management VPC for the region. For example: "sandbox-management". |
| MAX STORAGE SIZE | numeric | The max number of GiB of the root volume. Must be greater than zero or the size of the snapshot used. If kept empty the default size of the snapshot will be used. For example 8. |
| MAX STORAGE IOPS | numeric | The max number of I/O operations per second that the volume can support. For Provisioned IOPS (SSD) volumes, you can provision up to 30 IOPS per GiB. If left empty the default in the AMI will be used. For example 240. |
| NETWORKS IN USE | string | Reserved networks that will be excluded when allocating Sandbox networks. Should include at least the management network. The syntax is comma separated CIDRs. For example: 10.0.0.0/24, 10.1.0.0/16, 172.31.0.0/24. |
| INSTANCE TYPE | string | The AWS EC2 instance type. The instance type determines the CPU, memory and networking capacity of the instance. For example: "t2.large". |
| VPC MODE | lookup | Every sandbox with AWS apps deploys a VPC to AWS. This setting determines how the sandbox VPC will chose a CIDR block. In DYNAMIC mode, the CIDR block is chosen by Cloudshell Server. In STATIC mode, the CIDR block for all sandboxes allocated will be taken from VPC CIDR attribute on AWS cloud provider. Select SHARED to indicate that the cloud provider resource will deploy to the shared VPC defined in Shared VPC ID. Select Single to deploy Apps based on this cloud provider resource to the Management VPC. |
| STATIC VPC CIDR | string | The CIDR used for sandbox VPC when VPC MODE is STATIC. |
| SHARED VPC ID | string | V(Mandatory for Shared VPC mode) Shared VPC’s ID. For example: “vpc-0bf24b1ebrd855e30”. |
| Shared VPC Role ARN | string | (Mandatory for Shared VPC mode) Role created by the CloudFormation process with read/write permissions in the AWS account. This role is used by CloudShell to operate in the shared VPC. To find the role, open the main CloudFormation stack, click the Outputs tab and copy the SharedRoleARN. |
| TRANSIT GATEWAY ID | string | (Mandatory for Shared VPC mode) ID of the transit gateway. To find the transit gateway id, open the CloudFormation stack that has “VPCNAT” in its name, click the Outputs tab and copy the TGWid value. |
| ADDITIONAL MANAGEMENT NETWORKS | string | Networks to be allowed to interact with all sandboxes. This is used for allowing connectivity to AWS resources outside the Management VPC. The syntax is comma separated CIDRs. For example, "10.0.0.0/24,10.1.0.0/16,172.31.0.0/24". |
| VPN GATEWAY ID | string | (Mandatory for Shared VPC mode) ID of the gateway to use. Leave empty if the UseTransitGateway attribute was enabled in the CloudFormation, specify the VPN gateway ID if the attribute was set to “False”. To find the VPN gateway ID, open the shared VPC's CloudFormation stack, click the Outputs tab and copy the VPNGWid value. |
| VPN CIDR | string | (Mandatory for Shared VPC mode if VPN Gateway ID is defined) Comma-separated list of CIDRs in the local network to be used to VPN to the shared VPC. For example: "10.1.0.0/24,10.3.0.0/16". |
This section describes the automation (driver) associated with the data model. The shell’s driver is provided as part of the shell package. There are two types of automation processes, Autoload and Resource Commands. Autoload is executed when creating the resource in the Inventory dashboard.
For detailed information on each available commands, see the following section of the Cloud Provider Standard:
Common Cloud Provider Commands
In order to integrate CloudShell with AWS, you need to first deploy the CloudShell management and sandbox VPCs on your AWS region. This is done using CloudFormation templates that define the VPC deployment type (dedicated VPCs per sandbox or shared VPCs in which the sandboxes deploy to a pre-defined VPC), the connection to your Quali Server and more. Additional steps are required, such as configuring the integration's management instances and creating App templates which include the definition of the instances to deploy, image and configuration management to be performed on the deployed instances. For details, see CloudShell Help's AWS Integration chapter.
The Amazon AWS Cloud Provider Shell 2G shell is available from the Quali Community Integrations page.
Download the files into a temporary location on your local machine.
The shell comprises of the following files:
| File name | Description |
|---|---|
| Amazon AWS Cloud Provider Shell 2G.zip | Device shell package |
| cloudshell-Amazon-AWS-Cloud-Provider-Shell-2G-dependencies-win32-package-1.0.x.zip, cloudshell-Amazon-AWS-Cloud-Provider-Shell-2G-dependencies-linux-package-1.0.x.zip - | |
| Shell Python dependencies (for offline deployments only) |
This section describes how to import the Amazon AWS Cloud Provider Shell 2G shell and configure and modify the Cloud Provider Resource created using the shell.
To import the shell into CloudShell:
-
Make sure you have the shell’s zip package. If not, download the shell from the Quali Community's Integrations page or from the releases page of this repo.
-
In CloudShell Portal, as a System Administrator, open the Manage –- Shells page (Global domain only).
-
Click Import.
-
In the dialog box, navigate to the shell's zip package, select it and click Open.
The shell is displayed in the Shells page and can be used by domain administrators in all CloudShell domains to create new inventory resources, as explained in Adding Inventory Resources.
Note: Offline installation instructions are relevant only if the CloudShell Execution Server has no access to PyPi.org. You can skip this section if your execution server has access to PyPi.org. For additional information, see the online help topic on offline dependencies.
In offline mode, import the shell into CloudShell and place any dependencies in the appropriate dependencies folder.
See Adding Shell and script packages to the local PyPi Server repository.
If your Quali Server and/or execution servers work offline, you will need to copy all required Python packages, including the out-of-the-box ones, to the PyPi Server's repository on the Quali Server computer.
(by default C:\Program Files (x86)\QualiSystems\CloudShell\Server\Config\Pypi Server Repository).
For more information, see Configuring CloudShell to Execute Python Commands in Offline Mode.
To add Python packages to the local PyPi Server repository:
-
If you haven't created and configured the local PyPi Server repository to work with the execution server, perform the steps in Add Python packages to the local PyPi Server repository (offline mode).
-
For each shell or script you add into CloudShell, do one of the following (from an online computer):
-
Connect to the Internet and download each dependency specified in the requirements.txt file with the following command:
pip download -r requirements.txt. The shell or script's requirements are downloaded as zip files. -
In the Quali Community's Integrations page, locate the shell and click the shell's Download link. In the page that is displayed, from the Downloads area, extract the dependencies package zip file.
-
-
Place these zip files in the local PyPi Server repository.
This section explains how to create a new Cloud Provider Resource using the shell.
To create a Amazon AWS Cloud Provider Resource:
-
In the CloudShell Portal, in the Inventory dashboard, click Add New.
-
From the list, select Amazon AWS Cloud Provider Shell 2G.
-
Click Create.
-
In the Resource dialog box, enter the following attributes with data from step 1:
- REGION: The public cloud region to be used by this cloud provider resource.
- AWS MGMT SG ID: The Management VPC's security group. Use the SG1id output when configuring the Management VPC for the region. For example, "sg-71240198".
This value is used by the Setup process to configure the communication between the Management VPC's instances and the Sandbox instances. - AWS MGMT VPC ID: ID of the Management VPC. Used by the Setup process to set up the VPC and subnet for the sandbox.
Use the ManagementVPCID output when configuring the Management VPC for the region. For example “vpc-633fb904”. - KEYPAIRS LOCATION: The name of an S3 bucket in which PEM files will be located. Each active Sandbox will have a PEM file under a designated folder.
Use the S3Name output when configuring the Management VPC for the region. For example: "sandbox-management". - MAX STORAGE SIZE: The max number of GiB of the root volume. Must be greater than zero or the size of the snapshot used. If kept empty the default size of the snapshot will be used. For example 8.
- MAX STORAGE IOPS: The max number of I/O operations per second that the volume can support. For Provisioned IOPS (SSD) volumes, you can provision up to 30 IOPS per GiB. If left empty the default in the AMI will be used. For example 240.
- NETWORKS IN USE: Reserved networks that will be excluded when allocating Sandbox networks. Should include at least the management network. The syntax is comma separated CIDRs. For example: 10.0.0.0/24, 10.1.0.0/16, 172.31.0.0/24.
- INSTANCE TYPE: The AWS EC2 instance type. The instance type determines the CPU, memory and networking capacity of the instance. For example: t2.large.
- VPC MODE: Every sandbox with AWS apps deploys a VPC to AWS. This setting determines how the sandbox VPC will chose a CIDR block. Options are:
- DYNAMIC: The CIDR block is chosen by Cloudshell Server. In other words, CloudShell deploys a new VPC with a dedicated CIDR for every sandbox.
- STATIC: The CIDR block for all sandboxes allocated will be taken from VPC CIDR attribute on AWS cloud provider.
- SHARED: Indicates that the cloud provider resource will deploy to the shared VPC defined in Shared VPC ID.
- Single: Apps based on this cloud provider resource will be deployed to the Management VPC.
- STATIC VPC CIDR: The CIDR used for sandbox VPC when VPC Mode is Static.
- SHARED VPC ID: (Mandatory for Shared VPC mode) Shared VPC’s ID. For example: “vpc-0bf24b1ebrd855e30”.
- SHARED VPC ROLE ARN: (Mandatory for Shared VPC mode) Role created by the CloudFormation process with read/write permissions in the AWS account. This role is used by CloudShell to operate in the shared VPC. To find the role, open the main CloudFormation stack, click the Outputs tab and copy the SharedRoleARN.
- TRANSIT GATEWAY ID: (Mandatory for Shared VPC mode) ID of the transit gateway. To find the transit gateway id, open the CloudFormation stack that has “VPCNAT” in its name, click the Outputs tab and copy the TGWid value.
- ADDITIONAL MANAGEMENT NETWORKS: Networks to be allowed to interact with all sandboxes. This is used for allowing connectivity to AWS resources outside the Management VPC.
The syntax is comma separated CIDRs. For example, "10.0.0.0/24,10.1.0.0/16,172.31.0.0/24". - VPN GATEWAY ID: (Mandatory for Shared VPC mode) ID of the gateway to use. Required to connect the shared VPC's sandbox subnets to the VPN gateway. CloudShell does this by creating a route between the specified VPN gateway and the connected subnet within the VPC CIDR. To find the role, open the shared VPC CloudFormation stack, click the Outputs tab and copy the VPNGWid value.
- VPN CIDR: (Mandatory for Shared VPC mode if VPN Gateway ID is defined) Comma-separated list of CIDRs in the local network to be used to VPN to the shared VPC. For example: "10.1.0.0/24,10.3.0.0/16".
-
Click Continue.
CloudShell will validate the provided settings and create the new resource.
_**in order to use the Amazon AWS Cloud Provider Shell 2G Shell you must create an appropriate App template, which will be deployed as part of the sandbox reservation. For details on app templates, see the following CloudShell Help article: Add an AWS EC2 App Template
This section explains how to update your Python dependencies folder. This is required when you upgrade a shell that uses new/updated dependencies. It applies to both online and offline dependencies.
To update offline Python dependencies:
-
Download the latest Python dependencies package zip file locally.
-
Extract the zip file to the suitable offline package folder(s).
-
Terminate the shell’s instance, as explained here.
In online mode, the execution server automatically downloads and extracts the appropriate dependencies file to the online Python dependencies repository every time a new instance of the driver or script is created.
To update online Python dependencies:
- If there is a live instance of the shell's driver or script, terminate the shell’s instance, as explained here. If an instance does not exist, the execution server will download the Python dependencies the next time a command of the driver or script runs.
Perform these steps to allow CloudShell to deploy sandboxes using the Static VPC Mode option. For details, see "Static Mode" in Add an AWS EC2 Cloud Provider Resource .
- In Resource Manager Client, open the Attributes tab and select the Allocated CIDR attribute.
- Click the Edit button, unselect the Read-only checkbox, and save your changes.
- Open the Resource Families tab.
- Expand Virtual Network and select Subnet.
- Select Allocated CIDR and click Edit Rules.
- Select the User Input checkbox and save.
- In CloudShell Portal, open the suitable blueprint, specify the appropriate CIDR in the Allocated CIDR attribute for each subnet service.
To download and share integrations, see Quali Community's Integrations.
For instructional training and documentation, see Quali University.
To suggest an idea for the product, see Quali's Idea box.
To connect with Quali users and experts from around the world, ask questions and discuss issues, see Quali's Community forums.
For release updates, see the shell's GitHub releases page.