summaryrefslogtreecommitdiffstats
path: root/docs/how-to-use/VirtEnvDeploy.rst
blob: 7f55f0c21eb958c1d98ddd20060d64ddbc10aa3a (plain)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
Overview
========

The main purpose of this project is to enable one to describe a virtual environment in a YAML file and enable the
user to deploy it to an OpenStack cloud in a repeatable manner. There are also options to un-deploy that same
environment by leveraging the original YAML file.

To deploy/clean virtual environments
====================================

-  Clone Repository

   -  git clone https://gerrit.cablelabs.com/snaps-provisioning

-  Install Library

   -  pip install -e /

-  Deploy

   -  cd
   -  python snaps/deploy\_venv.py -e -d
   -  Working example:

::

    python deploy_venv.py -e <path to repo>/examples/complex-network/deploy-complex-network.yaml -d

-  Clean

   -  python deploy\_venv.py -e -c
   -  Working example (cleanup of a previously deployed virtual
      environment where the VM has Yardstick installed):

::

    python deploy_venv.py -e <path to repo>/examples/complex-network/deploy-complex-network.yaml -c

Environment Configuration YAML File
===================================

The configuration file used to deploy and provision a virtual environment has been designed to describe the required
images, networks, SSH public and private keys, associated VMs, as well as any required post deployment provisioning
tasks.

\*\*\* Please note that many of the more esoteric optional supported
attributes still have not been fully tested. ***
*** Some of the nested bullets are being hidden by GitLabs, please see
doc/VirtEnvDeploy.md.\*\*\*

