How to install or upgrade MAAS

billwear · 11 September 2021 17:20

;; Welcome to your streamlined Emacs!

Errors or typos? Topics missing? Hard to read? Let us know.

Install MAAS (snap or packages)

Install from snap:
```
sudo snap install --channel=<version> maas
```
Replace <version> with the desired MAAS version.

Install from packages:

sudo apt-add-repository ppa:maas/<version>
sudo apt update
sudo apt-get -y install maas

Post-install setup (POC)

There is a proof-of-concept configuration defined for the MAAS snap version only. To initialise the MAAS snap in this POC configuration, use the --help flag with maas init and follow the instructions. This POC uses the maas-test-db.

Post-install setup (production)

Disable conflicting NTP:

sudo systemctl disable --now systemd-timesyncd

Configure PostgreSQL for production:

sudo apt install -y postgresql
sudo -i -u postgres psql -c "CREATE USER \"$DBUSER\" WITH ENCRYPTED PASSWORD '$DBPASS'"
sudo -i -u postgres createdb -O "$DBUSER" "$DBNAME"

Edit /etc/postgresql/14/main/pg_hba.conf, adding a line for the newly created database:
```
 host    $MAAS_DBNAME    $MAAS_DBUSER    0/0     md5
```

Initialize MAAS with the database:

sudo maas init region+rack --database-uri "postgres://$DBUSER:$DBPASS@$HOSTNAME/$DBNAME"

Create an admin user:

sudo maas create admin --username=$PROFILE --email=$EMAIL_ADDRESS

Upgrading MAAS

Upgrade MAAS (snap):

sudo snap refresh maas --channel=<version>/stable

Upgrade MAAS (packages):

sudo apt-add-repository ppa:maas/<version>
sudo do-release-upgrade --allow-third-party

Notes

For PostgreSQL 12 users, upgrade to PostgreSQL 14 before installing or upgrading to MAAS 3.5+.
Review the new PostgreSQL requirements in the installation requirements document before installing MAAS.
For Ubuntu 20.04 LTS users, upgrade to Ubuntu 22.04 before moving to MAAS 3.5+.
Always back up your MAAS server before upgrading.

Special upgrade situations

For multi-node setups, upgrade rack nodes before region nodes. For BMC setups with duplicate IP/username combos, ensure unique combinations to avoid migration failures.

Configuring and starting MAAS

Checking MAAS status

To check the status of MAAS services, use:

sudo maas status

Output example:

bind9        RUNNING   pid 7999, uptime 0:09:17
dhcpd        STOPPED   Not started
postgresql   RUNNING   pid 8001, uptime 0:09:17
...

MAAS UI setup

Access the UI:
http://$API_HOST:5240/MAAS
Log in with the credentials created during installation.
DNS forwarder: Set to a suitable value (e.g., 8.8.8.8).
Image import: Select at least one Ubuntu LTS image.
SSH key import: Choose between Launchpad, GitHub, or upload a key from .ssh/id_rsa.pub.

MAAS CLI setup

Login:

maas login $PROFILE $MAAS_URL $(cat api-key-file)

Configure DNS:

maas $PROFILE maas set-config name=upstream_dns value="8.8.8.8"

Add SSH key:

maas $PROFILE sshkeys create "key=$SSH_KEY"

Enabling DHCP

UI

Navigate to Subnets > VLAN > Configure DHCP.
Select the appropriate DHCP options (Managed or Relay).
Save and apply changes.

CLI

Enable DHCP:

maas $PROFILE vlan update $FABRIC_ID untagged dhcp_on=True \
    primary_rack=$PRIMARY_RACK_CONTROLLER

Set default gateway:

maas $PROFILE subnet update $SUBNET_CIDR gateway_ip=$MY_GATEWAY

axino · 21 February 2022 17:12

On Ubuntu 20.04, postgresql is version 12 so this path doesn’t exist.

billwear · 22 February 2022 15:26

thanks for reading so closely. kudos for catching this.

serdarvural80 · 27 April 2022 16:05

I think this should be --database-uri maas-test-db:///

serdarvural80 · 27 April 2022 16:07

Maybe in the following paragraph, we could mention that gh stands for github, and this should be and existing github username from which ssh keys would be imported, e.g. gh:your-github-username

astatide · 8 April 2023 01:53

hiiiii! Sorry to bump an old topic, but I uh… was testing out the install with the maas-test-db instructions. After running the sudo maas init region+rack --database-uri maas-test-db:/// command and confirming the MAAS URL, I realized I probably didn’t want to use the default IP of the KVM machine I’m running in (as it doesn’t have a guaranteed address since this is a test environment) and hit ctrl+c.

This led to a borked install and some interesting errors (no stdout after the init command finished, running maas createadmin led to a weird error, etc). I figured out that I needed to remove/reinstall the maas-test-db snap, but it might be worth noting on the page how to get back to a ‘clean install’ for similarly indecisive individuals such as myself.

billwear · 10 April 2023 15:34

lol. good point. got some suggested text? we crowdsource doc when we can…

astatide · 10 April 2023 16:12

