Browse Source

Added instructions to build images and cleaned up trailing whitespace

Change-Id: I6bd8b020025159181c3b920c5e48381c5dbe5769
Scott Daniels 5 years ago
parent
commit
e6bef98990
2 changed files with 116 additions and 96 deletions
  1. 61
    42
      doc/source/ic_user/prep.tex
  2. 55
    54
      doc/source/ic_user/running.tex

+ 61
- 42
doc/source/ic_user/prep.tex View File

@@ -1,27 +1,28 @@
1 1
 \section{Preparation}
2
-To prepare the workstation and the virtual environment to start an inception cloud, the tasks listed below, and 
3
-explained in more detail in subsequent sections,  must first be performed. 
4
-All of these should be done on the workstation or from the workstation browser via the OpenStack dashboard or the 
5
-Nova client CLI. 
2
+To prepare the workstation and the virtual environment to start an inception cloud, the tasks listed below, and
3
+explained in more detail in subsequent sections,  must first be performed.
4
+All of these should be done on the workstation or from the workstation browser via the OpenStack dashboard or the
5
+Nova client CLI.
6 6
 
7 7
 \begin{enumerate}
8 8
 \item Install software
9 9
 \item Set environment variables
10 10
 \item Create keys
11 11
 \item Start small boot-up VM
12
+\item Create Images
12 13
 \item Add floating IP to the VM
13 14
 \item Start \verb!sshuttle!
14 15
 \end{enumerate}
15 16
 
16
-\subsubsection{Install Software}
17
-Some or all of the required software might already be installed. 
17
+\subsection{Install Software}
18
+Some or all of the required software might already be installed.
18 19
 Verify that the correct versions of each of the software packages are available on the workstation
19
-and take steps to upgrade or load the missing packages as is needed.  
20
+and take steps to upgrade or load the missing packages as is needed.
20 21
 The flavour of Linux installed on your workstation will dictate the exact commands (e.g. apt-get or zypper)
21
-that are needed to load and\/or upgrade Python, sshuttle, and pip. 
22
-Pip can then be used to install Nova and Oslo. 
23
-Examples of each of the commands that might be needed to manage the required software packages are presented 
24
-in Appendix A. 
22
+that are needed to load and\/or upgrade Python, sshuttle, and pip.
23
+Pip can then be used to install Nova and Oslo.
24
+Examples of each of the commands that might be needed to manage the required software packages are presented
25
+in Appendix A.
25 26
 
26 27
 \subsubsection{Inception source}
27 28
 The source for inception is available from github.
@@ -31,19 +32,19 @@ The command below will fetch the inception source and place it in a directory un
31 32
    git clone https://github.com/stackforge/inception.git
32 33
 \end{verbatim}\normalsize
33 34
 
34
-Following the execution of the \verb!git! command, switch to the inception directory and verify that the 
35
-directory was populated.  
36
-Inception may be installed, or used from this directory.  
35
+Following the execution of the \verb!git! command, switch to the inception directory and verify that the
36
+directory was populated.
37
+Inception may be installed, or used from this directory.
37 38
 If the decision is made to install inception, the following command should be used:
38 39
 
39 40
 \small\begin{verbatim}
40 41
    python setup.py install
41 42
 \end{verbatim}\normalsize
42 43
 
43
-\subsubsection{Set Environment Variables}
44
-Ensure that the environment variables which define the authorisation URL and credentials for OpenStack are set and exported. 
44
+\subsection{Set Environment Variables}
45
+Ensure that the environment variables which define the authorisation URL and credentials for OpenStack are set and exported.
45 46
 OpenStack credentials can be obtained using the OpenStack dashboard interface and following these steps:
46
-\label{set_env_sect} 
47
+\label{set_env_sect}
47 48
 %
48 49
 \begin{enumerate}
49 50
 \item Log into the dashboard
@@ -53,7 +54,7 @@ OpenStack credentials can be obtained using the OpenStack dashboard interface an
53 54
 \end{enumerate}
54 55
 %&uindent
