The Shell Project Guide
When starting a new Shell, the first thing you’ll want to do is generate the Shell project files and directory structure. Thankfully, this happens automatically when you 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, 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 driver and shell definition in CloudShell.
Let’s begin by generating a new shell project. If you’ve previously completed the Getting Started tutorial you should have a reference project. If you haven’t completed the initial tutorial, its recommended you do so now. Otherwise, just run the following in your command line:
This will create a new linux_server_shell directory 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. The suggested workflow is to use this as a baseline and continue to incrementally add functionality on top of the generated shell.
The Shell project root
- cloudshell_config.yml: This file contains the address, username and password of your local development CloudShell Server. The settings in this file are used by the Shellfoundry CLI tool to install the Shell to CloudShell using the ‘shellfoundry install’ command. The file structure is pretty simple:
Notice that this file shouldn’t generally be stored in a public source control index (in fact, its excluded in the auto-generated .gitignore file) as it contains your Dev CloudShell’s administrator login credentials.
- readme.rst: Default Shell readme file.
- shell.yml: Basic shell metadata such as the name of the shell, the author name/email, create date etc.
- test_requirements.txt: Python requirements for running the shell tests
- version.txt: The current shell version. You should increment the shell version in this file on each release.
The src folder
The src folder contains the shell 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 it already contains some example functions.
- drivermetadata.xml: This file 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 virtual environment. Any dependency the shell driver has needs to be in this file.
The datamodel folder
The datamodel folder contains all of the custom attributes and basic definitions about the shell type in CloudShell. These will allow users to instantiate resource instances of the shell in their inventory (if applicable) and control how these can be filtered, searched, and interacted with.
- datamodel.xml: This file describes the standard used for this shell, including attributes, families, models, resource structure and more.
- shellconfig.xml: This file defines how users can instantiate shell inventory resource instances from the web portal. It defines which attribute inputs they need to provide and whether the shell driver supports automatic discovery.
- shell_model.xml: This file defines the shell ‘type’ in CloudShell. It links it to one of the CloudShell standards and defines custom attributes.
- metadata.xml: You generally don’t need to do anything with this file, it will be used as a part of CloudShell’s internal API.
The docs and tests folders
These are placeholders to place shell documentation and shell tests. Some tests are already automatically generated in the tests folder.