blob: 95b5749f740d81ea7a4b82e3772c7501a3339510 [file] [log] [blame]
Petr Ospalýbe81ab02019-02-14 21:30:31 +01001.. This work is licensed under a Creative Commons Attribution 4.0 International License.
2.. http://creativecommons.org/licenses/by/4.0
3.. Copyright 2019 Samsung Electronics Co., Ltd.
4
5.. _oooi_installguide:
6
7OOM ONAP Offline Installer - Installation Guide
8===============================================
9
10This document describes the correct offline installation procedure for `OOM ONAP`_, which is done by the ansible based `offline-installer <https://gerrit.onap.org/r/#/admin/projects/oom/offline-installer>`_.
11
12Before you dive into the installation you should prepare the offline installer itself - the installer consists of at least two packages/resources. You can read about it in the `Build Guide`_, which provides the instructions for creating them.
13
14This current version of the *Installation Guide* supports `Casablanca release`_.
15
16-----
17
18.. _oooi_installguide_preparations:
19
20Part 1. Prerequisites
21---------------------
22
23OOM ONAP deployment has certain hardware resource requirements - `Casablanca requirements`_:
24
25- 14 VM (1 Rancher, 13 K8s nodes) - 8 vCPU - 16 GB RAM
26- 160 GB Storage
27
28That means the full deployment footprint is about ``224 GB RAM`` and ``112 vCPUs``. We will not follow strictly this setup due to such demanding resource consumption and so we will deploy our installation across four nodes (VMs) instead of fourteen. Our simplified setup is definitively not supported or recommended - you are free to diverge - you can follow the official guidelines or make completely different layout, but the minimal count of nodes should not drop below three - otherwise you may have to do some tweaking to make it work, which is not covered here (there is a pod count limit for a single kubernetes node - you can read more about it in this `discussion <https://lists.onap.org/g/onap-discuss/topic/oom_110_kubernetes_pod/25213556>`_).
29
30.. _oooi_installguide_preparations_k8s_cluster:
31
32Kubernetes cluster
33~~~~~~~~~~~~~~~~~~
34
35The four nodes/VMs will be running these services:
36
37- **infra-node**::
38
39 - nexus
40 - nginx proxy
41 - dns
42 - rancher server
43
44- **kubernetes node 1-3**::
45
46 - rancher agent
47
48You don't need to care about these services now - that is the responsibility of the installer (described below). Just start four VMs as seen in this table (or according to your needs as we hinted above):
49
50.. _Overview table of the kubernetes cluster:
51
52Kubernetes cluster overview
53^^^^^^^^^^^^^^^^^^^^^^^^^^^
54
55=================== ========= ==================== ============== ============ ===============
56KUBERNETES NODE OS NETWORK CPU RAM STORAGE
57=================== ========= ==================== ============== ============ ===============
58**infra-node** RHEL 7 ``10.8.8.100/24`` ``8 vCPUs`` ``8 GB`` ``100 GB``
59**kube-node1** RHEL 7 ``10.8.8.101/24`` ``16 vCPUs`` ``48+ GB`` ``100 GB``
60**kube-node2** RHEL 7 ``10.8.8.102/24`` ``16 vCPUs`` ``48+ GB`` ``100 GB``
61**kube-node3** RHEL 7 ``10.8.8.103/24`` ``16 vCPUs`` ``48+ GB`` ``100 GB``
62SUM ``56 vCPUs`` ``152+ GB`` ``400 GB``
63================================================== ============== ============ ===============
64
65Unfortunately, the offline installer supports only **RHEL 7.x** distribution as of now. So, your VMs should be preinstalled with this operating system - the hypervisor and platform can be of your choosing. It is also worth knowing that the exact RHEL version (major and minor number - 7.6 for example) should match for the package build procedure and the target installation. That means: if you are building packages on RHEL 7.6 release your VMs should be RHEL 7.6 too.
66
67We will expect from now on that you installed four VMs and they are connected to the shared network. All VMs must be reachable from our *install-server* (below), which can be the hypervisor, *infra-node* or completely different machine. But in either of these cases the *install-server* must be able to connect over ssh to all of these nodes.
68
69.. _oooi_installguide_preparations_installserver:
70
71Install-server
72~~~~~~~~~~~~~~
73
74We will use distinct *install-server* and keep it separate from the four-node cluster. But if you wish so, you can use *infra-node* for this goal (if you use the default ``'chroot'`` option of the installer), but in that case double the size of the storage requirement!
75
76Prerequisites for the *install-server*:
77
78- packages described in `Build Guide`_
79- extra ``100 GB`` storage (to have space where to store these packages)
80- installed ``'chroot'`` and/or ``'docker'`` system commands
81- network connection to the nodes - especially functioning ssh client
82
83Our *install-server* will have ip: ``10.8.8.4``.
84
85**NOTE:** All the subsequent commands below, are executed from within this *install-server*.
86
87-----
88
89.. _oooi_installguide_config:
90
91Part 2. Preparation and configuration
92-------------------------------------
93
94We *MUST* do all the following instructions from the *install-server* and also we will be running them as a user ``root``. But that is not necessary - you can without any problem pick and use a regular user. The ssh/ansible connection to the nodes will also expect that we are connecting as a ``root`` - you need to elevate privileges to be able to install on them. Although it can be achieved by other means (sudo), we decided here to keep instructions simple.
95
96.. _oooi_installguide_config_packages:
97
98Installer packages
99~~~~~~~~~~~~~~~~~~
100
101As was stated above you must have prepared the installer packages (names will differ - check out the `Build Guide`_):
102
Michal Ptaceke45f3a52019-05-07 07:38:40 +0000103- offline-onap-3.0.2-resources.tar
104- offline-onap-3.0.2-aux-resources.tar
105- offline-onap-3.0.2-sw.tar
Petr Ospalýbe81ab02019-02-14 21:30:31 +0100106
Michal Ptaceke45f3a52019-05-07 07:38:40 +0000107**NOTE:** ``'offline-onap-3.0.2-aux-resources.tar'`` is optional and if you don't have use for it, you can ignore it.
Petr Ospalýbe81ab02019-02-14 21:30:31 +0100108
109We will store them in the ``/data`` directory on the *install-server* and then we will unpack the ``'sw'`` package to your home directory for example::
110
111 $ mkdir ~/onap-offline-installer
Michal Ptaceke45f3a52019-05-07 07:38:40 +0000112 $ tar -C ~/onap-offline-installer -xf /data/offline-onap-3.0.2-sw.tar
Petr Ospalýbe81ab02019-02-14 21:30:31 +0100113
114.. _oooi_installguide_config_app:
115
116Application directory
117~~~~~~~~~~~~~~~~~~~~~
118
119Change the current directory to the ``'ansible'``::
120
121 $ cd ~/onap-offline-installer/ansible
122
123You can see multiple files and directories inside - this is the *offline-installer*. It is implemented as a set of ansible playbooks.
124
Bartek Grzybowski30b2cbf2019-03-26 16:10:10 +0100125If you created the ``'sw'`` package according to the *Build Guide* then you should have had the ``'application'`` directory populated with at least the following files:
Petr Ospalýbe81ab02019-02-14 21:30:31 +0100126
127- ``application_configuration.yml``
128- ``hosts.yml``
129
130**NOTE:** The following paragraph describes a way how to create or fine-tune your own ``'application_configuration.yml'`` - we are discouraging you from executing this step. The recommended way is to use the packaged files inside the ``'application'`` directory.
131
132**NOT RECOMMENDED:** If for some reason you don't have these files inside the ``'application'`` directory or you simply want to do things the hard way then you can recreate them from their templates. It is better to keep the originals (templates) intact - so we will copy them to the ``'application'`` directory::
133
134 $ cp ../config/application_configuration.yml application/
135 $ cp inventory/hosts.yml application/
136
137.. _oooi_installguide_config_hosts:
138
139hosts.yml
140~~~~~~~~~
141
142We need to setup the ``'hosts.yml'`` first, the template looks like this::
143
144 ---
145 # This group contains hosts with all resources (binaries, packages, etc.)
146 # in tarball.
147 all:
148 vars:
149 # this key is supposed to be generated during setup.yml playbook execution
150 # change it just when you have better one working for all nodes
151 ansible_ssh_private_key_file: /root/.ssh/offline_ssh_key
152 ansible_ssh_common_args: '-o StrictHostKeyChecking=no'
153
154 children:
155 resources:
156 hosts:
157 resource-host:
158 ansible_host: 10.8.8.5
159
160 # This is group of hosts where nexus, nginx, dns and all other required
161 # services are running.
162 infrastructure:
163 hosts:
164 infrastructure-server:
165 ansible_host: 10.8.8.13
166 #IP used for communication between infra and kubernetes nodes, must be specified.
167 cluster_ip: 10.8.8.13
168
169 # This is group of hosts which are/will be part of Kubernetes cluster.
170 kubernetes:
171 hosts:
172 kubernetes-node-1:
173 ansible_host: 10.8.8.19
174 #ip of the node that it uses for communication with k8s cluster.
175 cluster_ip: 10.8.8.19
176
Bartek Grzybowskicf6797c2019-05-22 14:53:31 +0200177 # This is a group of hosts that are to be used as kubernetes control plane nodes.
178 # This means they host kubernetes api server, controller manager and scheduler.
179 # This example uses infra for this purpose, however note that any
180 # other host could be used including kubernetes nodes.
181 # cluster_ip needs to be set for hosts used as control planes.
182 kubernetes-control-plane:
183 hosts:
184 infrastructure-server
185
Petr Ospalýbe81ab02019-02-14 21:30:31 +0100186 nfs-server:
187 hosts:
188 kubernetes-node-1
189
190There is some ssh configuration under the ``'vars'`` section - we will deal with ssh setup a little bit later in the `SSH authentication`_.
191
192We need to first correct the ip addresses and add a couple of kubernetes nodes to match our four-node cluster:
193
194- Under the ``'resource-host'`` set the ``'ansible_host'`` address to the ip of your server, where the packages are stored - it must be reachable by ssh from the *install-server* (for ansible to run playbooks on it) **AND** *infra-node* (to extract resource data from *resource-host* to *infra-node* over ssh). In our scenario the *resource-host* is the same as the *install-server*: ``'10.8.8.4'``
195- Similarly, set the ``'ansible_host'`` to the address of the *infra-node* under the ``'infrastructure-server'``.
196- Copy the whole ``'kubernetes-node-1'`` subsection and paste it twice directly after. Change the numbers to ``'kubernetes-node-2'`` and ``'kubernetes-node-3'`` respectively and fix the addresses in the ``'ansible_host'`` variables again to match *kube-node1*, *kube-node2* and *kube-node3*.
197
198As you can see, there is another ``'cluster_ip'`` variable for each node - this serve as a designated node address in the kubernetes cluster. Make it the same as the respective ``'ansible_host'``.
199
200**NOTE:** In our simple setup we have only one interface per node, but that does not need to be a case for some other deployment - especially if we start to deal with a production usage. Basically, an ``'ansible_host'`` is an entry point for the *install-server's* ansible (*offline-installer*), but the kubernetes cluster can be communicating on a separate network to which *install-server* has no access. That is why we have this distinctive variable, so we can tell the installer that there is a different network, where we want to run the kubernetes traffic and what address each node has on such a network.
201
202After all the changes, the ``'hosts.yml'`` should look similar to this::
203
204 ---
205 # This group contains hosts with all resources (binaries, packages, etc.)
206 # in tarball.
207 all:
208 vars:
209 # this key is supposed to be generated during setup.yml playbook execution
210 # change it just when you have better one working for all nodes
211 ansible_ssh_private_key_file: /root/.ssh/offline_ssh_key
212 ansible_ssh_common_args: '-o StrictHostKeyChecking=no'
213
214 children:
215 resources:
216 hosts:
217 resource-host:
218 ansible_host: 10.8.8.4
219
220 # This is group of hosts where nexus, nginx, dns and all other required
221 # services are running.
222 infrastructure:
223 hosts:
224 infrastructure-server:
225 ansible_host: 10.8.8.100
226 #IP used for communication between infra and kubernetes nodes, must be specified.
227 cluster_ip: 10.8.8.100
228
229 # This is group of hosts which are/will be part of Kubernetes cluster.
230 kubernetes:
231 hosts:
232 kubernetes-node-1:
233 ansible_host: 10.8.8.101
234 #ip of the node that it uses for communication with k8s cluster.
235 cluster_ip: 10.8.8.101
236 kubernetes-node-2:
237 ansible_host: 10.8.8.102
238 #ip of the node that it uses for communication with k8s cluster.
239 cluster_ip: 10.8.8.102
240 kubernetes-node-3:
241 ansible_host: 10.8.8.103
242 #ip of the node that it uses for communication with k8s cluster.
243 cluster_ip: 10.8.8.103
244
Bartek Grzybowskicf6797c2019-05-22 14:53:31 +0200245 # This is a group of hosts that are to be used as kubernetes control plane nodes.
246 # This means they host kubernetes api server, controller manager and scheduler.
247 # This example uses infra for this purpose, however note that any
248 # other host could be used including kubernetes nodes.
249 # cluster_ip needs to be set for hosts used as control planes.
250 kubernetes-control-plane:
251 hosts:
252 infrastructure-server
253 ansible_host: 10.8.8.100
254 #IP used for communication between infra and kubernetes nodes, must be specified.
255 cluster_ip: 10.8.8.100
256
Petr Ospalýbe81ab02019-02-14 21:30:31 +0100257 nfs-server:
258 hosts:
259 kubernetes-node-1
260
261.. _oooi_installguide_config_appconfig:
262
263application_configuration.yml
264~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
265
266Here, we will be interested in the following variables:
267
268- ``resources_dir``
269- ``resources_filename``
270- ``aux_resources_filename``
271- ``app_data_path``
272- ``aux_data_path``
273- ``app_name``
Bartek Grzybowski30b2cbf2019-03-26 16:10:10 +0100274- ``timesync``
Petr Ospalýbe81ab02019-02-14 21:30:31 +0100275
276``'resource_dir'``, ``'resources_filename'`` and ``'aux_resources_filename'`` must correspond to the file paths on the *resource-host* (variable ``'resource_host'``), which is in our case the *install-server*.
277
Michal Ptaceke45f3a52019-05-07 07:38:40 +0000278The ``'resource_dir'`` should be set to ``'/data'``, ``'resources_filename'`` to ``'offline-onap-3.0.2-resources.tar'`` and ``'aux_resources_filename'`` to ``'offline-onap-3.0.2-aux-resources.tar'``. The values should be the same as are in the `Installer packages`_ section.
Petr Ospalýbe81ab02019-02-14 21:30:31 +0100279
Michal Ptaceke45f3a52019-05-07 07:38:40 +0000280``'app_data_path'`` is the absolute path on the *infra-node* to where the package ``'offline-onap-3.0.2-resources.tar'`` will be extracted and similarly ``'aux_data_path'`` is another absolute path for ``'offline-onap-3.0.2-aux-resources.tar'``. Both the paths are fully arbitrary, but they should point to the filesystem with enough space - the storage requirement in `Overview table of the kubernetes cluster`_.
Petr Ospalýbe81ab02019-02-14 21:30:31 +0100281
282**NOTE:** As we mentioned in `Installer packages`_ - the auxiliary package is not mandatory and we will not utilize it in here either.
283
Bartek Grzybowski30b2cbf2019-03-26 16:10:10 +0100284The ``'app_name'`` variable should be short and descriptive. We will set it simply to: ``onap``.
Petr Ospalýbe81ab02019-02-14 21:30:31 +0100285
Bartek Grzybowski30b2cbf2019-03-26 16:10:10 +0100286The ``'timesync'`` variable is optional and controls synchronisation of the system clock on hosts. It should be configured only if a custom NTP server is available and needed. Such a time authority should be on a host reachable from all installation nodes. If this setting is not provided then the default behavior is to setup NTP daemon on infra-node and sync all kube-nodes' time with it.
287
288If you wish to provide your own NTP servers configure their IPs as follows::
289
290 timesync:
291 servers:
292 - <ip address of NTP_1>
293 - <...>
294 - <ip address of NTP_N>
295
296Another time adjustment related variables are ``'timesync.slewclock'`` and ``'timesync.timezone'`` .
297First one can have value of ``'true'`` or ``'false'`` (default). It controls whether (in case of big time difference compared to server) time should be adjusted gradually by slowing down or speeding up the clock as required (``'true'``) or in one step (``'false'``)::
298
299 timesync:
300 slewclock: true
301
302Second one controls time zone setting on host. It's value should be time zone name according to tz database names with ``'Universal'`` being the default one::
303
304 timesync.
305 timezone: UTC
306
307``'timesync.servers'``, ``'timesync.slewclock'`` and ``'timesync.timezone'`` settings can be used independently.
308
309Final configuration can resemble the following::
Petr Ospalýbe81ab02019-02-14 21:30:31 +0100310
311 resources_dir: /data
Michal Ptaceke45f3a52019-05-07 07:38:40 +0000312 resources_filename: offline-onap-3.0.2-resources.tar
Petr Ospalýbe81ab02019-02-14 21:30:31 +0100313 app_data_path: /opt/onap
314 app_name: onap
Bartek Grzybowski30b2cbf2019-03-26 16:10:10 +0100315 timesync:
316 servers:
317 - 192.168.0.1
318 - 192.168.0.2
319 slewclock: true
320 timezone: UTC
Petr Ospalýbe81ab02019-02-14 21:30:31 +0100321
Michal Zegana579c982019-04-02 15:33:30 +0200322.. _oooi_installguide_config_appconfig_overrides:
323
324Helm chart value overrides
325^^^^^^^^^^^^^^^^^^^^^^^^^^
326
327If there is a need to change onap settings such as managed openstack credentials, service ports, or even docker image versions used, you can do this by putting settings under the ``overrides`` key in ``application_configuration.yml``.
328These settings will override helm values originally stored in ``values.yaml`` files in helm chart directories.
329
330For example, the following lines could be appended to ``application_configuration.yml`` to set up managed openstack credentials for onap's so component::
331
332 overrides:
333 so:
334 config:
335 openStackUserName: "os_user"
336 openStackRegion: "region_name"
337 openStackKeyStoneUrl: "keystone_url"
338 openStackEncryptedPasswordHere: "encrypted_password"
339
Petr Ospalýbe81ab02019-02-14 21:30:31 +0100340.. _oooi_installguide_config_ssh:
341
342SSH authentication
343~~~~~~~~~~~~~~~~~~
344
345We are almost finished with the configuration and we are close to start the installation, but we need to setup password-less login from *install-server* to the nodes.
346
347You can use the ansible playbook ``'setup.yml'`` like this::
348
349 $ ./run_playbook.sh -i application/hosts.yml setup.yml -u root --ask-pass
350
351You will be asked for password per each node and the playbook will generate a unprotected ssh key-pair ``'~/.ssh/offline_ssh_key'``, which will be distributed to the nodes.
352
353Another option is to generate a ssh key-pair manually. We strongly advise you to protect it with a passphrase, but for simplicity we will showcase generating of a private key without any such protection::
354
355 $ ssh-keygen -N "" -f ~/.ssh/identity
356
357The next step will be to distribute the public key to these nodes and from that point no password is needed::
358
359 $ for ip in 100 101 102 103 ; do ssh-copy-id -i ~/.ssh/identity.pub root@10.8.8.${ip} ; done
360
361This command behaves almost identically to the ``'setup.yml'`` playbook.
362
363If you generated the ssh key manually then you can now run the ``'setup.yml'`` playbook like this and achieve the same result as in the first execution::
364
365 $ ./run_playbook.sh -i application/hosts.yml setup.yml
366
367This time it should not ask you for any password - of course this is very redundant, because you just distributed two ssh keys for no good reason.
368
369We can finally edit and finish the configuration of the ``'hosts.yml'``:
370
371- if you used the ``'setup.yml'`` playbook then you can just leave this line as it is::
372
373 ansible_ssh_private_key_file: /root/.ssh/offline_ssh_key
374
375- if you created a ssh key manually then change it like this::
376
377 ansible_ssh_private_key_file: /root/.ssh/identity
378
379-----
380
381.. _oooi_installguide_install:
382
383Part 3. Installation
384--------------------
385
386We should have the configuration complete and be ready to start the installation. The installation is done via ansible playbooks, which are run either inside a **chroot** environment (default) or from the **docker** container. If for some reason you want to run playbooks from the docker instead of chroot then you cannot use *infra-node* or any other *kube-node* as the *install-server* - otherwise you risk that installation will fail due to restarting of the docker service.
387
388If you built your ``'sw'`` package well then there should be the file ``'ansible_chroot.tgz'`` inside the ``'docker'`` directory. If not then you must create it - to learn how to do that and to get more info about the scripts dealing with docker and chroot, go to `Appendix 1. Ansible execution/bootstrap`_
389
390We will use the default chroot option so we don't need any docker service to be running.
391
392Installation is actually very straightforward now::
393
394 $ ./run_playbook.sh -i application/hosts.yml -e @application/application_configuration.yml site.yml
395
396This will take a while so be patient.
397
398``'site.yml'`` playbook actually runs in the order the following playbooks:
399
400- ``upload_resources.yml``
401- ``infrastructure.yml``
Bartek Grzybowskicf6797c2019-05-22 14:53:31 +0200402- ``rke.yml``
Petr Ospalýbe81ab02019-02-14 21:30:31 +0100403- ``application.yml``
404
Michal Ptacekc424cff2019-03-06 16:25:43 +0000405----
406
407.. _oooi_installguide_postinstall:
408
Bartek Grzybowski32bf2fb2019-05-30 11:52:40 +0200409Part 4. Post-installation and troubleshooting
410---------------------------------------------
Michal Ptacekc424cff2019-03-06 16:25:43 +0000411
Bartek Grzybowski32bf2fb2019-05-30 11:52:40 +0200412After all of the playbooks are run successfully, it will still take a lot of time until all pods are up and running. You can monitor your newly created kubernetes cluster for example like this::
Petr Ospalýbe81ab02019-02-14 21:30:31 +0100413
414 $ ssh -i ~/.ssh/offline_ssh_key root@10.8.8.4 # tailor this command to connect to your infra-node
415 $ watch -d -n 5 'kubectl get pods --all-namespaces'
416
Bartek Grzybowski32bf2fb2019-05-30 11:52:40 +0200417Alternatively you can monitor progress with ``helm_deployment_status.py`` script located in offline-installer directory. Transfer it to infra-node and run::
Milan Verespej1a230472019-03-20 13:51:40 +0100418
419 $ python helm_deployment_status.py -n <namespace_name> # namespace defaults to onap
420
Bartek Grzybowski32bf2fb2019-05-30 11:52:40 +0200421To automatically verify functionality with healthchecks after deployment becomes ready or after timeout period expires, append ``-hp`` switch followed by the full path to the healthcheck script and ``--health-mode`` optional switch with appropriate mode supported by that script (``health`` by default, ``--help`` displays available modes)::
Milan Verespej1a230472019-03-20 13:51:40 +0100422
Bartek Grzybowski32bf2fb2019-05-30 11:52:40 +0200423 $ python helm_deployment_status.py -hp <app_data_path>/<app_name>/helm_charts/robot/ete-k8s.sh --health-mode <healthcheck mode>
Milan Verespej1a230472019-03-20 13:51:40 +0100424
Bartek Grzybowski32bf2fb2019-05-30 11:52:40 +0200425It is strongly recommended to tailor ``helm_deployment_status.py`` to your needs since default values might not be what you'd expect. The defaults can be displayed with ``--help`` switch.
Michal Ptacekc424cff2019-03-06 16:25:43 +0000426
427Final result of installation varies based on number of k8s nodes used and distribution of pods. In some dev envs we quite frequently hit problems with not all pods properly deployed. In successful deployments all jobs should be in successful state.
428This can be verified using ::
429
430 $ kubectl get jobs -n <namespace>
431
432If some of the job is hanging in some wrong end-state like ``'BackoffLimitExceeded'`` manual intervention is required to heal this and make also dependent jobs passing. More details about particular job state can be obtained using ::
433
434 $ kubectl describe job -n <namespace> <job_name>
435
436If manual intervention is required, one can remove failing job and retry helm install command directly, which will not launch full deployment but rather check current state of the system and rebuild parts which are not up & running. Exact commands are as follows ::
437
438 $ kubectl delete job -n <namespace> <job_name>
439 $ helm deploy <env_name> <helm_chart_name> --namespace <namespace_name>
440
441 E.g. helm deploy dev local/onap --namespace onap
442
443Once all pods are properly deployed and in running state, one can verify functionality e.g. by running onap healthchecks ::
444
445 $ cd <app_data_path>/<app_name>/helm_charts/robot
446 $ ./ete-k8s.sh onap health
447
448
Petr Ospalýbe81ab02019-02-14 21:30:31 +0100449-----
450
451.. _oooi_installguide_appendix1:
452
453Appendix 1. Ansible execution/bootstrap
454---------------------------------------
455
456There are two ways how to easily run the installer's ansible playbooks:
457
458- If you already have or can install a docker then you can build the provided ``'Dockerfile'`` for the ansible and run playbooks in the docker container.
459- Another way to deploy ansible is via chroot environment which is bundled together within this directory.
460
461(Re)build docker image and/or chroot archive
462~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
463
464Inside the ``'docker'`` directory is the ``'Dockerfile'`` and ``'build_ansible_image.sh'`` script. You can run ``'build_ansible_image.sh'`` script on some machine with the internet connectivity and it will download all required packages needed for building the ansible docker image and for exporting it into a flat chroot environment.
465
466Built image is exported into ``'ansible_chroot.tgz'`` archive in the same (``'docker'``) directory.
467
468This script has two optional arguments:
469
470#. ansible version
471#. docker image name
472
473**Note:** if optional arguments are not used, docker image name will be set to ``'ansible'`` by default.
474
475Launching ansible playbook using chroot environment
476~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
477
478This is the default and preferred way of running ansible playbooks in an offline environment as there is no dependency on docker to be installed on the system. Chroot environment is already provided by included archive ``'ansible_chroot.tgz'``.
479
480It should be available in the ``'docker'`` directory as the end-result of the packaging script or after manual run of the ``'build_ansible_image.sh'`` script referenced above.
481
482All playbooks can be executed via ``'./run_playbook.sh'`` wrapper script.
483
484To get more info about the way how the ``'./run_playbook.sh'`` wrapper script should be used, run::
485
486 $ ./run_playbook.sh
487
488The main purpose of this wrapper script is to provide the ansible framework to a machine where it was bootstrapped without need of installing additional packages. The user can run this to display ``'ansible-playbook'`` command help::
489
490 $ ./run_playbook.sh --help
491
492Developers notes
493~~~~~~~~~~~~~~~~
494
495* There are two scripts which work in tandem for creating and running chroot
496* First one can convert docker image into chroot directory
497* Second script will automate chrooting (necessary steps for chroot to work and cleanup)
498* Both of them have help - just run::
499
500 $ cd docker
501 $ ./create_docker_chroot.sh help
502 $ ./run_chroot.sh help
503
504Example usage::
505
506 $ sudo su
507 $ docker/create_docker_chroot.sh convert some_docker_image ./new_name_for_chroot
508 $ cat ./new_name_for_chroot/README.md
509 $ docker/run_chroot.sh execute ./new_name_for_chroot cat /etc/os-release 2>/dev/null
510
511Launching ansible playbook using docker container (ALTERNATIVE APPROACH)
512~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
513
514This option is here just to keep support for the older method which relies on a running docker service. For the offline deployment use the chroot option as indicated above.
515
516You will not need ``'ansible_chroot.tgz'`` archive anymore, but the new requirement is a prebuilt docker image of ansible (based on the provided ``'Dockerfile'``). It should be available in your local docker repository (otherwise the default name ``'ansible'`` may fetch unwanted image from default registry!).
517
518To trigger this functionality and to run ``'ansible-playbook'`` inside a docker container instead of the chroot environment, you must first set the ``ANSIBLE_DOCKER_IMAGE`` variable. The value must be a name of the built ansible docker image.
519
520Usage is basically the same as with the default chroot way - the only difference is the existence of the environment variable::
521
522 $ ANSIBLE_DOCKER_IMAGE=ansible ./run_playbook.sh --help
523
524-----
525
526.. _Build Guide: ./BuildGuide.rst
527.. _Casablanca requirements: https://onap.readthedocs.io/en/casablanca/guides/onap-developer/settingup/index.html#installing-onap
528.. _Casablanca release: https://docs.onap.org/en/casablanca/release/
529.. _OOM ONAP: https://wiki.onap.org/display/DW/ONAP+Operations+Manager+Project