Installing for Developers¶

Installing Prerequisites¶

Cloud Custodian supports Python 3.7 and above. To work on Custodian’s code base, you will need:

A make/C toolchain
A supported release of Python 3
Some basic Python tools

Install Python 3¶

You’ll need to have a Python 3 environment set up. You may have a preferred way of doing this. Here are instructions for a way to do it on Ubuntu and Mac OS X.

On Ubuntu¶

Python 3 is included in recent Ubuntu releases.

To install Ubuntu’s default Python 3 version along with additional packages required to manage Python packages and environments, run:

sudo apt-get install python3 python3-venv python3-pip

When this is complete you should be able to check that you have pip properly installed:

python3 -m pip --version
pip 20.0.2 from /usr/lib/python3/dist-packages/pip (python 3.8)

(your exact version numbers will likely differ)

On macOS with Homebrew¶

brew install python3

Installing python3 will get you the latest version of Python 3 supported by Homebrew, currently Python 3.9.

On Windows¶

The Windows Store provides apps for active Python 3 releases.

Other Installation Methods¶

If python3 --version shows a Python version that is not actively supported and the steps above don’t apply to your environment, you can still install a current release of Python manually. This guide may be a useful reference.

Install Poetry¶

Cloud Custodian uses Poetry to manage its dependencies. Once your Python environment is set up, you will need to install install Poetry.

On Mac/Linux¶

curl -sSL https://install.python-poetry.org | python3 -

On Windows with Powershell¶

(Invoke-WebRequest -Uri https://install.python-poetry.org -UseBasicParsing).Content | python -

Installing Custodian¶

First, clone the repository:

git clone https://github.com/cloud-custodian/cloud-custodian.git
cd cloud-custodian

Note

If you have the intention to contribute to Cloud Custodian, it’s better to make a fork of the Cloud-Custodian repository first, and work inside your fork, so that you can push changes to your fork and make a pull request from there. Make the fork from the Github UI, then clone your fork instead of the main repository.

git clone https://github.com/<your github account>/cloud-custodian.git

To keep track of the changes to the original cloud-custodian repository, add a remote upstream repository in your fork:

git remote add upstream https://github.com/cloud-custodian/cloud-custodian.git

Then, to get the upstream changes and merge them into your fork:

git fetch upstream
git merge upstream/main

Now that the repository is set up, perform a developer installation using Poetry:

make install

This creates a sandboxed “virtual environment” (“venv”) inside the cloud-custodian directory, and installs the full suite of Cloud Custodian packages.

You can run tests via Poetry as well:

make test

To run executables from your Poetry environment, precede them with poetry run:

poetry run custodian version

Alternatively, activate a Poetry shell so that commands will run from your development environment by default:

poetry shell
custodian version
custodian schema

You’ll also be able to invoke pytest directly with the arguments of your choosing, though that requires mimicking make test-poetry’s environment preparation:

poetry shell
source test.env
pytest tests/test_s3.py -x -k replication