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:[email protected]: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
-- Mailing list: https://launchpad.net/~sts-sponsors Post to : [email protected] Unsubscribe : https://launchpad.net/~sts-sponsors More help : https://help.launchpad.net/ListHelp
