cloudlab-tutorial.scrbl 32 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 @(tb) using a GENI portal account}
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 31
@section{Prerequisites}

This tutorial assumes that:

@itemlist[
    @item{You have an existing account on  the
32
        @link["https://portal.geni.net"]{GENI portal}. (Instructions for
33
        getting an account can be found
34
        @link["http://groups.geni.net/geni/wiki/SignMeUp"]{here}.)}
35
    @item{You have set up an @(ssh) keypair in your GENI portal
36 37 38
        account. (When logged into the GENI portal, you can add a public key
        under ``Profile -> SSH Keys''.)}
    @item{You have an @(ssh) client set up to use that keypair.}
39 40
]

41 42
@section{Logging In}

43 44 45 46
The first step is to log in to @(tb); @(tb) is available to all
researchers and educators who work in cloud computing. If you have
an account at one of its federated facilities, like @link["http://geni.net"]{GENI},
then you already have an account at @(tb).
47

48 49
@margin-note{This document assumes that you will log in using an existing
    @seclink["geni-users"]{GENI account}. If you want to use a different
50 51 52
    account, or need to apply for one, see the @seclink["users"]{chapter about
    user accounts}.}

53 54
@itemlist[#:style 'ordered

55
    @instructionstep["Open the CloudLab web interface"
56
                     #:screenshot "tutorial/front-page.png"]{
57
        To log in to @(tb) using a GENI account, start by visiting
58 59 60 61
        @url{https://www.cloudlab.us/} in your browser and using the ``Log In''
        button in the upper right.
    }

62
    @instructionstep["Click the \"GENI User\" button"
63 64 65
                     #:screenshot "tutorial/login-page.png"]{
        On the login page that appears, you will use the ``GENI User'' button.
        This will start the GENI authorization tool, which lets you connect
66
        your GENI account with @(tb). 
67 68 69 70
    }

    @instructionstep["Select the GENI portal"
                     #:screenshot "tutorial/authorization-tool.png"]{
71 72 73 74
        You will be asked which facility your account is with. Select the GENI
        icon, which will take you to the GENI portal. There are several other
        facilities that are federated with @(tb), which can be found in the
        drop-down list. 
75 76 77 78
    }

    @instructionstep["Log into the GENI portal"
                     #:screenshot "tutorial/geni-login.png"]{
79 80 81 82 83 84 85 86 87
        You will be taken to the GENI portal, and will need to select the
        institution that is your identity provider. Usually, this is the
        university you are affiliated with. If your university is not in
        the list, you may need to log in using the ``GENI Project Office''
        identity provider. If you have ever logged in to the GENI portal
        before, your identity provider should be pre-selected; if you
        are not familiar with this login page, there is a good chance that
        you don't have a GENI account and need to 
        @link["http://groups.geni.net/geni/wiki/SignMeUp"]{apply for one}.
88 89 90 91 92
    }

    @instructionstep["Log into your institution"
                     #:screenshot "tutorial/utah-login.png"]{
        This will bring you to your institution's standard login page, which you
Robert Ricci's avatar
Robert Ricci committed
93
        likely use to access many on-campus services. (Yours will look different
94 95 96
        from this one.)
    }

97
    @instructionstep["Authorize CloudLab to use your GENI account"]{
98
        @margin-note{What's happening in this step is that your browser
Robert Ricci's avatar
Robert Ricci committed
99
        uses your GENI user certificate (which it obtained from the GENI
100 101
        portal) to cryptographically sign a
        @link["http://groups.geni.net/geni/wiki/GAPI_AM_API_DRAFT/SpeaksFor"]{``speaks-for'' credential }
102 103 104
        that authorizes the @(tb) portal to make
        @link["http://groups.geni.net/geni/wiki/GeniApi"]{GENI API calls}
        on your behalf.}
105
        Click the ``Authorize'' button: this will create a signed statement
106
        authorizing the @(tb) portal to speak on your behalf. This
107
        authorization is time-limited (see ``Show Advanced'' for the details),
108
        and all actions the @(tb) portal takes on your behalf are clearly
109
        traceable.
110

111 112
        @screenshot["tutorial/authorize.png"]

113 114
    }

115

116
    @instructionstep["Set up an SSH keypair in the GENI portal"
117 118 119 120
                     #:screenshot "tutorial/portal-keypair.png"]{
        Though not strictly required, many parts of this tutorial will
        work better if you have an @(ssh) public key associated with your
        GENI Portal account. To upload one, visit
Robert Ricci's avatar
Robert Ricci committed
121
        @link["http://portal.geni.net"]{portal.geni.net} and to the
122 123 124 125
        ``Profile'' page, ``SSH Keys'' tab.

        If you are not familiar with @(ssh) keys, you may skip this step. You
        may find
126 127 128
        @link["https://help.github.com/articles/generating-ssh-keys/"]{GitHub's
        @(ssh) key page} helpful in learning how to generate and use them.
    }
129
]
130

131

132 133
@section{Building Your Own OpenStack Cloud}

134

135
Once you have logged in to @(tb), you will ``instantiate'' a @secref["profiles"]{``profile''}
136 137 138
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
139 140
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
141 142 143
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.
144

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

Robert Ricci's avatar
Robert Ricci committed
149
For this tutorial, we will use a basic profile that brings up a small OpenStack
150 151 152 153 154 155
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.
156 157


158
@itemlist[#:style 'ordered
159 160 161
    @instructionstep["Select a profile"]{

        @screenshot["tutorial/start-experiment.png"]
162 163 164 165 166 167 168 169

        @margin-note{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.}

        The ``Start an Experiment'' page is where you will select a profile
170 171
        to instantiate. We will use the @bold{Tutorial-OpenStack} profile; if
        it is not selected, follow
172
        @link["https://cloudlab.us/p/CloudLab/Tutorial-OpenStack"]{this link}
173 174
        or click the ``Change Profile'' button, and select
        ``Tutorial-OpenStack'' from the list on the left.
175 176 177 178

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

        @screenshot["tutorial/click-next.png"]
179 180
    }

181
    @instructionstep["Select a cluster"
182
                     #:screenshot "tutorial/pick-cluster.png"]{
183
        @(tb) has multiple clusters available to it. Some profiles can run
184
        on any cluster, some can only run on specific ones due to specific hardware
185 186 187 188
        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
189
        cluster; the ``cluster status'' link on this page can be used to check
190
        which clusters have available resources.
191 192 193 194 195 196

        @margin-note{The ``Check Cluster Status'' link opens a page (in a new
        tab) showing the current utilization of all @(tb) clusters---this can
        be useful for finding a cluster that has enough free machines for your
        experiment.}

197
    }
198

199
    @instructionstep["Click Finish!"
200
                     #:screenshot "tutorial/click-create.png"]{
201
        When you click the ``finish'' button, @(tb) will start
202 203
        provisioning the resources that you requested on the cluster that
        you selected.
204 205 206 207

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

208 209
    }

210
    @instructionstep["CloudLab instantiates your profile"]{
211
        @(tb) will take a few minutes to bring up your copy of OpenStack, as
212 213
        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
214
        machines, re-configuring the network topology, etc. While this is
215 216 217 218 219 220 221 222 223 224 225 226 227 228 229
        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
        call these provisioning APIs from their own code.}


        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
230
        @link["http://docs.cloudlab.us"]{@(tb)
231 232
        user manual}, or use the ``Sliver'' button to watch the logs of the
        resources (``slivers'') being provisioned and booting.
233 234
    }

235
    @instructionstep["Your cloud is ready!"
236 237
                     #:screenshot "tutorial/status-ready.png"]{
         When the web interface reports the state as ``Ready'', your cloud
238 239 240 241 242
         is provisioned, and you can proceed to the next section.

         @bold{Important:} A ``Ready'' status indicates that resources are
         provisioned and booted; this particular profile runs scripts to
         complete the OpenStack setup, and it will be a few more minutes before
243 244 245 246
         OpenStack is fully ready to log in and create virtual machine
         instances. For now, don't attempt to log in to OpenStack, we will
         explore the CloudLab experiment first.

247 248 249
    }

]
250