55 56
 %
56
-Once the file has been saved to disk you can source the file (the assumption is made that the 
57
+Once the file has been saved to disk you can source the file (the assumption is made that the
57 58
 shell being used is bash compatible).
58 59
 Sourcing the file should prompt for a password, and then export the following variables to the environment:
59 60
 
@@ -70,10 +71,10 @@ Sourcing the file should prompt for a password, and then export the following va
70 71
 \dlitem{OS\_USERNAME}{ Your user name.}
71 72
 \dlend
72 73
 
73
-\subsubsection{Create Keys}
74
+\subsection{Create Keys}
74 75
 Create (if needed) a public/private key pair and register it with OpenStack.   If you do not have a key pair, generate one using
75
-nova. (I prefer to name these with the OpenStack cluster/environment name, and then the key name with an extension that 
76
-indicates private key: agave.scooter.pk.) 
76
+nova. (I prefer to name these with the OpenStack cluster/environment name, and then the key name with an extension that
77
+indicates private key: agave.scooter.pk.)
77 78
 
78 79
 \small\begin{verbatim}
79 80
    touch agave.scooter.pk
@@ -82,8 +83,8 @@ indicates private key: agave.scooter.pk.)
82 83
 \end{verbatim}\normalsize
83 84
 
84 85
 The commands above will create the key, write it to disk and register the public key with OpenStack.
85
-Executing the \verb!touch! and \verb!chmod! commands prior to generating the key adds a bit of security which prevents the exposure of the key 
86
-which results if the permissions on the key file are changed after it is generated. 
86
+Executing the \verb!touch! and \verb!chmod! commands prior to generating the key adds a bit of security which prevents the exposure of the key
87
+which results if the permissions on the key file are changed after it is generated.
87 88
 Regardless of when the permissions are changed, they will need to be changed in order for the file to recognised and used by ssh.
88 89
 
89 90
 If you already have a private key (one that several users might share) then a public key can be generated from the private key and registered with OpenStack:
@@ -94,53 +95,71 @@ If you already have a private key (one that several users might share) then a pu
94 95
 
95 96
 \end{verbatim}\normalsize
96 97
 
97
-If you have both a public and private key file, then the \verb!ssh-keygen! command can be skipped; it is only necessary to supply the existing public key to 
98
-OpenStack using the nova command line. 
98
+If you have both a public and private key file, then the \verb!ssh-keygen! command can be skipped; it is only necessary to supply the existing public key to
99
+OpenStack using the nova command line.
99 100
 
100
-\subsubsection{Start Tiny Boot-up VM}
101
-Create and initialise a tiny VM that will act as the initial gateway to the virtual environment for processes running on the workstation.
102
-For the examples used in the remainder of this document, the boot-up VM is given the name \verb!scooter_bv.! 
103
-The VM should be started with the key that was registered with OpenStack. 
101
+\subsection{Start Boot-up VM}
102
+Create and initialise a tiny\footnote{If you are going to need to create OS images during setup, use a meidum VM.}
103
+VM that will act as the initial gateway to the virtual environment for processes running on the workstation.
104
+For the examples used in the remainder of this document, the boot-up VM is given the name \verb!scooter_bv.!
105
+The VM should be started with the key that was registered with OpenStack.
104 106
 
105 107
 \small\begin{verbatim}
106 108
    nova boot --image centos --flavor m1.tiny --key_name shared \
107 109
        --security_groups default scooter_bv
108
-}
109 110
 \end{verbatim}\normalsize
110 111
 
111 112
 \noindent
112 113
 The VM should boot quickly and once it is active you may continue.
113 114
 
