From 18ae8f4a69ca732c0520385f8366ef32d61f314d Mon Sep 17 00:00:00 2001 From: Anton Smorodskyi Date: Wed, 24 Jul 2024 19:20:09 +0200 Subject: [PATCH] Update and tidy up documentation --- README.md | 82 ++++++++++++++++++++++++++----------------------------- 1 file changed, 38 insertions(+), 44 deletions(-) diff --git a/README.md b/README.md index 7db6d2b8..4c04bf7e 100644 --- a/README.md +++ b/README.md @@ -7,7 +7,7 @@ > **Anton Smorodskyi**: YES, constantly! :partygeeko: I see it in every palm on the beach ! PublicCloud-Watcher (PCW) is a web app which monitors, displays and deletes resources on various Cloud Service Providers (CSPs). -PCW has two main flows : +PCW has three main flows : 1. **Update run ( implemented in [ocw/lib/db.py](ocw/lib/db.py) )** Executed every 45 minutes. Concentrates on deleting VMs (in case of Azure Resource Groups). - Each update scans accounts defined in configuration file and writes the obtained results into a local sqlite database. Newly discovered entities get assigned an obligatory time-to-life value (TTL). TTL may be taken from tag `openqa_ttl` if entity is tagged with such tag if not PCW will check `pcw.ini` for `updaterun/default_ttl` setting and if setting is not defined than PCW will use hard-coded value from [webui/settings.py](webui/settings.py). Database has a web UI where you can manually trigger certain entity deletion. @@ -19,9 +19,10 @@ PCW has two main flows : 2. **Cleanup ( implemented in [ocw/lib/cleanup.py](ocw/lib/cleanup.py) )** Execution via django command. Concentrates on everything except VM deletion. This vary a lot per CSP so let's clarify that on per provider level. - For Azure such entities monitored (check details in [ocw/lib/azure.py](ocw/lib/azure.py)): a. bootdiagnostics - b. Blobs in `sle-images` container - c. Disks assigned to certain resource groups - d. Images assigned to certain resource groups + b. Blobs in all containers + c. Disks assigned to certain resource group defined in pcw.ini ('azure-storage-resourcegroup') + d. Images assigned to certain resource group defined in pcw.ini ('azure-storage-resourcegroup') + e. Image versions assigned to certain resource group defined in pcw.ini ('azure-storage-resourcegroup') - For EC2 such entities monitored (check details in [ocw/lib/ec2.py](ocw/lib/ec2.py)): a. Images in all regions defined b. Snapshots in all region defined @@ -29,35 +30,37 @@ PCW has two main flows : d. VPC's ( deletion of VPC means deletion of all assigned to VPC entities first ( security groups , networks etc. )) - For GCE deleting disks, images & network resources (check details in [ocw/lib/gce.py](ocw/lib/gce.py)) - For Openstack deleting instances, images & keypairs (check details in [ocw/lib/openstack.py](ocw/lib/openstack.py) +3. **Dump entities quantity ( implemented in [ocw/lib/dumpstate.py](ocw/lib/dumpstate.py) )**. To be able to react fast on possible bugs in PCW and/or unexpected creation of many resources there is ability to dump real time data from each CSP into defined InfluxDB instance. This allow building real-time dashboards and/or setup notification flow. The fastest way to run PCW is via the provided containers, as described in the [Running a container](#running-a-container) section. -## Install +# Usage + +## Python virtualenv + +### Requirements files PCW has 3 sets of virtual env requirements files : - [requirements.txt](requirements.txt) common usage for everything except K8S related cleanups - [requirements_k8s.txt](requirements_k8s.txt) due to high volume of dependencies needed only in single use case (k8s cleanups) they excluded in independent category - [requirements_test.txt](requirements_test.txt) contains dependencies allowing to run pcw's unit tests -It's recommended to setup `pcw` in a virtual environment to avoid package collisions: - -```bash -virtualenv venv -. venv/bin/activate -pip install -r requirements.txt -``` - -## Configure and run +### Configuration Configuration of PCW happens via a global config file in `/etc/pcw.ini`. See [templates/pcw.ini](templates/pcw.ini) for a configuration template. To start, copy the template over: +```bash cp templates/pwc.ini /etc/pcw.ini +``` +### CSP credentials To be able to connect to CSP PCW needs Service Principal details. Depending on namespaces defined in `pcw.ini` PCW will expect some JSON files to be created under `/var/pcw/[namespace name]/[Azure/EC2/GCE/Openstack].json`. See [templates/var/example_namespace/](templates/var/example_namespace/) for examples. PCW supports email notifications about left-over instances. See the `notify` section therein and their corresponding comments. +### Build and run + ```bash # Setup virtual environment virtualenv env @@ -79,7 +82,9 @@ python manage.py runserver By default, PCW runs on http://127.0.0.1:8000/ -## Building PCW containers +## PCW in container + +### Available containers In [containers](containers/) folder you main find several Dockerfiles to build several different images: @@ -87,12 +92,12 @@ In [containers](containers/) folder you main find several Dockerfiles to build s - [Dockerfile_k8s](containers/Dockerfile_k8s) image based on [bci-python3.11](https://registry.suse.com/categories/bci-devel/repositories/bci-python311) and can be used to run k8s cleanup - [Dockerfile_k8s_dev](containers/Dockerfile_k8s_dev) and [Dockerfile_dev](containers/Dockerfile_dev) images which contains same set of dependencies as [Dockerfile](containers/Dockerfile) and [Dockerfile_k8s](containers/Dockerfile_k8s) and expect PCW source code to be mounted as volumes. Very usefull for development experiments -## Running a container +### Execution You can use the already build containers within [this repository](https://github.com/orgs/SUSE/packages?repo_name=pcw): ```bash -podman pull ghcr.io/suse/pcw:latest +podman pull ghcr.io/suse/pcw_main:latest podman pull ghcr.io/suse/pcw_k8s:latest ``` @@ -104,7 +109,7 @@ The PCW container supports two volumes to be mounted: To create a container using e.g. the data directory `/srv/pcw` for both volumes and expose port 8000, run the following: ```bash -podman create --hostname pcw --name pcw -v /srv/pcw/pcw.ini:/etc/pcw.ini -v /srv/pcw/db:/pcw/db -v :/var/pcw -p 8000:8000/tcp ghcr.io/suse/pcw:latest +podman create --hostname pcw --name pcw -v /srv/pcw/pcw.ini:/etc/pcw.ini -v /srv/pcw/db:/pcw/db -v :/var/pcw -p 8000:8000/tcp ghcr.io/suse/pcw_main:latest podman start pcw ``` @@ -113,7 +118,7 @@ The `pcw` container runs by default the [/pcw/container-startup](containers/cont ```bash podman exec pcw /pcw/container-startup help -podman run -ti --rm --hostname pcw --name pcw -v /srv/pcw/pcw.ini:/etc/pcw.ini -v :/var/pcw -v /srv/pcw/db:/pcw/db -p 8000:8000/tcp ghcr.io/suse/pcw:latest /pcw/container-startup help +podman run -ti --rm --hostname pcw --name pcw -v /srv/pcw/pcw.ini:/etc/pcw.ini -v :/var/pcw -v /srv/pcw/db:/pcw/db -p 8000:8000/tcp ghcr.io/suse/pcw_main:latest /pcw/container-startup help ``` To create an user within the created container named `pcw`, run @@ -122,33 +127,36 @@ To create an user within the created container named `pcw`, run podman exec pcw /pcw/container-startup createuser admin USE_A_STRONG_PASSWORD ``` -## Devel version of container +### Devel version There is [devel version](containers/Dockerfile_dev) of container file. Main difference is that source files are not copied into image but expected to be mounted via volume. This ease development in environment close as much as possible to production run. Expected use would be : ```bash -make podman-container-devel +make container-devel podman run -v :/etc/pcw.ini -v :/var/pcw -v :/pcw -t pcw-devel "python3 manage.py " ``` +## Test and debug -## Codecov - -Running codecov locally require installation of `pytest pytest-cov codecov`. -Then you can run it with +### Testing ```bash -BROWSER=$(xdg-settings get default-web-browser) -pytest -v --cov=./ --cov-report=html && $BROWSER htmlcov/index.html +virtualenv . +source bin/activate +pip install -r requirements_test.txt +make test ``` -and explore the results in your browser +The tests contain a Selenium test for the webUI that uses Podman. Make sure that you have the latest [geckodriver](https://github.com/mozilla/geckodriver/releases) installed anywhere in your `PATH` and that the `podman.socket` is enabled: +`systemctl --user enable --now podman.socket` + +Set the `SKIP_SELENIUM` environment variable when running `pytest` or `make test` to skip the Selenium test. -## Debug +### Debug -To simplify problem investigation pcw has two [django commands](https://docs.djangoproject.com/en/3.1/howto/custom-management-commands/) : +To simplify problem investigation pcw has several [django commands](https://docs.djangoproject.com/en/3.1/howto/custom-management-commands/) : [cleanup](ocw/management/commands/cleanup.py) @@ -160,17 +168,3 @@ To simplify problem investigation pcw has two [django commands](https://docs.dja those allows triggering core functionality without web UI. It is highly recommended to use `dry_run = True` in `pcw.ini` in such cases. - -## Testing - -```bash -virtualenv . -source bin/activate -pip install -r requirements_test.txt -make test -``` - -The tests contain a Selenium test for the webUI that uses Podman. Make sure that you have the latest [geckodriver](https://github.com/mozilla/geckodriver/releases) installed anywhere in your `PATH` and that the `podman.socket` is enabled: -`systemctl --user enable --now podman.socket` - -Set the `SKIP_SELENIUM` environment variable when running `pytest` or `make test` to skip the Selenium test.