diff --git a/docs/images/infrastructure/network/carp_maintenance.png b/docs/images/infrastructure/network/carp_maintenance.png new file mode 100644 index 0000000000000000000000000000000000000000..0000000000000000000000000000000000000000 GIT binary patch literal 0 Hc$@[From network.uml (line 19) ]... (skipping 15 lines) ...pergamon;group {description = "<b>FIREWALLS</b>";Syntax Error? \ No newline at end of file diff --git a/docs/images/network.uml b/docs/images/network.uml new file mode 100644 --- /dev/null +++ b/docs/images/network.uml @@ -0,0 +1,49 @@ +@startuml + +nwdiag { + inet [ shape = cloud ]; + inet -- inria_gw; + + network VLAN210 { + louvre [address = "VPN" ]; + inria_gw [description = "INRIA GW"]; + } + network VLAN1300 { + workers; + kafka; + inria_gw; + forge; + pergamon; + + group { + description = "FIREWALLS"; + + pushkin; + glyptotek; + } + + } + network VLAN440 { + workers; + pushkin; + glyptotek; + louvre; + forge; + kafka; + pergamon; + production_nodes [description = "Production nodes"]; + } + + network VLAN443 { + pushkin; + glyptotek; + staging_nodes [description = "Staging nodes"]; + } + + network VLAN442 { + pushkin; + glyptotek; + admin_nodes [description = "Admin nodes"]; + } +} +@enduml diff --git a/docs/index.rst b/docs/index.rst --- a/docs/index.rst +++ b/docs/index.rst @@ -52,6 +52,11 @@ * :ref:`roadmap-2021` +Engineering +----------- + +* :ref:`infrastructure` + Components ---------- @@ -196,6 +201,7 @@ contributing/index tutorials/index roadmap/roadmap-2021.rst + infrastructure/index swh.auth swh.core swh.counters diff --git a/docs/infrastructure/index.rst b/docs/infrastructure/index.rst new file mode 100644 --- /dev/null +++ b/docs/infrastructure/index.rst @@ -0,0 +1,14 @@ +.. _infrastructure: + +Infrastructure +############## + +.. keep this in sync with the 'sysadm' section in swh-docs/docs/index.rst + +This section regroups the knowledge base and procedures relative to the |swh| infrastructure management. + +.. toctree:: + :maxdepth: 2 + :titlesonly: + + network diff --git a/docs/infrastructure/network.rst b/docs/infrastructure/network.rst new file mode 100644 --- /dev/null +++ b/docs/infrastructure/network.rst @@ -0,0 +1,151 @@ +Network documentation +##################### + +.. keep this in sync with the 'sysadm' section in swh-docs/docs/index.rst + +This section regroups the knowledge base for our network components. + + +.. toctree:: + :maxdepth: 2 + :titlesonly: + + +Network architecture +******************** + +The network is split in several VLANs provided by the INRIA network team: + +.. thumbnail:: ../images/network.png + + +Firewalls +========= + +The firewalls are 2 `OPNsense `_ VMs deployed on the PROXMOX cluster with an `High Availability `_ configuration. + +They are sharing a virtual IP on each VLAN to act as the gateway. Only one of the 2 firewalls is owning all the GW ips at the same time. The owner is called the ``PRIMARY`` + +.. list-table:: + :header-rows: 1 + + * - Nominal Role + - name (link to the inventory) + - login page + * - PRIMARY + - `pushkin `_ + - `https://pushkin.internal.softwareheritage.org `_ + * - BACKUP + - `glyptotek `_ + - `https://glyptotek.internal.softwareheritage.org `_ + + +Configuration backup +-------------------- + +The configuration is automatically committed on a `git repository `_. +Each firewall regularly pushes its configuration on a dedicated branch of the repository. + +The configuration is visible on the `System / Configuration / Backups `_ page +of each one. + +Upgrade procedure +----------------- + +Initial status +^^^^^^^^^^^^^^ + +This is the nominal status of the firewalls: + +.. list-table:: + :header-rows: 1 + + * - Firewall + - Status + * - pushkin + - PRIMARY + * - glyptotek + - BACKUP + +Preparation +^^^^^^^^^^^ + +* Connect to the `principal `_ (pushkin here) +* Check the `CARP status `_ to ensure the firewall is the principal (must have the status MASTER for all the IPS) +* Connect to the `backup `_ (glytotek here) +* Check the `CARP status `_ to ensure the firewall is the backup (must have the status BACKUP for all the IPS) +* Ensure the 2 firewalls are in sync: + + * On the principal, go to the `High availability status `_ and force a synchronization + * click on the button on the right of ``Synchronize config to backup`` + .. image:: ../images/infrastructure/network/sync.png + +* Switch the principal/backup to prepare the upgrade of the master + (The switch is transparent from the user perspective and can be done without service interruption) + + * [1] On the principal, go to the `Virtual IPS status `_ page + * Activate the CARP maintenance mode + .. image:: ../images/infrastructure/network/carp_maintenance.png + * check the status of the VIPs, they must be ``BACKUP`` on pushkin and ``PRIMARY`` on glyptotek + + +* wait a few minutes to let the monitoring detect if there are connection issues, check ssh connection on several servers on different VLANs (staging, admin, ...) + +If everything is ok, proceed to the next section. + + +Upgrade the first firewall +^^^^^^^^^^^^^^^^^^^^^^^^^^ + +Before starting this section, the firewall statuses should be: + +.. list-table:: + :header-rows: 1 + + * - Firewall + - Status + * - pushkin + - BACKUP + * - glyptotek + - PRIMARY + +If not, be sure of what you are doing and adapt the links accordingly + +* [2] go to the `System Firmware: status `_ page (pushkin here) +* Click on the ``Check for upgrades`` button +.. image:: ../images/infrastructure/network/check_for_upgrade.png +* follow the interface indication, one or several reboots can be necessary depending to the number of upgrade to apply +.. image:: ../images/infrastructure/network/proceed_update.png +* repeat from the ``Check for upgrades`` operation until there is no upgrades to apply +* Switch the principal/backup to restore ``pushkin`` as the principal: + + * on the current backup (pushkin here) go to `Virtual IPS status `_ + * [3] click on `Leave Persistent CARP Maintenance Mode` + .. image:: ../images/infrastructure/network/reactivate_carp.png + * refresh the page, the role should have changed from ``BACKUP`` to ``MASTER`` + * check on the other firewall, if the roles is indeed ``BACKUP`` for all the IPs + +* Wait few moment to ensure everything is ok with the new version + +Upgrade the second firewall +^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +Before starting this section, the firewall statuses should be: + +.. list-table:: + :header-rows: 1 + + * - Firewall + - Status + * - pushkin + - PRIMARY + * - glyptotek + - BACKUP + +If not, be sure of what you are doing and adapt the links accordingly + +* Proceed to the second firewall upgrade + + * perform [1] on the backup (should be ``glyptotek`` here) + * perform [2] on the backup (should be ``glyptotek`` here) + * perform [3] on the backup (should be ``glyptotek`` here)