Metadata-Version: 2.4
Name: vigie
Version: 0.0.1
Summary: VM Migration Scheduler for OpenStack
Home-page: https://www.openstack.org/
Author: OpenStack
Author-email: openstack-discuss@lists.openstack.org
Classifier: Environment :: OpenStack
Classifier: Intended Audience :: Information Technology
Classifier: Intended Audience :: System Administrators
Classifier: License :: OSI Approved :: Apache Software License
Classifier: Operating System :: POSIX :: Linux
Classifier: Programming Language :: Python
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.8
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Requires-Dist: pbr>=5.7.0
Requires-Dist: Flask>=2.0.0
Requires-Dist: oslo.config>=8.7.0
Requires-Dist: oslo.context>=4.1.0
Requires-Dist: oslo.db>=12.1.0
Requires-Dist: oslo.log>=4.1.0
Requires-Dist: oslo.middleware>=5.0.0
Requires-Dist: oslo.messaging>=12.5.2
Requires-Dist: oslo.policy>=3.5
Requires-Dist: keystoneauth1>=4.2
Requires-Dist: keystonemiddleware>=9.1.0
Requires-Dist: alembic>=1.7.0
Requires-Dist: sqlalchemy>=1.4.0
Requires-Dist: tooz>=2.7.1
Requires-Dist: vigietools>=0.0.8
Requires-Dist: python-mistralclient>=4.1.1
Requires-Dist: Jinja2>=2.11.3
Dynamic: author
Dynamic: author-email
Dynamic: classifier
Dynamic: description
Dynamic: home-page
Dynamic: requires-dist
Dynamic: summary

# Table of Contents

- [Waht is Vigie](#what-is-vigie)
  * [General description](#general-description)
  * [Features](#features)
- [Installation](#installation)
  * [Package](#package)
  * [Configuration](#configuration)
- [Usage](#usage)
  * [Starting-up](#starting-up)
  * [Vigie client](#vigie-client)
  * [API Endpoints](#api-endpoints)
- [Internal code structure](#internal-code-structure)
  * [Heritage from Cinder](#heritage-from-cinder)
  * [Writing a new API function](#writing-a-new-api-function)
  * [Using vigietools](#using-vigietools)

# What is Vigie

## General description

Vigie is an OpenStack operator API aimed to ease the administration of an
existing deployment. It typically will be used by operators to do daily tasks
such as purging all resources of a project, evacuate a compute or a network
node for maintenance and more.

## Features

### Currently implemented

* validating a compute node by spaning a VM in it and ssh to the VM

### Planned features

* Public image management (downloads from distro repos)
* Project pre-delete
* Proejct purge of resources
* Emptying / evacuate of a compute node (live and cold migrate depending if VMs support it)
* Emptying / evacutae of a network node (gracefully, with conntrak)

# Installation

## Package

Use the Debian package or invent a deployment method yourself.

## Configuration

The service requires a configuration file typically located at
``/etc/vigie/vigie.conf``.

Example configuration::

```
    [DEFAULT]
    transport_url=rabbit://vigie:PASSWORD@cl1-controller-3.example.com:5671
    [database]
    connection=sqlite:///var/lib/vigie/vigie.db

    [keystone_authtoken]
    www_authenticate_uri = http://keystone:5000
    auth_url = http://keystone:5000
    auth_type = password
    project_domain_name = Default
    user_domain_name = Default
    project_name = service
    username = vigie
    password = vigie_password

    [validate_compute]
    glance_image=debian-13-generic-amd64-daily.qcow2
    flavor=cpu1-ram2-disk5
    network=ext-net1
    ssh_username=debian
    keep_enabled=True
    ssh_use_jump_host=False
    ssh_jump_host_hostname=jump.example.com
    ssh_jump_host_key_file=/etc/vigie/.ssh/id_rsa

    [worker]
    coordination_url=zookeeper://192.168.0.2:2181,192.168.0.66:2181,192.168.0.130:2181/
    mistral_use_keystone_auth=True
```

# Usage

## Starting-up

Start the API service using uwsgi.

Start the worker daemon::

```
vigie-worker
```

The Debian package of course comes with systemd .service unit files,
so it is possible to do:

```
systemctl restart vigie-api
systemctl restart vigie-worker
```

A minimum of one worker is needed, though it is best, for redundancy,
to provision 3 of them. Same for the API.

## Vigie client

Then you may use the vigieclient:

```
openstack vigie validate compute node1.example.com
```

## API Endpoints

* ``POST /v2/evacutate-compute`` - Evacuate a compute node
* ``POST /v2/purge-project`` - Purge a project

# Internal code structure

## Heritage from Cinder

As I have been reading a lot of OpenStack code, I have found
that the Manager class from Cinder was really nice, so I used
that one as an example for writing vigie/manager.py. The
worker in vigie/worker/manager.py is a child class of that one.

## Writing a new API function

The Vigie API uses Flask, as it is the most commonly used,
simple, and understandable framework.

To write a new API route, simply cheat on one of the existing one.
For example:

```
@app.route('/v2/validate-compute', methods=['POST'])
@policy_checker('vigie:validate_compute')
def validate_compute():
```

Simply using the @policy_checker is enough provided that such a
policy is written in vigie/policy/rules.py. The @app.route is
handled by Flask.

## Using vigietools

Vigie is mostly a scheduler for using vigietools. For example,
the validate-compute task will call vigietools's function to
perform the task. The advantage is that vigietools itself also
contains a command line utility (ie: /usr/bin/vgt) that can be
used stand-alone, without the Vigie task manager.

Though Vigie, with its tasks manager, is providing orchestration
and assynchronous tasks, that would otherwise not be possible
with vigietools only.

