Metadata-Version: 2.4
Name: vigietools
Version: 0.0.11
Summary: OpenStack OPS API tools
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: keystoneauth1
Requires-Dist: oslo.config
Requires-Dist: oslo.context
Requires-Dist: oslo.log
Requires-Dist: openstacksdk
Requires-Dist: paramiko
Requires-Dist: requests
Requires-Dist: PyYAML
Dynamic: author
Dynamic: author-email
Dynamic: classifier
Dynamic: description
Dynamic: home-page
Dynamic: requires-dist
Dynamic: summary

# About

This project is a collection of OpenStack OPS tools.

# More in details

This package contains tools useful for OpenStack cloud administrators. It
includes things like:

  * Validating a compute host before putting it into service.
  * Suspending, unsuspending and purging the resources of a project.
  * Downloading, uploading and keeping up to date the public cloud
    images of the free software distributions (Debian, Ubuntu, CentOS,
    Rocky, AlmaLinux, Fedora, openSUSE, Arch, and more).

It can be used either on the command line, using /usr/bin/vgt, or as a
Python module, called by a higher level thing.

# Example usage for validating a compute:

```
vgt validate-compute \
	--image-name debian-image \
	--flavor-name cpu2-ram6-disk0 \
	--network-name ext-net1 \
	--host cluster1-compute-2.example.com \
	--keep-enabled
```

Once done validating multiple compute nodes, one can:

```
vgt validate-cleanup
```

If the compute node isn't directly reachable over SSH, connections can
be proxied through a jump/bastion host:

```
vgt validate-compute \
	--host cluster1-compute-2.example.com \
	--jump-host bastion.example.com \
	--jump-username admin \
	--jump-port 22 \
	--jump-key-file ~/.ssh/bastion_key
```

This will:
- create an aggregate "hosts-to-validate"
- add the trait: CUSTOM_COMPUTE_TO_VALIDATE
- Make this trait required for that aggregate
- add the trait to the compute
- create a new "vgt" project and user
- create a bootable volume
- add the trait:CUSTOM_COMPUTE_TO_VALIDATE as required on that volume
- boot a VM from that volume
- make sure it is possible to ssh the newly created VM

After validate-compute the compute node trait is removed.

validate-cleanup deletes the aggregate and custom trait.

# Example usage for the project operations:

Three sub-commands take care of the resources of a whole project:
project-suspend, project-unsuspend and project-purge. They all take
the project to operate on, either by name or ID:

```
vgt project-suspend --target-project myproject
```

Suspending a project removes the Swift container ACLs, stops every
server (unlock, confirm resize, unrescue and unpause first), suspends
the Heat stacks and disables the load balancers. The Designate zones
are left alone so that the suspension stays reversible, and the
keystone project is disabled so that no new token can be issued for
it.

The operation runs as a temporary user created in the project and
deleted again afterwards. By default, this user gets the member,
creator, SwiftOperator, ResellerAdmin and load-balancer_member
roles; this can be replaced with a comma separated list:

```
vgt project-suspend --target-project myproject \
	--tmp-user-role member,SwiftOperator
```

Unsuspending a project reverses what can be reversed (resume the
suspended stacks, re-enable the load balancers, unshelve the shelved
servers) and re-enables the keystone project. The servers which were
stopped by the suspension are not restarted: this is left to the end
user.

```
vgt project-unsuspend --target-project myproject
```

Purging a project destroys everything it holds, no question asked:
load balancers, servers, floating IPs, routers, ports, subnets,
networks, security groups, DNS zones, images, volumes and snapshots,
Barbican secrets, Heat stacks, then the Swift data, with a final
check that nothing was left behind. The keystone project is left
alone by default; with --delete-project, it is deleted as well once
the purge succeeded:

```
vgt project-purge --target-project myproject
```

The project operations can also be called as a Python module, which
is how a task manager is expected to use them:

```
from vigietools.project import purge_project

success, error_message = purge_project(conn=conn,
                                       project='myproject')
```

# Example usage for the public images:

The public cloud images of the free software distributions are
described by YAML files under
/etc/vigietools/glance-public-images.d/, one directory per
distribution, and are managed with:

```
vgt image-distro-list
vgt image-suite-list --distro debian
vgt image-download --distro cirros --suite latest
vgt image-upload --distro debian --suite trixie
vgt image-update
```

The whole configuration file format, the discovery steps, the
checksum handling, the Swift hosted images and the web-download
import are documented in
[doc/glance-images.md](doc/glance-images.md).

As for the project operations, everything is callable as a Python
module, which is how a task manager is expected to use them:

```
from vigietools.glance_images import manager

image, error_message = manager.upload_image(conn=conn,
                                            distro='debian',
                                            suite='trixie',
                                            callback=callback)
success, error_message = manager.update_images(conn=conn)
```

