The Shell Project Guide Suggest edits

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:

shellfoundry new linux-server-shell

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:
install:
        host: localhost
        port: 9000
        username: YOUR_USERNAME
        password: YOUR_PASSWORD
        domain: Global

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.