Merge pull request #784 from ansible/devel

April 16th, 2020 Release PR

.gitignore

@@ -19,7 +19,7 @@ ansible/
 *.retry
 demos/servicenow/private.yml
 *.html
-!exercises/ansible_rhel/1.3-playbook/index.html
+!exercises/ansible_rhel/1.3-playbook/web.html
 demos/servicenow/closed_loop_incident_mgmt/input_vars.yaml
 demos/servicenow/closed_loop_incident_mgmt/snow_demo2/snow_vars.yaml
 provisioner/roles/ansible_security.ids_config/

docs/contribute-aws.md

@@ -0,0 +1,11 @@
+# Contribute a new workshop environment for AWS (Amazon Web Services )
+
+There are four components to the AWS `manage_ec2_instances` role:
+
+   - **resources** - this provisions AWS Virtual Private Cloud (VPC), the associated Security Group, the EC2 subnet, route table and SSH key-pair.  The network and security workshop types use two VPCs to create separate networks.  Example for resources can be found in `provisioner/roles/manage_ec2_instances/tasks/resources`.  If you only need a single VPC, you most likely do not have to worry about the resources, and can just copy the default `workshop_type: rhel` setup.
+
+   - **instances** - this provisions the actual Amazon instances (e.g. Red Hat Enterprise Linux 8, Cisco IOS, Microsoft Windows, etc) onto the VPC recreated in the `resources` part of the provisioner.  Examples for each `workshop_type` can be found in `provisioner/roles/manage_ec2_instances/tasks/instances`
+
+   - **ami_find** - this dynamically figures out the correct AMI (Amazon Machine Image) to use depending on which Amazon region you are in (e.g. `us-east-1`).  Examples for each `workshop_type` can be found in `provisioner/roles/manage_ec2_instances/tasks/ami_find`
+
+   - **inventory** - this loads the newly created instances into Ansible Inventory so subsequent Ansible Plays can be executed.  This is so Ansible can now configure the vanilla images by making changes to the newly created instances.  For example we install Ansible for each student, configure their `/etc/hosts`, the `~/.ssh/config` and much more depending the `workshop_type`.  Examples of inventory can be found in `provisioner/roles/manage_ec2_instances/tasks/inventory`

docs/contribute.md

@@ -1,5 +1,22 @@
 # Contribute
 