251
@section{Exploring Your Experiment}
252

253
Now that your experiment is ready, take a few minutes to look at various parts
254
of the @(tb) status page to help you understand what resources you've got and what
255 256 257 258
you can do with them.

@subsection{Experiment Status}

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

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

267
Note that the default lifetime for experiments on @(tb) is less than a day;
268
after this time, the resources will be reclaimed and their disk contents will
269
be lost. If you need to use them for longer, you can use the ``Extend'' button
270
and provide a description of why they are needed. Longer extensions require
271
higher levels of approval from @(tb) staff. You might also consider
272
@seclink["creating-profiles"]{creating a profile} of your own if you might need
273 274 275 276 277 278 279 280 281 282
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
283
OpenStack, and give you passwords to use to log in. (Don't log into OpenStack
284
yet---for now, let's keep exploring the @(tb) interface.)
285 286 287 288 289

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

@subsection{Topology View}

Robert Ricci's avatar
Robert Ricci committed
290
At the bottom of the page, you can see the topology of your experiment. This
291
profile has three nodes connected by a 10 Gigabit LAN, which is represented by
292 293 294 295 296 297 298 299
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"]
300

301
It is important to note that every node in @(tb) has at least @italic{two}
302
network interfaces: one ``control network'' that carries public IP
303 304 305 306 307 308
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}.
309 310


