Reorganize manuals and architecture pages
This commit is contained in:
parent
26084741d0
commit
4fe3a73980
|
|
@ -1,43 +0,0 @@
|
|||
# PVC Ansible architecture
|
||||
|
||||
The PVC Ansible setup and management framework is written in Ansible. It consists of two roles: `base` and `pvc`.
|
||||
|
||||
## Base role
|
||||
|
||||
The Base role configures a node to a specific, standard base Debian system, with a number of PVC-specific tweaks. Some examples include:
|
||||
|
||||
* Installing the custom PVC repository at Boniface Labs.
|
||||
|
||||
* Removing several unnecessary packages and installing numerous additional packages.
|
||||
|
||||
* Automatically configuring network interfaces based on the `group_vars` configuration.
|
||||
|
||||
* Configuring several general `sysctl` settings for optimal performance.
|
||||
|
||||
* Installing and configuring rsyslog, postfix, ntpd, ssh, and fail2ban.
|
||||
|
||||
* Creating the users specified in the `group_vars` configuration.
|
||||
|
||||
* Installing custom MOTDs, bashrc files, vimrc files, and other useful configurations for each user.
|
||||
|
||||
The end result is a standardized "PVC node" system ready to have the daemons installed by the PVC role.
|
||||
|
||||
## PVC role
|
||||
|
||||
The PVC role configures all the dependencies of PVC, including storage, networking, and databases, then installs the PVC daemon itself. Specifically, it will, in order:
|
||||
|
||||
* Install Ceph, configure and bootstrap a new cluster if `bootstrap=yes` is set, configure the monitor and manager daemons, and start up the cluster ready for the addition of OSDs via the client interface (coordinators only).
|
||||
|
||||
* Install, configure, and if `bootstrap=yes` is set, bootstrap a Zookeeper cluster (coordinators only).
|
||||
|
||||
* Install, configure, and if `bootstrap=yes` is set`, bootstrap a Patroni PostgreSQL cluster for the PowerDNS aggregator (coordinators only).
|
||||
|
||||
* Install and configure Libvirt.
|
||||
|
||||
* Install and configure FRRouting.
|
||||
|
||||
* Install and configure the main PVC daemon and API client, including initializing the PVC cluster (`pvc init`).
|
||||
|
||||
## Completion
|
||||
|
||||
Once the entire playbook has run for the first time against a given host, the host will be rebooted to apply all the configured services. On startup, the system should immediately launch the PVC daemon, check in to the Zookeeper cluster, and become ready. The node will be in `flushed` state on its first boot; the administrator will need to run `pvc node unflush <node>` to set the node into active state ready to handle virtual machines.
|
||||
|
|
@ -1,7 +0,0 @@
|
|||
# PVC API architecture
|
||||
|
||||
The PVC API is a standalone client application for PVC. It interfaces directly with the Zookeeper database to manage state.
|
||||
|
||||
The API is built using Flask and is packaged in the Debian package `pvc-client-api`. The API depends on the common client functions of the `pvc-client-common` package as does the CLI client.
|
||||
|
||||
Details of the API interface can be found in [the manual](/manuals/api).
|
||||
|
|
@ -1,7 +0,0 @@
|
|||
# PVC CLI architecture
|
||||
|
||||
The PVC CLI is a standalone client application for PVC. It interfaces with the PVC API, via a configurable list of clusters with customizable hosts, ports, addresses, and authentication.
|
||||
|
||||
The CLI is build using Click and is packaged in the Debian package `pvc-client-cli`. The CLI does not depend on any other PVC components and can be used independently on arbitrary systems.
|
||||
|
||||
The CLI is self-documenting, however [the manual](/manuals/cli) details the required configuration.
|
||||
|
|
@ -1,53 +0,0 @@
|
|||
# PVC Node Daemon architecture
|
||||
|
||||
The PVC Node Daemon is the heart of the PVC system and runs on each node to manage the state of the node and its configured resources. The daemon connects directly to the Zookeeper cluster for coordination and state.
|
||||
|
||||
The node daemon is build using Python 3.X and is packaged in the Debian package `pvc-daemon`.
|
||||
|
||||
Configuration of the daemon is documented in [the manual](/manuals/daemon), however it is recommended to use the [Ansible configuration interface](/manuals/ansible) to configure the PVC system for you from scratch.
|
||||
|
||||
## Overall architecture
|
||||
|
||||
The PVC daemon is object-oriented - each cluster resource is represented by an Object, which is then present on each node in the cluster. This allows state changes to be reflected across the entire cluster should their data change.
|
||||
|
||||
During startup, the system scans the Zookeeper database and sets up the required objects. The database is then watched in real-time for additional changes to the database information.
|
||||
|
||||
## Startup sequence
|
||||
|
||||
The daemon startup sequence is documented below. The main daemon entry-point is `Daemon.py` inside the `pvcnoded` folder, which is called from the `pvcnoded.py` stub file.
|
||||
|
||||
0. The configuration is read from `/etc/pvc/pvcnoded.yaml` and the configuration object set up.
|
||||
|
||||
0. Any required filesystem directories, mostly dynamic directories, are created.
|
||||
|
||||
0. The logger is set up. If file logging is enabled, this is the state when the first log messages are written.
|
||||
|
||||
0. Host networking is configured based on the `pvcnoded.yaml` configuration file. In a normal cluster, this is the point where the node will become reachable on the network as all networking is handled by the PVC node daemon.
|
||||
|
||||
0. Sysctl tweaks are applied to the host system, to enable routing/forwarding between nodes via the host.
|
||||
|
||||
0. The node determines its coordinator state and starts the required daemons if applicable. In a normal cluster, this is the point where the dependent services such as Zookeeper, FRR, and Ceph become available. After this step, the daemon waits 5 seconds before proceeding to give these daemons a chance to start up.
|
||||
|
||||
0. The daemon connects to the Zookeeper cluster and starts its listener. If the Zookeeper cluster is unavailable, it will wait some time before abandoning the attempt and starting again from step 1.
|
||||
|
||||
0. Termination handling/cleanup is configured.
|
||||
|
||||
0. The node checks if it is already present in the Zookeeper cluster; if not, it will add itself to the database. Initial static options are also updated in the database here. The daemon state transitions from `stop` to `init`.
|
||||
|
||||
0. The node checks if Libvirt is accessible.
|
||||
|
||||
0. The node starts up the NFT firewall if applicable and configures the base rule-set.
|
||||
|
||||
0. The node ensures that `dnsmasq` is stopped (legacy check, might be safe to remove eventually).
|
||||
|
||||
0. The node begins setting up the object representations of resources, in order:
|
||||
|
||||
a. Node entries
|
||||
|
||||
b. Network entries, creating client networks and starting them as required.
|
||||
|
||||
c. Domain (VM) entries, starting up the VMs as required.
|
||||
|
||||
d. Ceph storage entries (OSDs, Pools, Volumes, Snapshots).
|
||||
|
||||
0. The node activates its keepalived timer and begins sending keepalive updates to the cluster. The daemon state transitions from `init` to `run` and the system has started fully.
|
||||
|
|
@ -1,3 +1,47 @@
|
|||
# PVC Ansible architecture
|
||||
|
||||
The PVC Ansible setup and management framework is written in Ansible. It consists of two roles: `base` and `pvc`.
|
||||
|
||||
## Base role
|
||||
|
||||
The Base role configures a node to a specific, standard base Debian system, with a number of PVC-specific tweaks. Some examples include:
|
||||
|
||||
* Installing the custom PVC repository at Boniface Labs.
|
||||
|
||||
* Removing several unnecessary packages and installing numerous additional packages.
|
||||
|
||||
* Automatically configuring network interfaces based on the `group_vars` configuration.
|
||||
|
||||
* Configuring several general `sysctl` settings for optimal performance.
|
||||
|
||||
* Installing and configuring rsyslog, postfix, ntpd, ssh, and fail2ban.
|
||||
|
||||
* Creating the users specified in the `group_vars` configuration.
|
||||
|
||||
* Installing custom MOTDs, bashrc files, vimrc files, and other useful configurations for each user.
|
||||
|
||||
The end result is a standardized "PVC node" system ready to have the daemons installed by the PVC role.
|
||||
|
||||
## PVC role
|
||||
|
||||
The PVC role configures all the dependencies of PVC, including storage, networking, and databases, then installs the PVC daemon itself. Specifically, it will, in order:
|
||||
|
||||
* Install Ceph, configure and bootstrap a new cluster if `bootstrap=yes` is set, configure the monitor and manager daemons, and start up the cluster ready for the addition of OSDs via the client interface (coordinators only).
|
||||
|
||||
* Install, configure, and if `bootstrap=yes` is set, bootstrap a Zookeeper cluster (coordinators only).
|
||||
|
||||
* Install, configure, and if `bootstrap=yes` is set`, bootstrap a Patroni PostgreSQL cluster for the PowerDNS aggregator (coordinators only).
|
||||
|
||||
* Install and configure Libvirt.
|
||||
|
||||
* Install and configure FRRouting.
|
||||
|
||||
* Install and configure the main PVC daemon and API client, including initializing the PVC cluster (`pvc init`).
|
||||
|
||||
## Completion
|
||||
|
||||
Once the entire playbook has run for the first time against a given host, the host will be rebooted to apply all the configured services. On startup, the system should immediately launch the PVC daemon, check in to the Zookeeper cluster, and become ready. The node will be in `flushed` state on its first boot; the administrator will need to run `pvc node unflush <node>` to set the node into active state ready to handle virtual machines.
|
||||
|
||||
# PVC Ansible configuration manual
|
||||
|
||||
This manual documents the various `group_vars` configuration options for the `pvc-ansible` framework. We assume that the administrator is generally familiar with Ansible and its operation.
|
||||
|
|
|
|||
|
|
@ -1,3 +1,11 @@
|
|||
# PVC API architecture
|
||||
|
||||
The PVC API is a standalone client application for PVC. It interfaces directly with the Zookeeper database to manage state.
|
||||
|
||||
The API is built using Flask and is packaged in the Debian package `pvc-client-api`. The API depends on the common client functions of the `pvc-client-common` package as does the CLI client.
|
||||
|
||||
Details of the API interface can be found in [the manual](/manuals/api).
|
||||
|
||||
# PVC HTTP API manual
|
||||
|
||||
The PVC HTTP API client is built with Flask, a Python framework for creating API interfaces, and run directly with the PyWSGI framework. It interfaces directly with the Zookeeper cluster to send and receive information about the cluster. It supports authentication configured statically via tokens in the configuration file as well as SSL. It also includes the provisioner client, an optional section that can be used to create VMs automatically using a set of templates and standardized scripts.
|
||||
|
|
|
|||
|
|
@ -1,3 +1,11 @@
|
|||
# PVC CLI architecture
|
||||
|
||||
The PVC CLI is a standalone client application for PVC. It interfaces with the PVC API, via a configurable list of clusters with customizable hosts, ports, addresses, and authentication.
|
||||
|
||||
The CLI is build using Click and is packaged in the Debian package `pvc-client-cli`. The CLI does not depend on any other PVC components and can be used independently on arbitrary systems.
|
||||
|
||||
The CLI is self-documenting, however [the manual](/manuals/cli) details the required configuration.
|
||||
|
||||
# PVC CLI client manual
|
||||
|
||||
The PVC CLI client is built with Click, a Python framework for creating self-documenting CLI applications. It interfaces with the PVC API.
|
||||
|
|
|
|||
|
|
@ -1,3 +1,57 @@
|
|||
# PVC Node Daemon architecture
|
||||
|
||||
The PVC Node Daemon is the heart of the PVC system and runs on each node to manage the state of the node and its configured resources. The daemon connects directly to the Zookeeper cluster for coordination and state.
|
||||
|
||||
The node daemon is build using Python 3.X and is packaged in the Debian package `pvc-daemon`.
|
||||
|
||||
Configuration of the daemon is documented in [the manual](/manuals/daemon), however it is recommended to use the [Ansible configuration interface](/manuals/ansible) to configure the PVC system for you from scratch.
|
||||
|
||||
## Overall architecture
|
||||
|
||||
The PVC daemon is object-oriented - each cluster resource is represented by an Object, which is then present on each node in the cluster. This allows state changes to be reflected across the entire cluster should their data change.
|
||||
|
||||
During startup, the system scans the Zookeeper database and sets up the required objects. The database is then watched in real-time for additional changes to the database information.
|
||||
|
||||
## Startup sequence
|
||||
|
||||
The daemon startup sequence is documented below. The main daemon entry-point is `Daemon.py` inside the `pvcnoded` folder, which is called from the `pvcnoded.py` stub file.
|
||||
|
||||
0. The configuration is read from `/etc/pvc/pvcnoded.yaml` and the configuration object set up.
|
||||
|
||||
0. Any required filesystem directories, mostly dynamic directories, are created.
|
||||
|
||||
0. The logger is set up. If file logging is enabled, this is the state when the first log messages are written.
|
||||
|
||||
0. Host networking is configured based on the `pvcnoded.yaml` configuration file. In a normal cluster, this is the point where the node will become reachable on the network as all networking is handled by the PVC node daemon.
|
||||
|
||||
0. Sysctl tweaks are applied to the host system, to enable routing/forwarding between nodes via the host.
|
||||
|
||||
0. The node determines its coordinator state and starts the required daemons if applicable. In a normal cluster, this is the point where the dependent services such as Zookeeper, FRR, and Ceph become available. After this step, the daemon waits 5 seconds before proceeding to give these daemons a chance to start up.
|
||||
|
||||
0. The daemon connects to the Zookeeper cluster and starts its listener. If the Zookeeper cluster is unavailable, it will wait some time before abandoning the attempt and starting again from step 1.
|
||||
|
||||
0. Termination handling/cleanup is configured.
|
||||
|
||||
0. The node checks if it is already present in the Zookeeper cluster; if not, it will add itself to the database. Initial static options are also updated in the database here. The daemon state transitions from `stop` to `init`.
|
||||
|
||||
0. The node checks if Libvirt is accessible.
|
||||
|
||||
0. The node starts up the NFT firewall if applicable and configures the base rule-set.
|
||||
|
||||
0. The node ensures that `dnsmasq` is stopped (legacy check, might be safe to remove eventually).
|
||||
|
||||
0. The node begins setting up the object representations of resources, in order:
|
||||
|
||||
a. Node entries
|
||||
|
||||
b. Network entries, creating client networks and starting them as required.
|
||||
|
||||
c. Domain (VM) entries, starting up the VMs as required.
|
||||
|
||||
d. Ceph storage entries (OSDs, Pools, Volumes, Snapshots).
|
||||
|
||||
0. The node activates its keepalived timer and begins sending keepalive updates to the cluster. The daemon state transitions from `init` to `run` and the system has started fully.
|
||||
|
||||
# PVC Node Daemon manual
|
||||
|
||||
The PVC node daemon ins build with Python 3 and is run directly on nodes. For details of the startup sequence and general layout, see the [architecture document](/architecture/daemon).
|
||||
|
|
|
|||
|
|
@ -1,4 +1,4 @@
|
|||
# PVC Provisioner API architecture
|
||||
# PVC Provisioner manual
|
||||
|
||||
The PVC provisioner is a subsection of the main PVC API. IT interfaces directly with the Zookeeper database using the common client functions, and with the Patroni PostgreSQL database to store details. The provisioner also interfaces directly with the Ceph storage cluster, for mapping volumes, creating filesystems, and installing guests.
|
||||
|
||||
Loading…
Reference in New Issue