How about something like… (assuming that I’m correct in that the database needs to be sandblasted away):

How to uninstall/revert to a clean install

If something goes wrong during the installation process, it might be necessary to return to a clean state before proceeding with the tutorial. As MAAS stores configuration information in database, the DB must be cleaned up.

If you used the maas-test-db snap, it’s as simple as uninstalling and reinstalling the snap:

sudo snap remove maas-test-db
sudo snap install maas-test-db

Since I have no idea yet what is actually stored in the database, I have no idea what you’d need to remove if you configured it with a stand alone install hah! But.

billwear · 10 April 2023 16:14

nice. that’s a great starting point for the test version, and I see ways to do something similar for the production version, too. lemme play with this and come back to see if i’ve captured your thoughts adequately!

astatide · 10 April 2023 16:15

Yay! That’s awesome!

I know this isn’t the place to suggest it, but I wonder if maas could be configured to capture ctrl-c events and print back that stopping now may lead to an inconsistent state, etc, and to hit ctrl-c again to confirm killing the process… I should figure out where to go make that suggestion, hah.

billwear · 10 April 2023 16:17

heh. there’s a doc for that!

bmcnally-uw · 21 April 2023 00:20

The documentation for package installation of MAAS suggests adding “ppa:maas/3.3-next”, but that repo is for beta builds of MAAS. Shouldn’t people be using “ppa:maas/3.3” instead for normal (non-developmental) installs?

nicolasf · 24 May 2023 13:15

Hello,

Maybe I’m missing a point but, when installing MAAS 3.2+ with PGSQL14 appears to be having some problems.

When I edit like you did :

with :

When I init the cluster I get a :

