Lab Guide: Creating Dynamic Documentation with Automation

This guide demonstrates how to generate dynamic documentation from cloud infrastructure using Ansible automation.

Estimated time to complete: 15 minutes

1. Lab Overview

Welcome to the third challenge. In this lab, you will generate a dynamic HTML website using the structured data gathered in the previous challenge.

First, log in to the Ansible Automation Platform UI with the following credentials.

Table 1. Login Credentials

Username

admin

Password

ansible123!

2. Task 1: Create a New Job Template

You will start by creating a job template that runs a playbook to generate the cloud report.

  1. Navigate to the Templates page.

    From the left navigation menu, select Templates.

    Templates link in menu

  2. Initiate the creation of a new job template.

    Click the Create template button, then select Create job template.

    Create a new job template

  3. Enter the job template details.

    Fill out the form with the following information:

    Parameter

    Value

    Name

    Create Cloud Report

    Job Type

    Run

    Inventory

    Demo Inventory

    Project

    AWS Demos Project

    Execution Environment

    AWS Execution Environment

    Playbook

    playbooks/cloud_report.yml

    Credentials

    AWS_Credential and SSH Controller Credential
    This job template requires two credentials. One is for retrieving information from AWS, and the second is for connecting via SSH to the report server to generate the report.

  4. Save the job template.

    Click the blue Save button.

3. Task 2: Add a Survey

Next, you will add a survey to allow the user to specify which server will host the generated HTML report.

  1. Open the job template’s settings.

    Navigate to the Templates page and click on the name of the Create Cloud Report job template.

  2. Navigate to the Survey tab.

    At the top of the template’s details page, click the Survey tab.

    Survey Tab

  3. Create a new survey question.

    Click the blue Add button.

  4. Configure the survey question.

    Fill out the form with the following values:

    Parameter

    Value

    Question

    Which server do you want to host the report?

    Answer variable name

    _hosts

    Answer type

    Text

    Default answer

    ansible-1

  5. Save the survey question.

    Click the blue Save button.

  6. Enable the survey.

    Make sure to click the toggle switch to enable the survey.

    Enable survey toggle
    For this lab, we will host the report on the ansible-1 host. However, this survey demonstrates how you can make the destination configurable, allowing you to host dynamic documentation anywhere, including on services like Amazon S3.

4. Task 3: Launch the Job Template

Now you are ready to run the job and generate the report.

  1. Launch the job template.

    From the Templates page, find the Create Cloud Report template and click the Launch icon (🚀).

    Launch Job Icon

  2. Complete the survey.

    When prompted by the survey, accept the default host (ansible-1) and launch the job.

  3. Review the playbook execution.

    This playbook uses two roles:

  4. The first role, retrieve_info, gathers structured data for VPCs, EC2 instances, and IGWs. View source code.

  5. The second role, build_report, installs a web server, copies assets (CSS, images), and uses the structured data to generate an HTML report. View source code.

  6. View the generated report.

    Once the job completes, navigate to the Dynamic Report tab in your lab window. You may need to refresh the page (⟳). Click on the gray boxes with the caret (▸) to expand the tables.

    The report will look similar to this:

    Picture of the cloud report

5. Task 4: Compare Regions

A cloud operator can use this report to gain quick awareness of their cloud footprint across different regions. This helps answer important questions, such as:

  • How can I identify unused VPCs that can be safely deleted?

  • Which regions are actively running instances?

  • Which regions contain stopped instances that could be restarted?

This automated report provides a powerful tool for resource management and cost optimization.

6. Finished!

You have successfully completed this lab. Press the Check button in your lab environment to validate your work.

7. Troubleshooting

If you have encountered an issue or have noticed something not quite right, please open an issue on GitHub.