-  openstack: the top level tag that denotes configuration for the
   OpenStack components

   -  connection: - contains the credentials and endpoints required to
      connect with OpenStack
   -  username: - the project's user (required)
   -  password: - the tentant's user password (required)
   -  auth\_url: - the URL to the OpenStack APIs (required)
   -  project\_name: - the name of the OpenStack project for the user
      (required)
   -  http\_proxy: - the {{ host }}:{{ port }} of the proxy server the
      HTTPPhotoman01(optional)
   -  images: - describes each image
   -  image:

      -  name: The unique image name. If the name already exists for
         your project, a new one will not be created (required)
      -  format: The format type of the image i.e. qcow2 (required)
      -  download\_url: The HTTP download location of the image file
         (required)
      -  nic\_config\_pb\_loc: The file location relative to the CWD
         (python directory) to the Ansible Playbook used to configure
         VMs with more than one port. VMs get their first NIC configured
         for free while subsequent ones are not. This value/script will
         only be leveraged when necessary. Centos has been supported
         with
         "provisioning/ansible/centos-network-setup/configure\_host.yml".

   -  networks:
   -  network:

      -  name: The name of the network to be created. If one already
         exists, a new one will not be created (required)
      -  admin\_state\_up: T\|F (default True)
      -  shared: (optional)
      -  project\_name: Name of the project who owns the network. Note:
         only administrative users can specify projects other than their
         own (optional)
      -  external: T\|F whether or not network is external (default
         False)
      -  network\_type: The type of network to create. (optional)
      -  subnets:
      -  subnet:

         -  name: The name of the network to be created. If one already
            exists, a new one will not be created. Note: although
            OpenStack allows for multiple subnets to be applied to any
            given network, we have not included support as our current
            use cases does not utilize this functionality (required)
         -  cidr: The subnet mask value (required)
         -  dns\_nameservers: A list of IP values used for DNS
            resolution (default: 8.8.8.8)
         -  ip\_version: 4\|6 (default: 4)
         -  project\_name: Name of the project who owns the network.
            Note: only administrative users can specify projects other
            than their own (optional)
         -  start: The start address for allocation\_pools (optional)
         -  end: The ending address for allocation\_pools (optional)
         -  gateway\_ip: The IP address to the gateway (optional)
         -  enable\_dhcp: T\|F (optional)
         -  dns\_nameservers: List of DNS server IPs
         -  host\_routes: A list of host route dictionaries (optional)
            i.e.:
            ``yaml    "host_routes":[    {    "destination":"0.0.0.0/0",    "nexthop":"123.456.78.9"    },    {    "destination":"192.168.0.0/24",    "nexthop":"192.168.0.1"    }    ]``
         -  destination: The destination for a static route (optional)
         -  nexthop: The next hop for the destination (optional)
         -  ipv6\_ra\_mode: Valid values: "dhcpv6-stateful",
            "dhcpv6-stateless", and "slaac" (optional)
         -  ipv6\_address\_mode: Valid values: "dhcpv6-stateful",
            "dhcpv6-stateless", and "slaac" (optional)

   -  routers:

      -  router:
      -  name: The name of the router to be created. If one already
         exists, a new one will not be created (required)
      -  project\_name: Name of the project who owns the network. Note:
         only administrative users can specify projects other than their
         own (optional)
      -  internal\_subnets: A list of subnet names on which the router
         will be placed (optional)
      -  external\_gateway: A dictionary containing the external gateway
         parameters: "network\_id", "enable\_snat",
         "external\_fixed\_ips" (optional)
      -  interfaces: A list of port interfaces to create to other
         subnets (optional)

         -  port (Leverages the same class/structure as port objects on
            VM instances. See port definition below for a
            full accounting of the port attributes. The ones listed
            below are generally used for routers)

            -  name: The name given to the new port (must be unique for
               project) (required)
            -  network\_name: The name of the new port's network
               (required)
            -  ip\_addrs: A list of k/v pairs (optional)
            -  subnet\_name: the name of a subnet that is on the port's
               network
            -  ip: An IP address of the associated subnet to assign to
               the new port (optional but generally required for router
               interfaces)

   -  keypairs:

      -  keypair:
      -  name: The name of the keypair to be created. If one already
         exists, a new one will not be created but simply loaded from
         its configured file location (required)
      -  public\_filepath: The path to where the generated public key
         will be stored if it does not exist (optional but really
         required for provisioning purposes)
      -  private\_filepath: The path to where the generated private key
         will be stored if it does not exist (optional but really
         required for provisioning purposes)

   -  instances:

      -  instance:
      -  name: The unique instance name for project. (required)
      -  flavor: Must be one of the preconfigured flavors (required)
      -  imageName: The name of the image to be used for deployment
         (required)
      -  keypair\_name: The name of the keypair to attach to instance
         (optional but required for NIC configuration and Ansible
         provisioning)
      -  sudo\_user: The name of a sudo\_user that is attached to the
         keypair (optional but required for NIC configuration and
         Ansible provisioning)
      -  vm\_boot\_timeout: The number of seconds to block waiting for
         an instance to deploy and boot (default 900)
      -  vm\_delete\_timeout: The number of seconds to block waiting for
         an instance to be deleted (default 300)
      -  ssh\_connect\_timeout: The number of seconds to block waiting
         for an instance to achieve an SSH connection (default 120)
      -  ports: A list of port configurations (should contain at least
         one)
      -  port: Denotes the configuration of a NIC

         -  name: The unique port name for project (required)
         -  network\_name: The name of the network to which the port is
            attached (required)
         -  ip\_addrs: Static IP addresses to be added to the port by
            subnet (optional)
         -  subnet\_name: The name of the subnet
         -  ip: The assigned IP address (when null, OpenStack will
            assign an IP to the port)
         -  admin\_state\_up: T\|F (default True)
         -  project\_name: The name of the project who owns the network.
            Only administrative users can specify a the project ID other
            than their own (optional)
         -  mac\_address: The desired MAC for the port (optional)
         -  fixed\_ips: A dictionary that allows one to specify only a
            subnet ID, OpenStack Networking allocates an available IP
            from that subnet to the port. If you specify both a subnet
            ID and an IP address, OpenStack Networking tries to allocate
            the specified address to the port. (optional)
         -  seurity\_groups: A list of security group IDs (optional)
         -  allowed\_address\_pairs: A dictionary containing a set of
            zero or more allowed address pairs. An address pair contains
            an IP address and MAC address. (optional)
         -  opt\_value: The extra DHCP option value (optional)
         -  opt\_name: The extra DHCP option name (optional)
         -  device\_owner: The ID of the entity that uses this port. For
            example, a DHCP agent (optional)
         -  device\_id: The ID of the device that uses this port. For
            example, a virtual server (optional)

   -  floating\_ips: list of floating\_ip configurations (optional)

      -  floating\_ip:
      -  name: Must be unique for VM instance (required)
      -  port\_name: The name of the port requiring access to the
         external network (required)
      -  subnet\_name: The name of the subnet contains the IP address on
         the port on which to create the floating IP (optional)
      -  router\_name: The name of the router connected to an external
         network used to attach the floating IP (required)
      -  provisioning: (True\|False) Denotes whether or not this IP can
         be used for Ansible provisioning (default True)

-  ansible: Each set of attributes below are contained in a list

   -  playbook\_location: Full path or relative to the directory in
      which the deployment file resides (required)
   -  hosts: A list of hosts to which the playbook will be executed
      (required)
   -  variables: Should your Ansible scripts require any substitution
      values to be applied with Jinga2templates, the values defined here
      will be used to for substitution
   -  tag name = substitution variable names. For instance, for any file
      being pushed to the host being provisioned containing a value such
      as {{ foo }}, you must specify a tag name of "foo"

      -  vm\_name:
      -  type: string\|port\|os\_creds\|vm-attr (note: will need to make
         changes to deploy\_venv.py#\_\_get\_variable\_value() for
         additional support)
      -  when type == string, an tag name "value" must exist and its
         value will be used for template substituion
      -  when type == port, custom code has been written to extract
         certain assigned values to the port:

         -  vm\_name: must correspond to a VM's name as configured in
            this file
         -  port\_name: The name of the port from which to extract the
            substitution values (required)
         -  port\_value: The port value. Currently only supporting
            "mac\_address" and "ip\_address" (only the first)

      -  when type == os\_creds, custom code has been written to extract
         the file's connection values:

         -  username: connection's user
         -  password: connection's password
         -  auth\_url: connection's URL
         -  project\_name: connection's project

      -  when type == vm-attr, custom code has been written to extract
         the following attributes from the vm:

         -  vm\_name: must correspond to a VM's name as configured in
            this file
         -  value -> floating\_ip: is currently the only vm-attr
            supported