sudo maas init region+rack --database-uri “postgres://$MAAS_DBUSER:$MAAS_DBPASS@$HOSTNAME/$MAAS_DBNAME”
MAAS URL [default=http://172.16.XX.YY:5240/MAAS]:
Failed to perfom migrations:ations
Traceback (most recent call last):
File “/snap/maas/26274/usr/lib/python3/dist-packages/django/db/backends/base/base.py”, line 217, in ensure_connection
self.connect()
File “/snap/maas/26274/usr/lib/python3/dist-packages/django/db/backends/base/base.py”, line 195, in connect
self.connection = self.get_new_connection(conn_params)
File “/snap/maas/26274/usr/lib/python3/dist-packages/django/db/backends/postgresql/base.py”, line 178, in get_new_connection
connection = Database.connect(**conn_params)
File “/snap/maas/26274/usr/lib/python3/dist-packages/psycopg2/init.py”, line 126, in connect
conn = _connect(dsn, connection_factory=connection_factory, **kwasync)
psycopg2.OperationalError: could not connect to server: Connection refused
Is the server running on host “172.16.XX.YY” and accepting
TCP/IP connections on port 5432?

The above exception was the direct cause of the following exception:

Traceback (most recent call last):
File “/snap/maas/26274/bin/maas-region”, line 8, in
sys.exit(run())
File “/snap/maas/26274/lib/python3.8/site-packages/maasserver/region_script.py”, line 77, in run
run_django(is_snap, is_devenv)
File “/snap/maas/26274/lib/python3.8/site-packages/maasserver/region_script.py”, line 66, in run_django
management.execute_from_command_line()
File “/snap/maas/26274/usr/lib/python3/dist-packages/django/core/management/init.py”, line 381, in execute_from_command_line
utility.execute()
File “/snap/maas/26274/usr/lib/python3/dist-packages/django/core/management/init.py”, line 375, in execute
self.fetch_command(subcommand).run_from_argv(self.argv)
File “/snap/maas/26274/usr/lib/python3/dist-packages/django/core/management/base.py”, line 323, in run_from_argv
self.execute(*args, **cmd_options)
File “/snap/maas/26274/usr/lib/python3/dist-packages/django/core/management/base.py”, line 364, in execute
output = self.handle(*args, **options)
File “/snap/maas/26274/lib/python3.8/site-packages/maasserver/management/commands/dbupgrade.py”, line 107, in handle
conn.ensure_connection()
File “/snap/maas/26274/usr/lib/python3/dist-packages/django/db/backends/base/base.py”, line 217, in ensure_connection
self.connect()
File “/snap/maas/26274/usr/lib/python3/dist-packages/django/db/utils.py”, line 89, in exit
raise dj_exc_value.with_traceback(traceback) from exc_value
File “/snap/maas/26274/usr/lib/python3/dist-packages/django/db/backends/base/base.py”, line 217, in ensure_connection
self.connect()
File “/snap/maas/26274/usr/lib/python3/dist-packages/django/db/backends/base/base.py”, line 195, in connect
self.connection = self.get_new_connection(conn_params)
File “/snap/maas/26274/usr/lib/python3/dist-packages/django/db/backends/postgresql/base.py”, line 178, in get_new_connection
connection = Database.connect(**conn_params)
File “/snap/maas/26274/usr/lib/python3/dist-packages/psycopg2/init.py”, line 126, in connect
conn = _connect(dsn, connection_factory=connection_factory, **kwasync)
django.db.utils.OperationalError: could not connect to server: Connection refused
Is the server running on host “172.16.XX.YY” and accepting
TCP/IP connections on port 5432?

My workaround was :
Edit pg_hba.conf
host $MAAS_DBNAME $MAAS_DBUSER 172.16.XX.YY/ZZ md5
And postgresql.conf
listen_addresses = '*'

And restarting postgresql service.

tmartins · 10 July 2023 08:47

Hello,

On the documentation page, when you select: v3.4 Snap, it tells you to sudo snap install --channel=latest/edge maas, which will bring the wrong version (3.5.0~alpha1-14457-g.c9d08507b).

I think that the correct one should be snap install maas --channel=3.4/beta.

Cheers!

timblaktu · 15 August 2023 01:07

THanks @tmartins. It also looks like the latest docs page has the “How to Configure MaaS” section at the bottom completely missing… THe only place I can find docs on this are on the 3.4 announcement page: https://maas.io/docs/what-is-new-with-maas-3-4. Anyone know the right place for the docs for 3.4 beta?

EDIT: After much head scratching, I now believe that THE OP IN THIS THREAD IS THE LATEST DOCUMENTATION FOR 3.4-BETA.

andre-ruiz · 17 September 2023 14:51

This should be “maas $PROFILE” and not “maas admin”.

erickeller · 8 December 2023 10:01

Hi there, it seems that the maas packages where not published to the ppa for the version 3.4, https://ppa.launchpadcontent.net/maas/3.4/ubuntu/pool/main/

there is no maas package which make it impossible to install it over debian package.

r00ta · 8 December 2023 10:15

Hi @erickeller

MAAS 3.4 is not released yet. We expect to release it in the next weeks or so.

dilyn-corner · 31 January 2024 18:15

The second line here appears to merely be a typo

Go to custom anchor

Should be more like

[Install MAAS](link)

In the “Distributed env (Deb)” section a useful step is given:

Add the MAAS 3.3 PPA to your apt repository paths on both region and rack target hosts:

It’s probably better to specify “Add the MAAS PPA for the version of MAAS you want” and anchor that to the install section above. Speaking of which, wouldn’t it be better to break it up into two sections, “Install snap” and “Install deb”, and then have each version be a subsection? But since the instructions are largely aligned independent of version, maybe just make it one section each with snap install --channel=${x.y} maas and sudo apt-add-repository ppa:maas/${x.y}
It would make the top-of-page index more readable, I think.

Wording in “Create an admin” is a bit confusing

Substitute $PROFILE is the administrative MAAS username you wish to create.

Axe substitute and replace $PROFILE with one of $LOGNAME, $USER or $USERNAME.
The numbering scheme also seems to indicate that each of the three points are different steps which must be undertaken to create an admin, but (2) and (3) appear to just be modifications on the command given in (1). Perhaps they should be notes or added to the explanation of $PROFILE?

Nit on user SSH key location:

Copy your entire public key from .ssh/id_rsa.pub

Maybe make it ~/.ssh/id_{scheme}.pub

nrvale0 · 13 February 2024 21:08

The init command is not correct. At least not for the .deb install. I haven’t tried the others.

$ sudo maas init region+rack --database-uri "postgres://$MAAS_DBUSER:$MAAS_DBPASS@$HOSTNAME/$MAAS_DBNAME"
usage: maas [-h] COMMAND ...

options:
  -h, --help      show this help message and exit

drill down:
  COMMAND
    login         Log in to a remote API, and remember its description and credentials.
    logout        Log out of a remote API, purging any stored credentials.
    list          List remote APIs that have been logged-in to.
    refresh       Refresh the API descriptions of all profiles.
    init          Initialize controller.
    apikey        Used to manage a user's API keys. Shows existing keys unless --generate or
                  --delete is passed.
    configauth    Configure external authentication.
    config-tls    Configure MAAS Region TLS.
    config-vault  Configure MAAS Region Vault integration.
    createadmin   Create a MAAS administrator account.
    changepassword
                  Change a MAAS user's password.

https://maas.io/

sudo maas init region+rack --database-uri "postgres://$MAAS_DBUSER:$MAAS_DBPASS@$HOSTNAME/$MAAS_DBNAME"
usage: maas [-h] COMMAND ...

options:
  -h, --help      show this help message and exit

drill down:
  COMMAND
    login         Log in to a remote API, and remember its description and credentials.
    logout        Log out of a remote API, purging any stored credentials.
    list          List remote APIs that have been logged-in to.
    refresh       Refresh the API descriptions of all profiles.
    init          Initialize controller.
    apikey        Used to manage a user's API keys. Shows existing keys unless --generate or
                  --delete is passed.
    configauth    Configure external authentication.
    config-tls    Configure MAAS Region TLS.
    config-vault  Configure MAAS Region Vault integration.
    createadmin   Create a MAAS administrator account.
    changepassword
                  Change a MAAS user's password.

https://maas.io/

unrecognized arguments: region+rack --database-uri postgres://<redacted>