RHEL Workshop improvements February 2020

[IPvSean]

SUMMARY

Feedback from multiple North America SAs that RHEL workshop needs some love to get it to a better state. Before I suggest feedback and make a PR (pull request) to modify workshop content I want to outline goals.

Goal Criteria

• Ansible Automation Workshops are primarily used for instructor led, in-person workshops
• Ansible Automation Workshops need to fit within 6 hours (including instructor slide time)
  • This means students can arrive before 9 and be done between 3:00PM and 4:00PM depending on lunch schedule
• Ansible Automation Workshops should cover at least 50% Ansible Tower

Problem Statement

With above goals in mind, the current problem with the workshop is the following (this is based on weekly SA meeting I conduct with SAs in North America, and some individuals in other territories like @eraser215):

• too many slides
• too many exercises
• awkwardness (I know this is ambiguous but hear me out for the draft improvements->)

First Draft for improvements

too many slides

we will tackle this once we re-factor workshop exercises, because we can obviously delete content if we don't have a relevant exercise to help shorten the workshop time, see below

too many exercises

I hope folks will not be offended by the removal of one of their exercises from the core content plan. The goal is not to "throw these away" but rather recycle content into additional lessons, demos, etc. We just have to cut somewhere given the goals and the feedback so this is my best attempt and trying to shorten the RHEL workshop and make it less complex and more turn key for SAs.

• kill ad hoc exercises 1.2-adhoc and move to supplemental . Instead we will just simplify ad-hoc to a ping in the setup exercise
• kill the facts part of the exercise 1.4-variables which will cut this down by half, we will keep this is supplemental exercises so instructors can choose to teach this if they want, but it won't be part of the prescriptive lab
• kill the conditionals entirely out of 1.5-handlers - the conditional needs to change to more relevant example like ubuntu vs rhel and moved to supplemental
• cut bonus exercise 1.8-bonus and move to supplemental
• discuss role exercise 1.7-role - my opinion (sean) is that we should cut this exercise due too complexity of teaching a role is such a short class geared towards 101 level folks. I got some disagreement here so I want to discuss here.
• shorten 2.2 considerably by removing ad-hoc 2.2-cred

awkwardness

I think these will be way less controversial!

• add ToC (table of contents) for every exercise
• add objective for every exercise
• add takeways section to conclusion of every exericse
• add links from each exercise to the index page and next exercise (so they navigate github pages easier)
• change bullet lists from tower exercises into tables to make them less confusing/complex
• add additional screenshots to tower exercises

ISSUE TYPE

• Feature Idea

COMPONENT NAME

• exercises

ADDITIONAL INFORMATION

Please provide feedback via comments below! . If you highly disagree with something and feel better about unicasting me please email me. If you are a community member you are also welcome to comment/contribute but keep the goals in mind above. I am going to be prototyping more ways to contribute exercises and demos outside the normal lesson plan but I need to get the normal lesson plan back under control and the SAs in a happy place

[ptoal]

May I suggest that we begin with the end in mind? I.e., what are the objectives? I think we sometimes confuse these workshops with training, which is how more complex exercises get added.

Is the goal still to help trigger the "ah ha" moment (lightbulb) in people new to Ansible?

If so, then I agree with most of your points. Also, I would suggest:

Workshop Structure

I would like to see us to keep true to the original lightbulb format: Introduce a concept, demo the concept, have the student try it, and then build on it in the next section.

Related to this, we should try to anchor the workshop around a practical example. The original lightbulb workshop, for example, used the deployment of a web server. I think this help anchor the concepts into a more practical context.

Ex 1.2 - Ad-hoc

Exercise Objectives

Understand how Ansible can automate simple repetitive tasks on numerous nodes.

Changes to meet objective

1. Move all the details about the inventory and the .cfg into a reference page with a link to it for those who are curious.
2. Near the end of the exercise, challenge the student to come up with a simple one-command task they might execute in their job.

My rationale for keeping this exercise is that I think Ad-hoc commands are a great way for sys-admins to get their first taste of the power of Ansible. The ability to run a command like "uname -a" on 100 hosts can be an ah-ha moment in itself.

Ex 1.4 - Variables

Exercise Objectives

Understand what Ansible Variables are, how they are defined, and their basic use.

Changes to meet objective

