Merge branch 'chef-tutorial' into 'master'

Chef tutorial: generalize, rename, and add to Emulab

See merge request !17

cloudlab-chef-tutorial.scrbl → chef-tutorial.scrbl

@@ -2,11 +2,18 @@
 
 @(require "defs.rkt")
 
-@title[#:tag "cloudlab-chef-tutorial" #:version apt-version]{CloudLab Chef Tutorial}
+@title[#:tag "chef-tutorial" #:version apt-version]{@(tb) Chef Tutorial}
 
 This tutorial will walk you through the process of creating and using
 an instance of the Chef configuration management system on @(tb).
 
+@not-clab{
+Since this tutorial was originally developed for CloudLab,
+you will find the screenshots below that have the CloudLab name and logo in
+them. When you use @(tb) to build Chef, the process is exactly the same;
+the only difference is that you will see the @(tb) name and logo instead in the portal pages you will open and use.
+}
+
 @margin-note{Chef is both the name of a company and the name of a popular modern configuration management system
 written in Ruby and Erlang. A large variety of tutorials, articles, technical docs and training opportunities
 is available at the @link["https://learn.chef.io/"]{Chef official website}.
@@ -48,7 +55,7 @@ This tutorial assumes that:
 
 @itemlist[
     @item{You have an existing account on @bold{either}: @itemlist[
-        @item{CloudLab (Instructions for getting an account can
+        @item{@(tb) (Instructions for getting an account can
             be found @seclink["register"]{here}.)}
         @item{The @link["https://portal.geni.net"]{GENI portal}.
             (Instructions for getting an account can be found
@@ -86,36 +93,42 @@ See this manual's @seclink["profiles"]{section on profiles} for more
 information about how they work.
 
 @itemlist[#:style 'ordered
+
+    @instructionstep["Start Experiment"]{
+        @clab-screenshot["tutorial/start-experiment-menu.png"]
+
+        After logging in, you are taken to your main status
+        @link[@apt-url["user-dashboard.php"]]{dashboard}.
+        Select ``Start Experiment'' from
+        the ``Experiments'' menu.
+    }
+
     @instructionstep["Select a profile"]{
 
-        After logging in, you will be taken to the
-        ``@link["https://www.cloudlab.us/instantiate.php"]{Start an
-        Experiment}'' page automatically if you do not have any current,
-        running experiments. You can get back to this page at any time by
-        selecting the ``Start Experiment'' link from the ``Actions'' menu.
-        By default, this page suggests launching the OpenStack profile which
+        By default, the ``Start an Experiment'' page suggests launching the OpenStack profile which
         is discribed in detail in the @seclink["openstack-tutorial"]{OpenStack tutorial}.
 
         Go to the list of available profile by clicking ``Change Profile'':
 
-        @screenshot["chef-tutorial/change-profile.png"]
+        @clab-screenshot["chef-tutorial/change-profile.png"]
 
         Find the profile by typing @bold{ChefCluster} in the search bar. Then, select the profile with the
         specified name in the list displayed below the search bar.
         A 2-node preview should now be shown along with high-level profile information.
         Click ``Select Profile'' at the bottom of the page:
 
-        @screenshot["chef-tutorial/find-chefcluster.png"]
+        @clab-screenshot["chef-tutorial/find-chefcluster.png"]
 
         After you select the correct profile, click ``Next'':
 
-        @screenshot["chef-tutorial/instantiate-next.png"]
+        @clab-screenshot["chef-tutorial/instantiate-next.png"]
     }
 
     @instructionstep["Set parameters"
-                     #:screenshot "chef-tutorial/params-next.png"]{
+                     #:screenshot "chef-tutorial/params-next.png"
+                     #:screenshot-where "clab"]{
 
-    Profiles in CloudLab can have @emph{parameters} that affect how they are
+    Profiles in @(tb) can have @emph{parameters} that affect how they are
     configured; for example, this profile has parameters that allow you to
     set the number of client nodes, specify the repository with the infrastructure
     code we plan to use, obtain copies of the application-specific infrastructure code developed
@@ -130,16 +143,17 @@ information about how they work.
         You may optionally give your experiment a meaningful name, e.g., ``chefdemo''.
         This is useful if you have many experiments running at once.
 
-        @screenshot["chef-tutorial/experiment-name.png"]
+        @clab-screenshot["chef-tutorial/experiment-name.png"]
     }
 
 
     @instructionstep["Select a cluster"
-                     #:screenshot "chef-tutorial/select-cluster.png"]{
+                     #:screenshot "chef-tutorial/select-cluster.png"
+                     #:screenshot-where "clab"]{
         @(tb) has multiple clusters available to it. Some profiles can run
         on any cluster, some can only run on specific ones due to specific hardware
         constraints. @bold{ChefCluster} can only run on the x86-based clusters.
-        This excludes the CloudLab Utah cluster which is built on ARMv8 nodes. 
+        This excludes the @(tb) Utah cluster which is built on ARMv8 nodes.
         Refer to the @seclink["hardware"]{Hardware} section for more information.
 
         @bold{Note:} If you are at an in-person tutorial, the instructor will
@@ -158,14 +172,14 @@ information about how they work.
         you selected.
     }
 
-    @instructionstep["CloudLab instantiates your profile"]{
+    @instructionstep["@(tb) instantiates your profile"]{
         @(tb) will take a few minutes to bring up your experiment, as
         many things happen at this stage, including selecting suitable
         hardware, loading disk images on local storage, booting bare-metal
         machines, re-configuring the network topology, etc. While this is
         happening, you will see the topology with yellow node icons:
 
-        @screenshot["chef-tutorial/booting.png"]
+        @clab-screenshot["chef-tutorial/booting.png"]
 
         @margin-note{Provisioning is done using the
         @link["http://groups.geni.net/geni/wiki/GeniApi"]{GENI APIs}; it
@@ -178,7 +192,7 @@ information about how they work.
         able to log in until they have gone through the process of imaging and
         booting.) While you are waiting for your resources to become available,
         you may want to have a look at the
-        @link["http://docs.cloudlab.us"]{@(tb)
+        @link[apt-doc-url]{@(tb)
         user manual}, or use the ``Sliver'' button to watch the logs of the
         resources (``slivers'') being provisioned and booting.
     }
@@ -186,7 +200,7 @@ information about how they work.
     @instructionstep["Your resources are ready!"]{
          Shortly, the web interface will report the state as ``Booted''.
 
-         @screenshot["chef-tutorial/booted.png"]
+         @clab-screenshot["chef-tutorial/booted.png"]
 
          @bold{Important:} A ``Booted'' status indicates that resources are
          provisioned and booted; this particular profile runs scripts to
@@ -199,7 +213,7 @@ information about how they work.
          In the Topology View tab, mouse over the circle in the @tt{head}'s icon,
          to confirm the current state of the node.
 
-         @screenshot["chef-tutorial/head-running.png"]
+         @clab-screenshot["chef-tutorial/head-running.png"]
     }
 ]
 
@@ -218,7 +232,7 @@ buttons in this area let you make a copy of the profile (so that you can
 @seclink["creating-profiles"]{customize it}), ask to hold on to the resources
 for longer, or release them immediately.
 
-@screenshot["chef-tutorial/experiment-status.png"]
+@clab-screenshot["chef-tutorial/experiment-status.png"]
 
 Note that the default lifetime for experiments on @(tb) is less than a day;
 after this time, the resources will be reclaimed and their disk contents will
@@ -242,7 +256,7 @@ Also, notice the list of private and public hostnames of the experiment nodes
 included in the instructions. You will use the public hostnames (shown in bold)
 in the exercise with the Apache web server and apache benchmark.
 
-@screenshot["chef-tutorial/experiment-instructions.png"]
+@clab-screenshot["chef-tutorial/experiment-instructions.png"]
 
 @subsection{Topology View}
 
@@ -267,7 +281,7 @@ by clicking the ``Run Linktest'' button at the bottom of the page. The available
 Higher levels will take longer to complete and require patience.
 }
 
-@screenshot["chef-tutorial/topology-view.png"]
+@clab-screenshot["chef-tutorial/topology-view.png"]
 
 If an experiment has startup services, their statuses are indicated by small icons in
 the upper right corners of the node icons. You can mouse over this icon to see a
@@ -298,7 +312,7 @@ authentication is supported, and you must have set up an @(ssh) keypair on your
 account @bold{before} starting the experiment in order for authentication to
 work.
 
-@screenshot["chef-tutorial/list-view.png"]
+@clab-screenshot["chef-tutorial/list-view.png"]
 
 @subsection{Manifest View}
 
@@ -314,7 +328,7 @@ topology and assigned resources.
 @margin-note{Most of the information displayed on the @(tb) status page comes
 directly from this manifest; it is parsed and laid out in-browser.}
 
-@screenshot["chef-tutorial/manifest-view.png"]
+@clab-screenshot["chef-tutorial/manifest-view.png"]
 
 @subsection[#:tag "chef-tutorial-actions"]{Actions}
 
@@ -329,7 +343,7 @@ become green again. The @seclink["chef-tutorial-web-shell"]{shell}
 action is described in more detail below and will be used as
 the main method for issuing commands on the experiment nodes throughout this tutorial.
 
-@screenshot["chef-tutorial/experiment-actions.png"]
+@clab-screenshot["chef-tutorial/experiment-actions.png"]
 
 @section{Brief Introduction to Chef}
 
@@ -478,7 +492,7 @@ While you are here, switch to the @italic{root} user by typing:
 
 @verbatim{@bold{sudo su -}}
 
-@screenshot["chef-tutorial/experiment-shell.png"]
+@clab-screenshot["chef-tutorial/experiment-shell.png"]
 
 Your prompt, the string which is printed on every line before the cursor,
 should change to @tt{root@"@"head}.
@@ -493,7 +507,7 @@ Type the following to print Chef credentials:
 You should see the unique login and password that have been
 generated by the startup scripts specifically for your instance of Chef:
 
-@screenshot["chef-tutorial/shell-chefauth.png"]
+@clab-screenshot["chef-tutorial/shell-chefauth.png"]
 
 Expand the ``Profile Instructions'' panel and
 click on the ``Chef web console'' link.
@@ -510,8 +524,8 @@ click ``Confirm Security Exception''.
 
 When the login page is finally displayed, use the credentials you have printed in the shell:
 
-@screenshot["chef-tutorial/chef-wui-login.png"]
-@screenshot["chef-tutorial/chef-wui-nodelist.png"]
+@clab-screenshot["chef-tutorial/chef-wui-login.png"]
+@clab-screenshot["chef-tutorial/chef-wui-nodelist.png"]
 
 If you see a console like the one above, with both @tt{head} and @tt{node-0} listed on the ``Nodes'' tab,
 you have a working Chef cluster! You can now proceed to managing your nodes using
@@ -537,17 +551,17 @@ on these nodes by installing NFS and exporting a directory from @tt{head} to
     Click on the row for @tt{head} in the node list (so the entire row is highlighted in orange),
     and then click "Edit" in the Run List panel in the bottom right corner of the page:
 
-    @screenshot["chef-tutorial/head-edit-runlist.png"]
+    @clab-screenshot["chef-tutorial/head-edit-runlist.png"]
   }
   @instructionstep["Apply nfs role:"]{
     In the popup window, find the role called @tt{nfs} in the Available Roles list on the left, drag and drop it into
     the "Current Run List" field on the right. When this is done, click "Save Run List".
 
-    @screenshot["chef-tutorial/head-nfs-drag.png"]
+    @clab-screenshot["chef-tutorial/head-nfs-drag.png"]
   }
   @instructionstep["Repeat the last two steps for node-0:"]{
-    @screenshot["chef-tutorial/node0-edit-runlist.png"]
-    @screenshot["chef-tutorial/node0-nfs-drag.png"]
+    @clab-screenshot["chef-tutorial/node0-edit-runlist.png"]
+    @clab-screenshot["chef-tutorial/node0-nfs-drag.png"]
 
     At this point, @tt{nfs} role is assigned to both nodes, but nothing has executed yet.
   }
@@ -560,7 +574,7 @@ on these nodes by installing NFS and exporting a directory from @tt{head} to
 
     The run lists for your nodes should be printed inside square brackets:
 
-    @screenshot["chef-tutorial/shell-knife-status.png"]
+    @clab-screenshot["chef-tutorial/shell-knife-status.png"]
 
     The output of this command also conveniently shows when Chef applied changes to your
     nodes last (first column) and what operating systems run on the nodes (last column).
@@ -570,7 +584,7 @@ on these nodes by installing NFS and exporting a directory from @tt{head} to
     Run the assigned role on @tt{head} by typing:
     @verbatim{@bold{chef-client}}
 
-    @screenshot["chef-tutorial/head-chef-client.png"]
+    @clab-screenshot["chef-tutorial/head-chef-client.png"]
 
     As a part of the startup procedure,
     passwordless @tt{ssh} connections are enabled between the nodes.
@@ -580,7 +594,7 @@ on these nodes by installing NFS and exporting a directory from @tt{head} to
 
     @verbatim{@bold{ssh node-0 chef-client}}
 
-    @screenshot["chef-tutorial/node0-chef-client.png"]
+    @clab-screenshot["chef-tutorial/node0-chef-client.png"]
 
     When nodes execute the ``@code{chef-client}'' command,
     they contact the server and request the cookbooks, recipes, and roles have been
@@ -615,7 +629,7 @@ on these nodes by installing NFS and exporting a directory from @tt{head} to
     @bold{ssh node-0 ls /exp-share/}
     }
 
-    @screenshot["chef-tutorial/nfs-is-working.png"]
+    @clab-screenshot["chef-tutorial/nfs-is-working.png"]
 
     If you can see the created file on @tt{node-0}, your NFS is working as expected.
     Now you can easily move files between your nodes using the @code{/exp-share} directory.
@@ -816,7 +830,7 @@ executed as @italic{root}). Run the commands described below in that shell.
     With the right hostname, copy and paste this URL into your browser to access the web server running on @tt{node-0}
     and serving the benchmarking graphs. You should see a directory listing like this:
 
-    @screenshot["chef-tutorial/apache-dir-listing-0.png"]
+    @clab-screenshot["chef-tutorial/apache-dir-listing-0.png"]
 
     You can explore the benchmarking graphs by clicking at the listed links.
     So far, @code{ab} has run against the local host (i.e. @tt{node-0}), therefore the
@@ -835,7 +849,7 @@ executed as @italic{root}). Run the commands described below in that shell.
     At the bottom of the page, you should now see
     a panel called ``Override Attributes''. Click the ``Edit'' button inside that panel:
 
-    @screenshot["chef-tutorial/console-apachebench-edit.png"]
+    @clab-screenshot["chef-tutorial/console-apachebench-edit.png"]
 
     In the popup window, change the @code{target_host} attribute from @code{null}
     to the @tt{head}'s public hostname (refer to the hostnames listed in the profile instructions).
@@ -846,7 +860,7 @@ executed as @italic{root}). Run the commands described below in that shell.
     is the port on which the Chef web console is running.
     Here is an example of the recommended changes:
 
-    @screenshot["chef-tutorial/console-apachebench-change-attr.png"]
+    @clab-screenshot["chef-tutorial/console-apachebench-change-attr.png"]
 
     When these changes are complete, click "Save Attributes".
 
@@ -875,14 +889,14 @@ executed as @italic{root}). Run the commands described below in that shell.
   @instructionstep["Check benchmarking results again"]{
     Go back to your browser window and update the page to see the directory listing with new benchmarking results.
 
-    @screenshot["chef-tutorial/apache-dir-listing-1.png"]
+    @clab-screenshot["chef-tutorial/apache-dir-listing-1.png"]
 
     The first two (the most recent) graphs represent the results of benchmarking
     of the web services running on @tt{head} performed from @tt{node-0}. Among many interesting facts
     that are revealed by these graphs, you will see that the response time is much higher
     on the port @code{443} than on the port @code{8080}.
 
-    @screenshot["chef-tutorial/bench-graphs.png"]
+    @clab-screenshot["chef-tutorial/bench-graphs.png"]
   }
 ]
 
@@ -908,7 +922,7 @@ into a specification that satisfy specific application needs.
 
 The @tt{apachebench} role is stored at @link["https://github.com/emulab/chef-repo/blob/master/roles/apachebench.rb"]{roles/apachebench.rb}
 It specifies values for several attributes and adds a custom cookbook @tt{emulab-apachebench} to the run list.
-We use the ``@code{emulab}'' prefix in the names of the cookbooks that have been developed by the CloudLab staff 
+We use the ``@code{emulab}'' prefix in the names of the cookbooks that have been developed by the @(tb) staff
 to emphasize that they are developed for @link["https://www.emulab.net/"]{Emulab} and derived testbeds such as @(tb).
 This also allows distinguishing them from the Supermarket cookbooks, which are installed in the same directory on @tt{head}.
 
@@ -929,7 +943,7 @@ can augment resources with additional checks like ``@code{only_if{::File.exists?
 and ``@code{not_if{::File.exists?(<file name>)}}'' to make your infrastructure code
 more reliable and repeatable (this refers to the notion of @italic{idempotent} code mentioned earlier).
 
-@section{Final Remarks about Chef on CloudLab}
+@section{Final Remarks about Chef on @(tb)}
 
 In this tutorial, you had a chance to explore the Chef configuration management system and used
 some of its powerful features for configuration management in a multi-node experiment on @(tb).
@@ -957,7 +971,7 @@ therefore limited and in high demand. When you are done, you should release
 them for use by other experimenters. Do this via the ``Terminate'' button on
 the @(tb) experiment status page.
 
-@screenshot["chef-tutorial/terminate.png"]
+@clab-screenshot["chef-tutorial/terminate.png"]
 
 @bold{Note:} When you terminate an experiment, all data on the nodes is lost,
 so make sure to copy off any data you may need before terminating.

cloudlab-manual.scrbl

@@ -55,5 +55,5 @@ control system can be found on CloudLab's @hyperlink[(apturl
 @include-section["hardware.scrbl"]
 @include-section["planned.scrbl"]
 @include-section["openstack-tutorial.scrbl"]
-@include-section["cloudlab-chef-tutorial.scrbl"]
+@include-section["chef-tutorial.scrbl"]
 @include-section["getting-help.scrbl"]

emulab-manual.scrbl

@@ -49,4 +49,5 @@ you can apply to start a new project.
 @include-section["emulab-hardware.scrbl"]
 @include-section["planned.scrbl"]
 @include-section["openstack-tutorial.scrbl"]
+@include-section["chef-tutorial.scrbl"]
 @include-section["getting-help.scrbl"]