Skip to content

Configuration

Jump to bottom
John Stange edited this page Nov 18, 2020 · 14 revisions

mu.yaml

Mu's configuration is stored in mu.yaml. An exhaustive list of options can be found here.

Simple gem-based Mu installations will look for ~/.mu.yaml in the home of the invoking user.

If you've installed a dedicated Mu Master, the main systemwide Mu configuration will be in /opt/mu/etc/mu.yaml. Non-root users on dedicated Mu Masters can customize some variables in their own personal ~/.mu.yaml files.

This file can be edited directly, but it's typically operated on by using mu-configure.

mu-configure

mu-configure is a menu-driven command line utility used to edit your mu.yaml file. During a manual full installation, you will be prompted by mu-configure for initial setup parameters:

1) Public Address - REQUIRED
2) Admin Email - REQUIRED
3) Admin Name - Mu Administrator (DEFAULT)
4) Local Hostname - REQUIRED
5) Momma Cat Listen Port - 2260 (DEFAULT)
6) Banner - Mu Master at stange-mu-dev (DEFAULT)
7) Mu Tools Repository - git://github.com/cloudamatic/mu.git (DEFAULT)
8) Additional Repositories - ["https://github.com/cloudamatic/mu_demo_platform"] (DEFAULT)
9) Mu Master Runlist Extras
10) Invade Foreign VPCs? - false (DEFAULT)
11) Ansible directory
12) Amazon Web Services
13) Google Cloud Platform
14) Microsoft Azure Cloud Computing Platform & Services

Only Public Address, Admin Email, and Local Hostname are required during initial installation. Note that Public Address can be, but is not always, the local machine's first IP address. This field may also be a hostname, an aliased public IP exposed by a cloud provider, or the address of a load balancer or proxy server.

In a gem-based installation, Mu will attempt to autodetect as much configuration as possible, but in most circumstances you will need to run mu-configure to add cloud provider credentials.

Most options are also exposed as switches, for use with no-menu mode (-n). See mu-configure --help for details.

Amazon Web Services accounts

1) Default Target Account
2) Default Region - us-east-1 (DEFAULT)
3) Credentials Vault:Item
4) Credentials File
5) Access Key
6) Access Secret
7) Log and Secret Bucket Name - REQUIRED
8) Is Default - false (DEFAULT)
9) Name - REQUIRED

Unless Mu is installed on an AWS instance which has, via an Instance Profile, working administrative API credentials, you will need to retrieve an Access Key and a Secret from an appropriate IAM user and provide them to Mu.

  1. Create a user in the IAM Console, being sure to check the Programmatic access box when doing so.
  2. In the permissions pane, either assign the user to a group with administrative access, or use the Attach existing policies directly option to attach the AdministratorAccess policy.
  3. Tag and review the account as desired, then create it
  4. Retrieve the access key and secret from the next page. Note that the latter will not be retrievable again. If necessary, you can edit the user to add a new key/secret pair later.

These credentials can be inserted into Mu in any of several ways:

  • If in a Chef environment (such as a full Mu Master install), create a vault item with access_key and access_secret elements, like knife vault create myawsacct creds '{ "access_key": "foo", "access_secret": "bar" }'. Then, using the menu options in mu-configure, select Credentials Vault:Item and point it to your new credentials.
  • Insert the raw Access Key and Access Secret strings using those mu-configure menu options/
  • Use the Credentials File option with a path to an awscli style credentials .ini file.

Google Cloud Project accounts

The Google subsection of the mu-configure menu:

1) Default Project - REQUIRED
2) Credentials Vault:Item
3) Credentials File
4) Base64-Encoded Credentials
5) Default Region - us-east4 (DEFAULT)
6) Log and Secret Bucket Name - REQUIRED
7) GSuite Masquerade User
8) GSuite Customer ID
9) Is Default Account - false (DEFAULT)
11) Name - REQUIRED

The Google Cloud layer uses the credentials of a GCP Service Account. Navigate to the Service Accounts page of the GCP console in your project, and choose Create Service Account. Under most circumstances, you will want to grant Project => Owner permissions to this service account. Be sure to select Create Key (JSON), which should generate and automatically download a JSON file with service credentials.

These credentials can be inserted into Mu in any of several ways:

  • If in a Chef environment (such as a full Mu Master install), create a vault from the JSON credentials file, e.g. knife vault create secrets google -J my-google-service-account.json. Then set the Credentials Vault:Item option.
  • Place the JSON credentials file in a file and set the path to that file with the Credentials File option.
  • Base64 encode the contents of the JSON credentials file, perhaps with the base64 utility, then select the Base64-Encoded Credentials option and paste the resulting string.

GSuite and Cloud Identity