1. host_vars/group_vars discussion is too deep, and should be linked reference material for those who are curious.
2. Structure the exercise to cover a simple use of an inventory defined variable (eg: hostname, or IP), explain discovered facts, and use a discovered fact.
3. Anchor the exercise around the use-case of deploying a web server, and declare and use a simple variable: (eg. docroot_path: /var/www).

Ex 1.5 - Conditionals Handlers and Loops

Exercise Objectives

Understand the basic control structures available in Ansible.
Understand the difference between Declarative and Imperative styles, and when to use each.

Changes to meet objective

1. Redo this whole section to build on previous sections
2. Use handler for httpd restart.
3. Use conditional for package name based on platform.
4. Use loop for copying files to web dir.

[liquidat]

Few things from my side:

• Too many slides - I am happy to kill many of them. I'd just like the people to be aware that the current slide deck was contributed by a set of SAs whose message was that we have way too few slides. So while I am totally ok with having for example way under 100 slides, others might strongly disagree here.
• too many exercises - I am happy to kill ad-hoc, bonus, and also the conditionals. They do not add as much value as they used to. I understand the idea of the "a-ha" moment, but we have to cut somewhere, and the a-ha moment is also there with a playbook to some extent.
• roles - in the near future, collections will be a crucial piece of everything Ansible related. Without collections, no one will be able to use Ansible properly at all. So we need a something about collections, if we want it or not.
• awkwardness - some good points there. The ToC is not going to happen as long as github pages does not support that properly. Keep again in mind that the current exercise material is a downgraded version of a previous asciidoc exercise which had all this.

A word about lightbulb: there were multiple iterations of lightbulb. The very first I met was NOT about exercises, but about giving people some ideas and time to research them on their own. This is in strong contrast to how we run the workshops today. I challenge that the old concept was of broader use to larger groups, or even of use for any group size at all.

@IPvSean I would be happy if you can craft some PRs out of this once the discussions reach a certain level. maybe even as a benevolent dictator who is not involved with the RHEL workshop as such.

Also, @cloin & @goetzrieger , I'd love to get your input here!

[rhcreynold]

I agree with @ptoal , the original lightbulb was much better at layout and bringing the concepts home. A workshop should tell a story. How do I accomplish a goal not a single task, why does this matter and how can this help me in my day to day.

The awkwardness is related to the flow in my opinion. As it stands today, it is a collection of random exercise's to demonstrate a concept for that section. IE lets do apache, then randomly vsftp, then back to apache, then motd. To much bouncing around.

Slides - Most don't flow well or they are too busy, and there are too many of them. Some have a black background on white text, and some are white background with black text. We mostly use ansible.red instead of the pdf, and we never run the tower slides, we show a demo instead.

When provisioned there are no more working examples, now I have to keep a copy of the playbooks that the students write. We also used them for students to catch up.

The original concept of lightbulb was to teach every day admins, what Ansible could do for them, while teaching them the foundational Ansible concepts. Honestly I think the issue was that this attempted to replace lightbulb and it shouldn't be that. Lightbulb was great at laying a foundation of concepts and showing them. This workshop should have been written as a continuation or an addition/follow-on, not a replacement. Personally I think lightbulb should come back as a first intro to Ansible. Then have this workshop build on that and continue. The devops workshop that I wrote is meant to take what they learned from their first Ansible workshop and start moving it into infra-as-code/source of truth, building on what they have learned. Also the Dinky theme sucks.

[cloin]

So, admittedly, I haven’t reviewed the RHEL workshop in some time so I’m a bit fuzzy. I did want to comment on @rhcreynold’s reply because I totally agree with the story telling bit. I feel like using workshops as a sales tool brings to life some identified use case that can be built out in a safe space. Story telling is a huge piece of solution selling.

I feel that more importantly, each workshop type needs to be a pretty good 100-150 level where content is stable and very few changes are made. Something that is adaptable and can be tailored to the story we’re trying to tell that day. Too much content then becomes a good thing. Use it if you want - but here’s the base message that everybody should hear.

I’m a big fan of roles, too. It’s like teaching an object oriented language instead of BASIC. Because we don’t use CLI at all in the windows workshop, I use adhoc to demonstrate manual steps vs writing a playbook and then optimizing what we’re automating by breaking it out into a role (function) instead of copying and pasting or rewriting code to do the same thing multiple times.

I do miss asciidoc TOC! Is there really no way we can get that back?

