1. Introduction to application centric deployment

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 your hosts by 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. Application centric deployment 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 by using the Foreman web 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 by 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 definitions are configured application definitions. You can define how many hosts to deploy per service and choose unique host names. You can create different configurations whether its 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 in Managing hosts.

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. For more information, see Provisioning guide and Managing Hosts guide.

2. ACD 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 definitions 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 Playbooks 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 definitions. 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 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

  • 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.

For more information about Ansible variable precedence, see the Ansible documentation.

2.5. User roles for application centric deployment

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 ACD on Foreman server

ACD has a Foreman plugin (foreman_acd) and a Smart Proxy plugin (smart_proxy_acd).

Procedure

  1. Install ACD on your Foreman server:

    # foreman-installer --enable-foreman-plugin-acd --enable-foreman-proxy-plugin-acd

4. Installing ACD on Smart Proxy server

Prerequisites
Procedure

  1. Install ACD on your Smart Proxy server:

    # foreman-installer --enable-foreman-proxy-plugin-acd

5. Using ACD

5.1. Viewing an Ansible Playbook

You can view existing Ansible Playbooks used for application centric deployment in the Foreman web UI.

Procedure

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

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

5.2. Adding an Ansible Playbook

You can add Ansible Playbooks used for application centric deployment in the Foreman web 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 Import groups 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 if 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 using the Foreman web UI.

5.3. Removing an Ansible Playbook

You can remove Ansible Playbooks used for application centric deployment in the Foreman web UI.

Procedure

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

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

5.4. Viewing an application definition

You can view existing Application definitions used for application centric deployment in the Foreman web UI.

Procedure

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

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

5.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.

5.6. Removing an application definition

You can remove Application definitions used for application centric deployment in the Foreman web UI.

Procedure

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

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

5.7. Setting host parameters in application definitions

You can add and edit host parameters for individual application definitions.

Procedure

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

  2. Select an application definition.

  3. Click the settings icon in the Actions column.

  4. Click the + sign to add a new host parameter.

  5. Optional: Using the Actions column, you can edit an existing host parameter, lock or unlock host parameters, and delete host parameters.

  6. Click Save to save your application definition to Foreman.

Locking parameters prevents users from changing them within an application instance.

5.8. Viewing an application instance

You can view existing Application instances used for application centric deployment in the Foreman web UI.

Procedure

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

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

5.9. 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.

  2. Click New Application Instance.

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

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

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

  6. In the table, connect the hosts and necessary services. You can either assign existing hosts to your application instance or deploy new hosts.

    1. To assign an existing host to a service, click on the Server icon. Select both a service and existing host, and click Save.

    2. Optional: Click the A character to edit, add, lock, or delete Ansible group variables. Note that you cannot change host parameters as existing hosts are not redeployed but only reconfigured using Ansible.

    3. Alternatively, 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.

    4. In the Description field, enter a description.

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

    6. 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.

        You can refer to any Foreman parameter using PARAM[name_of_your_parameter], for example, based on an operating system or a host group. The Foreman parameter name cannot contain whitespace.

        When the host is configured, ACD gets the value for the variable name_of_your_parameter. When you deploy your application instance or reconfigure it afterwards, navigate to the Preview templates tab to check if the parameters are resolved correctly.

      4. Click the delete icon to delete an entry.

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

  8. Click Submit to save your application instance.

5.10. 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 Deploy. 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. Ensure to open any required network ports for any defined service by creating an additional role or task in the Ansible Playbook.
Note

ACD detects which Smart Proxy server is used to configure the application instance and its hosts.

For each Smart Proxy server, the Ansible Playbook runs to configure all hosts. The remote execution plugin, which works host-based, is used to run the Ansible Playbook on each Smart Proxy server.

The first host of the application instance runs the Ansible Playbook. The configuration jobs page shows the first host of each Smart Proxy server as target host. The ACD component of Smart Proxy starts an Ansible Playbook which configures all hosts connected to this Smart Proxy server.

5.10.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 Run Playbook from the drop down menu.

5.10.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 select Run Playbook – customize first 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 Submit without making a change 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.

5.11. Removing an application instance

You can remove Application instances used for application centric deployment using the Foreman web 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 either use the checkbox to select all or tick the hosts you want to delete when deleting the application instance. Otherwise, those hosts remain.

5.12. Overwriting Ansible group variables in application instances

You can overwrite Ansible group variables in application instances unless the parameters are locked by the application definition.

Procedure

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

  2. Select an application instance.

  3. To overwrite Ansible group variables for all services, click the A character below the table.

  4. To overwrite Ansible group variables on a per service basis, click the A character in the action menu next to a service.

  5. Click the edit icon to overwrite Ansible group variables from the application definition.

    A grayed out edit icon indicates that this Ansible group variable has been locked by the application definition.

  6. Click Save to update the Ansible group variables.

Note that it is not possible to add or remove parameters in the application instance.

5.13. Viewing application instance reports

You can view reports on the last application instance deployment.

Procedure

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

  2. Click on Show Report in the list of application instances.

  3. Click on Last deployment task to view the last deployment task in Foreman.

5.14. Viewing the last deployment task

You can view the last deployment task for each application instance.

Procedure

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

  2. Click Show Report in the list of application instances.

  3. Click Last deployment task to view the last deployment task in Foreman.

    The table shows basic information regarding the execution of the task. The indicator shows the state and overall status of the task, for example 100% complete. The other tabs Running Steps, Errors, Locks, and Raw contain more detailed information about the task.