DO274 - ch03s02

Bookmark this page

Guided Exercise: GitOps with Event-Driven Ansible

Use Event-Driven Ansible to react to events generated by Git operations.

Outcomes

Create an outgoing webhook in GitLab.
Update an Ansible Rulebook to run different job templates in automation controller based on specific events from GitLab.
Modify a web application and monitor the automated deployment.

As the student user on the workstation machine, use the lab command to prepare your environment for this exercise, and to ensure that all required resources are available:

[student@workstation ~]$ lab start example-gitops

Instructions

Examine the gitops_application and gitops_automation projects in GitLab.
1. Navigate to https://git.lab.example.com and log in as student using Stud3nt123 as the password.
2. Click the gitops_application project. This project contains a web application that is deployed in a production environment hosted at http://servera.lab.example.com and in a development environment hosted at http://dev.servera.lab.example.com.
3. Click the Back button in the browser to go back to the project list and click the gitops_automation project. This project contains playbooks that are used in automation controller job templates along with a partially completed rulebook used in a rulebook activation in Event-Driven Ansible (EDA) controller.
Examine the automation resources in automation controller and EDA controller.
1. In a new browser tab, navigate to https://controller.lab.example.com and log in as admin using redhat as the password. If necessary, click the main menu icon at the upper left of the page to display the main menu.
2. Go to Resources → Templates and then click the Deploy Prod template. This job template uses the deploy_prod.yml playbook from the GitOps Automation project. This project in automation controller uses the playbooks from the gitops_automation project in GitLab.
3. Go to Resources → Templates and then click the Deploy Dev template. This job template uses the deploy_dev.yml playbook from the GitOps Automation project.
4. In a new browser tab, navigate to https://eda-controller.lab.example.com and log in as admin using redhat as the password. If necessary, click the main menu icon at the upper left of the page to display the main menu.
5. Go to Rulebook Activations and then click the Deploy Code rulebook activation. This rulebook activation uses the git_actions.yml rulebook from the GitOps Automation project. This project in EDA controller uses the rulebooks from the gitops_automation project in GitLab.
Create an outgoing webhook in the gitops_application project in GitLab to trigger the Deploy code rulebook activation.
1. On the web browser tab for GitLab, click the gitops_application project. If necessary, click the sidebar icon at the upper left of the page to display the sidebar menu.
2. Go to Settings → Webhooks and then click Add new webhook. In the URL field, enter http://eda-controller.lab.example.com:5000. In the Trigger section, select Push events and ensure that All branches is selected. Select Merge request events and then click Add webhook at the bottom of the page.
3. In the Webhooks section, click Test for the webhook and select Push events. If the test succeeds, then the page displays Hook executed successfully: HTTP 200.
4. On the web browser tab for EDA controller, go to Rulebook Activations and then click the Deploy Code rulebook activation. Click the History tab and click the name that has the running status.
5. Scroll down to the bottom of the Details tab to examine the payload of the Push events test from the webhook in GitLab. The following event keys worth examining:
  Key Description
  meta.headers.X-Gitlab-Event The type of event the webhook is sending
  payload.ref The Git reference, which includes the branch name
  payload.repository.name The name of the Git repository
  Figure 3.6: Event meta key
  Figure 3.7: Event payload key

Key	Description
`meta.headers.X-Gitlab-Event`	The type of event the webhook is sending
`payload.ref`	The Git reference, which includes the branch name
`payload.repository.name`	The name of the Git repository

Modify the git_actions.yml rulebook so that the Deploy code rulebook activation takes actions for different event types sent from the GitLab webhook.

From a terminal window, change to the /home/student/git-repos directory and then clone the git@git.lab.example.com:student/gitops_automation Git repository. After cloning the repository, change to the gitops_automation/ directory:
```
[student@workstation ~]$ cd ~/git-repos
[student@workstation git-repos]$ git clone \
git@git.lab.example.com:student/gitops_automation
Cloning into 'gitops_automation'...
...output omitted...
[student@workstation git-repos]$ cd gitops_automation/
[student@workstation gitops_automation]$
```
Note
The student user uses the ~/.ssh/gitlab_rsa SSH key to connect to the Git repository.

Use a text editor, such as VS Code, to edit the rulebooks/git_actions.yml rulebook.

Note

The ~/example-gitops/solutions/git_actions.yml file contains the correct updates. You can use that file for comparison or copy it to the ~/git-repos/gitops_automation/rulebooks directory.

Add the ansible.eda.dashes_to_underscores filter to the source and then replace the existing rule with a rule that captures details on Push Hook events sent from the GitLab webhook:

