From 2bdcf67e04a320419c7b5e7357230491e0b57069 Mon Sep 17 00:00:00 2001 From: Konrad Bucheli Date: Thu, 7 Mar 2024 16:29:10 +0100 Subject: [PATCH] improve documentation for adding new host/environment --- _toc.yml | 8 +- admin-guide/deployment/sample.md | 65 ++++++++++++++ admin-guide/deployment/sample.rst | 78 ---------------- admin-guide/deployment/sysdb_env.md | 133 ++++++++++++++++++++++++++++ 4 files changed, 202 insertions(+), 82 deletions(-) create mode 100644 admin-guide/deployment/sample.md delete mode 100644 admin-guide/deployment/sample.rst create mode 100644 admin-guide/deployment/sysdb_env.md diff --git a/_toc.yml b/_toc.yml index 0244638e..00dc5fe5 100644 --- a/_toc.yml +++ b/_toc.yml @@ -66,13 +66,13 @@ chapters: - file: admin-guide/guidelines - file: admin-guide/deployment sections: + - file: admin-guide/deployment/sample + - file: admin-guide/deployment/reinstall + - file: admin-guide/deployment/partitioning + - file: admin-guide/deployment/sysdb_env - file: admin-guide/deployment/ipxe - file: admin-guide/deployment/kickstart - - file: admin-guide/deployment/partitioning - - file: admin-guide/deployment/sample - file: admin-guide/deployment/infrastructure - - file: admin-guide/deployment/workflow - - file: admin-guide/deployment/reinstall - file: admin-guide/puppet sections: - file: admin-guide/puppet/general diff --git a/admin-guide/deployment/sample.md b/admin-guide/deployment/sample.md new file mode 100644 index 00000000..4e3c716c --- /dev/null +++ b/admin-guide/deployment/sample.md @@ -0,0 +1,65 @@ +# Sample deployment of a new server + +In this section we describe the deployment of a new server from +scratch. +All the operations will be performed using `bob`, the command-line +client for interacting with `sysdb`. + +The informations we need are: + + - the server name: `logging-ra.psi.ch` + - the server MAC address: `23:3d:ef:33:11:22` + - static or dynamic IP: `static` + - the OS installer: `rhel8install` + - the server role: `role::logging_server` + - the server environment in puppet: `prod` + - the sysdb deployment environment: `daas` + - optional the group inside the sysdb environment (`default` if not specified): `logging` + +## Setting up bob + +The `bob` tool is already set up on `lxsup.psi.ch`. +You might connect with `ssh` and use it from there. + +Altenatively you many have on your workstation a local copy of `bob`. This can be done by installing the RPM from the pli-misc repository - https://repos.psi.ch/rhel8/latest/pli-misc/ + +You might need to set a `PSI_BOB_USER` environment variable (`export PSI_BOB_USER=`) or use the option `--user` if your local user is different from +the one on sysdb. + +## Sysdb configuration + +We add the node to the environment, specifing `netboot` as +the boot action + + bob node add logging-ra.psi.ch daas netboot + +We setup its MAC address: + + bob node add-mac logging-ra.psi.ch 23:3d:ef:33:11:22 + +Next decide how the IP address is configured (`dhcp` or `static`): + + bob node set-attr syslog-ra.psi.ch network=static + +And which installer is used: + + bob node set-attr syslog-ra.psi.ch ipxe_installer=rhel8install + +And we finally setup the puppet role and puppet environment: + + bob node set-attr syslog-ra.psi.ch puppet_role=role::log_server + bob node set-attr syslog-ra.psi.ch puppet_env=prod + bob node set-attr syslog-ra.psi.ch puppet_group=logging + + +## Example + +Full example: + + bob node add lx-test-02.psi.ch lx netboot + bob node add-mac lx-test-02 00:50:56:9d:19:76 + bob node set-attr lx-test-02.psi.ch ipxe_installer=rhel8install puppet_env=prod puppet_group=default puppet_role=role::server + bob node netboot lx-test-02.psi.ch + bob node list -v lx-test-02 + +Ensure that a potential previous puppet certificate for this server is deleted on the puppet server: https://puppet.psi.ch diff --git a/admin-guide/deployment/sample.rst b/admin-guide/deployment/sample.rst deleted file mode 100644 index 85e3329c..00000000 --- a/admin-guide/deployment/sample.rst +++ /dev/null @@ -1,78 +0,0 @@ -Sample deployment of a new server -================================= - -In this section we describe the deployment of a new server from -scratch. -All the operations will be performed using `bob`, the command-line -client for interacting with `sysdb`. - -The informations we need are: - - - the server name: ``logging-ra.psi.ch`` - - the server MAC address: ``23:3d:ef:33:11:22`` - - static or dynamic IP: ``static`` - - the OS installer: ``rhel8install`` - - the server role: ``role::logging_server`` - - the server environment in puppet: ``prod`` - - the sysdb environment: ``daas`` - - optional the group inside the sysdb environment (``default`` if not specified): ``logging`` - -Setting up bob --------------- - -The `bob` tool is already set up on `lxsup.psi.ch`. -You might connect with `ssh` and use it from there. - -Altenatively you many have on your workstation a local copy of `bob`. This can be done by installing the RPM from the pli-misc repository - https://repos.psi.ch/rhel7/latest/pli-misc/ - -You might need to set a `PSI_BOB_USER` environment variable (`export PSI_BOB_USER=`) or use the option `--user` if your local user is different from -the one on sysdb. - -Sysdb configuration -------------------- - -We then create a deployment environment:: - - bob env add daas talamo_i daas-admins 'DaaS Cluster' - -We add the node to the environment, specifing ``netboot`` as -the boot action :: - - bob node add logging-ra.psi.ch daas netboot - -We setup its MAC address: :: - - bob node add-mac logging-ra.psi.ch 23:3d:ef:33:11:22 - -Next decide how the IP address is configured (``dhcp`` or ``static``): :: - - bob node set-attr syslog-ra.psi.ch network=static - -And which installer is used: :: - - bob node set-attr syslog-ra.psi.ch ipxe_installer=rhel8install - -And we finally setup the puppet role and puppet environment: :: - - bob node set-attr syslog-ra.psi.ch puppet_role=role::log_server - bob node set-attr syslog-ra.psi.ch puppet_env=prod - bob node set-attr syslog-ra.psi.ch puppet_group=logging - - -Example -------- - -Full example: :: - - bob node add lx-test-02.psi.ch lx netboot - bob node add-mac lx-test-02 00:50:56:9d:19:76 - bob node set-attr lx-test-02.psi.ch ipxe_installer=rhel8install - bob node set-attr lx-test-02.psi.ch puppet_env=prod - bob node set-attr lx-test-02.psi.ch puppet_group=default - bob node set-attr lx-test-02.psi.ch puppet_role=role::server - bob node netboot lx-test-02.psi.ch - bob node list -v lx-test-02 - -Ensure that a potential previous puppet certificate for this server is deleted on the puppet server: https://puppet.psi.ch - - diff --git a/admin-guide/deployment/sysdb_env.md b/admin-guide/deployment/sysdb_env.md new file mode 100644 index 00000000..32de72d8 --- /dev/null +++ b/admin-guide/deployment/sysdb_env.md @@ -0,0 +1,133 @@ +# New Sysdb Deploment Environment + +## Introduction + +Deploying a new environment requires the following: + 1. Configuring the environment in **bob** + 2. Configuring the environment in GIT (`https://git.psi.ch/linux-infra/hiera`) + - Environment format: `data-` + - And change permissions accordingly + - Configure the necessary webhooks for the Puppet and Sysdb server + 3. Configuring the environment in Puppet (e.g. `puppet01.psi.ch`) + +## Configuring the environment in sysdb + +Bob allows to create a new environment in `sysdb` by using the `bob env` option. +You must have permissions to do that. + + +You must belong to the `sysdb-admins` group that is actually +configured on the local `/etc/group` file. A migration to Active +Directory should be done for that group. + +To list current defined environments run + + bob env list + +To add a new environment, run + + bob env add "" + +In example, for the MeG cluster + + bob env add meg caubet_m unx-hpc_adm "MeG Cluster" + +### Test new environment in BOB + +In order to test that environment was successfully created + + bob env list | grep + +An example + + caubet_m@caubet-laptop:~/GIT/admin-guide/deployment$ bob env list | grep meg + meg caubet_m unx-hpc_adm MeG Cluster + + +## Configuring the environment in GIT + +You must belong to the `unx-puppet_adm` Active Directory group in order to be able to create new projects. + +In order to create a new environment in **GIT**, you should access and login in the following link: https://git.psi.ch/linux-infra/hiera/. +Here you can see the different environments. + +The steps to create and configure a new **GIT** project are: + +1. Create a new project (environment). It can be done here: https://git.psi.ch/projects/new + + - Go to `[Blank project] Tab` (which is the *default* tab) + - Change `[Project Path]` as follows: + - `https://git.psi.ch/` + `linux-infra/hiera` + - Define `[Project Name]`, which *must* have the following format: + - `data-` where `` is the one defined in **Bob** + - *[Optional]* Specify `[Project description]` + - Specify `[Visibility Level]`: + - Should be `Internal` or `Private` + +2. Configure project permissions as follows: + + - `[data-[Settings]->[Repository]`, or directly: https://git.psi.ch/linux-infra/hiera/data-(environment_name)/-/settings/repository + - `[Deploy Keys]` -> `[Privately accessible deploy keys]` -> select `root@puppet01.psi.ch'` -> click on `'Enable'` + - `[data-[Settings]->[Members]`, or directly: https://git.psi.ch/linux-infra/hiera/data-(environment_name)/project_members + - Setup specific permissions for specific users or groups. In example: + - Set project `Master`: + - `[Select members to invite]` (`caubet_m`) + `[Choose a role permission]` (`Master`) + `[Add to project]` + - Set other roles: + - `[Select members to invite]` (`dorigo_a`) + `[Choose a role permission]` (`Developer`) + `[Add to project]` + - `[data-[Settings]->[Integrations]`, or directly: https://git.psi.ch/linux-infra/hiera/data-(environment_name)/-/hooks + - Add WebHooks as follows: + - `[URL]`: http://puppet01.psi.ch/events/dataupdate + - `[URL]`: http://sysdb.psi.ch/events/dataupdate + - (Checked) `[Push events]`. Uncheck the rest. + - `[SSL verification]` -> (uncheck) `[Enable SSL verification]` + - Confirm information from above, and click on `[Add webhook]` to add the new WebHook. + +### Test new environment in GIT + +In order to test that environment was successfully created + + git clone git@git.psi.ch:linux-infra/hiera/data-.git + +An example + + caubet_m@caubet-laptop:~/GIT$ git clone git@git.psi.ch:linux-infra/hiera/data-meg.git + Cloning into 'data-meg'... + X11 forwarding request failed + warning: You appear to have cloned an empty repository. + +## Configuring the environment in Puppet server + +In [bootstrap](https://git.psi.ch/linux-infra/bootstrap) add the new repo to `instcode/puppet/puppet_server/manifests/data.pp` and run the bootstrap for the Puppet server. + +## Configuring the environment in Sysdb Server + +In [bootstrap](https://git.psi.ch/linux-infra/bootstrap) add the new repo to the suitable inventory file (eg. `ansible/inventory.yaml` for production) and run the playbook for the Sysdb server. + +## Test new environment in Puppet + +In order to test that environment was successfully created + + git clone git@git.psi.ch:linux-infra/data-.git + +Add a new file .yaml in to the project: + + cd data- + touch .yaml + git add .yaml + git commit -a -m "Added first empty file" + git push + +After a few seconds (needs time to trigger the change), check in `puppet01.psi.ch:/srv/puppet/data/` that file was successfully triggered (copied) to the puppet server from **GIT** + + ssh root@puppet01.psi.ch ls /srv/puppet/data//.yaml + +Full real example: + + git clone git@git.psi.ch:linux-infra/data-meg.git + cd data-meg + touch meg.yaml + git add meg.yaml + git commit -a -m "Added first empty file" + git push + sleep 5 + ssh root@puppet01.psi.ch ls /srv/puppet/data/meg/meg.yaml