1. Introduction

Application Centric Deployment (ACD) describes a fundamentally different approach to provisioning and configuring hosts in Foreman. Traditionally, Foreman has pursued a host-centric approach. Now, the ACD approach presents a new idea: deploying hosts to run an application that requires a predefined set of services.

Generally, an application consists of multiple services and therefore requires different kinds of hosts connected to each other. These hosts have dependencies on each other, for example, an application server might require a database server.

The number of deployed hosts depends on the expected usage of the application. You can scale an application instance vertically via compute profile or horizontally by choosing multiple hosts to run the same service to handle increased workloads.

Within ACD, Ansible playbooks are executed on Foreman server. Ensure that Foreman server can connect to all managed hosts using Ansible.

Host Centric vs. Application Centric Deployment

Host Centric Deployment

Application Centric Deployment

Requirements

none (possible by default)

ACD plugin

Focus

individual hosts

applications

Number of Hosts

one

one to many

Automation

via Host Group

via Ansible playbook and application definition

Advantages

full control over each host

deploy a number of hosts at once; self service for technically less inclined; scale vertically and/or horizontally

Disadvantages

extra abstraction layer between a host and its purpose

dependency on/limitation to existing application templates

1.1. Usage Example

The following application centric deployment example illustrates the deployment of hosts in an application centric approach. The web application requires an HAProxy, an Apache web server, a Tomcat application server, and a database server.

Using ACD, this web application can be deployed and configured in a single step:

  1. Import the Ansible playbook

    Upload the Ansible playbook to your Foreman server. Specify the path and the name of the Ansible playbook via management UI.

  2. Create an application definition

    This example requires four different services: proxy servers, web servers, application servers, and database servers. Those hosts are ideally part of a host group.

  3. Optional: Customize Ansible variables

    You can either use the default values, change values, or lock the Ansible variables from being edited for an application instance. Ansible variables are read from the group variables of the Ansible playbook.

  4. Optional: Overwrite variables from the host group

    For example, change the compute profile or set a different lifecycle environment.

  5. Deploy an application instance

    You may simply deploy the application instance; run the Ansible playbook as is; or customize the Ansible playbook before running it.

Note

If you want to install a package using an Ansible playbook and the host is subscribed to Foreman server, ensure that the package exists in the Content View.

1.2. Key Terms in Application Centric Deployment

ACD

ACD stands for Application Centric Deployment and describes a new approach to provision and configure hosts based on the service they provide.

Ansible Playbooks

Ansible playbooks are the core of the application definition. They connect the different services and provide a whole application with one click of a button. These playbooks contain roles, which in turn contain tasks to properly configure hosts.

Application Definitions

Application definitions are blueprints of how to deploy an application and its services.

Application Instances

Application instances are configured application definitions. You can define how many hosts to deploy per service and choose unique host names.

There might be different configurations based on a testing or production environment or its expected usage. For example, deploying a wiki platform for 20 users might use the 1-small compute profile, whereas hundreds of expected users might require the 3-large compute profile.

Service

A service is a type of host necessary to run an application. For example, the LAMP stack consists of three services: an Apache webserver, a MySQL database, and PHP scripting language all running on Linux servers.

Host Groups

Host groups are predefined sets of provisioning and configuration settings for a new host. For more information, see Creating a Host Group.

1.3. Prerequisites for Application Centric Deployment

In order to use the ACD plugin, your Foreman instance must be able to deploy a host and offer properly configured host groups. Refer to the Foreman and Katello documentation for more information.

2. Architecture

ACD uses Smart Proxies and a remote execution provider called acd.

Ansible playbooks are downloaded from Foreman server to Smart Proxy server before being executed. Submit any Ansible playbooks that you want to use to Foreman server. You do not have to manually add Ansible playbooks to Smart Proxy servers.

2.1. Ansible Playbooks

Ansible playbooks provide the configuration of deployed applications. They are required along with to an application definition to create application instances.

Ansible group variables are mandatory and support any valid YAML data.

Ansible playbooks need to contain Ansible group variables for each provided service.

The Ansible inventory is automatically created by the ACD plugin.

