Skip to content
Snippets Groups Projects

Compare revisions

Changes are shown as if the source revision was being merged into the target revision. Learn more about comparing revisions.

Source

Select target project
No results found

Target

Select target project
  • ardumont/swh-docs
  • anlambert/swh-docs
  • douardda/swh-docs
  • vlorentz/swh-docs
  • vsellier/swh-docs
  • lunar/swh-docs
  • cmatrix/swh-docs
  • bchauvet/swh-docs
  • guillaume/swh-docs
  • HarshvMahawar/swh-docs
  • swh/devel/swh-docs
  • olasd/swh-docs
  • pabs/swh-docs
  • rboyer/swh-docs
  • marmoute/swh-docs
  • varasterix/swh-docs
16 results
Show changes
Expand all Hide whitespace changes
Inline Side-by-side
Showing
with 2455 additions and 93 deletions
docs/devel/roadmap/roadmap-2024.rst 0 → 100644
View file @ bf2aa56d
This diff is collapsed.
docs/devel/services.txt
View file @ bf2aa56d
......@@ -15,6 +15,7 @@ swh-search: 5010
swh-counters: 5011
swh-winery: 5012
swh-graphql: 5013
swh-provenance: 5014
# Edit this line with your nick to get a merge conflict if there's an overlap
# Next available ID (jayeshv) : 5014
# Next available ID (ardumont) : 5015
docs/devel/tutorials/add-new-package.rst
View file @ bf2aa56d
......@@ -15,65 +15,29 @@ project to the documentation.
Create a project
----------------
Creating the project should be done using the ``gitlab`` command-line tool
provided by the `python-gitlab <https://python-gitlab.readthedocs.io/>`_ module.
Make sure to have the configuration working and an access token with ``api`` as
scope.
To create the project:
.. code:: bash
PROJECT_NAME=swh-foo
DESCRIPTION="Software Heritage Foo management library"
NAMESPACE_ID="$(gitlab --output json namespace get --id 'swh/devel' | jq .id)"
gitlab project create \
--name "$PROJECT_NAME" \
--path "$PROJECT_NAME" \
--namespace "$NAMESPACE_ID" \
--description "$DESCRIPTION" \
--issues-access-level enabled \
--auto-devops-enabled false \
--wiki-access-level disabled \
--requirements-access-level disabled \
--pages-access-level disabled \
--operations-access-level disabled \
--container-registry-access-level disabled \
--visibility public
Initialize the repository with our template
-------------------------------------------
Creating the project from swh-py-template_ can be done using the
``bin/init-py-repo`` tool. This script uses the ``gitlab`` command-line tool
provided by the `python-gitlab <https://python-gitlab.readthedocs.io/>`_
module. Before running ``init-py-repo``, please make sure that the ``gitlab``
command is working and configured with an access token of scope ``api``.
The following commands need to run from the base directory
``swh-environment``.
1. Clone the new repository:
.. code:: bash
git clone https://gitlab.softwareheritage.org/swh/devel/swh-foo.git
1. Use ``bin/init-py-repo`` to initialize the repository with a project
template and create the corresponding gitlab project:
2. Use ``bin/init-py-repo`` to initialize the repository with a project template:
.. code:: bash
.. code-block:: console
pip install -r requirements.txt
bin/init-py-repo swh-foo
3. Install the pre-commit hook:
2. Install the pre-commit hook:
.. code:: bash
.. code-block:: console
pre-commit install
Customize the template
----------------------
Now look for the string ``foo`` in all files and file names and replace it with
the name of the new package. Push these commits directly to the repository as
initial content.
For an example, you can see `what was done for swh-counters <https://gitlab.softwareheritage.org/swh/devel/swh-counters/-/commit/142fff84305b>`__.
Add the repo on the swh-environment project
-------------------------------------------
......@@ -99,13 +63,25 @@ Install CI jobs
``swh-jenkins-jobs`` repository. See `Jenkins documentation <ci_jenkins>`_
for details.
Hack hack hack
--------------
The generated project should have everything needed to start hacking in. You
should typically start with:
- fill the README file
- write some code in ``swh/foo``
- write tests in ``swh/foo/tests``
- add yourself in ``CONTRIBUTORS`` if needed
- add some sphinx documentation in ``docs``
Make an initial release
-----------------------
Releases are made automatically by Jenkins when a tag is pushed to a module
repository. Making an initial release is thus done by doing:
.. code:: bash
.. code-block:: console
git tag v0.0.0
git push origin --tags v0.0.0
......@@ -132,7 +108,7 @@ To add a new module to the documentation:
- Add the package with a concise description to the index of the development part, located in
``docs/devel/index.rst``.
::
.. code-block:: rst
:ref:`swh.foo <swh-foo>`
short description of the repository
......@@ -143,5 +119,6 @@ To add a new module to the documentation:
.. _`Continuous Integration (CI)`: https://jenkins.softwareheritage.org
.. _swh-py-template: https://gitlab.softwareheritage.org/swh/devel/swh-py-template
.. _swh-jenkins-jobs: https://gitlab.softwareheritage.org/swh/infra/ci-cd/swh-jenkins-jobs
.. _swh-docs: https://gitlab.softwareheritage.org/swh/devel/swh-docs
docs/index.rst
View file @ bf2aa56d
......@@ -24,7 +24,7 @@ Welcome to Software Heritage documentation
.. button-ref:: landing-basics
:ref-type: ref
:color: secondary
:color: primary
:expand:
Discover Software Heritage
......@@ -41,7 +41,7 @@ Welcome to Software Heritage documentation
.. button-ref:: landing-preserve
:ref-type: ref
:color: secondary
:color: primary
:expand:
Archive source code
......@@ -59,7 +59,7 @@ Welcome to Software Heritage documentation
.. button-ref:: landing-browse
:ref-type: ref
:color: secondary
:color: primary
:expand:
Learn how to search the archive
......@@ -76,7 +76,7 @@ Welcome to Software Heritage documentation
Join our network of partners. Collaborate with the team or become an ambassador. Teach others how to use the archive. Get materials for your next events.
.. button-link:: http://example.com
:color: secondary
:color: primary
:expand:
Tell the world about Software Heritage
......@@ -94,7 +94,7 @@ Welcome to Software Heritage documentation
.. button-ref:: landing-interface
:ref-type: ref
:color: secondary
:color: primary
:expand:
Use Software Heritage in your applications
......@@ -112,7 +112,7 @@ Welcome to Software Heritage documentation
.. button-ref:: landing-contribute
:ref-type: ref
:color: secondary
:color: primary
:expand:
Improve the universal archive of source code
......@@ -280,7 +280,7 @@ Search, browse and reference
code <https://www.softwareheritage.org/howto-archive-and-reference-your-code/>`__
- `Make your code identifiable : get a PID for your source
code <https://annex.softwareheritage.org/public/tutorials/getswhid_dir.gif>`__
- `Choosing what type of Software Heritage Identifier (SWHID) to
- `Choosing what type of Software Hash Identifier (SWHID) to
use <devel/swh-model/persistent-identifiers.html#choosing-what-type-of-swhid-to-use>`__
- `Navigating through Software Heritage: behind the
scenes <https://www.softwareheritage.org/2019/05/28/mining-software-metadata-for-80-m-projects-and-even-more/>`__
......@@ -321,6 +321,7 @@ Ambassador program
- `Ambassadors mailing list <https://sympa.inria.fr/sympa/info/swh-ambassadors>`__
- `Outreach material (only available to ambassadors) <https://www.softwareheritage.org/ambassador-material/>`__
- `Outreach material on a Git repository <https://github.com/moranegg/swh-ambassadors/tree/main/Materials>`__
- `Questions Frequently Asked to ambassadors <https://gitlab.softwareheritage.org/outreach/swh-academy/swh-faq>`__
Presentations
-------------
......@@ -365,7 +366,7 @@ Data model and identifiers
- `Our data
model <devel/swh-model/data-model.html#data-model>`__
- :ref:`Software Heritage IDentifiers
- :ref:`Software Hash IDentifiers
(SWHID) <persistent-identifiers>` specifications
- Compute a SWHID locally using the `swh identify <devel/swh-model/cli.html>`__ command-line tool.
......@@ -437,3 +438,4 @@ Table of contents
devel/api-reference
user/index
sysadm/index
About this documentation project <README>
docs/software-origins-support.yml
View file @ bf2aa56d
......@@ -4,9 +4,13 @@ forges:
lister:
status: dev
issue: https://gitlab.softwareheritage.org/swh/meta/-/issues/4233
supports_last_update: true
loader:
status: dev
issue: https://gitlab.softwareheritage.org/swh/meta/-/issues/4233
metadata:
intrinsic: collected
extrinsic: none
grant: sloan-hashbang-2022
developer: hashbang
......@@ -17,15 +21,22 @@ forges:
loader:
status: prod
id_in_swh_web: tar
metadata:
intrinsic: none
extrinsic: none
aur:
name: AUR
lister:
status: dev
issue: https://gitlab.softwareheritage.org/swh/meta/-/issues/4466
supports_last_update: true
loader:
status: dev
issue: https://gitlab.softwareheritage.org/swh/meta/-/issues/4466
metadata:
intrinsic: collected
extrinsic: none
grant: sloan-hashbang-2022
developer: hashbang
......@@ -37,6 +48,9 @@ forges:
status: prod
source: https://gitlab.softwareheritage.org/swh/devel/swh-loader-bzr/
package_name: swh.loader.bzr
metadata:
intrinsic: none
extrinsic: none
grant: sloan-octobus-2021
developer: octobus
......@@ -44,15 +58,23 @@ forges:
name: Bitbucket
lister:
status: prod
supports_last_update: true
loader:
status: N/A
metadata:
intrinsic: none
extrinsic: not collected
bower:
name: Bower
lister:
status: staging
supports_last_update: false
loader:
status: N/A
metadata:
intrinsic: none
extrinsic: not collected
grant: nlnet-octobus-2022
developer: octobus
......@@ -60,17 +82,25 @@ forges:
name: CGit
lister:
status: prod
supports_last_update: true
loader:
status: N/A
metadata:
intrinsic: none
extrinsic: not collected
conda:
name: Conda
lister:
status: dev
issue: https://gitlab.softwareheritage.org/swh/devel/swh-lister/-/issues/4547
supports_last_update: true
loader:
status: dev
issue: https://gitlab.softwareheritage.org/swh/devel/swh-loader-core/-/issues/4579
metadata:
intrinsic: collected
extrinsic: not collected
grant: nlnet-octobus-2022
developer: octobus
......@@ -78,9 +108,14 @@ forges:
name: CPAN
lister:
status: dev
issue: https://gitlab.softwareheritage.org/swh/devel/swh-lister/-/issues/2833
issue: https://gitlab.softwareheritage.org/swh/devel/swh-lister/-/issues/4520
supports_last_update: true
loader:
status: N/A
status: dev
issue: https://gitlab.softwareheritage.org/swh/devel/swh-lister/-/issues/2833
metadata:
intrinsic: collected
extrinsic: not collected
grant: nlnet-octobus-2022
developer: octobus
......@@ -89,17 +124,25 @@ forges:
lister:
status: prod
id_in_swh_web: CRAN
supports_last_update: true
loader:
status: prod
metadata:
intrinsic: collected
extrinsic: none
crates:
name: Crates
lister:
status: dev
issue: https://gitlab.softwareheritage.org/swh/devel/swh-lister/-/issues/1424
supports_last_update: true
loader:
status: dev
issue: https://gitlab.softwareheritage.org/swh/meta/-/issues/4104
metadata:
intrinsic: collected
extrinsic: not collected
grant: sloan-hashbang-2022
developer: hashbang
......@@ -111,6 +154,9 @@ forges:
status: prod
source: https://gitlab.softwareheritage.org/swh/devel/swh-loader-cvs/
package_name: swh.loader.cvs
metadata:
intrinsic: none
extrinsic: none
grant: sloan-stsp-cvs
developer: stsp
......@@ -118,9 +164,13 @@ forges:
name: Debian
lister:
status: prod
supports_last_update: true
loader:
status: prod
id_in_swh_web: deb
metadata:
intrinsic: collected
extrinsic: not collected
deposit:
name: Deposit
......@@ -128,14 +178,21 @@ forges:
status: N/A
loader:
status: prod
metadata:
intrinsic: indexed
extrinsic: indexed
gitea:
name: Gitea
notes: "Reuses the Gogs lister"
lister:
status: prod
supports_last_update: true
loader:
status: N/A
metadata:
intrinsic: none
extrinsic: indexed
git:
name: Git
......@@ -145,44 +202,67 @@ forges:
status: prod
source: https://gitlab.softwareheritage.org/swh/devel/swh-loader-git/
package_name: swh.loader.git
metadata:
intrinsic: none
extrinsic: none
github:
name: GitHub
lister:
status: prod
supports_last_update: true
loader:
status: N/A
metadata:
intrinsic: none
extrinsic: indexed
gitlab:
name: GitLab
notes: "Also supports `Heptapod <https://heptapod.net/>`_"
lister:
status: prod
supports_last_update: true
loader:
status: N/A
metadata:
intrinsic: none
extrinsic: not collected
gnu:
name: GNU
lister:
status: prod
id_in_swh_web: GNU
supports_last_update: true
loader:
status: N/A
metadata:
intrinsic: collected
extrinsic: none
gogs:
name: Gogs
lister:
status: dev
status: prod
issue: https://gitlab.softwareheritage.org/swh/devel/swh-lister/-/issues/1721
supports_last_update: true
loader:
status: N/A
metadata:
intrinsic: none
extrinsic: not collected
golang:
name: Golang
lister:
status: staging
status: prod
supports_last_update: true
loader:
status: staging
status: prod
metadata:
intrinsic: none
extrinsic: none
grant: nlnet-octobus-2022
developer: octobus
......@@ -191,9 +271,13 @@ forges:
lister:
status: dev
issue: https://gitlab.softwareheritage.org/swh/meta/-/issues/4494
supports_last_update: true
loader:
status: dev
issue: https://gitlab.softwareheritage.org/swh/meta/-/issues/4494
metadata:
intrinsic: collected
extrinsic: none
grant: nlnet-octobus-2022
developer: octobus
......@@ -201,8 +285,12 @@ forges:
name: Launchpad
lister:
status: prod
supports_last_update: true
loader:
status: N/A
metadata:
intrinsic: none
extrinsic: not collected
maven:
name: Maven
......@@ -210,6 +298,9 @@ forges:
status: prod
loader:
status: prod
metadata:
intrinsic: collected
extrinsic: collected
grant: sloan-castalia-maven
developer: castalia
......@@ -222,6 +313,9 @@ forges:
id_in_swh_web: hg
source: https://gitlab.softwareheritage.org/swh/devel/swh-loader-mercurial/
package_name: swh.loader.mercurial
metadata:
intrinsic: none
extrinsic: none
grant: sloan-2020
developer: octobus
......@@ -230,7 +324,12 @@ forges:
lister:
status: prod
loader:
status: N/A
status: prod
source: https://gitlab.softwareheritage.org/swh/devel/swh-loader-core/
package_name: swh.loader.core
metadata:
intrinsic: none
extrinsic: none
grant: nlnet-tweag-2020
developer: tweag
......@@ -257,6 +356,14 @@ forges:
loader:
status: N/A
pagure:
name: pagure
lister:
status: prod
issue: https://gitlab.softwareheritage.org/swh/meta/-/issues/5043
loader:
status: N/A
phabricator:
name: Phabricator
lister:
......@@ -327,7 +434,6 @@ forges:
loader:
status: N/A
grants:
nlnet-octobus-2022:
funder: NLnet Foundation
......@@ -355,7 +461,6 @@ grants:
funder: Alfred P. Sloan Foundation
announcement: https://www.softwareheritage.org/2020/12/10/sloan-subgrant-cvs-subversion-loaders/
developers:
castalia:
name: Castalia Solutions
......@@ -375,4 +480,3 @@ developers:
tweag:
name: Tweag
url: https://www.tweag.io/
docs/sysadm/data-silos/cassandra/debian-upgrade.rst 0 → 100644
View file @ bf2aa56d
.. _upgrade-debian-cassandra-cluster:
Upgrade Procedure for Debian Nodes in a Cassandra Cluster
=========================================================
.. admonition:: Intended audience
:class: important
sysadm staff members
Purpose
--------
This page documents the steps to upgrade Debian nodes running in a Cassandra
cluster. The upgrade process involves various commands and checks before and
after rebooting the node.
Prerequisites
-------------
+ Familiarity with SSH and CLI-based command execution
+ Out-of-band Access to the node (IDRAC/ILO) for reboot
+ Access to the node through SSH (requires the vpn)
Step 0: Initial Steps
---------------------
Ensure the out of band access to the machine is ok. This definitely helps when
something goes wrong during a reboot (disk order or names change, network,
...).
Step 1: Migrate to the next debian suite
----------------------------------------
Update the Debian version of the node (e.g. bullseye to bookworm) using the
following command:
.. code::
root@node:~# /usr/local/bin/migrate-to-${NEXT_CODENAME}.sh
Note: The script should be present on the machine (installed through puppet).
Step 2: Run Puppet Agent
-------------------------
Once the upgrade procedure happened, run the puppet agent to apply any necessary
configuration changes (e.g. /etc/apt/sources.list change, etc...)
.. code::
root@node:~# puppet agent -t
Step 3: Stop Puppet Agent
-------------------------
As we will stop the service, we don't want the agent to start it back again.
.. code::
root@node:~# puppet agent --disable "Ongoing debian upgrade"
Step 4: Autoremove and Purge
-----------------------------
Perform autoremove to remove unnecessary packages left-over from the migration:
.. code::
root@node:~# apt autoremove
Step 5: Stop the cassandra service
----------------------------------
The cluster can support one non-responding node so it's ok to stop the
service.
.. code-block:: shell
$ nodetool drain
Lookup for the '- DRAINED' pattern in the service log to know it's done.
.. code-block:: shell
$ journalctl -e cassandra@instance1 | grep DRAINED
Nov 27 14:09:06 cassandra01 cassandra[769383]: INFO [RMI TCP Connection(20949)-192.168.100.181] 2024-11-27 14:09:06,084 StorageService.java:1635 - DRAINED
Then stop the cassandra service.
.. code-block:: shell
$ systemctl stop cassandra@instance1
In the output of the ``nodetool status``, the node whose service is stopped
should be marked as DN (``Down and Normal``):
$ nodetool -h cassandra02 status -r | grep DN
DN cassandra01.internal.softwareheritage.org 8.63 TiB 16 22.7% cb0695ee-b7f1-4b31-ba5e-9ed7a068d993 rack1
Step 6: Reboot the Node
------------------------
We are finally ready to reboot the node, so just do it:
.. code::
root@node:~# reboot
You can connect to the serial console of the machine to follow through the
reboot.
Step 7: Clean up some more
--------------------------
Once the machine is restarted, some cleanup might be necessary.
.. code::
root@node:~# apt autopurge
Step 8: Activate puppet agent
-----------------------------
Activate back the puppet agent and make it run. This will start back the
cassandra service again.
.. code::
root@node:~# puppet agent --enable && puppet agent --test
Post cluster migration
----------------------
Once all the nodes of the cluster have been migrated:
- Remove the argocd sync window so the cluster is back to nominal state.
- Enable back the Rancher etcd snapshots.
- Check the `holderIdentity` value in `rke2` and `rke2-lease` leases and configmaps.
docs/sysadm/data-silos/cassandra/index.rst
View file @ bf2aa56d
......@@ -8,3 +8,5 @@ Cassandra
.. toctree::
installation
upgrade
debian-upgrade
docs/sysadm/data-silos/cassandra/installation.rst
View file @ bf2aa56d
......@@ -42,27 +42,329 @@ In the `common/cassandra.yaml` file, declare the node configuration:
System installation
-------------------
- Install the node with a debian bullseye distribution
- Install zfs and configure the pools according to the instances that will run on the node.
Based on the usual cassandra server swh uses:
- Configure the ipxe configuration for the new server (follow :ref:`server_architecture_install_physical`)
without running puppet to avoid the zfs configuration if declared
- Perform a low level nvme disk format to use a lbf format of 4096b
- one pool for the commitlogs using a fast write intensive disk
- one or several pools with the mixeduse disks
- for each nvme disk, execute:
- If the server name starts with `cassandra[0-9]+`, puppet will install all the necessary
packages and the configured instances.
.. code-block:: shell
.. warning:: The services are just enabled, aka puppet doesn't force the service start. It's done
on purpose to let the system administrator control the restarts of the instances
# apt update
# apt install nvme
# # for each disk
# # nvme id-ns -H /dev/nvme0n1| grep LBA
[3:0] : 0x1 Current LBA Format Selected
[0:0] : 0x1 Metadata as Part of Extended Data LBA Supported
LBA Format 0 : Metadata Size: 0 bytes - Data Size: 512 bytes - Relative Performance: 0x1 Better (in use)
LBA Format 1 : Metadata Size: 0 bytes - Data Size: 4096 bytes - Relative Performance: 0 Best <-- we want to use this one
LBA Format 2 : Metadata Size: 8 bytes - Data Size: 512 bytes - Relative Performance: 0x3 Degraded
LBA Format 3 : Metadata Size: 8 bytes - Data Size: 4096 bytes - Relative Performance: 0x2 Good
LBA Format 4 : Metadata Size: 64 bytes - Data Size: 4096 bytes - Relative Performance: 0x3 Degraded
# nvme format -f --lbaf=1 /dev/nvme0n1
Success formatting namespace:1
- Launch puppet
.. code-block:: shell
# puppet agent --vardir /var/lib/puppet --server pergamon.internal.softwareheritage.org -t
.. warning::
Do not restart the server without disabling the `cassandra@instance1` service or cassandra
will start after the reboot without zfs configured
- Disable cassandra to avoid any issue in case of restart
.. code-block:: shell
# systemctl disable cassandra@instance1
- Create the zfs pool and datasets
.. note::
Always use the WWN (World Wide Name) of the device to be sure it will never change
.. code-block:: shell
# # get the wwmn name
# ls -al /dev/disk/by-id/nvme-*
#
# # Load the zfs module (only if the server was not restarted after initial puppet run)
# modprobe zfs
#
# # Create the zfs pool(s)
# zpool create -o ashift=12 -O atime=off -O relatime=on -O mountpoint=none -O compression=off \
mixeduse \
nvme-XX nvme-XY nvme-XZ nvme-YX
# # Only if the server has a write intensive disk for the commit log
# zpool create -o ashift=12 -O atime=off -O relatime=on -O mountpoint=none -O compression=off \
writeintensive \
nvme-XX
#
# Create the zfs datasets
# zfs create -o mountpoint=/srv/cassandra/instance1/data mixeduse/cassandra-instance1-data
# # Change the pool to writeintensive if the server has a dedicated disk for the commit logs
# zfs create -o mountpoint=/srv/cassandra/instance1/commitlog mixeduse/cassandra-instance1-commitlog
#
# # Reboot the server to ensure everything is correct
# reboot
#
# # Check the zfs configuration after the reboot
# zpool status
# zfs list
- Ensure the zfs dataset permissions are correct
.. code-block:: shell
# chown cassandra: /srv/cassandra/instance1/{data,commitlog}
- Start cassandra
.. code-block:: shell
# systemctl enable cassandra@instance1
# systemctl start cassandra@instance1
.. note::
During the first start, cassandra will bootstrap the new node with the data it must manage.
It usually take around 12 hours to finish
- Check everything is Ok
- On any node of the cluster
.. code-block:: shell
$ % /opt/cassandra/bin/nodetool -u cassandra --password [redacted] status -r
Datacenter: sesi_rocquencourt
=============================
Status=Up/Down
|/ State=Normal/Leaving/Joining/Moving
-- Address Load Tokens Owns (effective) Host ID Rack
UN cassandra04.internal.softwareheritage.org 9.91 TiB 16 27.4% 9c618479-7898-4d89-a8e0-dc1a23fce04e rack1
UN cassandra01.internal.softwareheritage.org 10 TiB 16 27.5% cb0695ee-b7f1-4b31-ba5e-9ed7a068d993 rack1
UN cassandra06.internal.softwareheritage.org 10.12 TiB 16 27.4% 557341c9-dc0c-4a37-99b3-bc71fb46b29c rack1
UN cassandra08.internal.softwareheritage.org 10.02 TiB 16 27.2% 247cd9e3-a70c-465c-bca1-ea9d3af9609a rack1
UN cassandra03.internal.softwareheritage.org 10.01 TiB 16 27.0% 4cc44367-67dc-41ea-accf-4ef8335eabad rack1
UN cassandra11.internal.softwareheritage.org 8.94 TiB 16 27.2% 1199974f-9f03-4cc8-8d63-36676d00d53f rack1
UN cassandra10.internal.softwareheritage.org 10.03 TiB 16 27.4% f39713c4-d78e-4306-91dd-25a8b276b868 rack1
UN cassandra05.internal.softwareheritage.org 9.99 TiB 16 26.8% ac5e4446-9b26-43e4-8203-b05cb34f2c35 rack1
UN cassandra09.internal.softwareheritage.org 9.92 TiB 16 27.4% e635af9a-3707-4084-b310-8cde61647a6e rack1
UJ cassandra12.internal.softwareheritage.org 22.01 GiB 16 ? 563d9f83-7ab4-41a2-95ff-d6f2bfb3d8ba rack1
UN cassandra02.internal.softwareheritage.org 9.75 TiB 16 27.6% a3c89490-ee69-449a-acb1-c2aa6b3d6c71 rack1
UN cassandra07.internal.softwareheritage.org 9.94 TiB 16 27.3% 0b7b2a1f-1403-48a8-abe1-65734cc02622 rack1
The new node appears with a status `UJ` Up and Joining
- On the new node, the bootstrap progressing can be checked with
.. code-block:: shell
$ /opt/cassandra/bin/nodetool -u cassandra --password [REDACTED] netstats -H | grep -v 100%
Mode: JOINING
Bootstrap 9af73f50-5f97-11ef-88d7-57efd8d208be
/192.168.100.191
Receiving 1206 files, 566.42 GiB total. Already received 37 files (3.07%), 80.61 GiB total (14.23%)
/192.168.100.189
Receiving 756 files, 647.48 GiB total. Already received 65 files (8.60%), 90.85 GiB total (14.03%)
/192.168.100.186
Receiving 731 files, 811.57 GiB total. Already received 35 files (4.79%), 76.18 GiB total (9.39%)
swh/directory_entry-7 253477270/8750624313 bytes (2%) received from idx:0/192.168.100.186
/192.168.100.183
Receiving 730 files, 658.71 GiB total. Already received 43 files (5.89%), 83.18 GiB total (12.63%)
swh/directory_entry-7 17988974073/19482031143 bytes (92%) received from idx:0/192.168.100.183
/192.168.100.185
Receiving 622 files, 477.56 GiB total. Already received 36 files (5.79%), 81.96 GiB total (17.16%)
swh/directory_entry-8 2812190730/12861515323 bytes (21%) received from idx:0/192.168.100.185
/192.168.100.181
Receiving 640 files, 679.54 GiB total. Already received 38 files (5.94%), 84.17 GiB total (12.39%)
/192.168.100.184
Receiving 743 files, 813.96 GiB total. Already received 42 files (5.65%), 93.4 GiB total (11.47%)
swh/directory_entry-5 13940867674/15691104673 bytes (88%) received from idx:0/192.168.100.184
/192.168.100.190
Receiving 804 files, 792.49 GiB total. Already received 69 files (8.58%), 95.88 GiB total (12.10%)
swh/directory_entry-11 2315131981/3494406702 bytes (66%) received from idx:0/192.168.100.190
/192.168.100.188
Receiving 741 files, 706.3 GiB total. Already received 43 files (5.80%), 82.24 GiB total (11.64%)
swh/directory_entry-6 6478486533/17721982774 bytes (36%) received from idx:0/192.168.100.188
/192.168.100.182
Receiving 685 files, 623.98 GiB total. Already received 38 files (5.55%), 77.86 GiB total (12.48%)
swh/directory_entry-6 9007635102/12045552338 bytes (74%) received from idx:0/192.168.100.182
/192.168.100.187
Receiving 638 files, 706.2 GiB total. Already received 41 files (6.43%), 83.17 GiB total (11.78%)
swh/directory_entry-6 1508815317/6276710418 bytes (24%) received from idx:0/192.168.100.187
Read Repair Statistics:
Attempted: 0
Mismatch (Blocking): 0
Mismatch (Background): 0
Pool Name Active Pending Completed Dropped
Large messages n/a 0 0 0
Small messages n/a 0 5134236 0
- New node declaration
- To activate the monitoring, declare the node in the monitoring endpoints in
`swh-charts/cluster-components/values/archive-production-rke2.yaml` for production.
In the section `scrapeExternalMetrics.cassandra.ips`, add the ip of the new server.
- Add the node in the list of seeds in `swh-charts/swh/values/production/default.yaml`
for a production node. Add it in the `cassandraSeeds` list.
- Cleanup of the old nodes
After the new node is bootstrapped, the old nodes are not automatically cleaned and continue
to host the data migrated to the new host. To free the space, the cleanup operation must but
launched manually on all the pre-existing nodes.
.. note::
If several new node must be added in the same batch, the cleanup operation can be done after
all the new nodes were added and bootstrapped. It will avoid to clean each old node after each new
node bootstrap.
.. note::
The cleanup operation can be started in several nodes in parallel without any problem. Just check
carefully in the monitoring if the load of the cluster is not too important.
.. code-block:: shell
$ # Run this on each node except the last one added
$ /opt/cassandra/bin/nodetool -u cassandra --password [REDACTED] cleanup -j 0
Cassandra configuration
-----------------------
This section explains how to configure the keyspaces and roles for the specific swh usage.
Cassandra need to be configured with authentication and authorization activated. The following options
need to be present on the `cassandra.yaml` file:
::
authenticator: PasswordAuthenticator
authorizer: CassandraAuthorizer
Several users are used:
- `swh-rw`: The main user used by swh-storage to manage the content in the database
- `swh-ro`: A read-only user used for read-only storages (webapp, ...) or humans
- `reaper`: A read-write user on the `reaper` keyspace. `Reaper <http://cassandra-reaper.io/>`_ is the tool in charge of managing the repairs
The command line will use the staging environment as examples. The configuration is for a medium
data volume, with a Replication factor (RF) of 3. Adapt according to your own needs.
1. Create the keyspaces to be able to configure the accesses
::
CREATE KEYSPACE swh WITH replication = {'class': 'NetworkTopologyStrategy', 'sesi_rocquencourt_staging': '3'} AND durable_writes = true;
# If needed
CREATE KEYSPACE reaper_db WITH replication = {'class': 'NetworkTopologyStrategy', 'sesi_rocquencourt_staging': '3'} AND durable_writes = true;
2. Alter the system keyspace replication to prepare the authenticated accesses
(from https://cassandra.apache.org/doc/latest/cassandra/operating/security.html#password-authentication)
::
export PASS=<your jmx password>
ALTER KEYSPACE system_auth WITH replication = {'class': 'NetworkTopologyStrategy', 'sesi_rocquencourt_staging': 3};
seq 1 3 | xargs -t -i{} /opt/cassandra/bin/nodetool -h cassandra{} -u cassandra --password $PASS repair --full -j4 system_auth
3. Create a new `admin` superuser
In cqlsh (the default admin user is `cassandra`/`cassandra`):
::
CREATE ROLE admin WITH SUPERUSER = true AND LOGIN = true AND PASSWORD = 'changeme';
4. Disable the default superuser
Connect to cqlsh with the new `admin` user:
::
ALTER ROLE cassandra WITH SUPERUSER = false AND LOGIN = false;
5. Create the `swh-rw` user
::
CREATE ROLE 'swh-rw' WITH LOGIN = true AND PASSWORD = 'changeme';
GRANT CREATE ON ALL KEYSPACES to 'swh-rw';
GRANT CREATE ON ALL FUNCTIONS to 'swh-rw';
GRANT ALTER ON ALL FUNCTIONS to 'swh-rw';
GRANT SELECT ON KEYSPACE swh to 'swh-rw';
GRANT MODIFY ON KEYSPACE swh to 'swh-rw';
GRANT EXECUTE ON ALL FUNCTIONS to 'swh-rw';
6. Create the `swh-ro` user
::
CREATE ROLE 'swh-ro' WITH LOGIN = true AND PASSWORD = 'changeme';
GRANT SELECT ON KEYSPACE swh to 'swh-ro';
GRANT EXECUTE ON ALL FUNCTIONS to 'swh-ro';
7. Create the `reaper` user
::
CREATE ROLE 'reaper' WITH LOGIN = true AND PASSWORD = 'changeme';
GRANT CREATE ON ALL KEYSPACES to 'reaper';
GRANT SELECT ON KEYSPACE reaper_db to 'reaper';
GRANT MODIFY ON KEYSPACE reaper_db to 'reaper';
GRANT ALTER ON KEYSPACE reaper_db to 'reaper';
8. Specific table configurations
The table compaction and compression strategies depend on the hardware topology cassandra is deployed on.
For the high density servers used by swh, these specific configurations are used:
- LCS compaction on big tables to reduce the free disk space needed by compactions
- ZSTD compression on big tables to optimize the disk space
.. warning:: These configurations can be applied only once the swh-storage schema was created by the storage
- In staging
::
ALTER TABLE content WITH
compaction = {'class' : 'LeveledCompactionStrategy', 'sstable_size_in_mb':'160'}
AND compression = {'class': 'ZstdCompressor', 'compression_level':'1'};
ALTER TABLE directory_entry WITH
compaction = {'class' : 'LeveledCompactionStrategy', 'sstable_size_in_mb':'4096'}
AND compression = {'class': 'ZstdCompressor', 'compression_level':'1'};
- In production
::
ALTER TABLE content WITH
compaction = {'class' : 'LeveledCompactionStrategy', 'sstable_size_in_mb':'2000'}
AND compression = {'class': 'ZstdCompressor', 'compression_level':'1'};
ALTER TABLE directory_entry WITH
compaction = {'class' : 'LeveledCompactionStrategy', 'sstable_size_in_mb':'20480'}
AND compression = {'class': 'ZstdCompressor', 'compression_level':'1'};
- Check the configuration looks correct and start the instance(s) with `systemctl start cassandra@<instance>`
Monitoring
^^^^^^^^^^
----------
TODO
Metric
^^^^^^
------
TODO
docs/sysadm/data-silos/cassandra/upgrade.rst 0 → 100644
View file @ bf2aa56d
This diff is collapsed.
docs/sysadm/data-silos/elasticsearch/debian-upgrade.rst 0 → 100644
View file @ bf2aa56d
This diff is collapsed.
docs/sysadm/data-silos/elasticsearch/index.rst
View file @ bf2aa56d
......@@ -3,5 +3,10 @@
ElasticSearch
=============
.. toctree::
:titlesonly:
debian-upgrade
.. todo::
This page is a work in progress.
docs/sysadm/data-silos/index.rst
View file @ bf2aa56d
......@@ -8,3 +8,5 @@ Data silos
cassandra/index
kafka/index
elasticsearch/index
winery/index
rancher/index
docs/sysadm/data-silos/kafka/debian-upgrade.rst 0 → 100644
View file @ bf2aa56d
This diff is collapsed.
docs/sysadm/data-silos/kafka/index.rst
View file @ bf2aa56d
......@@ -7,6 +7,7 @@ Kafka
:titlesonly:
manage-topics
debian-upgrade
.. todo::
This page is a work in progress.
docs/sysadm/data-silos/rancher/debian-upgrade.rst 0 → 100644
View file @ bf2aa56d
This diff is collapsed.
docs/sysadm/data-silos/rancher/index.rst 0 → 100644
View file @ bf2aa56d
.. _cluster-rancher:
Cluster Rancher
===============
.. toctree::
:titlesonly:
debian-upgrade
.. todo::
This page is a work in progress.
docs/sysadm/data-silos/winery/ceph.rst 0 → 100644
View file @ bf2aa56d
.. _winery-ceph:
Winery Ceph Architecture
========================
.. admonition:: Intended audience
:class: important
sysadm staff members
.. todo::
This page is a work in progress.
docs/sysadm/data-silos/winery/frontends.rst 0 → 100644
View file @ bf2aa56d
.. _winery-frontends:
Winery Frontends Documentation
==============================
.. admonition:: Intended audience
:class: important
sysadm staff members
.. todo::
This page is a work in progress.
docs/sysadm/data-silos/winery/index.rst 0 → 100644
View file @ bf2aa56d
This diff is collapsed.