Robert Ricci's avatar
Robert Ricci committed
311
@subsection[#:tag "tutorial-list-view"]{List View}
312

Robert Ricci's avatar
Robert Ricci committed
313
The list view tab shows similar information to the topology view, but in a
314 315 316 317 318 319 320 321
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.
322

323
@screenshot["tutorial/experiment-list.png"]
324

325
@subsection{Manifest View}
326 327

The final default tab shows a
328
@link["http://groups.geni.net/geni/wiki/GENIExperimenter/RSpecs#ManifestRSpec"]{manifest} detailing the hardware that has been assigned to you. This is the
329 330 331
@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
332
@link["http://groups.geni.net/geni/wiki/GeniGet"]{@tt{geni-get}} command, 
333
enabling you to do rich scripting that is fully aware of both the requested
334
topology and assigned resources.
335

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

339
@screenshot["tutorial/experiment-manifest.png"]
340

341
@subsection[#:tag "tutorial-actions"]{Actions}
342 343

In both the topology and list views, you have access to several actions that
344
you may take on individual nodes. In the topology view, click on the node to
345
access this menu; in the list view, it is accessed through the icon in the
346 347 348 349 350 351 352
``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
become green again. The @seclink["tutorial-web-shell"]{shell} and
@seclink["tutorial-console"]{console} actions are described in more detail
below.
353

354
@screenshot["tutorial/experiment-actions.png"]
355

Robert Ricci's avatar
Robert Ricci committed
356
@subsection[#:tag "tutorial-web-shell"]{Web-based Shell}
357

358
@(tb) provides a browser-based shell for logging into your nodes, which is
359 360 361
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
362
and @(ssh) program.
363

364
This shell can be used even if you did not establish an @(ssh) keypair with
365 366 367 368 369 370 371 372
your account.

Two things of note:

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

373 374 375
    @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.}
376 377
]

378
@screenshot["tutorial/experiment-shell.png"]
379

380
@subsection[#:tag "tutorial-console"]{Serial Console}
381

382
@(tb) provides serial console access for all nodes, which can be used
383
in the event that normal IP or @(ssh) access gets intentionally or
Robert Ricci's avatar
Robert Ricci committed
384
unintentionally broken. Like the browser-based shell, it is launched through
385
the access menu, and the same caveats listed above apply as well. In addition:
386 387 388 389 390 391

@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.}

392 393 394 395
    @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.}
396 397
]

398
@screenshot["tutorial/experiment-console.png"]
399