114
-\subsubsection{Add A Floating IP Address}
115
+\subsection{Create O/S Images}
116
+If suitable inception cloud images are not already available in the current virtual environment, they must be created.
117
+The following lists the steps necessary to create the O/S images:
118
+
119
+\begin{enumerate}
120
+	\item Ssh to the boot-up VM.
121
+	\item Copy inception utility scripts from the source installed on the workstation.
122
+	\item Run the script \verb!pre_switch_kernel.sh! to convert from a vertual kernel to a generic kernel.
123
+	\item Wait for the VM to reboot and log in again.
124
+	\item Run the script \verb!pre_install_ovs.sh! to install open vswitch.
125
+	\item Using nova, or the dashboard, take a snapshot of the VM giving it an image name of XXX-gv.
126
+	\item Run the script \verb!pre_install_chefserver.sh! to install the Chef software.
127
+	\item Create another image naming it XXX-gvc.
128
+\end{enumerate}
129
+
130
+Image names (shown as XXX in the above list), can be anything that aligns with local policy and are used
131
+with the \verb!--image! and \verb!--chefserver_image! options on the \verb!orcehestrator! command line.
132
+
133
+\subsection{Add A Floating IP Address}
115 134
 Add a floating (public) IP address to the new VM so that it can be reached from the "real world."