If you are in a GSuite or Cloud Identity organization, with multiple projects, choose or create a project intended for long-term administrative use when creating your service account. You can later grant access to multiple projects one of several ways:

  • Grant domain-wide access to Mu by selecting your whole organization from the drop-down menu at the top of the page. Go to the IAM pane and add the service account user from your administrative project to the domain. You may also wish to add Resource Manager => Organization Administrator, if Mu will be expected to have full dominion over all organization resources.
  • Navigate to a folder which contains projects which Mu will be permitted to manage. Go to the IAM pane and add the service account user from your administrative project to this folder (and thus all child folders/projects), with the Project => Owner role. You may also wish to add Resource Manager => Folder Admin, if Mu will be creating and deleting folders.
  • Navigate to each individual project which Mu will be permitted to manage. Go to the IAM pane and add the service account user from your administrative project to this project, with the Owner role.

Mu can also manage GSuite-level GCP resources, such as users and groups. This requires a special delegation of directory-level privileges to Mu's GCP service account. Certain folder and project management API calls also require this delegation.

These instructions are intended for GSuite customers. While they are also applicable to Cloud Identity domains, Oauth delegation does not seem to work consistently with Cloud Identity. Investigation with Google Support is ongoing.

  1. On the Service Accounts management tab, click on your service account to view its details. In the Unique ID field, there should be a long numeric string. Save this string.
  2. As a GSuite domain administrative user, log into admin.google.com. Choose Security, the Single Sign On, and look for the Entity ID field. The value after idpid= in the URL there should be the Customer ID`. Save this string.
  3. Using mu-configure, fill in the GSuite Customer ID value with the string obtained in step 2, and the GSuite Masquerade User value with the email address of a GSuite user in this organization with appropriate domain privileges.
  4. Now, as a GSuite domain administrative user, navigate to the Oauth Client Management page. In the Client Name field, enter the service account unique ID we saved in step 1. In the API Scopes field, enter the following list of scopes:
https://www.googleapis.com/auth/admin.directory.group.member, https://www.googleapis.com/auth/admin.directory.group, https://www.googleapis.com/auth/admin.directory.user, https://www.googleapis.com/auth/admin.directory.domain, https://www.googleapis.com/auth/admin.directory.orgunit, https://www.googleapis.com/auth/admin.directory.rolemanagement, https://www.googleapis.com/auth/admin.directory.customer, https://www.googleapis.com/auth/admin.directory.user.alias, https://www.googleapis.com/auth/admin.directory.userschema, https://www.googleapis.com/auth/admin.directory.group.member.readonly, https://www.googleapis.com/auth/admin.directory.group.readonly, https://www.googleapis.com/auth/admin.directory.user.readonly, https://www.googleapis.com/auth/admin.directory.domain.readonly, https://www.googleapis.com/auth/admin.directory.orgunit.readonly, https://www.googleapis.com/auth/admin.directory.rolemanagement.readonly, https://www.googleapis.com/auth/admin.directory.customer.readonly, https://www.googleapis.com/auth/admin.directory.user.alias.readonly, https://www.googleapis.com/auth/admin.directory.userschema.readonly

To only grant Mu read-only access to organization-level resources, you can instead use:

https://www.googleapis.com/auth/admin.directory.group.member.readonly, https://www.googleapis.com/auth/admin.directory.group.readonly, https://www.googleapis.com/auth/admin.directory.user.readonly, https://www.googleapis.com/auth/admin.directory.domain.readonly, https://www.googleapis.com/auth/admin.directory.orgunit.readonly, https://www.googleapis.com/auth/admin.directory.rolemanagement.readonly, https://www.googleapis.com/auth/admin.directory.customer.readonly, https://www.googleapis.com/auth/admin.directory.user.alias.readonly, https://www.googleapis.com/auth/admin.directory.userschema.readonly

Microsoft Azure accounts

The Azure subsection of the mu-configure menu:

1) Directory ID
2) Client ID
3) Client Secret
4) Default Subscription
5) Credentials File
6) Default Region - eastus (DEFAULT)
7) Is Default Account - false (DEFAULT)
9) Name - REQUIRED

We'll need a Directory ID, Client ID, Client Secret, and Subscription for credentials with sufficient privileges to create and destroy resources will be required. These can be entered directly, or saved in a JSON file with the values in a hash (keys directory_id, client_id, client_secret, subscription).

Azure credentials can be retrieved from the Azure web portal.

We suggest creating a Managed Identity for Mu's application credentials. When creating, be sure to retrieve and save the client_secret, which can only be accessed once. Then, return to the Subscriptions page and select your subscription to reach its dashboard. From there, Access control (IAM), and choose Add a role assignment to grant Mu subscription-wide administrator privileges so that it can create and delete resources, modify users, etc.

Install
Configuration
Your First Deployment
Simple Use Cases
More Complex Cases
Mu Master Backup
Inspec Tests
Technical Documentation

Clone this wiki locally