sts-sponsors team mailing list archive

[Samuel Walladge <mp+434284@xxxxxxxxxxxxxxxxxx>]

Samuel Walladge has proposed merging ~swalladge/crbs:docs into crbs:master.

Commit message:
Add tutorial and notes for using with MAAS

Requested reviews:
  Alberto Donato (ack)

For more details, see:
https://code.launchpad.net/~swalladge/crbs/+git/crbs/+merge/434284

Add some more information in a step-by-step format that may be helpful to those who wish to use this project to set up maas with rbac.
-- 
Your team Canonical RBAC Service team is subscribed to branch crbs:master.

diff --git a/README.md b/README.md
index a2baac5..a481201 100644
--- a/README.md
+++ b/README.md
@@ -10,6 +10,10 @@ The required setup is as follows
 - run `make dep` to install .deb dependencies
 - run `make setup` to create the virtualenv and set up the Postgres database.
 
+Usage
+=====
+
+See [docs/maas-rbac](./docs/maas-rbac.md) for a tutorial and notes on using this to configure MAAS with RBAC.
 
 Candid setup
 ============
diff --git a/docs/maas-rbac.md b/docs/maas-rbac.md
new file mode 100644
index 0000000..8fac586
--- /dev/null
+++ b/docs/maas-rbac.md
@@ -0,0 +1,69 @@
+# MAAS + RBAC tutorial
+
+1. Prerequisites: maas, postgresql server, snapd installed
+2. Install candid via snap: `sudo snap install candid`
+3. configure candid as desired.  See here for docs: https://github.com/canonical/candid/blob/master/docs/configuration.md
+4. Install the canonical-rbac snap.  This is not available on the snap store, because it is private proprietary software.
+   1. option 1:
+      1. install snapcraft and build the snap from source - see the readme for instructions.
+      2. copy the snap file to the machines where it needs to be installed
+   2. option 2:
+      1. find the canonical rbac private ppa on launchpad (ppa:crbs/stable)
+      2. install the ppa
+      3. `apt update`
+      4. `apt download canonical-rbac`
+      5. extract the canonical-rbac_<version>.snap file from the deb
+      6. copy the snap file to the machines where it needs to be installed
+   3. snap install the resulting snap file for canonical-rbac
+5. Add a user and database for canonical-rbac to a postgresql server.
+   canonical-rbac must be able to login with user/password,
+   so take into account when creating the user and editing /etc/postgresql/VERSION/main/pg_hba.conf
+6. Make a copy of candid's admin keys to somewhere that will be accessible by canonical-rbac running as root.
+   For example: `sudo cp /var/snap/candid/current/admin.keys /root/`
+7. Create the candid agent file with canonical-rbac:
+   `sudo canonical-rbac create-candid-agent /root/admin.keys --service-agent-file /root/rbac.agent`
+8. Init canonical-rbac.  For example:
+   `sudo canonical-rbac init --service-url http://192.168.1.2:5000 --database-url "postgresql://ubuntu:ubuntu@192.168.151.102:5432/rbac" --candid-agent-file /root/rbac.agent `
+   1. service-url should be the public url that this will be accessible at (unsure if this is the interface/port it listens on, or simply information about what it's public facing url should be)
+   2. database-url should be a standard postgres database url.  The protocol must be `postgresql`.
+9. Run `sudo canonical-rbac create-admin`.
+   This will give you a url to login to candid - the user you log in as will be configured as an admin to manage canonical-rbac config.
+   Remember the user backend is candid, so you can login with any user configured in candid.
+10. navigate to the canonical-rbac web interface and add a service for use with maas:
+   1. type: MAAS
+   2. name: arbitrary, but note it down for the next step
+   3. description: arbitrary
+   4. add administrator for the service: as you wish; this can be configured later anyway.  
+      Note that if you choose to add a group (here or later),  the group name should not be the same as any of the usernames due to a bug in the canonical-rbac web ui - [#1995230](https://bugs.launchpad.net/crbs/+bug/1995230).
+11. Configure maas to use canonical-rbac as the auth backend:
+    `sudo maas configauth --rbac-url http://192.168.1.2:5000 --rbac-service-name SERVICE_NAME`
+   1. rbac-url is the --service-url configured with canonical-rbac previously
+   2. SERVICE_NAME is the name of the service added in the previous step
+12. Now return to the canonical-rbac web interface and configure access for groups and users as desired.
+   1. Scopes are based around resource pools in maas.
+      1. all dns, azs, settings, images
+      2. all resource pools
+      3. then a scope for each resource pool
+   2. Group membership and users are managed from candid.
+   3. See https://maas.io/docs/about-rbac#heading--how-the-four-maas-roles-protect-maas-resources for info about the roles available
+
+
+Some miscellaneous notes:
+
+- Installing canonical-rbac from the ppa via apt is only intended for development and only installs cleanly on bionic.
+  Its install scripts set up a dev database on postgresql 10 on the local machine.
+  This is why we should install directly from the snap.
+  The snap is only distributed in that deb.
+- If installing in an HA environment:
+  - canonical-rbac should be installed on all machines,
+    but it only needs to be init'd on a single machine,
+    because all instances should share the same postgresql database.
+  - set up candid on one machine first, then on each subsequent machine:
+    1. install candid
+    2. copy the config (`/var/snap/candid/current/{admin.keys,config.yaml}`) from the first machine
+    3. snap restart candid
+- Other resources:
+  - presentation by Vern: https://docs.google.com/presentation/d/1apMfKt16xElkpmimYypSGQsKh3tK7qTLY0OIiuuElkQ/edit (this describes a lot of workarounds, mainly due to installing from the deb rather than directly from the snap)
+  - document by Vern to complement the presentation: https://docs.google.com/document/d/1fBg3Dge4joHuEMzaeOIN8dXZoWMjSQ22kk0NjDD4UGE/edit.
+  - More candid docs: https://github.com/canonical/candid/tree/master/docs
+- https://maas.io/docs/about-rbac