Skip to content

Latest commit

 

History

History
155 lines (108 loc) · 4.69 KB

tool_dev_guide.md

File metadata and controls

155 lines (108 loc) · 4.69 KB
Raw

CFT Developer Guide

Overview

The Cloud Foundation toolkit (henceforth, CFT) includes the following parts: project is comprised of two parts:

  • A comprehensive set of production-ready resource templates that follow Google's best practices, which can be used with the CFT or the gcloud utility (part of the Google Cloud SDK)
  • A command-line interface (henceforth, CLI) that deploys resources defined in single or multiple CFT-compliant config files - see the CFT User Guide

This Guide is intended for the developers who are planning to modify and/or programmatically interface with the CFT.

Prerequisites

Google Cloud SDK

  1. Install the Google Cloud SDK, which includes the gcloud CLI.

Because the SDK is not in pypi, its installation cannot be easily automated from within this project, due to the fact that users on the different platforms need the different packages. Follow the SDK installation instructions for your platform.

  1. Ensure that the gcloud CLI is in your user PATH (because the CFT uses this CLI to find the location of the Python libraries included in the SDK).

The gcloud CLI is usually placed in the PATH automatically when you:

  • Install the SDK via the official package manager for your OS (RPM, DEB, etc.), or
  • Use the installer (install.sh) bundled in a Linux tarball

However, if you used neither of the above installation methods, you need to ensure that gcloud can be found in one of the directories specified by the PATH environment variable.

Development Environment

The CFT development environment is based on:

  • Tox for streamlined management of Python virtual environments
  • pytest for unit tests

Proceed as follows:

  1. Install Tox with the system Python.
  2. Install CFT prerequisites:
sudo make cft-prerequisites

The CFT development is carried out in a virtual environment.

  1. Create the virtual development environment called venv with tox in the root of the project directory:
make cft-venv
  1. Activate the virtual environment:
source venv/bin/activate
source src/cftenv

The above activates the virtual environment, then finds the Google SDK path and adds libraries to PYTHONPATH. These cannot be simply added to the Makefile because make creates sanitized sub-shells for each command, and the parent shell does not get the environment variables that the virtual environment sets up on activation.

Note: The tox.ini file in this project is configured to "install" the utility using pip's "develop" mode, i.e., the pip does not actually package and install the utility in the virtual environment's site-packages.

  1. To install or update any of the packages in your virtual environment (created by tox), delete and re-create the environment:
  • Deactivate the virtual environment (if it has been activated):
deactivate
unset CLOUDSDK_ROOT_DIR CLOUDSDK_PYTHON_SITEPACKAGES PYTHONPATH
  • Delete the deactivated virtual environment:
make cft-clean-venv
  • Create the environment as described in Step 3 above.

Unit Tests

You can run the CFT unit tests either from withing your development environment or from outside of it.

From Outside the Development Environment

This testing mode is typically used when running tests from a CI tool.

  1. Use tox to create the necessary virtual environments (not venv, which is used only for active development):
make cft-test
  1. Run all the tests within the "test" virtual environments.

From Within the Development Environment

This testing mode is typically used while actively developing within the development virtual environment.

  1. Activate the venv environment as shown in Step 4 of the Development Environment section.
  2. Source src/cftdev to get PYTHONPATH set as shown in Step 5 of the Development Environment section.
  3. Run tests as follows:
# use the make target to run all tests:
make cft-test-venv

# alternatively, use pytest directly to run all tests:
python -m pytest -v

# alternatively, run a single test file:
python -m pytest -v tests/unit/test_deployment.py