diff --git a/sysadm/getting-started/index.rst b/sysadm/getting-started/index.rst new file mode 100644 index 0000000..f845fa6 --- /dev/null +++ b/sysadm/getting-started/index.rst @@ -0,0 +1,7 @@ +Getting started +=============== + +.. toctree:: + :titlesonly: + + setup-repositories diff --git a/sysadm/getting-started/setup-repositories.rst b/sysadm/getting-started/setup-repositories.rst new file mode 100644 index 0000000..8d44791 --- /dev/null +++ b/sysadm/getting-started/setup-repositories.rst @@ -0,0 +1,56 @@ +.. _setup-repositories: + +Reference: Setup sysadm repositories +==================================== + +.. admonition:: Intended audience + :class: important + + new sysadm member + +This page describes the steps to clone locally all sysadm repositories. + +.. _multiple_repository_setup: + +Multiple umbrella repositories setup +------------------------------------ + +We use multiple umbrella repositories to manage specific repositories for dedicated +perimeters: + +- sysadm-environment_: Deployment related and credentials repositories + (k8s-cluster-conf, ...) +- puppet-environment_ : Various swh puppet and third-party repositories (swh-site, ...) +- ci-environment_: CI (Jenkins) related repositories (jobs, dockerfile, ...) + + +Clone umbrella repositories +--------------------------- + +Clone each of those repositories. They each contain a .mrconfig file and a README file. + +:: + + $ git clone git@gitlab.softwareheritage.org:infra/sysadm-environment.git + $ git clone git@gitlab.softwareheritage.org:infra/puppet/puppet-environment.git + $ git clone ssh://git@forge.softwareheritage.org/source/ci-environment.git + +Then, use the `mr` (myrepos) command that uses the .mrconfig file to clone the +repositories managed by myrepos: + +:: + + $ for repository in sysadm-environment puppet-environment ci-environment; \ + do + pushd $repository ; \ + readlink -f .mrconfig >> ~/.mrtrust ; \ + mr up ; \ + popd ; \ + done + +(the *mr* command is in the `myrepos Debian package +`_). + +.. _puppet-environment: https://gitlab.softwareheritage.org/infra/puppet/puppet-environment +.. _sysadm-environment: https://gitlab.softwareheritage.org/infra/sysadm-environment +.. _ci-environment: https://forge.softwareheritage.org/source/ci-environment diff --git a/sysadm/index.rst b/sysadm/index.rst index 3c05318..b38cf1b 100644 --- a/sysadm/index.rst +++ b/sysadm/index.rst @@ -1,23 +1,24 @@ Welcome to the Software Heritage sysadmin documentation ======================================================= .. toctree:: :maxdepth: 2 :caption: Contents: + getting-started/index puppet/index network-architecture/index server-architecture/index data-silos/index deployment/index user-management/index life-cycle-management/index mirror-operations/index support-services/index Indices and tables ================== * :ref:`genindex` * :ref:`search` diff --git a/sysadm/puppet/reference-setup.rst b/sysadm/puppet/reference-setup.rst index e57e5f5..9f3c004 100644 --- a/sysadm/puppet/reference-setup.rst +++ b/sysadm/puppet/reference-setup.rst @@ -1,85 +1,66 @@ .. _puppet-setup: Puppet setup ============ .. admonition:: Intended audience :class: important sysadm members -.. _mutiple_repository_setup: +.. _puppet_multiple_repository_setup: Multiple repository setup ------------------------- -Our puppet environment is split into multiple repos (one repo per module), plus one -"root" repository for multi-repository management. - -First, clone the base repository, containing the configuration file for myrepos and a -README file. - -:: - - $ git clone git@gitlab.softwareheritage.org:infra/puppet/puppet-environment.git - -Then, use that configuration to clone all the repositories: - -:: - - $ cd puppet-environment - $ readlink -f .mrconfig >> ~/.mrtrust - $ mr up - -(the *mr* command is in the `myrepos Debian package -`_). +Report to :ref:`setup-repositories` to prepare your machine with puppet-environment. All the swh-specific repositories are in *swh-*-prefixed repositories. The other repositories come from other sources and have an *upstream* remote allowing updates (the *origin* remote is always on the swh git server). Our puppet workflow is documented in `the README.md file in the puppet-environment repository `_. .. _configure_octocatalog_diff: Configure octocatalog-diff to ease testing ------------------------------------------ *puppet-environment* contains the whole scaffolding to be able to use `octocatalog-diff `_ on our manifests. This allows for quick(er) local iterations while developing complex puppet manifests. Dependencies ~~~~~~~~~~~~ You need the following packages installed on your machine: - r10k octocatalog-diff - puppet Running ~~~~~~~ The ``bin/octocatalog-diff`` script allows diffing the manifests between two environments (that is, between two branches of the *swh-site* repository. By default it diffs between ``production`` and ``staging``. Default usage: .. code:: cd puppet-environment # Diff between branches "staging" and "production" for node "pergamon" bin/octocatalog-diff pergamon # Diff between branches "staging_feature" and "production" for node "worker01" bin/octocatalog-diff --to staging_feature worker01 Limitations ~~~~~~~~~~~ Our setup for octocatalog-diff doesn't support exported resources, so you won't see your fancy icinga checks there. For more evolved checks as those, use our `vagrant vms definitions `_.