---
- name: Capture posted events from GitLab
  hosts: all
  sources:
    - name: Match events posted to port 5000
      ansible.eda.webhook:
        host: 0.0.0.0
        port: 5000
      filters:
        - ansible.eda.dashes_to_underscores: 

  rules:
    # Capture push events
    - name: Get push event details 
      condition: event.meta.headers.X_Gitlab_Event == "Push Hook"
      action:
        post_event:
          event: 
            type: "{{ event.meta.headers.X_Gitlab_Event }}"
            gitref: "{{ event.payload.ref }}"
            repo_name: "{{ event.payload.repository.name }}"

	Event-Driven Ansible does not support dashes in key names. The `ansible.eda.dashes_to_underscores` filter converts the dashes to underscores in the keys.
	The `Get push event details` rule takes action when the event is a `Push Hook` event.
	If the condition is met, then the action creates shorter key names for specific payload keys sent by the webhook.

Edit the git_actions.yml rulebook to add a second rule to capture details on Merge Request Hook events sent from the GitLab webhook:

...output omitted...
    # Capture merge request creation events
    - name: Get merge request creation event details 
      condition: >
        event.meta.headers.X_Gitlab_Event == "Merge Request Hook"
        and event.payload.object_attributes.action == "open"
      action:
        post_event:
          event: 
            type: "{{ event.meta.headers.X_Gitlab_Event }}"
            source_branch: "{{ event.payload.object_attributes.source_branch }}"
            repo_name: "{{ event.payload.repository.name }}"
            merge_request_action: "{{ event.payload.object_attributes.action }}"

	The `Get merge request creation event details` rule takes action when the event is a `Merge Request Hook` event and only triggers an action if a new merge request is opened.
	If the conditions are met, then the action creates shorter key names for specific payload keys sent by the webhook.

Edit the git_actions.yml rulebook to add a third rule to run the Deploy Prod job template when a Push Hook event happens on the main branch:

...output omitted...
    # Run Deploy Prod job template when there is a push to the main branch
    - name: Respond to push events to the main branch 
      condition: >
        event.repo_name == "gitops_application"
        and event.type == "Push Hook"
        and event.gitref is search("main")
      action:
        run_job_template: 
          name: Deploy Prod
          organization: Default

	The `Respond to push event to main branch` rule takes action when the event is a `Push Hook` event to the `main` branch in the `gitops_application` repository.
	If the conditions are met, then the `Deploy Prod` job template runs in automation controller.

Edit the git_actions.yml rulebook to add a fourth rule to run the Deploy Dev job template when a Merge Request Hook event happens to open a merge request in the devel branch:

...output omitted...
    # Run Deploy Dev job template when a merge request is created
    # in the devel branch
    - name: Respond to merge request creation 
      condition: >
        event.repo_name == "gitops_application"
        and event.type == "Merge Request Hook"
        and event.merge_request_action == "open"
        and event.source_branch == "devel"
      action:
        run_job_template: 
          name: Deploy Dev
          organization: Default

	The `Respond to merge request creation` rule takes action when the event is a `Merge Request Hook` event that opens a new merge request in the `devel` branch in the `gitops_application` repository.
	If the conditions are met, then the `Deploy Dev` job template runs in automation controller.

The final git_actions.yml rulebook should contain the following content:

---
- name: Capture posted events from GitLab
  hosts: all
  sources:
    - name: Match events posted to port 5000
      ansible.eda.webhook:
        host: 0.0.0.0
        port: 5000
      filters:
        - ansible.eda.dashes_to_underscores:

  rules:
    # Capture push events
    - name: Get push event details
      condition: event.meta.headers.X_Gitlab_Event == "Push Hook"
      action:
        post_event:
          event:
            type: "{{ event.meta.headers.X_Gitlab_Event }}"
            gitref: "{{ event.payload.ref }}"
            repo_name: "{{ event.payload.repository.name }}"

    # Capture merge request creation events
    - name: Get merge request creation event details
      condition: >
        event.meta.headers.X_Gitlab_Event == "Merge Request Hook"
        and event.payload.object_attributes.action == "open"
      action:
        post_event:
          event:
            type: "{{ event.meta.headers.X_Gitlab_Event }}"
            source_branch: "{{ event.payload.object_attributes.source_branch }}"
            repo_name: "{{ event.payload.repository.name }}"
            merge_request_action: "{{ event.payload.object_attributes.action }}"

    # Run Deploy Prod job template when there is a push to the main branch
    - name: Respond to push events to the main branch
      condition: >
        event.repo_name == "gitops_application"
        and event.type == "Push Hook"
        and event.gitref is search("main")
      action:
        run_job_template:
          name: Deploy Prod
          organization: Default

    # Run Deploy Dev job template when a merge request is created
    # in the devel branch
    - name: Respond to merge request creation
      condition: >
        event.repo_name == "gitops_application"
        and event.type == "Merge Request Hook"
        and event.merge_request_action == "open"
        and event.source_branch == "devel"
      action:
        run_job_template:
          name: Deploy Dev
          organization: Default