400
@section[#:tag "tutorial-instances"]{Bringing up Instances in OpenStack}
401 402 403 404 405

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
406 407
bringing up a new VM instance in your cloud.

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

Robert Ricci's avatar
Robert Ricci committed
412 413
@itemlist[#:style 'ordered

414 415 416 417 418 419 420 421 422 423 424 425 426 427 428 429 430 431 432 433 434
    @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
        scripts are probably done. You can be sure by checking:

         @itemlist[
            @item{The setup script will attempt to send mail to the addresses
                associated with your GENI portal account when it is finished.
                We find, however, that this mail often gets caught by spam
                filters.}

            @item{You can watch the setup log by logging into the @tt{controller}
                node via @(ssh) (either a traditional @(ssh) client, or the
                @seclink["tutorial-web-shell"]{web-based shell} described
                above), and running
435 436 437
                @tt{sudo tail -F /root/setup/setup-controller.log} . When
                this process is finished, the final message will be something
                like @tt{Your OpenStack instance has completed setup!}
438 439 440 441 442 443 444 445 446 447
            }

         ]

         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.
    }

448
    @instructionstep["Visit the OpenStack Horizon web interface"
449 450 451
                     #:screenshot "tutorial/experiment-instructions.png"]{
        On the status page for your experiment, in the ``Instructions''
        panel (click to expand it if it's collapsed), you'll find a link
Robert Ricci's avatar
Robert Ricci committed
452
        to the web interface running on the @tt{controller} node. Open this
453
        link (we recommend opening it in a new tab, since you will still
454
        need information from the @(tb) web interface). 
455 456
    }

457
    @instructionstep["Log in to the OpenStack web interface"
458 459 460 461
                     #:screenshot "tutorial/os-login.png"]{
        Log in using the username @tt{admin} and the password shown in 
        the instructions for the profile.

462 463 464
        @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
465
        working properly.
466 467
    }

468
    @instructionstep["Launch a new VM instance"
469 470 471 472 473
                     #:screenshot "tutorial/os-launch.png"]{
        Click the ``Launch Instance'' button on the ``Instances'' page of the
        web interface.
    }

474
    @instructionstep["Set Basic Settings For the Instance"]{
475 476 477 478

        There a few settings you will need to make in order to launch your
        instance:

479 480
        @screenshot["tutorial/os-launch-basic.png"]

481 482
        @itemlist[
            @item{Pick any ``Instance Name'' you wish}
483

484 485 486 487
            @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.}
488

489 490
            @item{For the ``Instance Boot Source'', select ``Boot from
                image''}
491

492 493
            @item{For the ``Image Name'', select ``trusty-server''}
        ]
494

495 496 497
        @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. 
498 499
    }

500
    @instructionstep["Set an SSH Keypair"
501
                     #:screenshot "tutorial/os-launch-key.png"]{
Robert Ricci's avatar
Robert Ricci committed
502
        On the ``Access & Security'' tab, you will add an @(ssh) keypair
503 504 505 506 507 508 509 510 511
        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. If
        not, you can add a new keypair with the ``+'' button. Alternately, you
        can skip this step and use a password for login later.
    }

    @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
512
        it a network. On the ``Networking'' tab, add the @tt{tun-data-net}
513 514 515 516
        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.
517 518 519 520 521

        @margin-note{The @tt{tun-data-net} consists of EGRE tunnels on the @(tb)
        experiment network.}

        @bold{Important:} If you are missing the Networking tab, you may have
522 523 524
        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.
525 526 527 528 529 530 531 532
    }
    
    @instructionstep["Launch, and Wait For Your Instance to Boot"
                     #:screenshot "tutorial/os-launch-finish.png"]{
        Click the ``Launch'' button, and wait for the status on the
        instances page to show up as ``Active''. 
    }

533 534 535 536
    @instructionstep["Add a Public IP Address"]{

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

537 538 539 540 541 542 543
        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.)}
544

545
        On the following screen, you will need to:
546

547
        @itemlist[#:style 'ordered
548

549 550 551 552 553 554 555 556 557 558 559
            @item{Press the ``+'' button to set up a new IP address}

            @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.}
        ]

        @margin-note{The public address is tunneled by the @tt{networkmanager} node
        from the control network to the experiment network.}
560 561

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

565
        @screenshot["tutorial/os-instance-publicip.png"]
566 567 568

    }

569 570
    @instructionstep["Log in to Your Instance"]{
        You can @(ssh) to this IP address.  If you provided a public key
571 572 573 574
        earlier, use the username @bold{ubuntu} and your private @(ssh) key. If
        you did not set up an @(ssh) key, use the username @bold{root} and the
        password shown in the profile instructions. Run a few commands to check
        out the VM you have launched.
575 576
    }
]
577 578 579

