Managing Organizations and Locations in Foreman

1. Introduction to Organization and Location Context in Foreman

Context in Foreman consists of Organizations and Locations.

Most resources in Foreman are associated with at least one organization and location context. Since resources and users can generally only access resources within their own context, organizations and locations are an integral part of Foreman’s user management.

You can structure locations hierarchically by providing a parent location. Unless otherwise specified, sub locations inherit the settings from their parent location.

Caution

If you use host groups to bundle provisioning and configuration information, ensure to not mismatch resources from mutually exclusive contexts. For example, setting a subnet from one organization or location and a compute resource from a different organization or location creates an invalid host group.

Some resources in Foreman, such as Ansible roles and operating systems, are not part of any organization or location context.

2. Managing Organizations

Organizations divide Foreman resources into logical groups based on ownership, purpose, content, security level, or other divisions. You can create and manage multiple organizations through Foreman, then divide and assign subscriptions to each individual organization. This provides a method of managing the content of several individual organizations under one management system. Here are some examples of organization management:

Single Organization: A small business with a simple system administration chain. In this case, you can create a single organization for the business and assign content to it.
Multiple Organizations: A large company that owns several smaller business units. For example, a company with separate system administration and software development groups. In this case, you can create organizations for the company and each of the business units it owns. This keeps the system infrastructure for each separate. You can then assign content to each organization based on its needs.
External Organizations: A company that manages external systems for other organizations. For example, a company offering cloud computing and web hosting resources to customers. In this case, you can create an organization for the company’s own system infrastructure and then an organization for each external business. You can then assign content to each organization where necessary.

A default installation of Foreman has a default organization called Default Organization.

New Users

If a new user is not assigned a default organization, their access is limited. To grant systems rights to users, assign them to a default organization. The next time the user logs on to Foreman, the user’s account has the correct system rights.

2.1. Creating an Organization

Use this procedure to create an organization. To use the CLI instead of the Foreman web UI, see the CLI procedure.

Procedure

In the Foreman web UI, navigate to Administer > Organizations.
Click New Organization.
In the Name field, enter a name for the organization.
In the Label field, enter a unique identifier for the organization. This is used for creating and mapping certain assets, such as directories for content storage. Use letters, numbers, underscores, and dashes, but no spaces.
Optional: If you do not wish to enable Simple Content Access (SCA), uncheck the Simple Content Access checkbox. For more information on SCA, see Simple Content Access.

Note

Foreman community does not recommend disabling SCA as entitlement mode is deprecated.
Optional: in the Description field, enter a description for the organization.
Click Submit.
If you have hosts with no organization assigned, select the hosts that you want to add to the organization, then click Proceed to Edit.
In the Edit page, assign the infrastructure resources that you want to add to the organization. This includes networking resources, installation media, kickstart templates, and other parameters. You can return to this page at any time by navigating to Administer > Organizations and then selecting an organization to edit.
Click Submit.

CLI procedure

To create an organization, enter the following command:

# hammer organization create \
--name "My_Organization" \
--label "My_Organization_Label" \
--description "My_Organization_Description"

Note	Organizations created this way have Simple Content Access (SCA) enabled by default. If you wish to disable SCA, add the `--simple-content-access false` parameter to the command. Foreman community does not advise you to disable SCA because entitlement mode (not using SCA) is deprecated.

Optional: To edit an organization, enter the hammer organization update command. For example, the following command assigns a compute resource to the organization:
```
# hammer organization update \
--name "My_Organization" \
--compute-resource-ids 1
```

2.2. Setting the Organization Context

An organization context defines the organization to use for a host and its associated resources.

Procedure

The organization menu is the first menu item in the menu bar, on the upper left of the Foreman web UI. If you have not selected a current organization, the menu says Any Organization. Click the Any Organization button and select the organization to use.

CLI procedure

While using the CLI, include either --organization "My_Organization" or --organization-label "My_Organization_Label" as an option. For example:

# hammer subscription list \
--organization "My_Organization"

This command outputs subscriptions allocated for the My_Organization.

2.3. Deleting an Organization

You can delete an organization if the organization is not associated with any life cycle environments or host groups. If there are any life cycle environments or host groups associated with the organization you are about to delete, remove them by navigating to Administer > Organizations and clicking the relevant organization. Do not delete the default organization created during installation because the default organization is a placeholder for any unassociated hosts in the Foreman environment. There must be at least one organization in the environment at any given time.

Procedure

In the Foreman web UI, navigate to Administer > Organizations.
From the list to the right of the name of the organization you want to delete, select Delete.
Click OK to delete the organization.

CLI procedure

Enter the following command to retrieve the ID of the organization that you want to delete:
```
# hammer organization list
```
From the output, note the ID of the organization that you want to delete.
Enter the following command to delete an organization:
```
# hammer organization delete --id Organization_ID
```

3. Managing Locations

Locations function similar to organizations: they provide a method to group resources and assign hosts. Organizations and locations have the following conceptual differences:

Locations are based on physical or geographical settings.
Locations have a hierarchical structure.

3.1. Creating a Location

Use this procedure to create a location so that you can manage your hosts and resources by location. To use the CLI instead of the Foreman web UI, see the CLI procedure.

Procedure

In the Foreman web UI, navigate to Administer > Locations.
Click New Location.
Optional: from the Parent list, select a parent location. This creates a location hierarchy.
In the Name field, enter a name for the location.
Optional: in the Description field, enter a description for the location.
Click Submit.
If you have hosts with no location assigned, add any hosts that you want to assign to the new location, then click Proceed to Edit.
Assign any infrastructure resources that you want to add to the location. This includes networking resources, installation media, kickstart templates, and other parameters. You can return to this page at any time by navigating to Administer > Locations and then selecting a location to edit.
Click Submit to save your changes.

CLI procedure

Enter the following command to create a location:

# hammer location create \
--description "My_Location_Description" \
--name "My_Location" \
--parent-id "My_Location_Parent_ID"

3.2. Creating Multiple Locations

The following example Bash script creates three locations – London, Munich, Boston – and assigns them to the Example Organization.

ORG="Example Organization"
LOCATIONS="London Munich Boston"

for LOC in ${LOCATIONS}
do
  hammer location create --name "${LOC}"
  hammer location add-organization --name "${LOC}" --organization "${ORG}"
done

3.3. Setting the Location Context

A location context defines the location to use for a host and its associated resources.

Procedure

The location menu is the second menu item in the menu bar, on the upper left of the Foreman web UI. If you have not selected a current location, the menu displays Any Location. Click Any location and select the location to use.

CLI procedure

While using the CLI, include either --location "My_Location" or --location-id "My_Location_ID" as an option. For example:

# hammer host list --location "My_Location"

This command lists hosts associated with the My_Location location.

3.4. Deleting a Location

You can delete a location if the location is not associated with any life cycle environments or host groups. If there are any life cycle environments or host groups associated with the location you are about to delete, remove them by navigating to Administer > Locations and clicking the relevant location. Do not delete the default location created during installation because the default location is a placeholder for any unassociated hosts in the Foreman environment. There must be at least one location in the environment at any given time.

Procedure

In the Foreman web UI, navigate to Administer > Locations.
Select Delete from the list to the right of the name of the location you want to delete.
Click OK to delete the location.

CLI procedure

Enter the following command to retrieve the ID of the location that you want to delete:
```
# hammer location list
```
From the output, note the ID of the location that you want to delete.
Enter the following command to delete the location:
```
# hammer location delete --id Location ID
```