Note

The ~/example-gitops/solutions/git_actions.yml file contains the correct updates. You can use that file for comparison or copy it to the ~/git-repos/gitops_automation/rulebooks directory.

Add, commit, and push the updated git_actions.yml rulebook to the main branch in the gitops_automation repository:

[student@workstation gitops_automation]$ git add rulebooks/git_actions.yml
[student@workstation gitops_automation]$ git commit -m 'Updating git_actions.yml'
...output omitted...
[student@workstation gitops_automation]$ git push -u origin main
...output omitted...

Sync the GitOps Automation project in EDA controller.
1. On the web browser tab for EDA controller, go to Projects and then click the Sync project icon to the right of the Git hash for the GitOps Automation project. The Git hash for the project changes to match the most recent commit.
Restart the rulebook activation in EDA controller.
1. On the web browser tab for EDA controller, go to Rulebook Activations. Click the vertical ellipsis icon for the Deploy code rulebook activation and click Restart rulebook activation.
2. Select the Yes, I confirm that I want to restart these 1 rulebook activations checkbox and click Restart rulebook activations.
3. After the Success status displays, close the Restart rulebook activations window. Note that the value in the Number of rules column for the Deploy code rulebook activation has increased from 1 to 4.
  Important
  If the Deploy code rulebook activation fails or the rule count does not increase from one to four, then look for mistakes in the git_actions.yml rulebook. Push any rulebook changes to the remote Git repository and then synchronize the GitOps Automation project again.
  Ensure that the Git hash for the GitOps Automation project matches your latest commit and then restart the Deploy code rulebook activation.
Update the web application in the gitops_application repository.
1. In two new browser tabs, navigate to http://servera.lab.example.com and http://dev.servera.lab.example.com. Notice that both applications look the same and both Red Hat logos are difficult to see due to the red background.
2. From a terminal window, change to the /home/student/git-repos directory and then clone the git@git.lab.example.com:student/gitops_application Git repository. After cloning the repository, change to the gitops_application directory:
```
[student@workstation gitops_automation]$ cd ~/git-repos
[student@workstation git-repos]$ git clone \
git@git.lab.example.com:student/gitops_application
Cloning into 'gitops_application'...
...output omitted...
[student@workstation git-repos]$ cd gitops_application
[student@workstation gitops_application]$
```
3. Create the devel branch and check it out:
```
[student@workstation gitops_application]$ git checkout -b devel
```
  Important
  Ensure that you create the correct branch name. The rulebook in this exercise only responds to merge requests for the devel branch.
4. Edit the index.html file in the repository to change the background color from red to black. The updated index.html file should contain the following content:
```
<!DOCTYPE html>
<html>
<body style="background-color:black;">
   <img src="logo.png">
   <h1 style="color:white;">Prod Application</h1>
   <p style="color:white;">This is the application text</p>
</body>
</html>
```
5. Add, commit, and push the updated index.html file to the devel branch in the gitops_application repository:
```
[student@workstation gitops_application]$ git add index.html
[student@workstation gitops_application]$ git commit -m 'Updating index.html'
...output omitted...
[student@workstation gitops_application]$ git push -u origin devel
...output omitted...
```
Create and merge a merge request in GitLab to test the webhook and rulebook activation.
1. On the web browser tab for GitLab, click the gitops_application project.
2. At the top of the page, click Create merge request. On the New merge request page, click Create merge request at the bottom of the page.
3. On the web browser tab for automation controller, go to Views → Jobs. If necessary, log in as admin using redhat as the password. Notice that a job using the Deploy Dev job template ran successfully.
4. Refresh the browser tab for the development application at http://dev.servera.lab.example.com. Notice that the background is now black, and the Red Hat logo is more visible.
5. On the web browser tab for GitLab, click Merge on the merge request page.
6. On the web browser tab for automation controller, go to Views → Jobs. Notice that a job using the Deploy Prod job template ran successfully.
7. Refresh the browser tab for the production application at http://servera.lab.example.com and notice that the background color matches the background color in the development application.

Finish

On the workstation machine, use the lab command to complete this exercise. This step is important to ensure that resources from previous exercises do not impact upcoming exercises.

[student@workstation ~]$ lab finish example-gitops

Revision: do274-2.4-65daa25

Introduction to Event-Driven Ansible

Guided Exercise: GitOps with Event-Driven Ansible

Note

Note

Note

Important

Important

Lab Controls