diff --git a/en/index.md b/en/index.md index d1b1a34b..6d30581e 100644 --- a/en/index.md +++ b/en/index.md @@ -49,11 +49,36 @@ MAAS works with any configuration system, and is recommended by the teams behind both [Chef][about-chef] and [Juju][about-juju] as a physical provisioning system. +The [web UI][webui] provides a responsive interface to the majority of MAAS +functionality, while the [CLI][manage-cli] and [REST API][api] facilitate +configuration and large-scale automation. + +![web UI showing node view][img__webui] + !!! Note: Windows, RHEL and SUSE images require [Ubuntu Advantage][ubuntu-advantage] to work properly with MAAS. +## Key components and colocation of all services + +The key components of a MAAS installation are the region controller and the +rack controller. See [Concepts and terms][concepts-controllers] for how each +are defined. + +Unless there is specific reason not to, it is recommended to have both +controllers residing on the same system. A no-fuss way to achieve this is by +installing the `maas` metapackage, or by installing from the Ubuntu Server ISO. + +Multiple region and rack controllers are required if +[high availability][manage-ha] and/or load balancing (see HA page) is desired. + +It's important to note that the all-in-one solution will provide a DHCP +service. Review your existing network design in order to determine whether this +will cause problems. See [DHCP][dhcp] for more on this subject. + +![intro-arch-overview][img__arch-overview] + ## How MAAS works MAAS manages a pool of nodes. After registering ("Enlisting" state) a new @@ -93,116 +118,6 @@ Juju terminology. However, everything that was stated earlier still applies. For instance, if Juju removes a machine then MAAS will, in turn, release that machine to the pool. - -## Key components and colocation of all services - -The key components of a MAAS installation are the region controller and the -rack controller. See [Concepts and terms][concepts-controllers] for how each -are defined. - -Unless there is specific reason not to, it is recommended to have both -controllers residing on the same system. A no-fuss way to achieve this is by -installing the `maas` metapackage, or by installing from the Ubuntu Server ISO. - -Multiple region and rack controllers are required if -[high availability][manage-ha] and/or load balancing (see HA page) is desired. - -It's important to note that the all-in-one solution will provide a DHCP -service. Review your existing network design in order to determine whether this -will cause problems. See [DHCP][dhcp] for more on this subject. - - -## Installation methods - -There are three ways to install MAAS: - -- From the Ubuntu Server ISO -- From software packages ("debs") -- As a self-contained LXD environment - -These methods, and their respective advantages, are fleshed out on the -[Installation][maas-install] page. - - -## Minimum requirements - -The minimum requirements for the machines that run MAAS vary widely depending -on local implementation and usage. - -Below, resource estimates are provided based on MAAS components and operating -system (Ubuntu Server). A test (or proof of concept) and a production -environment are considered. - - -^# Test environment - - This is a proof of concept scenario where all MAAS components are installed - on a single host. *Two* complete sets of images (latest two Ubuntu - LTS releases) for a *single* architecture (amd64) have been assumed. - - | | Memory (MB) | CPU (GHz) | Disk (GB) | - | --------------------------------------------------- | ----------- | --------- | --------- | - | [Region controller][concepts-controllers] (minus PostgreSQL) | 512 | 0.5 | 5 | - | PostgreSQL | 512 | 0.5 | 5 | - | [Rack controller][concepts-controllers] | 512 | 0.5 | 5 | - | Ubuntu Server (including logs) | 512 | 0.5 | 5 | - - Therefore, the approximate requirements for this scenario are: 2 GB memory, - 2 GHz CPU, and 20 GB of disk space. - - -^# Production environment - - This is a production scenario that is designed to handle a high number of - sustained client connections. Both high availability (region and rack) and load - balancing (region) have been implemented. - - Even though extra space has been reserved for images (database and rack - controller) some images such as those for Microsoft Windows may require a lot - more (plan accordingly). - - | | Memory (MB) | CPU (GHz) | Disk (GB) | - | --------------------------------------------------- | ----------- | --------- | --------- | - | [Region controller][concepts-controllers] (minus PostgreSQL) | 2048 | 2.0 | 5 | - | PostgreSQL | 2048 | 2.0 | 20 | - | [Rack controller][concepts-controllers] | 2048 | 2.0 | 20 | - | Ubuntu Server (including logs) | 512 | 0.5 | 20 | - - Therefore, the approximate requirements for this scenario are: - - - A region controller (including PostgreSQL) is installed on one host: 4.5 GB - memory, 4.5 GHz CPU, and 45 GB of disk space. - - A region controller (including PostgreSQL) is duplicated on a second - host: 4.5 GB memory, 4.5 GHz CPU, and 45 GB of disk space. - - A rack controller is installed on a third host: 2.5 GB memory, 2.5 GHz CPU, - and 40 GB of disk space. - - A rack controller is duplicated on a fourth host: 2.5 GB memory, 2.5 GHz CPU, - and 40 GB of disk space. - -!!! Note: - Figures in the above two tables are for the MAAS infrastructure only. - That is, they do not cover resources needed on the nodes that will subsequently - be added to MAAS. That said, node machines should have IPMI-based BMC - controllers for power cycling, see [BMC power types][power-types]. - -Examples of factors that influence hardware specifications include: - - - the number of connecting clients (client activity) - - the manner in which services are distributed - - whether [high availability][manage-ha] is used - - whether [load balancing][load-balancing] is used - - the number of images that are stored (disk space affecting PostgreSQL and - the rack controller) - -Equally not taken into account is a possible [local image mirror][mirror] which -would be a large consumer of disk space. - -One rack controller should not be used to service more than 1000 nodes (whether -on the same or multiple subnets). There is no load balancing at the rack level -so further independent rack controllers will be needed with each one servicing -its own subnet(s). - - [about-chef]: https://www.chef.io/chef @@ -216,3 +131,10 @@ its own subnet(s). [power-types]: nodes-power-types.md [load-balancing]: manage-ha.md#load-balancing-(optional) [mirror]: installconfig-images-mirror.md +[webui]: installconfig-webui.md +[manage-cli]: manage-cli.md +[api]: api.md + + +[img__webui]: ../media/intro__2.3_webui.png +[img__arch-overview]: ../media/intro-arch-overview.png diff --git a/en/intro-architecture.md b/en/intro-architecture.md deleted file mode 100644 index ade0bc06..00000000 --- a/en/intro-architecture.md +++ /dev/null @@ -1,13 +0,0 @@ -Title: Architectural Overview - - -# Architectural Overview - -The high level architecture of MAAS is presented below. - -![intro-arch-overview][img__arch-overview] - - - - -[img__arch-overview]: ../media/intro-arch-overview.png diff --git a/en/intro-management.md b/en/intro-management.md deleted file mode 100644 index d933d9e2..00000000 --- a/en/intro-management.md +++ /dev/null @@ -1,43 +0,0 @@ -Title: Management Summary - - -# Management Summary - -MAAS can be managed, typically by a systems administrator, in the following -ways: - -- Web UI (graphical interface) -- CLI (text-based terminal) -- API (involves programming) - -This section will cover each briefly. Details of each will be provided in -future chapters. - - -## Web UI - -The web UI gets installed along with the MAAS software. This documentation -regards the web UI as the primary means for configuring and managing MAAS and -will use it as the preferred method in all instructions and examples. See -[Web UI][webui] once MAAS is installed. - -Some advanced functionality is only available with the CLI. See below. - - -## CLI - -The CLI consists of the `maas` wrapper command that interacts with the API. To -get a sense of what is possible with the CLI see [MAAS CLI][manage-cli]. - - -## API - -The API is typically reserved for large-scale automization. See -[API documentation][api]. - - - - -[webui]: installconfig-webui.md -[manage-cli]: manage-cli.md -[api]: api.md diff --git a/en/intro-requirements.md b/en/intro-requirements.md new file mode 100644 index 00000000..76a9f148 --- /dev/null +++ b/en/intro-requirements.md @@ -0,0 +1,84 @@ +Title: What is MAAS? +table_of_contents: True + +# Requirements + +The minimum requirements for the machines that run MAAS vary widely depending +on local implementation and usage. + +Below, resource estimates are provided based on MAAS components and operating +system (Ubuntu Server). A test (or proof of concept) and a production +environment are considered. + + +## Test environment + + This is a proof of concept scenario where all MAAS components are installed + on a single host. *Two* complete sets of images (latest two Ubuntu + LTS releases) for a *single* architecture (amd64) have been assumed. + + | | Memory (MB) | CPU (GHz) | Disk (GB) | + | --------------------------------------------------- | ----------- | --------- | --------- | + | [Region controller][concepts-controllers] (minus PostgreSQL) | 512 | 0.5 | 5 | + | PostgreSQL | 512 | 0.5 | 5 | + | [Rack controller][concepts-controllers] | 512 | 0.5 | 5 | + | Ubuntu Server (including logs) | 512 | 0.5 | 5 | + + Therefore, the approximate requirements for this scenario are: 2 GB memory, + 2 GHz CPU, and 20 GB of disk space. + + +## Production environment + + This is a production scenario that is designed to handle a high number of + sustained client connections. Both high availability (region and rack) and load + balancing (region) have been implemented. + + Even though extra space has been reserved for images (database and rack + controller) some images such as those for Microsoft Windows may require a lot + more (plan accordingly). + + | | Memory (MB) | CPU (GHz) | Disk (GB) | + | --------------------------------------------------- | ----------- | --------- | --------- | + | [Region controller][concepts-controllers] (minus PostgreSQL) | 2048 | 2.0 | 5 | + | PostgreSQL | 2048 | 2.0 | 20 | + | [Rack controller][concepts-controllers] | 2048 | 2.0 | 20 | + | Ubuntu Server (including logs) | 512 | 0.5 | 20 | + + Therefore, the approximate requirements for this scenario are: + + - A region controller (including PostgreSQL) is installed on one host: 4.5 GB + memory, 4.5 GHz CPU, and 45 GB of disk space. + - A region controller (including PostgreSQL) is duplicated on a second + host: 4.5 GB memory, 4.5 GHz CPU, and 45 GB of disk space. + - A rack controller is installed on a third host: 2.5 GB memory, 2.5 GHz CPU, + and 40 GB of disk space. + - A rack controller is duplicated on a fourth host: 2.5 GB memory, 2.5 GHz CPU, + and 40 GB of disk space. + +!!! Note: + Figures in the above two tables are for the MAAS infrastructure only. + That is, they do not cover resources needed on the nodes that will subsequently + be added to MAAS. That said, node machines should have IPMI-based BMC + controllers for power cycling, see [BMC power types][power-types]. + +Examples of factors that influence hardware specifications include: + + - the number of connecting clients (client activity) + - the manner in which services are distributed + - whether [high availability][manage-ha] is used + - whether [load balancing][load-balancing] is used + - the number of images that are stored (disk space affecting PostgreSQL and + the rack controller) + +Equally not taken into account is a possible [local image mirror][mirror] which +would be a large consumer of disk space. + +One rack controller should not be used to service more than 1000 nodes (whether +on the same or multiple subnets). There is no load balancing at the rack level +so further independent rack controllers will be needed with each one servicing +its own subnet(s). + +[concepts-controllers]: intro-concepts.md#controllers +[manage-ha]: manage-ha.md +[load-balancing]: manage-ha.md#load-balancing-(optional) diff --git a/en/metadata.yaml b/en/metadata.yaml index bac25141..774d7e5f 100644 --- a/en/metadata.yaml +++ b/en/metadata.yaml @@ -1,52 +1,70 @@ navigation: - - title: Introduction + - title: Get started + location: index.md children: - title: About MAAS location: index.md - - title: Management summary - location: intro-management.md + - title: Requirements + location: intro-requirements.md - - title: Concepts and terms - location: intro-concepts.md + - title: User guide + location: installconfig-install.md - - title: Architectural overview - location: intro-architecture.md + children: + + - title: Install MAAS + location: installconfig-install.md - - title: Install & Configure + - title: Controllers - children: + children: - - title: Checklist - location: installconfig-checklist.md + - title: Rack controller + location: installconfig-rack.md - - title: Install MAAS - location: installconfig-install.md + - title: Nodes children: + + - title: Node overview + location: nodes-overview.md + + - title: Add nodes + location: nodes-add.md + + - title: BMC power types + location: nodes-power-types.md + + - title: Commission nodes + location: nodes-commission.md - - title: Install from ISO - location: installconfig-iso-install.md + - title: Deploy nodes + location: nodes-deploy.md - - title: Install from packages - location: installconfig-package-install.md + - title: Tags + location: nodes-tags.md - - title: Install from a snap - location: installconfig-snap-install.md + - title: Kernel boot options + location: nodes-kernel-options.md - - title: Install with LXD - location: installconfig-lxd-install.md + - title: Ubuntu kernels + location: nodes-kernels.md - - title: Upgrade from 1.9 to 2.0 - location: installconfig-upgrade-to-2.md + - title: Hardware testing + location: nodes-hw-testing.md - - title: Rack controller - location: installconfig-rack.md + - title: Hardware testing scripts + location: nodes-hw-scripts.md + + - title: Composable hardware + location: nodes-comp-hw.md + + - title: Custom node setup + location: nodes-custom.md - - title: Web UI - location: installconfig-webui.md - title: Images location: installconfig-images.md @@ -59,7 +77,7 @@ navigation: - title: Local image mirror location: installconfig-images-mirror.md - - title: Networking + - title: Networks location: installconfig-networking.md children: @@ -91,56 +109,12 @@ navigation: - title: STP location: installconfig-network-stp.md + - title: Zones + location: manage-zones.md + - title: Storage location: installconfig-storage.md - - title: Nodes - - children: - - - title: Add nodes - location: nodes-add.md - - - title: BMC power types - location: nodes-power-types.md - - - title: Node overview - location: nodes-overview.md - - - title: Commission nodes - location: nodes-commission.md - - - title: Deploy nodes - location: nodes-deploy.md - - - title: Tags - location: nodes-tags.md - - - title: Kernel boot options - location: nodes-kernel-options.md - - - title: Ubuntu kernels - location: nodes-kernels.md - - - title: Hardware testing - location: nodes-hw-testing.md - - - title: Hardware testing scripts - location: nodes-hw-scripts.md - - - title: Composable hardware - location: nodes-comp-hw.md - - - title: Custom node setup - location: nodes-custom.md - - - title: Manage MAAS - - children: - - - title: Zones - location: manage-zones.md - - title: User accounts location: manage-account.md @@ -153,53 +127,56 @@ navigation: - title: Backup location: manage-backup.md - - title: MAAS CLI - location: manage-cli.md + - title: Concepts & terms + location: intro-concepts.md + + - title: Troubleshoot children: - - title: Common tasks - location: manage-cli-common.md + - title: FAQ + location: troubleshoot-faq.md - - title: Kernel management - location: manage-cli-kernels.md + - title: Getting help + location: troubleshoot-getting-help.md - - title: Image management - location: manage-cli-images.md + - title: Command reference + location: manage-cli.md - - title: Interface management - location: manage-cli-interfaces.md + children: - - title: Tag management - location: manage-cli-tags.md + - title: Common tasks + location: manage-cli-common.md - - title: DHCP snippet management - location: manage-cli-dhcp-snippets.md + - title: Kernel management + location: manage-cli-kernels.md - - title: Hardware testing scripts - location: nodes-hw-scripts-cli.md + - title: Image management + location: manage-cli-images.md - - title: Script metadata - location: nodes-hw-scripts-fields.md + - title: Interface management + location: manage-cli-interfaces.md - - title: Advanced tasks - location: manage-cli-advanced.md + - title: Tag management + location: manage-cli-tags.md - - title: Composable hardware - location: manage-cli-comp-hw.md + - title: DHCP snippet management + location: manage-cli-dhcp-snippets.md - - title: API client - location: manage-libmaas.md + - title: Hardware testing scripts + location: nodes-hw-scripts-cli.md - - title: Troubleshoot + - title: Script metadata + location: nodes-hw-scripts-fields.md - children: + - title: Advanced tasks + location: manage-cli-advanced.md - - title: FAQ - location: troubleshoot-faq.md + - title: Composable hardware + location: manage-cli-comp-hw.md - - title: Getting help - location: troubleshoot-getting-help.md + - title: API client + location: manage-libmaas.md - title: API documentation location: api.md @@ -214,9 +191,6 @@ navigation: - title: Release notes location: release-notes.md - + - title: Help improve these docs location: contributing-writing.md - - - title: Report a docs issue - location: https://github.com/CanonicalLtd/maas-docs/issues/new diff --git a/media/intro__2.3_webui.png b/media/intro__2.3_webui.png new file mode 100644 index 00000000..9057571f Binary files /dev/null and b/media/intro__2.3_webui.png differ