[liquidat]

Few comments on that:

• Story telling - Good idea. The security workshop tells the story along actual use cases (threat hunting is one of them). Maybe there is value to come up with two or three use cases and follow them while providing the basics of Ansible? Would require quite some rewrites but I certainly like the idea.
• lightbulb - There was not "a" lightbulb. Please be more specific what you refer to. For example, in the original lightbulb had "workshkops" as well as guides. They had very different approaches.
• ansible.red - The current workshop deck is based on what Kev created out of ansible.red. Yes, it is not fully consistent in terms of design because it takes time to merge such a large deck into the common styl we have across the workshop decks. I fail to see that ansible.red solves any of the challenges mentioned anyway: it has serious shortcomings like introducing handlers way before playbooks, spending a lot of time on ansible-doc, having vault as the single most important feature, etc. and is overall very, very long.
• dinky theme - Open for suggestions. Where does it suck? What are the issues, what needs to be improved?

How do we proceed from here? I think there are some things at least many people agree one, like killing ad-hoc, bonus, streamlining the deck to have a consistent style and story improvements. How about we create issues at least for what people agree on and work on those?

[rhcreynold]

lightbulb - the guides is what we typically ran and it was a better story and flow when students went through it.

ansible.red - this slide deck is no where near as long as the current pdf. The pdf is fine until ROI slide, we skip this in the workshop. They have seen it already from the account team and it isn't the point when teaching engineers how to ansible. How to install and consume ansible is not in the pdf, we have taken the liberty of installing it for them on their control node. Being that this workshop is focused on infrastructure people, we don't actually tell them how to install either cli or tower anymore as we do it for them. ansible.red does have a few slides on ansible-doc BUT in public sector a good chunk of our customers do not have internet, so it is very useful.

Section 1.1 - is alright until towards the end then it gets bit ham sandwhich. We are stepping through the anisble subsystem, then we pimp the number of modules, then all of the sudden the next slide is how network automation works. Then now we are verifying access and doing section 1.1, has the instructor done any demos of anything yet?. This is confusing for the students.

The inventories section (1.2) is fine until the ansible.cfg file. In our delivery experience this is just something that doesn't need to be covered, just another layer of confusion for the student. We are trying to teach them how to automate and write playbooks to make their jobs easier. Is the config file needed, yes, but default out of the box ansible ignoring it is fine for writing 'my first playbook'.

Ad-hoc - (slide 40) we show them a command output, then spend a few slides explaining it. This is backwards.

Slides 45, we finally start talking about modules, and guess what it shows, networking modules (yes i understand it is alphabetical). Need to show the high level categories and rhel admin commonly used ones, like ansible.red does.

Slide 50 - this is bad, this is the second piece of yaml they have seen. It has nothing to do with the yaml they have seen earlier. Oh and now there are roles, vars, hosts, things which we have not covered in the slides. Several times a student stops to ask what a role is. After the yaml example, we explain the parts of a play.

Slide 57 - somewhat back on track with the first example, but now there are handlers, which has not been covered. Which isn't covered until slide 82.

Slide 65 - we call out the setup module, but it the explanation isn't until slide 70

1.4 - variables section is alright, though it doesn't relate to the apache which is the story here, right? the vars in ansible.red relate to apache.

slide 75 - too much going on here, you are explaining group vars and host vars on the same slide

Slide 78 - this doesn't speak to a sys admin. now we are using debug? whats that? we have not shown this to a student yet. you are using some words to show how a when clause works. a linux admin knows that apt doesn't work on rhel. so using the ansible fact for the os to only run the yum module when it is rhel makes sense. it also reinforces the ansible facts that we already covered. and it will lead them into blocks. ansible is write once, run many. for a bash script i'd have to have one for rhel and one for non rhel, with ansible i can write one playbook, use a block with a when clause for os dependent tasks. which is what is done slide 80.

1.6 - all good as it keeps with the apache story

1. 7 - drops how we create roles via cli, doesn't talk about how to use roles in a playbook, it just gives the folder structure

A common theme in the slides is to demo first, then teach. This is backwards to how most learning is done, demos should be there to reenforce the concept and to provide context.

dinky theme - it is just boring theme. it doesn't have any of the rh/ansible colors in it. there is no TOC (i understand that it isn't markdown), there is no pagination either. it is just basic.

