cloudlab-tutorial.scrbl 30.9 KB
Newer Older
1 2 3 4
#lang scribble/manual

@(require "defs.rkt")

5
@title[#:tag "cloudlab-tutorial" #:version apt-version]{@(tb) OpenStack Tutorial}
6 7

This tutorial will walk you through the process of creating a small cloud on
Robert Ricci's avatar
Robert Ricci committed
8
@(tb) using OpenStack. Your copy of OpenStack will run on bare-metal machines
9 10 11 12 13 14 15 16 17
that are dedicated for your use for the duration of your experiment. You will
have complete administrative access to these machines, meaning that you have
full ability to customize and/or configure your installation of OpenStack.

@section{Objectives}

In the process of taking this tutorial, you will learn to:

@itemlist[
18
    @item{Log in to CloudLab}
19
    @item{Create your own cloud by using a pre-defined profile}
20
    @item{Access resources in a cloud that you create}
21
    @item{Use administrative access to customize your cloud}
22
    @item{Clean up your cloud when finished}
23
    @item{Learn where to get more information}
24 25
]

26 27 28 29 30
@section{Prerequisites}

This tutorial assumes that:

@itemlist[
31 32 33 34 35
    @item{You have an existing account on @bold{either}: @itemlist[
        @item{CloudLab (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
36
        @link["http://groups.geni.net/geni/wiki/SignMeUp"]{here}.)}
37
        ]}
38 39
]

40
@include-section["tutorial-login-common.scrbl"]
41

42
@section[#:tag "openstack-tutorial-body"]{Building Your Own OpenStack Cloud}
43

44
Once you have logged in to @(tb), you will ``instantiate'' a @seclink["profiles"]{``profile''}
45 46 47
to create an @seclink["experiments"]{experiment}. (An experiment in @(tb) is similar
to a @link["http://groups.geni.net/geni/wiki/GENIConcepts#Slice"]{``slice''} in
GENI.) Profiles are @(tb)'s way of packaging up configurations and experiments
48 49
so that they can be shared with others. Each experiment is separate:
the experiment that you create for this tutorial will be an instance of a profile provided by
50 51 52
the facility, but running on resources that are dedicated to you, which you
have complete control over. This profile uses local disk space on the nodes, so
anything you store there will be lost when the experiment terminates.
53

Robert Ricci's avatar
Robert Ricci committed
54
@margin-note{The OpenStack cloud we will build in this tutorial is very small, but @(tb)
55 56 57
has @seclink["hardware"]{large clusters} that can be used for larger-scale
experiments.}

Robert Ricci's avatar
Robert Ricci committed
58
For this tutorial, we will use a basic profile that brings up a small OpenStack
59 60 61 62 63 64
cloud. The @(tb) staff have built this profile by capturing
@seclink["disk-images"]{disk images} of a partially-completed OpenStack installation
and scripting the remainder of the install (customizing it for the specific
machines that will get allocated, the user that created it, etc.)
See this manual's @seclink["profiles"]{section on profiles} for more
information about how they work.
65 66


67
@itemlist[#:style 'ordered
68 69 70 71 72 73

    @instructionstep["Start Experiment"]{
        @screenshot["tutorial/start-experiment-menu.png"]

        
        After logging in, you are taken to your main status
Robert Ricci's avatar
Robert Ricci committed
74 75
	@link["https://www.cloudlab.us/user-dashboard.php"]{dashboard}.
	Select ``Start Experiment'' from
76 77 78
	the ``Experiments'' menu.
    }

79 80 81
    @instructionstep["Select a profile"]{

        @screenshot["tutorial/start-experiment.png"]
82 83

        The ``Start an Experiment'' page is where you will select a profile
Robert Ricci's avatar
Robert Ricci committed
84
        to instantiate. We will use the @bold{OpenStack} profile; if
85
        it is not selected, follow
Robert Ricci's avatar
Robert Ricci committed
86
        @link["https://cloudlab.us/p/emulab-ops/OpenStack"]{this link}
87
        or click the ``Change Profile'' button, and select
Robert Ricci's avatar
Robert Ricci committed
88
        ``OpenStack'' from the list on the left.
89 90 91 92

        Once you have the correct profile selected, click ``Next''

        @screenshot["tutorial/click-next.png"]
93 94
    }

95 96 97 98 99 100 101 102 103 104 105 106
    @instructionstep["Set parameters"
                     #:screenshot "tutorial/set-parameters.png"]{

    Profiles in CloudLab can have @emph{parameters} that affect how they are
    configured; for example, this profile has parameters that allow you to
    set the size of your cloud, spread it across multiple clusters, and turn on
    and off many OpenStack options.

    For this tutorial, we will leave all parameters at their defaults and
    just click ``next''.
    } 

107
    @instructionstep["Select a cluster"
108
                     #:screenshot "tutorial/pick-cluster.png"]{
109
        @(tb) has multiple clusters available to it. Some profiles can run
110
        on any cluster, some can only run on specific ones due to specific hardware
111 112 113 114
        constraints, etc.

        @bold{Note:} If you are at an in-person tutorial, the instructor will
        tell you which cluster to select. Otherwise, you may select any
115
        cluster.
116

117 118 119 120
        @margin-note{The dropdown menu for the clusters shows you both the
        health (outer ring) and available resources (inner dot) of each
        cluster. The ``Check Cluster Status'' link opens a page (in a new
        tab) showing the current utilization of all @(tb) clusters.}
121
    }
122

123
    @instructionstep["Click Finish!"
124
                     #:screenshot "tutorial/click-create.png"]{
125
        When you click the ``finish'' button, @(tb) will start
126 127
        provisioning the resources that you requested on the cluster that
        you selected.
128 129 130 131

        @margin-note{You may optionally give your experiment a name---this
        can be useful if you have many experiments running at once.}

132 133
    }

134
    @instructionstep["CloudLab instantiates your profile"]{
135
        @(tb) will take a few minutes to bring up your copy of OpenStack, as
136 137
        many things happen at this stage, including selecting suitable
        hardware, loading disk images on local storage, booting bare-metal
Robert Ricci's avatar
Robert Ricci committed
138
        machines, re-configuring the network topology, etc. While this is
139 140 141 142 143 144 145
        happening, you will see this status page:

        @screenshot["tutorial/status-waiting.png"]
        
        @margin-note{Provisioning is done using the 
        @link["http://groups.geni.net/geni/wiki/GeniApi"]{GENI APIs}; it
        is possible for advanced users to bypass the @(tb) portal and
146 147
        call these provisioning APIs from their own code. A good way to
        do this is to use the @link["https://geni-lib.readthedocs.org"]{@tt{geni-lib} library for Python.}}
148 149 150 151 152 153 154


        As soon as a set of resources have been assigned to you, you will see
        details about them at the bottom of the page (though you will not be
        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
155
        @link["http://docs.cloudlab.us"]{@(tb)
156 157
        user manual}, or use the ``Sliver'' button to watch the logs of the
        resources (``slivers'') being provisioned and booting.
158 159
    }

160
    @instructionstep["Your cloud is ready!"
161
                     #:screenshot "tutorial/status-ready.png"]{
162
         When the web interface reports the state as ``Booted'', your cloud
163 164
         is provisioned, and you can proceed to the next section.

165
         @bold{Important:} A ``Booted'' status indicates that resources are
166 167
         provisioned and booted; this particular profile runs scripts to
         complete the OpenStack setup, and it will be a few more minutes before
168
         OpenStack is fully ready to log in and create virtual machine
169 170 171
         instances. You will be able to tell that this has finished when the
         status changes from ``Booted'' to ``Ready''. For now, don't attempt to
         log in to OpenStack, we will explore the CloudLab experiment first.
172

173 174 175
    }

]
176

177
@section{Exploring Your Experiment}
178

179
Now that your experiment is ready, take a few minutes to look at various parts
180
of the @(tb) status page to help you understand what resources you've got and what
181 182 183 184
you can do with them.

@subsection{Experiment Status}

185
The panel at the top of the page shows the status of your experiment---you can
186
see which profile it was launched with, when it will expire, etc. The
187
buttons in this area let you make a copy of the profile (so that you can
188
@seclink["creating-profiles"]{customize it}), ask to hold on to the resources
189 190 191
for longer, or release them immediately.

@screenshot["tutorial/experiment-status.png"]
192

193
Note that the default lifetime for experiments on @(tb) is less than a day;
194
after this time, the resources will be reclaimed and their disk contents will
195
be lost. If you need to use them for longer, you can use the ``Extend'' button
196
and provide a description of why they are needed. Longer extensions require
197
higher levels of approval from @(tb) staff. You might also consider
198
@seclink["creating-profiles"]{creating a profile} of your own if you might need
199 200 201 202 203 204 205 206 207 208
to run a customized environment multiple times or want to share it with others.

You can click the title of the panel to expand or collapse it.


@subsection{Profile Instructions}

Profiles may contain written instructions for their use. Clicking on the title
of the ``Profile Instructions'' panel will expand (or collapse) it; in this
case, the instructions provide a link to the administrative interface of
209
OpenStack, and give you passwords to use to log in. (Don't log into OpenStack
210
yet---for now, let's keep exploring the @(tb) interface.)
211 212 213 214 215

@screenshot["tutorial/experiment-instructions.png"]

@subsection{Topology View}

Robert Ricci's avatar
Robert Ricci committed
216
At the bottom of the page, you can see the topology of your experiment. This
217
profile has three nodes connected by a 10 Gigabit LAN, which is represented by
218 219 220 221 222 223 224 225
a gray box in the middle of the topology. The names given for each node are
the names assigned as part of the profile; this way, every time you instantiate
a profile, you can refer to the nodes using the same names, regardless of which
physical hardware was assigned to them. The green boxes around each node
indicate that they are up; click the ``Refresh Status'' button to initiate a
fresh check.

@screenshot["tutorial/topology-view.png"]
226

227 228 229 230
If an experiment has ``startup services'' (programs that run at the beginning
of the experiment to set it up), their status is indicated by a small icon in
the upper right corner of the node. You can mouse over this icon to see a
description of the current status. In this profile, the startup services
231
on the compute node(s) typically complete quickly, but
232 233
the control node may take much longer.

234
It is important to note that every node in @(tb) has at least @italic{two}
235
network interfaces: one ``control network'' that carries public IP
236 237 238 239 240 241
connectivity, and one ``experiment network'' that is isolated from the Internet
and all other experiments. It is the experiment net that is shown in this
topology view.  You will use the control network to @(ssh) into your nodes,
interact with their web interfaces, etc. This separation gives you more
freedom and control in the private experiment network, and sets up a clean
environment for @seclink["repeatable-research"]{repeatable research}.
242 243


244
@subsection[#:tag "openstack-tutorial-list-view"]{List View}
245

Robert Ricci's avatar
Robert Ricci committed
246
The list view tab shows similar information to the topology view, but in a
247 248 249 250 251 252 253 254
different format. It shows the identities of the nodes you have been
assigned, and the full @(ssh) command lines to connect to them. In some
browsers (those that support the @tt{ssh://} URL scheme), you can click on the
SSH commands to automatically open a new session. On others, you may need to
cut and paste this command into a terminal window. Note that only public-key
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.
255

256
@screenshot["tutorial/experiment-list.png"]
257

258
@subsection{Manifest View}
259

260
The third default tab shows a
261
@link["http://groups.geni.net/geni/wiki/GENIExperimenter/RSpecs#ManifestRSpec"]{manifest} detailing the hardware that has been assigned to you. This is the
262 263 264
@seclink["rspecs"]{``request'' RSpec} that is used to define the profile,
annotated with details of the hardware that was chosen to instantiate your
request. This information is available on the nodes themselves using the
265
@link["http://groups.geni.net/geni/wiki/GeniGet"]{@tt{geni-get}} command, 
266
enabling you to do rich scripting that is fully aware of both the requested
267
topology and assigned resources.
268

269
@margin-note{Most of the information displayed on the @(tb) status page comes
Robert Ricci's avatar
Robert Ricci committed
270
directly from this manifest; it is parsed and laid out in-browser.}
271

272
@screenshot["tutorial/experiment-manifest.png"]
273

274 275 276 277 278 279 280 281 282 283 284 285 286 287 288 289 290 291 292 293 294 295
@subsection{Graphs View}

The final default tab shows a page of CPU load and network traffic
graphs for the nodes in your experiment.  On a freshly-created
experiment, it may take several minutes for the first data to appear.
After clicking on the ``Graphs'' tab the first time, a small reload icon
will appear on the tab, which you can click to refresh the data and
regenerate the graphs.  For instance, here is the load average graph for
an OpenStack experiment running this profile for over 6 hours.  Scroll
past this screenshot to see the control and experiment network traffic
graphs.  In your experiment, you'll want to wait 20-30 minutes before
expecting to see anything interesting.

@screenshot["tutorial/experiment-graphs.png"]

Here are the control network and experiment network packet graphs at the
same time.  The spikes at the beginning are produced by OpenStack setup
and configuration, as well as the simple OpenStack tasks you'll perform
later in this profile, like adding a VM.

@screenshot["tutorial/experiment-graphs-nets.png"]

296
@subsection[#:tag "openstack-tutorial-actions"]{Actions}
297 298

In both the topology and list views, you have access to several actions that
299
you may take on individual nodes. In the topology view, click on the node to
300
access this menu; in the list view, it is accessed through the icon in the
301 302 303 304
``Actions'' column. Available actions include rebooting (power cycling) a node,
and re-loading it with a fresh copy of its disk image (destroying all data on
the node).  While nodes are in the process of rebooting or re-imaging, they
will turn yellow in the topology view. When they have completed, they will
305 306
become green again. The @seclink["openstack-tutorial-web-shell"]{shell} and
@seclink["openstack-tutorial-console"]{console} actions are described in more detail
307
below.
308

309
@screenshot["tutorial/experiment-actions.png"]
310

311
@subsection[#:tag "openstack-tutorial-web-shell"]{Web-based Shell}
312

313
@(tb) provides a browser-based shell for logging into your nodes, which is
314 315 316
accessed through the action menu described above. While this shell is
functional, it is most suited to light, quick tasks; if you are going to do
serious work, on your nodes, we recommend using a standard terminal
317
and @(ssh) program.
318

319
This shell can be used even if you did not establish an @(ssh) keypair with
320 321 322 323 324 325 326 327
your account.

Two things of note:

@itemlist[
    @item{Your browser may require you to click in the shell window before
        it gets focus.}

328 329 330
    @item{Depending on your operating system and browser, cutting and pasting into
        the window may not work. If keyboard-based pasting does not
        work, try right-clicking to paste.}
331 332
]

333
@screenshot["tutorial/experiment-shell.png"]
334

335
@subsection[#:tag "openstack-tutorial-console"]{Serial Console}
336

337
@(tb) provides serial console access for all nodes, which can be used
338
in the event that normal IP or @(ssh) access gets intentionally or
Robert Ricci's avatar
Robert Ricci committed
339
unintentionally broken. Like the browser-based shell, it is launched through
340
the access menu, and the same caveats listed above apply as well. In addition:
341 342 343 344 345 346

@itemlist[
    @item{If you look at the console for a node that is already booted,
    the console may be blank due to a lack of activity; press enter
    several times to get a fresh login prompt.}

347 348 349 350
    @item{If you need to log in, do so as @bold{root}; your normal user account
    does not allow password login. There is a link above the console window
    that reveals the randomly-generated root password for your node. Note that
    this password changes frequently for security reasons.}
351 352
]

353
@screenshot["tutorial/experiment-console.png"]
354

355
@section[#:tag "openstack-tutorial-instances"]{Bringing up Instances in OpenStack}
356 357 358 359 360

Now that you have your own copy of OpenStack running, you can use it just like
you would any other OpenStack cloud, with the important property that you have
full @tt{root} access to every machine in the cloud and can modify them however
you'd like. In this part of the tutorial, we'll go through the process of
361 362
bringing up a new VM instance in your cloud.

363
@margin-note{We'll be doing all of the work in this section using the Horizon
364
web GUI for OpenStack, but you could also @(ssh) into the machines directly and use the
365 366
command line interfaces or other APIs as well.}

Robert Ricci's avatar
Robert Ricci committed
367 368
@itemlist[#:style 'ordered

369 370 371 372 373 374 375 376 377
    @instructionstep["Check to see if OpenStack is ready to log in"]{

        As mentioned earlier, this profile runs several scripts to complete
        the installation of OpenStack. These scripts do things such as
        finalize package installation, customize the installation for the 
        specific set of hardware assigned to your experiment, import cloud
        images, and bring up the hypervisors on the compute node(s).

        If exploring the @(tb) experiment took you more than ten minutes, these
378 379 380 381 382
        scripts are probably done. You can be sure by checking that @bold{all}
        nodes have completed their startup scripts (indicated by a checkmark
        on the Topology view); when this happens, the experiment state will
        also change from ``Booting'' to ``Ready''

383 384
        @screenshot["tutorial/status-scriptsdone.png"]

385 386 387 388
        If you continue without verifying that the setup scripts are
        complete, be aware that you may see temporary errors from the
        OpenStack web interface. These errors, and the method for dealing with
        them, are generally noted in the text below.
389 390
    }

391
    @instructionstep["Visit the OpenStack Horizon web interface"
Robert Ricci's avatar
Robert Ricci committed
392
                     #:screenshot "tutorial/experiment-password.png"]{
393 394
        On the status page for your experiment, in the ``Instructions''
        panel (click to expand it if it's collapsed), you'll find a link
395
        to the web interface running on the @tt{ctl} node. Open this
396
        link (we recommend opening it in a new tab, since you will still
397
        need information from the @(tb) web interface). 
398 399
    }

400
    @instructionstep["Log in to the OpenStack web interface"
401 402
                     #:screenshot "tutorial/os-login.png"]{
        Log in using the username @tt{admin} and the password shown in 
403 404
        the instructions for the profile.  Use the domain name @tt{default}
        if prompted for a domain.
405

Robert Ricci's avatar
Robert Ricci committed
406
        @margin-note{This profile generates a new (random) password for every
407 408
        experiment.}

409 410 411
        @bold{Important:} if the web interface rejects your password, wait
        a few minutes and try again. If it gives you another type of error,
        you may need to wait a minute and reload the page to get login
412
        working properly.
413 414
    }

415
    @instructionstep["Launch a new VM instance"
416 417 418 419 420
                     #:screenshot "tutorial/os-launch.png"]{
        Click the ``Launch Instance'' button on the ``Instances'' page of the
        web interface.
    }

421
    @instructionstep["Set Basic Settings For the Instance"]{
422 423

        There a few settings you will need to make in order to launch your
424 425 426 427 428 429 430
        instance.  These instructions are for the launch wizard in the
        OpenStack @tt{Mitaka}, but the different release wizards are all
        similar in function and required information.
        Use the tabs in the column on the left of the launch
        wizard to add the required information (i.e., @tt{Details},
        @tt{Source}, @tt{Flavor}, @tt{Networks}, and @tt{Key Pair}),
	as shown in the following screenshots:
431

432 433
        @screenshot["tutorial/os-launch-basic.png"]

434 435
        @itemlist[
            @item{Pick any ``Instance Name'' you wish}
436
	]
437

438 439 440 441
	@screenshot["tutorial/os-launch-source.png"]
	
	@itemlist[
            @item{For the ``Image Name'', select ``trusty-server''}
442

443 444
            @item{For the ``Instance Boot Source'', select ``Boot from
                image''}
445
	]
446

447 448 449
        @bold{Important:} If you do not see any available images,
        the image import script may not have finished yet; wait a few
        minutes, reload the page, and try again. 
450

451 452 453 454 455 456 457 458
	@screenshot["tutorial/os-launch-flavor.png"]

	@itemlist[
            @item{Set the ``Flavor'' to @tt{m1.small}---the disk for the
                default @tt{m1.tiny} instance is too small for the image we
                will be using, and since we have only one compute node, we
                want to avoid using up too many of its resources.}
        ]
459 460 461 462 463
    }

    @instructionstep["Add a Network to the Instance"
                     #:screenshot "tutorial/os-launch-net.png"]{
        In order to be able to access your instance, you will need to give
464
        it a network. On the ``Networking'' tab, add the @tt{tun0-net}
465 466 467 468
        to the list of selected networks by clicking the ``+'' button or
        dragging it up to the blue region. This will set up an internal
        tunneled connection within your cloud; later, we will assign a public
        IP address to it.
469

470
        @margin-note{The @tt{tun0-net} consists of EGRE tunnels on the @(tb)
471 472 473
        experiment network.}

        @bold{Important:} If you are missing the Networking tab, you may have
474 475 476
        logged into the OpenStack web interface before all services were
        started.  Unfortunately, reloading does not solve this, you will need
        to log out and back in.
477
    }
478 479

    @instructionstep["Set an SSH Keypair"
480
                     #:screenshot "tutorial/os-launch-finish.png"]{
481 482 483 484 485 486 487 488 489 490 491 492 493 494 495
        On the ``Key Pair'' tab (or ``Access & Security'' in previous versions), you will add an @(ssh) keypair
        to log into your node. If you configured an @(ssh) key in your GENI
        account, you should find it as one of the options in this
        list. You can filter the list by typing your Cloudlab username,
        or a portion of it, into the filter box to reduce the size of
        the list.  (By default, we load in public keys for all users in the
        project in which you created your experiment, for convenience --
        thus the list can be long.)  If you don't see your keypair,
	you can add a new one with the red button to the right of the
        list. Alternately, you
        can skip this step and use a password for login later.
    }
    
    @instructionstep["Launch, and Wait For Your Instance to Boot"]{
        Click the ``Launch'' button on the ``Key Pair'' wizard page, and wait for the status on the
496 497 498
        instances page to show up as ``Active''. 
    }

499 500 501 502
    @instructionstep["Add a Public IP Address"]{

        @screenshot["tutorial/os-launch-associate.png"]

503 504 505 506 507 508 509
        At this point, your instance is up, but it has no connection to the
        public Internet. From the menu on the right, select ``Associate
        Floating IP''.

        @margin-note{Profiles may request to have public IP addresses allocated
        to them; this profile requests four (two of which are used by OpenStack
        itself.)}
510

511
        On the following screen, you will need to:
512

513
        @itemlist[#:style 'ordered
514

515
            @item{Press the red button to set up a new IP address}
516 517 518 519 520 521 522 523

            @item{Click the ``Allocate IP'' button---this allocates a new
            address for you from the public pool available to your cloud.}

            @item{Click the ``Associate'' button---this associates the
            newly-allocated address with this instance.}
        ]

524 525 526 527 528 529
        @margin-note{The public address is tunneled by the @tt{ctl}
        (controller) node from the control network to the experiment network.
	(In older OpenStack profile versions, or depending the profile
        parameters specified to the current profile version, the public
        address may instead be tunneled by the @tt{nm} (network manager) node,
        in a split controller/network manager OpenStack deployment.)}
530 531

        You will now see your instance's public address on the ``Instances''
532 533
        page, and should be able to ping this address from your laptop or
        desktop.
534

535
        @screenshot["tutorial/os-instance-publicip.png"]
536 537 538

    }

539
    @instructionstep["Log in to Your Instance"]{
540 541 542 543 544
        You can @(ssh) to this IP address. Use the username @bold{ubuntu};  if you provided a public key
        earlier, use your private @(ssh) key to connect. If you did not set up
        an @(ssh) key, use the same password you used to log in to the OpenStack
        web interface (shown in the profile instructions.) Run a few commands to
        check out the VM you have launched.
545 546
    }
]
547 548 549

@section{Administering OpenStack}

550 551 552 553
Now that you've done some basic tasks in OpenStack, we'll do a few things
that you would not be able to do as a user of someone else's OpenStack
installation. These just scratch the surface---you can upgrade, downgrade,
modify or replace any piece of your own copy of OpenStack.
554

555
@subsection{Log Into The Control Nodes}
556

557 558
If you want to watch what's going on with your copy of OpenStack, you can use
@(ssh) to log into any of the hosts as described above in the
559
@secref["openstack-tutorial-list-view"] or @secref["openstack-tutorial-web-shell"] sections. Don't
560 561
be shy about viewing or modifying things; no one else is using your cloud,
and if you break this one, you can easily get another.
562

563 564 565
Some things to try:

@itemlist[
566
    @item{Run @tt{ps -ef} on the @tt{ctl} to see the list of OpenStack
567
        services running}
568 569
    @item{Run @tt{ifconfig} on the @tt{ctl} node (or the @tt{nm} node,
        if your experiment has one), to see the various
570 571
        bridges and tunnels that have been brought to support the networking in
        your cloud}
572
    @item{Run @tt{sudo virsh list @literal{--}all} on @tt{cp1} to see the VMs that
573 574 575
        are running}
]

576 577
@;{

578 579
@subsection{Create a New Network}

580 581 582
You can define a new network for instances in your cloud to connect to:

@itemlist[#:style 'ordered
583
    @instructionstep["Start the ``Create Network'' wizard"
584 585 586 587 588
                     #:screenshot "tutorial/os-networks.png"]{
        One the ``Project -> Networks'' page on the OpenStack Horizon
        interface, click ``Create Network.''
    }

589
    @instructionstep["Give your network a name"
590 591 592 593
                     #:screenshot "tutorial/os-network-name.png"]{
        Any name will do
    }

594
    @instructionstep["Create a subnet for your network"
595
                     #:screenshot "tutorial/os-network-subnet.png"]{
596 597 598
        Give the subnet any name you wish. In the ``Network Address'' field,
        put in a subnet definition (address/netmask). @tt{192.0.2.0/24} (the
        RFC 5737 TEST-NET-1) works well.
599

Robert Ricci's avatar
Robert Ricci committed
600
        @bold{Important:} This profile already uses all of the usual private
601 602 603
        (RFC 1918) address ranges (@tt{10.0.0.0/8}, @tt{192.168.0.0./16}, and
        @tt{172.16.0.0/12}) for other purposes, so you should not use them
        here.
604 605 606 607 608 609 610

        Leave the gateway information empty.
    }

    @instructionstep["Enable DHCP"
                     #:screenshot "tutorial/os-network-dhcp.png"]{

Robert Ricci's avatar
Robert Ricci committed
611
        On the final screen, make sure DHCP is enabled, and click the
612 613 614
        ``Create'' button.
    }

615
    @instructionstep["Use your new network"]{
616 617
        
        Follow the instructions from @secref["tutorial-instances"] to bring
618 619 620
        up two new instances. During the launch process, when you get to
        step of adding networks to your new instances, this time you will
        connect them to two networks: connect your instances to 
621
        @tt{tun-data-net} as before, but also connect them to the new network
622
        that you just created.
623

624 625 626 627
        @bold{Important:} This profile only has two available floating IP
        addresses. If one of them is still associated with your earlier
        instance, only one of these new instances will be able to have a public
        IP address.
628

629 630 631 632
        Log in to one of your instances: you should be able to see this new
        network interface with @tt{ifconfig}, and to @tt{ping} the other node
        across it. You can find the addresses that were assigned to each node
        on the ``Instances'' page of the OpenStack interface.
633 634 635 636
    }

]

637 638
}

639
@subsection{Reboot the Compute Node}
640

641
Since you have this cloud to yourself, you can do things like reboot or
642
re-image nodes whenever you wish. We'll reboot the @tt{cp1} (compute) node and
643 644 645
watch it through the serial console.

@itemlist[#:style 'ordered
646
    @instructionstep["Open the serial console for cp1"]{
647
        On your experiment's @(tb) status page, use the action menu as
648
        described in @secref["openstack-tutorial-actions"] to launch the console.
649 650
        Remember that you may have to click to focus the console window and hit
        enter a few times to see activity on the console.
651 652
    }
    
653 654
    @instructionstep["Reboot the node"]{
        On your experiment's @(tb) status page, use the action menu as
655
        described in @secref["openstack-tutorial-actions"] to reboot @tt{cp1}. Note
656
        that in the topology display, the box around @tt{cp1} will turn
657
        yellow while it is rebooting, then green again when it has booted.
658 659
    }

660
    @instructionstep["Watch the node boot on the console"
661 662 663 664 665
                     #:screenshot "tutorial/reboot-console.png"]{
        Switch back to the console tab you opened earlier, and you
        should see the node starting its reboot process.
    }

666 667
    @instructionstep["Check the node status in OpenStack"]{

668
        You can also watch the node's status from the OpenStack Horizon
669
        web interface. In Horizon, select ``Hypervisors'' under the ``System''
670 671 672 673 674 675 676 677
        menu, and switch to the ``Compute Host'' tab.

        @screenshot["tutorial/os-node-down.png"]

        @bold{Note:} This display can take a few minutes to notice that the
        node has gone down, and to notice when it comes back up. Your instances
        will not come back up automatically; you can bring them up with a
        ``Hard Reboot'' from the ``Admin -> System ->Instances'' page.
678 679 680
    }
]

681 682
@section{Terminating the Experiment}

683
Resources that you hold in @(tb) are real, physical machines and are
684 685 686
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.
687

688
@screenshot["tutorial/status-terminate.png"]
689

690
@bold{Note:} When you terminate an experiment, all data on the nodes is lost,
691
so make sure to copy off any data you may need before terminating.
692

693 694 695 696 697
If you were doing a real experiment, you might need to hold onto the nodes for
longer than the default expiration time. You would request more time by using
the ``Extend'' button the on the status page. You would need to provide a
written justification for holding onto your resources for a longer period of
time.
698

699
@section{Taking Next Steps}
700

701
Now that you've got a feel for for what @(tb) can do, there are several
702
things you might try next:
703

704
@itemlist[
705 706
    @item{@seclink["create-project"]{Create a new project} to continue working
    on @(tb) past this tutorial}
707 708 709 710 711 712 713 714
    @item{Try out some profiles other than OpenStack (use the ``Change
        Profile'' button on the ``Start Experiment'' page)}
    @item{Read more about the @seclink["basic-concepts"]{basic concepts} in
        @(tb)}
    @item{Try out different @seclink["hardware"]{hardware}}
    @item{Learn how to @seclink["creating-profiles"]{make your own profiles}}

]