Skip to main content
Version: 2024.1

The Shell Project Guide

CloudShell’s 2nd generation Shells are based on the Topology and Orchestration Specification for Cloud Applications (TOSCA) industry standard and use yaml files. To develop a Shell for CloudShell there is no need to dive deep into the details of TOSCA. We made it all simple. However, if you do wish to learn more about TOSCA, follow this list of references.

When starting a new Shell, the first thing we’ll want to do is generate the Shell project files and directory structure. Thankfully, this happens automatically when we use the ShellFoundry CLI tool.

In this section, we’ll look into the generated files and structure, and their different roles. At this stage, we’ll only take a bird’s eye view of the different files and folders, and what they are used for. In the following sections, we’ll delve deeper into the specific options and format of each file and learn how to customize the Shell’s driver and definition .

Let’s begin by generating a new Shell project. If you’ve previously completed the Getting Started with Shell Development tutorial, you should have a reference project. If you haven’t completed the initial tutorial, it’s recommended to do so now. Otherwise, just run the following in your Command Line:

shellfoundry new linux-server-shell
cd linux-server-shell

This will create a new linux_server_shell folder using the default Shell template and generate some scaffolding for it. Notice that the generated project is already a valid Shell. From this point on, you can further customize it or develop its driver commands, but all of the basic components are there already. We recommend that you use this as a baseline and continue to incrementally add functionality on top of the generated Shell.

The Shell project’s root folder​

Directory Structure

  • The dist folder: Contains the Shell package that is created by running the shellfoundry install or shellfoundry pack commands.

  • The docs and tests folders: Placeholders to place Shell documentation and Shell tests. Some tests are already automatically generated in the tests folder.

  • The src folder: Contains the Shell’s Python driver source files:

    • driver.py: The main driver file. This file contains the functions that will be published as CloudShell commands. By default, the driver.py file contains a single Python class named Driver. You’ll see that it already contains some functions.

    • drivermetadata.xml: Contains metadata related to the display and behavior of the driver functions as CloudShell commands.

    • requirements.txt: A pip requirements file used for setting up the driver’s virtual environment . Any dependency of the Shell driver needs to be in this file.

  • The TOSCA-Metadata folder: Contains a TOSCA standard file. Its content is filled out by Quali and requires no additional updates on your part.

  • The .gitignore.txt file: Standard Git repository file that specifies files which are not managed by source control.

  • The deployment.xml file: Contains the debugging specifications. For more information, see Debugging Shell Driver Commands.

  • The shell-definition.yaml file: Contains the information needed for importing the Shell’s data model, which defines how the Shell resources are presented in CloudShell. This file is automatically generated by ShellFoundry according to the selected ShellFoundry template.

  • The shell-icon.png file: Default icon that will appear for the Shell in CloudShell Portal.

  • The test_requirements.txt file: Contains all Python requirements for running the Shell’s tests.