In the Foreman web UI, navigate to Applications > Ansible Playbooks to manage Ansible playbooks for application centric deployment.

Caution

The Ansible playbook must contain all necessary roles and tasks to execute the playbook.

If your Ansible playbooks are currently using Ansible collections, ensure that these Ansible collections are added manually to every Smart Proxy server. To install Ansible collections manually, enter the following command on your Foreman server and Smart Proxy server:

# ansible-galaxy collection install namespace.collection

Replace namespace.collection with the Ansible collection you are intending to use, for example community.general. This uses the Ansible galaxy as configured in the ansible.cfg file.

2.2. Application Definitions

Application definitions are blueprints of deployed applications. They are required along with an Ansible playbook to create application instances.

Application definitions consist of a list of services and Ansible group variables and serve as a preconfigured blueprint providing easy self service for end users. Each service has a name, host group, Ansible group, and minimum and maximum number of host running this service.

Users with administrative access to Foreman handle application definitions and specify the allowed number of hosts for each service.

In the Foreman web UI, navigate to Applications > App Definitions to add, edit, and remove application definitions for application centric deployment.

2.3. Application Instances

An application instance is based on a preconfigured application definition. You can use an application instance to automatically deploy and configure hosts based on its application definition and Ansible playbook.

Based on one application definition, end users can configure and deploy multiple application instances.

In the Foreman web UI, navigate to Applications > App Instances to add, deploy, and remove application instances for application centric deployment.

2.4. Ansible Variables and Parameter Hierarchy

There are different levels on how to set Ansible variables and parameters for a service/host.

Ansible variables
  • On the base, there are Ansible group variables for all services as defined in the Ansible playbook.

  • Next, there are Ansible group variables defined for all services in the application definition. Individual Ansible variables can be locked, removed, or added to the application definition. They overwrite the ones from the Ansible playbook.

  • An application definition also contains Ansible variables for service groups. These overwrite Ansible variables set for all services.

  • An application instance can overwrite any unlocked Ansible variables from the application definition.

Parameters
  • Managed hosts inherit parameters from multiple entities:

    • Global parameters

    • Organization parameters

    • Location parameters

    • Domain parameters

    • Subnet parameters

    • Operating system parameters

    • Host group parameters

    • Host parameters

    For example, domain level parameters overwrite both location and organization based parameters and host parameters overwrite any other defined parameter.

Refer to the Ansible documentation for more information about Ansible variable precedence.

2.5. User Roles

The ACD plugin requires the specific Foreman permissions. Depending on your environment, there might be two different groups of users in regard to managing an application and deploying an application:

You can interact with three different resources for ACD:

ACD Resources
  • Ansible playbooks: Applications > Ansible Playbooks

  • Application definitions: Applications > App Definitions

  • Application instances: Applications > App Instances

You can create custom roles in the Foreman web UI based on existing user role filters for these resources.

  • An administrative group of users might be responsible for providing the tools to deploy an application, that is an Ansible playbook and application definition. Note that the Ansible playbook is not related to the Ansible plugin for configuration management.

  • An end user group might be using Foreman to deploy applications, that is creating and deploying application instances based on application definitions within their organization and location context. Many application instances can be created based on the same application definition.

By default, there are two ACD user roles:

Application Centric Deployment Manager

Configuring Ansible playbooks and application definitions requires the Application Centric Deployment Manager user role. It bundles permissions to manage Ansible playbooks, application definitions, and application instances as well as using ACD remote execution features. This role is suited for administrative users.

The ACD manager role includes permissions to deploy and configure hosts; to manage Ansible playbooks, application definitions, and application instances; and to view, create, and cancel job invocations and templates.

Application Centric Deployment User

Creating and deploying application instances requires the Application Centric Deployment User user role. It bundles permissions to manage application instances and access to the ACD remote execution features. This role is suited for end users.

The ACD user role includes permissions to deploy and configure hosts; to manage application instances; and to view, create, and cancel job invocations and templates.

3. Installing the ACD Plugins

You need to install both the foreman_acd and smart_proxy_acd plugins to use ACD.

This describes the package installation on CentOS 7, Red Hat Enterprise Linux 7, and Oracle Linux 7.