+We treat Ansible Automation Workshops just like we treat the Ansible Project.  Please help us!  Check out the [Issues](https://github.com/ansible/workshops/issues) for a list of what we are working on.
+
+## Table of Contents
+
+* [Pull Requests ](#pull-requests)
+   * [Create a fork!](#create-a-fork)
+   * [Stay in Sync](#stay-in-sync)
+      * [Configuring Your Remotes](#configuring-your-remotes)
+      * [Rebasing Your Branch](#rebasing-your-branch)
+      * [Updating your Pull Request](#updating-your-pull-request)
+   * [Create a pull requests](#create-a-pull-requests)
+   * [Testing and Continuous Integration](#testing-and-continuous-integration)
+* [Contributing New Workshop Types of content](#contributing-new-workshop-types-of-content)
+* [Going Further](#going-further)
+
+# Pull Requests
+
 We take pull requests!  What is a pull request?
 
 >Pull requests let you tell others about changes you've pushed to a branch in a repository on GitHub. Once a pull request is opened, you can discuss and review the potential changes with collaborators and add follow-up commits before your changes are merged into the base branch
@@ -32,7 +49,7 @@ Rebase the branch on your fork
 git pull --rebase upstream devel
 ```
 
-Check your status 
+Check your status
 
 ```bash
 git status
@@ -82,6 +99,11 @@ ________________________________________________________________________________
 
 To make sure this is run everytime one commits a change, and hence one is not sending a Pull Request that won't be merged, one could enable this as part of a git [pre-commit hook](https://git-scm.com/book/en/v2/Customizing-Git-Git-Hooks)
 
+# Contributing New Workshop Types of content
+
+- [Contribute New Workshop Topology for AWS](contribute-aws.md)
+- [Contrbitue New Workshop Exercises](exercises.md)
+
 # Going Further
 
 The following links will be helpful if you want to contribute code to the Ansible Workshops project, or any Ansible project:

docs/exercises.md

@@ -0,0 +1,92 @@
+# Create New Exercise Content
+
+We encourage folks to create new exercise content, fork with your own content, and customize the workshop any way you want.  This will give you the flexibility to customize workshops for your own friends, customers, community or project!
+
+## Table of Contents
+
+* [Using your own fork](#using-your-own-fork)
+   * [Practical Example](#practical-example)
+* [Changing solution folder on control node](#changing-solution-folder-on-control-node)
+   * [Practical Example](#practical-example-1)
+* [Changing source folder for exercise solutions](#changing-source-folder-for-exercise-solutions)
+   * [Practical Example](#practical-example-2)
+
+# Using your own fork
+
+When a workshop is provisioned, the control node for every workbench (where the Red Hat Ansible Automation is installed and executed from) will load solution exercises into `~/{{workshop}}-workshop`.  For example if you are running the `networking` workshop the home directory for every student will have `~/home/networking-workshop`.
+
+This can be customized!  There are three variables that you can change with your provisioner code
+
+   - `ansible_workshops_url` - points to the git repo where you want to load exercises from.  By default this uses [https://github.com/ansible/workshops.git](https://github.com/ansible/workshops.git) if this is not specified.
+   - `version` - points to the git [branch](https://git-scm.com/docs/git-branch) for the specified git repo.  By default this uses `master`
+   - `refspec` - points to the git [refspec](https://git-scm.com/book/en/v2/Git-Internals-The-Refspec).  By default this is set to `""` (nothing).
+
+These variables are used in the `control_node` role which can found here: `provisioner/roles/control_node/tasks/main.yml`
+
+
+## Practical Example
+
+Here is the `extra_vars` example of provisioning the `workshop_type: rhel` with exercises from a forked repository on a different branch:
+
+```
+---
+ec2_region: us-east-2
+ec2_name_prefix: sean-workshop
+admin_password: ansible123
+student_total: 1
+workshop_type: rhel
+create_login_page: true
+ansible_workshops_url: https://github.com/ipvsean/workshops.git
+ansible_workshops_version: "test_branch"
+```
+
+This would load the exercises `/exercises/ansible_rhel` from fork `github.com/ipvsean/workshops.git` branch `test_branch` into the student home directory of `~/rhel-workshop`
+
+
+# Changing solution folder on control node
+
+It is possible to change the location of the destination folder where the exercises are loaded into with the `exercise_dest_location` variable.
+
+
+## Practical Example
+
+Here is the `extra_vars` example of provisioning the `workshop_type: rhel` with exercises from a forked repository on a different branch:
+
+```
+---
+ec2_region: us-east-1
+ec2_name_prefix: sean-workshop2
+admin_password: ansible123
+student_total: 1
+workshop_type: rhel
+create_login_page: true
+ansible_workshops_url: https://github.com/ipvsean/workshops.git
+ansible_workshops_version: "test_branch"
+exercise_dest_location: "my_folder"
+```
+
+This would load the exercises `/exercises/ansible_rhel` from fork `github.com/ipvsean/workshops.git` branch `test_branch` into the student home directory of `~/my_folder`
+
+# Changing source folder for exercise solutions
+
+It is possible to change the location of the source folder with the `exercise_src_location` variable.  This defaults to `exercises/ansible_{{workshop_type}}`.  For example by default it would load `exercises/ansible_rhel` for the `workshop_type: rhel` workshop.
+
+## Practical Example
+
+Here is the `extra_vars` example of provisioning the `workshop_type: rhel` with different exercises from a forked repository on a different branch:
+
+```
+---
+ec2_region: us-east-1
+ec2_name_prefix: sean-workshop2
+admin_password: ansible123
+student_total: 1
+workshop_type: rhel
+create_login_page: true
+ansible_workshops_url: https://github.com/ipvsean/workshops.git
+ansible_workshops_version: "test_branch"
+exercise_dest_location: "my_folder"
+exercise_src_location: "exercises/my_exercises"
+```
+
+This would load the exercises `/exercises/my_exercises` from fork `github.com/ipvsean/workshops.git` branch `test_branch` into the student home directory of `~/my_folder`

docs/faq.md

@@ -119,7 +119,7 @@ cd into the relevant project folder and execute the Playbook from the command li
 
 ```
 TASK [manage_ec2_instances : Create EC2 instances for rtr3 node (NETWORKING MODE)] ***
-fatal: [localhost]: FAILED! => changed=false 
+fatal: [localhost]: FAILED! => changed=false
   msg: 'Instance creation failed => OptInRequired: In order to use this AWS Marketplace product you need to accept terms and subscribe. To do so please visit https://aws.amazon.com/marketplace/pp?sku=bw54e0gl17zf0vxq54dttwvow'
 
 ```

exercises/ansible_f5/1.0-explore/README.ja.md

@@ -47,7 +47,7 @@ ansible 2.6.2
 [defaults]
 connection = smart
 timeout = 60
-inventory = /home/student1/networking-workshop/lab_inventory/hosts
+inventory = /home/student1/lab_inventory/hosts
 host_key_checking = False
 private_key_file = /home/student1/.ssh/aws-private.pem
 [student1@ansible networking-workshop]$
@@ -65,7 +65,7 @@ Note: `ansible.cfg` には以下のパラメーターが含まれています:
 
 この演習では **ini** 形式で書かれたファイルを使います. `cat` コマンドでインベントリーの中身を確認します:
 
-`[student1@ansible networking-workshop]$ cat lab_inventory/hosts`
+`[student1@ansible networking-workshop]$ cat ~/lab_inventory/hosts`
 
 以下が student2 の出力例です:
 ```

exercises/ansible_f5/1.0-explore/README.md

@@ -42,7 +42,7 @@ Use the `cat` command to view the contents of the `ansible.cfg` file.
 [defaults]
 connection = smart
 timeout = 60
-inventory = /home/student1/networking-workshop/lab_inventory/hosts
+inventory = /home/student1/lab_inventory/hosts
 host_key_checking = False
 private_key_file = /home/student1/.ssh/aws-private.pem
 [student1@ansible networking-workshop]$
@@ -60,7 +60,7 @@ The scope of a `play` within a `playbook` is limited to the groups of hosts decl
 
 In this lab you will work with a file based inventory written in the **ini** format. Use the `cat` command to view the contents of your inventory:
 
-`[student1@ansible networking-workshop]$ cat lab_inventory/hosts`
+`[student1@ansible networking-workshop]$ cat ~/lab_inventory/hosts`
 
 The output will look as follows with student2 being the respective student workbench:
 ```

exercises/ansible_network/1-explore/README.ja.md

@@ -79,7 +79,7 @@ timeout = 60
 deprecation_warnings = False
 host_key_checking = False
 retry_files_enabled = False
-inventory = /home/student1/networking-workshop/lab_inventory/hosts
+inventory = /home/student1/lab_inventory/hosts
 [persistent_connection]
 connect_timeout = 60
 command_timeout = 60
@@ -96,7 +96,7 @@ command_timeout = 60
 この演習では **ini** 形式で記述されたファイルベースのインベントリーを利用します。`cat` コマンドを利用して演習環境のインベントリーを確認してみます。
 
 ```bash
-[student1@ansible ~]$ cat ~/networking-workshop/lab_inventory/hosts
+[student1@ansible ~]$ cat ~/lab_inventory/hosts
 ```
 
 ```

exercises/ansible_network/1-explore/README.md

@@ -80,7 +80,7 @@ timeout = 60
 deprecation_warnings = False
 host_key_checking = False
 retry_files_enabled = False
-inventory = /home/student1/networking-workshop/lab_inventory/hosts
+inventory = /home/student1/lab_inventory/hosts
 [persistent_connection]
 connect_timeout = 60
 command_timeout = 60
@@ -97,7 +97,7 @@ The scope of a `play` within a `playbook` is limited to the groups of hosts decl
 In this lab you will work with a file based inventory written in the **ini** format. Use the `cat` command to view the contents of your inventory:
 
 ```bash
-[student1@ansible ~]$ cat ~/networking-workshop/lab_inventory/hosts
+[student1@ansible ~]$ cat ~/lab_inventory/hosts
 ```
 
 ```

exercises/ansible_network/3-facts/README.md

@@ -21,6 +21,8 @@ This exercise will cover:
 - Using the [ios_facts module](https://docs.ansible.com/ansible/latest/modules/ios_facts_module.html).
 - Using the [debug module](https://docs.ansible.com/ansible/latest/modules/debug_module.html).
 
+# Guide
+
 #### Step 1
 
 On the control host read the documentation about the `ios_facts` module and the `debug` module.

exercises/ansible_rhel/1.1-setup/README.md

@@ -1,11 +1,23 @@
-# Exercise 1.1 - Check the Prerequisites
+# Workshop Exercise - Check the Prerequisites
 
 **Read this in other languages**: ![uk](../../../images/uk.png) [English](README.md),  ![japan](../../../images/japan.png)[日本語](README.ja.md), ![brazil](../../../images/brazil.png) [Portugues do Brasil](README.pt-br.md).
 
+## Table of Contents
+
+* [Objective](#objective)
+* [Guide](#guide)
 * [Your Lab Environment](#your-lab-environment)
-* [Step 1.1 - Access the Environment](#step-11---access-the-environment)
-* [Step 1.2 - Working the Labs](#step-12---working-the-labs)
-* [Step 1.3 - Challenge Labs](#step-13---challenge-labs)
+* [Step 1 - Access the Environment](#step-1---access-the-environment)
+* [Step 2 - Working the Labs](#step-2---working-the-labs)
+* [Step 3 - Challenge Labs](#step-3---challenge-labs)
+
+# Objective
+
+- Understand the lab topology and how to access the environment.
+- Understand how to work the workshop exercises
+- Understand challenge labs
+
+# Guide
 
 ## Your Lab Environment
 
@@ -18,7 +30,7 @@ In this lab you work in a pre-configured lab environment. You will have access t
 | Managed Host 2       | node2          |
 | Managed Host 3       | node3          |
 
-## Step 1.1 - Access the Environment
+## Step 1 - Access the Environment
 
 Login to your control host via SSH:
 
@@ -63,7 +75,7 @@ Log out of the root account again:
 >
 > In all subsequent exercises you should work as the student\<X\> user on the control node if not explicitly told differently.
 
-## Step 1.2 - Working the Labs
+## Step 2 - Working the Labs
 
 You might have guessed by now this lab is pretty commandline-centric…​ :-)
 
@@ -75,10 +87,13 @@ You might have guessed by now this lab is pretty commandline-centric…​ :-)
 >
 > In the lab guide commands you are supposed to run are shown with or without the expected output, whatever makes more sense in the context.
 
-## Step 1.3 - Challenge Labs
+## Step 3 - Challenge Labs
 
 You will soon discover that many chapters in this lab guide come with a "Challenge Lab" section. These labs are meant to give you a small task to solve using what you have learned so far. The solution of the task is shown underneath a warning sign.
 
 ----
+**Navigation**
+<br>
+[Next Exercise](../1.2-adhoc)
 
 [Click here to return to the Ansible for Red Hat Enterprise Linux Workshop](../README.md#section-1---ansible-engine-exercises)