116
-(xxx.xxx.xxx.xxx is one of the public floating IP addresses that are available; use \verb!nova floating-ip-list! 
135
+(xxx.xxx.xxx.xxx is one of the public floating IP addresses that are available; use \verb!nova floating-ip-list!
117 136
 to get a list of available addresses.
118 137
 
119 138
 \small\begin{verbatim}
120 139
    nova  add-floating-ip scooter_bv xxx.xxx.xxx.xxx
121 140
 \end{verbatim}\normalsize
122 141
 
123
-\subsubsection{Start sshuttle}
124
-The sshuttle programme creates a tunnel through ssh allowing programmes on the workstation to access VMs created on the 
125
-same internal network as the boot-up VM without having to assign each VM a public address. 
126
-The sshuttle command is given the private key portion of the key pair that was used to start the boot-up VM; this is 
142
+\subsection{Start sshuttle}
143
+The sshuttle programme creates a tunnel through ssh allowing programmes on the workstation to access VMs created on the
144
+same internal network as the boot-up VM without having to assign each VM a public address.
145
+The sshuttle command is given the private key portion of the key pair that was used to start the boot-up VM; this is
127 146
 necessary to allow sshuttle to start an ssh session through which the tunnel is created.
128 147
 The user name (ubuntu in the example below) is any user on the boot-up VM that is available and allows access via
129
-the key (the assumption is that OpenStack created this user, or it was a part of the saved imagee,  and the public key was 
148
+the key (the assumption is that OpenStack created this user, or it was a part of the saved imagee,  and the public key was
130 149
 inserted into the \verb!authorized_keys! file in the user's \verb!.ssh! directory.)
131 150
 
132 151
 \small\begin{verbatim}
133 152
    sshuttle -e ssh -A -i ~/.vmkeys/agave.shared.pk -v \
134
-      -r ubuntu@xxx.xxx.xxx.xxx 192.168.254.0/24 
153
+      -r ubuntu@xxx.xxx.xxx.xxx 192.168.254.0/24
135 154
 \end{verbatim}\normalsize
136 155
 
137 156
 \noindent
138 157
 The \verb!-v! option causes sshuttle to be more verbose with messages to the standard error device.
139
-Ultimately, redirecting the output of sshuttle to \verb!/dev/null! and running the process asynchronously, is probably 
140
-wise, but initially seeing the verbose messages scroll by in the window is a nice confirmation that the tunnel is active and data 
141
-is being transferred. 
158
+Ultimately, redirecting the output of sshuttle to \verb!/dev/null! and running the process asynchronously, is probably
159
+wise, but initially seeing the verbose messages scroll by in the window is a nice confirmation that the tunnel is active and data
160
+is being transferred.
142 161
 The \verb!xxx! IP address is the public floating IP address assigned earlier.  The second address (192.168.254.0 in the example)
143
-bb the virtual network that is created by OpenStack.  
162
+bb the virtual network that is created by OpenStack.
144 163
 If it is not known, the following command (with suitable path for the public key) might provide the address:
145 164
 
146 165
 \small\begin{verbatim}

+ 55
- 54
doc/source/ic_user/running.tex View File

@@ -1,22 +1,22 @@
1 1
 \section{Running Orchestrator}
2
-The \verb!orchestrator! command, located in the bin directory under the source that was fetched from github, 
3
-is used to start and stop an inception cloud. 
2
+The \verb!orchestrator! command, located in the bin directory under the source that was fetched from github,
3
+is used to start and stop an inception cloud.
4 4
 The inception cloud environment consists of at least 4 Inception Control VMs (ICVMs)  in the environment:
5 5
 
6 6
 %&indent
7 7
 \begin{itemize}
8
-\item A gateway machine that will be given a public IP address and function much in the same way as the 
9
-boot-up VM being used to start the cloud. 
8
+\item A gateway machine that will be given a public IP address and function much in the same way as the
9
+boot-up VM being used to start the cloud.
10 10
 
11
-\item A controller machine used to run the OpenStack software and to provide the OpenStack Dashboard interface. 
11
+\item A controller machine used to run the OpenStack software and to provide the OpenStack Dashboard interface.
12 12
 
13
-\item A chef machine used to manage Chef installation and configuration scripts. 
13
+\item A chef machine used to manage Chef installation and configuration scripts.
14 14
 
15
-\item One or more worker machines used to host the inception virtual machines (iVMs). 
15
+\item One or more worker machines used to host the inception virtual machines (iVMs).
16 16
 \end{itemize}
17 17
 
18 18
 \noindent
19
-The following sections describe how orchestrator is used. 
19
+The following sections describe how orchestrator is used.
20 20
 
21 21
 \begin{figure}
22 22
   \centering
@@ -29,40 +29,41 @@ The following sections describe how orchestrator is used.
29 29
 \end{figure}
30 30
 
31 31
 \subsection{Starting The Inception Cloud}
32
-The \verb!orchestrator! command is located in the \verb!bin! directory within the source cloned from github. 
33
-The bin directory can be added to the path, or the command can be executed with a fully qualified path.  
32
+The \verb!orchestrator! command is located in the \verb!bin! directory within the source cloned from github.
33
+The bin directory can be added to the path, or the command can be executed with a fully qualified path.
34 34
 It will probably be necessary to add the top level inception directory to the \verb!PYTHONPATH! environment variable
35
-if inception was not installed. 
35
+if inception was not installed.
36 36
 %.sp
37
-Using the \verb!--help! option will cause all of the possible command line options to be written to the tty device. 
38
-For the most part, at least for the first time user, only a few are needed and are described below. 
37
+Using the \verb!--help! option will cause all of the possible command line options to be written to the tty device.
38
+For the most part, at least for the first time user, only a few are needed and are described
39
+below. %\footnote{A complete list of orchestrator command line options are presented in an appendix}.
39 40
 
40 41
 \dlbeg{0.85in}
41
-\dlitem{-p prefix}{ 
42
-	This command line flag is required and supplies the prefix string that is used when defining the ICVM names. 
42
+\dlitem{-p prefix}{
43
+	This command line flag is required and supplies the prefix string that is used when defining the ICVM names.
43 44
 }
44 45
 
45 46
 \vspace{5pt}
46
-\dlitem{-n n}{ 
47
-	Specifies the number of work ICVMs that are created.  The iVMs which are created in the inception cloud are hosted 
48
-	on the work VMs thus the number needed is directly related to the number of iVMs that will be created in the inception cloud. 
47
+\dlitem{-n n}{
48
+	Specifies the number of work ICVMs that are created.  The iVMs which are created in the inception cloud are hosted
49
+	on the work VMs thus the number needed is directly related to the number of iVMs that will be created in the inception cloud.
49 50
 }
50 51
 
51 52
 \vspace{5pt}
52
-\dlitem{-~-image=}{ 
53
-	Supplied the image name to be used for all ICVMs.  If not supplied a base image of Ubuntu 12.04 (64 bit) is 
54
-	created and used for each ICVM. 
53
+\dlitem{-~-image=}{
54
+	Supplied the image name to be used for all ICVMs.  If not supplied a base image of Ubuntu 12.04 (64 bit) is
55
+	created and used for each ICVM.
55 56
 }
56 57
 
57 58
 \vspace{5pt}
58
-\dlitem{-~-ssh\_keyfile=}{ 
59
-	Provides the name of the private key that is to be injected as the user key for each of the 
59
+\dlitem{-~-ssh\_keyfile=}{
60
+	Provides the name of the private key that is to be injected as the user key for each of the
60 61
 	control VMs that are created.
61 62
 }
62 63
 
63 64
 \vspace{5pt}
64
-\dlitem{-~-user=}{ 
65
-	The user name created on each node with sudo capabilities. If not given, ubuntu is used. 
65
+\dlitem{-~-user=}{
66
+	The user name created on each node with sudo capabilities. If not given, ubuntu is used.
66 67
 }
67 68
 \dlend
68 69
 
@@ -75,9 +76,9 @@ The following illustrates the command to start an inception cloud with one worke
75 76
 \end{verbatim}\normalsize
76 77
 \noindent
77 78
 The creation and initialisation of the ICVMs takes about 20 minutes during which time a fair few messages
78
-are written to standard error. 
79
-When orchestrator has finished, a set of messages should be written to stdout indicating success and which give the IP 
80
-addresses and URLs for various things in the newly created environment.  
79
+are written to standard error.
80
+When orchestrator has finished, a set of messages should be written to stdout indicating success and which give the IP
81
+addresses and URLs for various things in the newly created environment.
81 82
 The following is a sample of these messages (date, time, and system indentification information has bee excluded for brevity):
82 83
 
83 84
 \small\begin{verbatim}
@@ -92,12 +93,12 @@ The inception cloud can be stopped manually by halting all of the ICVMs, or orch
92 93
 giving it the \verb!--cleanup! command line flag which causes it to terminate all of the ICVMs.
93 94
 
94 95
 \small\begin{verbatim}
95
-   orchestrator  -p scooter0  --cleanup 
96
+   orchestrator  -p scooter0  --cleanup
96 97
 \end{verbatim}\normalsize
97 98
 
98 99
 \subsection{Finalisation}
99 100
 It will take approximately 20 minutes for orchestrator to start the inception cloud.
100
-Once orchestrator reports that the inception cloud is ready, a small amount of housekeeping should be done. 
101
+Once orchestrator reports that the inception cloud is ready, a small amount of housekeeping should be done.
101 102
 These tasks include:
102 103
 
103 104
 \begin{itemize}
@@ -113,14 +114,14 @@ These tasks include:
113 114
 \end{itemize}
114 115
 
115 116
 \subsubsection{Repointing Sshuttle}
116
-Once the ICVMs are running, sshuttle should be "pointed" at the gateway ICVM so that the boot-up VM can be stopped. 
117
-Sshuttle must also be set to tunnel requests for the private control network that is used by the 
118
-ICVMs as this is the network on which the nova authorisation and dashboard processes listen on. 
119
-The following commands illustrate how this can be done:  
117
+Once the ICVMs are running, sshuttle should be "pointed" at the gateway ICVM so that the boot-up VM can be stopped.
118
+Sshuttle must also be set to tunnel requests for the private control network that is used by the
119
+ICVMs as this is the network on which the nova authorisation and dashboard processes listen on.
120
+The following commands illustrate how this can be done:
120 121
 
121 122
 \small\begin{verbatim}
122
-   nova list | grep scooter0-gateway          
123
-   ssh ubuntu@yyy.yyy.yyy.yyy ifconfig eth1   
123
+   nova list | grep scooter0-gateway
124
+   ssh ubuntu@yyy.yyy.yyy.yyy ifconfig eth1
124 125
    sshuttle -e ssh -A -i ~/.vmkeys/agave.shared.pk -v \
125 126
             -r ubuntu@yyy.yyy.yyy.yyy  \
126 127
             192.168.254.0/24 zzz.zzz.zzz.0/24
@@ -136,34 +137,34 @@ Where:
136 137
 \dlitem{yyy.yyy.yyy.yyy}{ Is the public IP address for the gateway.}
137 138
 
138 139
 \vspace{5pt}
139
-\dlitem{zzz.zzz.zzz.0} { 
140
-	Is the network address of the control network. The netmask also must be checked to determine if /24 is 
141
-	the appropriate number of bits being used to represent a host id; if not it must be changed to match the netmask.  
140
+\dlitem{zzz.zzz.zzz.0} {
141
+	Is the network address of the control network. The netmask also must be checked to determine if /24 is
142
+	the appropriate number of bits being used to represent a host id; if not it must be changed to match the netmask.
142 143
 }
143 144
 
144 145
 \vspace{5pt}
145 146
 \dlitem{ubuntu}{ Is the user name that was injected onto each of the ICVMs. }
146 147
 \dlend
147 148
 
148
-After these commands are executed sshuttle will again be running on the workstation and managing a tunnel between the 
149
-workstation and both the virtual network and the inception cloud's private control network in the OpenStack environment. 
149
+After these commands are executed sshuttle will again be running on the workstation and managing a tunnel between the
150
+workstation and both the virtual network and the inception cloud's private control network in the OpenStack environment.
150 151
 
151 152
 \subsubsection{Modifying /etc/hosts}
152 153
 In order to use the inception cloud OpenStack dashboard (URL given in the last set of messages generated by orchestrator),
153
-the workstation must be able to resolve the 
154
-controller host name (e.g. \verb!scooter0-controller! using the earlier example prefix).  
155
-The easiest way to do this is to have sshuttle forward all DNS requests to the inception cloud environment for resolution. 
154
+the workstation must be able to resolve the
155
+controller host name (e.g. \verb!scooter0-controller! using the earlier example prefix).
156
+The easiest way to do this is to have sshuttle forward all DNS requests to the inception cloud environment for resolution.
156 157
 This is done with the addition of a command line flag on the sshuttle command, however shuffling all of the workstation's DNS
157
-traffic into the VM environment is probably not a very wise choice. 
158
-Instead, the host name of the controller, and it's control network IP address (zzz.zzz.zzz.hhh) should be added to the 
159
-\verb!/etc/hosts! file on the workstation.   
158
+traffic into the VM environment is probably not a very wise choice.
159
+Instead, the host name of the controller, and it's control network IP address (zzz.zzz.zzz.hhh) should be added to the
160
+\verb!/etc/hosts! file on the workstation.
160 161
 
161 162
 
162 163
 \subsubsection{Setting Credentials}
163
-Credentials must be set in the environment to allow nova to be used on the workstation to control the iVMs in the 
164
-inception cloud.  
165
-The following is a list of variables that must be exported and their approximate values (the IP address supplied for the 
166
-authorisation URL will be different as might the username).  
164
+Credentials must be set in the environment to allow nova to be used on the workstation to control the iVMs in the
165
+inception cloud.
166
+The following is a list of variables that must be exported and their approximate values (the IP address supplied for the
167
+authorisation URL will be different as might the username).
167 168
 The password was given to the user \emph{demo} via the dashboard using the \emph{admin} user ID.
168 169
 
169 170
 \small\begin{verbatim}
@@ -173,9 +174,9 @@ The password was given to the user \emph{demo} via the dashboard using the \emph
173 174
   export OS_PASSWORD=demo
174 175
 \end{verbatim}\normalsize
175 176
 
176
-The network address given is that of the private control network. 
177
-The dashboard can be used to setup any users and\/or projects (tenants) that are needed in the inception cloud. 
178
-The admin user ID and password are admin/admin by default. 
177
+The network address given is that of the private control network.
178
+The dashboard can be used to setup any users and\/or projects (tenants) that are needed in the inception cloud.
179
+The admin user ID and password are admin/admin by default.
179 180
 
180 181
 \begin{figure}
181 182
   \centering

Loading…
Cancel
Save