This guide assumes you already have a working Foreman or Foreman and Katello installation.

Procedure
  1. Create a new yum repository /etc/yum.repos.d/foreman-plugins.repo on your Foreman server:

    [foreman-plugins]
    name=Foreman plugins
    baseurl=https://yum.theforeman.org/plugins/3.0/el7/x86_64/
    enabled=1
    gpgcheck=0
  2. Install the required packages on your Foreman server:

    # yum install tfm-rubygem-foreman_acd tfm-rubygem-smart_proxy_acd tfm-rubygem-smart_proxy_acd_core
  3. Run database migrations on your Foreman server:

    # foreman-rake db:migrate
    # foreman-rake db:seed
  4. Restart the Foreman services:

    # foreman-maintain service restart

For more information, see Foreman plugin installation.

4. Usage

4.1. Viewing an Ansible Playbook

You can view existing Ansible playbooks used for application centric deployment via your Foreman server management UI.

Procedure
  1. In the Foreman web UI, navigate to Applications > Ansible Playbooks.

  2. Select an entry in the list of Ansible playbooks.

4.2. Adding an Ansible Playbook

You can add Ansible playbooks used for application centric deployment via your Foreman server management UI.

Procedure
  1. In the Foreman web UI, navigate to Applications > Ansible Playbooks.

  2. Click New Ansible Playbook.

  3. In the Name field, enter the name of new Ansible playbook.

  4. In the Description field, enter an arbitrary description.

  5. In the SCM Type list, select either directory if the Ansible playbook is located on your Foreman server or git to reference a remote git repository.

    • If you select directory, enter the location of the Ansible playbook on your Foreman server in the Directory Path field.

      To avoid SELinux issues, add the Ansible playbook to the /var/lib/foreman/foreman_acd/ansible-playbooks/ directory.

    • If you select git, enter the remote location in the Git Url field and a git branch, commit, or tag in the Git Branch/Commit/Tag field.

      Click Sync Repository to fetch the remote git repository.

  6. In the Playfile field, enter the name of the Ansible playbook.

  7. Click Submit to save your Ansible playbook.

  8. Once submitted, click the Import groups button to import Ansible group variables before this Ansible playbook can be used for an application definition.

Note

You can only edit the directory path or git URL as long as it is not used by any application definition.

Tip

Making changes to any Ansible roles included in your Ansible playbook does not require reimporting the Ansible playbook via management UI.

4.3. Removing an Ansible Playbook

You can remove Ansible playbooks used for application centric deployment via your Foreman server management UI.

Procedure
  1. In the Foreman web UI, navigate to Applications > Ansible Playbooks.

  2. Click the Delete button in the drop down menu to remove the Ansible playbook from your Foreman server.

4.4. Viewing an Application Definition

You can view existing application definitions used for application centric deployment via your Foreman server management UI.

Procedure
  1. In the Foreman web UI, navigate to Applications > App Definitions.

  2. Select an entry in the list of application definitions.

4.5. Creating an Application Definition

Use this procedure to create application definitions to use as part of your application centric deployment.

Prerequisites

You need existing host groups in order to use application centric deployment.

Procedure
  1. In the Foreman web UI, navigate to Applications > App Definitions.

  2. Click New Application Definition.

  3. In the Name field, enter the name of the new application definition.

  4. In the Description field, enter an arbitrary description.

  5. From the Ansible Playbook list, select the name of an Ansible playbook.

  6. Click the plus icon to add new sets of hosts.

    1. In the Name field, enter the name of the new set of hosts.

    2. In the Description field, enter an arbitrary description.

    3. From the Hostgroup menu, select an existing host group.

    4. From the Ansible Group menu, select existing Ansible group variables from the selected Ansible playbook.

    5. In the min count field, enter the minimum number of hosts providing this service. If it is unset, users can choose to not deploy a host providing this service at all.

    6. In the max count field, enter the maximum number of hosts providing this service. If it is unset, users can choose to deploy an unlimited number of hosts providing this service.

    7. In the Actions column, complete the following steps:

      1. Click the edit icon to edit an entry;

      2. Click the settings icon to add or edit existing Foreman parameters. Every hierarchy level of Foreman parameters can be overwritten.

      3. Click the A character to edit, add, lock, or delete Ansible group variables;

      4. Click the delete icon to delete an entry.

  7. Click Submit to save your application definition.