[IPvSean]

maybe even as a benevolent dictator

:) :)

[IPvSean]

I think that #672 should also be part of this

[IPvSean]

the merge is on devel right now but if you are curious you can see it live on my mirror https://ipvsean.github.io/workshops/exercises/ansible_rhel/

[goetzrieger]

I think this discussion is valuable as there are definitely things to improve about the workshops. But as the original author of the two labs (they where separate labs initially) let me add some context first:

Background

Both labs where conceived as short Summit-Style labs, so two hours each. And they where run all over the place: last three Summits (with best feedback), EMEA Partner Conferences, Red Hat Forums, dedicated Ansible Events, customer workshops. I know a good number of SAs in EMEA use the workshops regularly (incl myself) and nobody ever came up with the idea that the workshops take too long or are too involved. To the contrary, I'd say somebody with basic sys admin skills can do the Engine part in two hours and the Tower part in 1.5 hours.

When I run one-day Ansible Workshops I usually take a modular approach, so I take my own slide decks and the Engine and Tower labs and then remix the agenda according to the audience. This could mean adding more presos (best practice/Windows automation/Network Automation). This works really well for me.

Discussed Changes

• Complexity and runtime: I really opt for leaving as is. Both labs can easily be finished in 4-5 hours by students with basic system admin skills. So even factoring in instructor time... 6 hours?

• Removal of Ad-Hocs / Conditionals: I still think ad-hocs make sense as the first contact and agree with @ptoal. Conditionals where screaming for a better example from the very beginning and should get an makeover but are needed. But I believe all other chapters should stay in place to get a well-rounded overview in a short time frame.

• Roles: As @liquidat pointed out collections will be an crucial thing to understand in the near future. So giving at least a brief idea what roles are about leading to collections should be in order.

• Awkwardness: Ah well... yes, the move away from Asciidoctor didn't make the guides better in terms of clarity, layout and ToC but I know you guys had to do this because of Github Pages. I'm esp missing the fold-outs for challenge solutions. @cbolz is looking into making the guides look/work better in MD for next Summit. Virtual that is, sigh...

• Clearer Structure in terms of lesson-objectives first and recap at the end is definitely making sense. I've tried to do this consistently but know I've failed this too often.

• Better Story Telling: This is something I fully agree with. But nobody should underestimate the work involved esp when writing a lab as a side project. Having a consistent story while learning automation is more fun and leads to better understanding. So if anybody will take this on, cool. I'm actually tired of the JSP application example... so 2000... ;)

So yes, there is good room for improvements, time permits, but I'd definitely opt for not changing the structure and content too much.

If the labs are not working for others in the same way as for us, what about having two "levels"? First level really short and to the point, the second level suited for a more experienced audience or longer slots, this could contain more complex/longer examples.

Another idea is to have more modular chapters that could be mixed and matched to be tailored to the audience. But again, this involves a lot of ongoing work and I guess the team around @IPvSean and @liquidat are pretty busy with maintaining the labs/workshops as they are.

[mhomann-TD]

I've used the ansible and the tower workshop with customers several times, and I never found either one too long or too complicated.

[cbolz]

HiHo,
I like the idea of streamlining the content and polish it further. I've delivered the workshop (RHEL, Networking and Tower) a few times as a one day workshop. I did not get the impression they are too long. But I guess there are a lot of variables and mileage may vary.

I would support they idea of making the content more modular. This would give the presenter more flexibility in choosing which content is relevant to the audience. And if you feel it's to much content, you can skip some modules...

My 2cents

[IPvSean]

@cbolz @goetzrieger @ptoal @rhcreynold please review this PR #777

there is a link to my github pages there, but I will also put this here-> https://ipvsean.github.io/workshops/exercises/ansible_rhel/#section-1---ansible-engine-exercises

I still think some other changes need to take place but this gets us maybe 10% of the way to where we want to be :). I hope that some of the tables will make things much easier on the eyes.

I am also working on securing funding for the digital team to redo the CSS on the github pages website to make it better

[IPvSean]

we have fixed some more issues with the RHEL workshop, thanks to @goetzrieger for creating new nodejs for RHEL8 #800

[IPvSean]

another release here with more solutions and fixes #878, this still doesn't fully close this out....

[IPvSean]

i think this issue is now too old... i think we should start a new discussion soon with EEs happening, but its time to close this issue