@section{Administering OpenStack}

580 581 582 583
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.
584

585
@subsection{Log Into The Control Nodes}
586

587 588 589 590 591
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
@secref["tutorial-list-view"] or @secref["tutorial-web-shell"] sections. Don't
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.
592

593 594 595 596 597 598 599 600
Some things to try:

@itemlist[
    @item{Run @tt{ps -ef} on the @tt{controller} to see the list of OpenStack
        services running}
    @item{Run @tt{ifconfig} on the @tt{networkmanager} to see the various
        bridges and tunnels that have been brought to support the networking in
        your cloud}
601
    @item{Run @tt{sudo virsh list @literal{--}all} on @tt{compute1} to see the VMs that
602 603 604
        are running}
]

605 606
@;{

607 608
@subsection{Create a New Network}

609 610 611
You can define a new network for instances in your cloud to connect to:

@itemlist[#:style 'ordered
612
    @instructionstep["Start the ``Create Network'' wizard"
613 614 615 616 617
                     #:screenshot "tutorial/os-networks.png"]{
        One the ``Project -> Networks'' page on the OpenStack Horizon
        interface, click ``Create Network.''
    }

618
    @instructionstep["Give your network a name"
619 620 621 622
                     #:screenshot "tutorial/os-network-name.png"]{
        Any name will do
    }

623
    @instructionstep["Create a subnet for your network"
624
                     #:screenshot "tutorial/os-network-subnet.png"]{
625 626 627
        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.
628

Robert Ricci's avatar
Robert Ricci committed
629
        @bold{Important:} This profile already uses all of the usual private
630 631 632
        (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.
633 634 635 636 637 638 639

        Leave the gateway information empty.
    }

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

Robert Ricci's avatar
Robert Ricci committed
640
        On the final screen, make sure DHCP is enabled, and click the
641 642 643
        ``Create'' button.
    }

644
    @instructionstep["Use your new network"]{
645 646
        
        Follow the instructions from @secref["tutorial-instances"] to bring
647 648 649
        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 
650
        @tt{tun-data-net} as before, but also connect them to the new network
651
        that you just created.
652

653 654 655 656
        @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.
657

658 659 660 661
        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.
662 663 664 665
    }

]

666 667
}

668
@subsection{Reboot the Compute Node}
669

670 671 672 673 674
Since you have this cloud to yourself, you can do things like reboot or
re-image nodes whenever you wish. We'll reboot the @tt{compute1} node and
watch it through the serial console.

@itemlist[#:style 'ordered
675 676 677 678 679
    @instructionstep["Open the serial console for compute1"]{
        On your experiment's @(tb) status page, use the action menu as
        described in @secref["tutorial-actions"] to launch the console.
        Remember that you may have to click to focus the console window and hit
        enter a few times to see activity on the console.
680 681
    }
    
682 683 684 685 686
    @instructionstep["Reboot the node"]{
        On your experiment's @(tb) status page, use the action menu as
        described in @secref["tutorial-actions"] to reboot @tt{compute1}. Note
        that in the topology display, the box around @tt{compute1} will turn
        yellow while it is rebooting, then green again when it has booted.
687 688
    }

689
    @instructionstep["Watch the node boot on the console"
690 691 692 693 694
                     #:screenshot "tutorial/reboot-console.png"]{
        Switch back to the console tab you opened earlier, and you
        should see the node starting its reboot process.
    }

695 696
    @instructionstep["Check the node status in OpenStack"]{

697 698
        You can also watch the node's status from the OpenStack Horizon
        web interface. In Horizon, select ``Hypervisors'' under the ``Admin''
699 700 701 702 703 704 705 706
        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.
707 708 709
    }
]

710 711
@section{Terminating the Experiment}

712
Resources that you hold in @(tb) are real, physical machines and are
713 714 715
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.
716

717
@screenshot["tutorial/status-terminate.png"]
718

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

722 723 724 725 726
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.
727

728
@section{Taking Next Steps}
729

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

733
@itemlist[
734 735
    @item{@seclink["create-project"]{Create a new project} to continue working
    on @(tb) past this tutorial}
736 737 738 739 740 741 742 743
    @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}}

]