4.6. Removing an Application Definition

You can remove application definitions used for application centric deployment via your Foreman server management UI.

Procedure
  1. In the Foreman web UI, navigate to Applications > App Definitions.

  2. Click the Delete button to remove the application definition from your Foreman server.

4.7. Viewing an Application Instance

You can view existing application instances used for application centric deployment via your Foreman server management UI.

Procedure
  1. In the Foreman web UI, navigate to Applications > App Instances.

  2. Select an entry in the list of application instances.

4.8. Creating an Application Instance

You can create application instances as a blueprint for users to provision and configure hosts.

Procedure
  1. In the Foreman web UI, navigate to Application > App Instances and click the New Application Instance button.

  2. In the Name field, enter the name of the new application instance.

  3. In the Description field, enter an arbitrary description.

  4. From the Application Definition menu, select an existing application definition.

  5. In the table, connect the hosts and necessary services:

    1. In the Hostname field, enter a unique name for the host. You can enter lowercase characters, digits, and hyphens. Hosts cannot start with a hyphen.

    2. In the Description field, enter a description.

    3. From the Service menu, choose a service from the selected application definition. Refer to the list of services in the top right corner.

    4. In the Actions column,

      1. click the edit icon to edit an entry;

      2. click the settings icon to add or edit existing Foreman parameters. Every hierarchy level of Foreman parameters can be overwritten.

      3. click the A character to edit, add, lock, or delete Ansible group variables;

      4. click the delete icon to delete an entry.

  6. Click the A character to view and edit the corresponding Ansible group variables. You may edit unlocked values.

  7. Click Submit to save your application instance.

4.9. Deploying an Application Instance

You can deploy multi-host applications using application instances.

Procedure
  1. In the Foreman web UI, navigate to Applications > App Instances.

  2. Select the application instance you want to deploy and click the Deploy button. If the selected application instance has been deployed before, confirm that you want to redeploy to existing hosts.

Caution

The firewall settings must be handled by the Ansible playbook itself. Make sure to open any required network ports for any defined service by creating an additional role or task in the Ansible playbook.

4.9.1. Running the Ansible Playbook

You can rerun the Ansible playbook to reconfigure existing hosts.

Procedure
  1. In the Foreman web UI, navigate to Applications > App Instances.

  2. Select the application instance you want to deploy and click the Run Playbook button from the drop down menu.

4.9.2. Customizing an Ansible Playbook to Reconfigure Hosts

You can customize and rerun the Ansible playbook to reconfigure existing hosts.

Procedure
  1. In the Foreman web UI, navigate to Applications > App Instances.

  2. Select the application instance you want to deploy and click the Run Playbook - customize first button from the drop down menu. You can customize your application instance deployment and configuration as follows:

    • You can make the Ansible playbook output more verbose.

    • You can add more Ansible variables before executing the Ansible playbook.

    • You can set the amount of concurrently running Ansible tasks.

    • You can select specific tags and hereby limit the tasks of the Ansible playbook that will be executed. Alternatively, you can also choose to skip specific tasks by selecting tags to skip.

      Those options are passed to the Ansible playbook.

    Clicking the Submit button at the bottom without making a change simply runs the Ansible playbook and deploys the application instance.

Tip

You can also choose to deploy the application instance at a certain point of time in the future or recurringly. For example, you can deploy an application every (Sunday) morning as part of a testing routine.

4.10. Removing an Application Instance

You can remove application instances used for application centric deployment via your Foreman server management UI.

Procedure
  1. In the Foreman web UI, navigate to Application > App Instances.

  2. In the list of application instances, open the drop down menu and select Delete on the application instance you want to remove.

    This prompts a list of hosts that have been deployed via the selected application instance. You can choose to also delete hosts when deleting the application instance. Otherwise, those managed hosts remain.

5. Developers

The Foreman ACD plugin was initially developed by ATIX AG with <3 and is completely open source software: