packer/README.markdown

   1 # OpenDaylight Packer
   2
   3 [Packer][1] is a tool for automatically creating VM and container images,
   4 configuring them and post-processing them into standard output formats.
   5
   6 We currently build OpenDaylight's Vagrant base box and Docker image via Packer.
   7
   8 ## Building
   9
  10 You'll need to [install Packer][2], of course.
  11
  12 OpenDaylight's Packer configuration is divided into build-specific variables,
  13 output-specific templates and a set of shared provisioning scripts. To do a
  14 specific build, combine the template for the desired output artifact type with
  15 a variable file. For example, to build a LibVirt-based Vagrant base box with
  16 ODL Beryllium and CentOS 7.2.1511:
  17
  18 ```
  19 packer build -var-file=vars/opendaylight-4.0.0-centos-7.2.1511.json templates/libvirt.json
  20 ```
  21
  22 To build the same box with VirtualBox as the virtualization provider:
  23
  24 ```
  25 packer build -var-file=vars/opendaylight-4.0.0-centos-7.2.1511.json templates/virtualbox.json
  26 ```
  27
  28 To build a Beryllium SR1 Docker container:
  29
  30 ```
  31 packer build -var-file=vars/opendaylight-4.1.0-centos-7.2.1511.json templates/docker.json
  32 ```
  33
  34 Note that LibVirt, VirtualBox and Docker will need to work on your local system
  35 to run Packer builds that use them. You may need to disable LibVirt/VBox when
  36 enabling the other.
  37
  38 From a high level, the builds:
  39
  40 * Download and verify the CentOS ISO specified in the variables file.
  41 * Boot the ISO and do low-level configuration via a Kickstart template.
  42 * Run a set of shell scripts, listed in the template's shell provisioner
  43   section, to do any configuration required by the builder (VBox, Docker),
  44   other provisioners (Ansible) or post-processors (Vagrant, Docker).
  45 * Install and configure the version of OpenDaylight specified in the variables
  46   file using the [ansible-opendaylight role][3].
  47 * Export, compress and package the VM as a Vagrant base box or Docker image.
  48
  49 ## Running
  50
  51 This section documents how to run OpenDaylight's Vagrant base boxes and Docker
  52 images.
  53
  54 ### Pre-Built
  55
  56 This section documents how to run OpenDaylight Vagrant base boxes and Docker
  57 images. That have been built by the Integration/Packaging project and pushed
  58 to hosting services for easy consumption.
  59
  60 #### Vagrant Base Boxes
  61
  62 OpenDaylight uses the official Atlas Vagrant base box hosting service.
  63
  64 The [opendaylight/odl][4] repository contains built versions of every box
  65 defined here.
  66
  67 To use the latest version, simply specify `opendaylight/odl` as the base
  68 box in your Vagrantfile.
  69
  70 ```
  71 $ vagrant init -m opendaylight/odl
  72 $ cat Vagrantfile
  73 Vagrant.configure(2) do |config|
  74   config.vm.box = "opendaylight/odl"
  75 end
  76 ```
  77
  78 Boot the box (will download from Atlas if not cached locally) and connect:
  79
  80 ```
  81 $ vagrant up
  82 $ vagrant ssh
  83 ```
  84
  85 OpenDaylight will already be installed and running:
  86
  87 ```
  88 $ sudo systemctl is-active opendaylight
  89 active
  90 ```
  91
  92 To connect to the Karaf shell:
  93
  94 ```
  95 $ ssh -p 8101 karaf@localhost
  96 # password: karaf
  97 ```
  98
  99 To use a version other than latest, specify it in your Vagrantfile.
 100
 101 ```
 102 Vagrant.configure(2) do |config|
 103   config.vm.box = "opendaylight/odl"
 104   config.vm.box_version = "= 3.4.0"
 105 end
 106 ```
 107
 108 #### Docker Images
 109
 110 OpenDaylight's [official DockerHub account][7] is very out-of-date. The
 111 Integration/Packaging project will eventually take control and update it,
 112 but for now pre-built Docker images can be pulled from [dfarrell07/odl][5],
 113 which is the account of the [Int/Pack PTL][6].
 114
 115 Download an image and start a container with ODL running:
 116
 117 ```
 118 $ docker run -ti dfarrell07/odl /opt/opendaylight/bin/karaf
 119 ```
 120
 121 ### Locally Built
 122
 123 This section documents how to run locally-built OpenDaylight Vagrant base boxes
 124 and Docker images. Users not interested in building their own artifacts should
 125 see the Pre-Built section above.
 126
 127 #### Vagrant Base Boxes
 128
 129 The `vagrant` post-processor outputs built .box files into the current
 130 working directory.
 131
 132 ```
 133 <snip>
 134 Build 'qemu' finished.
 135
 136 ==> Builds finished. The artifacts of successful builds are:
 137 --> qemu: 'qemu' provider box: opendaylight-4.1.0-centos-7.2.1511-libvirt.box
 138 $ ls -rc | tail -n 1
 139 opendaylight-4.1.0-centos-7.2.1511-libvirt.box
 140 ```
 141
 142 Import the local box into Vagrant with:
 143
 144 ```
 145 $ vagrant box add --name "odl" opendaylight-4.1.0-centos-1511.box --force
 146 ==> box: Adding box 'odl' (v0) for provider:
 147     box: Downloading: file:///home/daniel/packaging/packer/opendaylight-4.1.0-centos-1511.box
 148 ==> box: Successfully added box 'odl' (v0) for 'virtualbox'!
 149 ```
 150
 151 To connect to your new box, you'll need a trivial Vagrantfile:
 152
 153 ```
 154 $ vagrant init -m odl
 155 $ cat Vagrantfile
 156 Vagrant.configure(2) do |config|
 157   config.vm.box = "odl"
 158 end
 159 ```
 160
 161 Boot the box and connect:
 162
 163 ```
 164 $ vagrant up
 165 $ vagrant ssh
 166 ```
 167
 168 OpenDaylight will already be installed and running:
 169
 170 ```
 171 $ sudo systemctl is-active opendaylight
 172 active
 173 ```
 174
 175 To connect to the Karaf shell:
 176
 177 ```
 178 $ ssh -p 8101 karaf@localhost
 179 # password: karaf
 180 ```
 181
 182 #### Docker Images
 183
 184 The `docker-tag` post-processor imports the built Docker image into your local
 185 image repository.
 186
 187 ```
 188 $ docker images
 189 REPOSITORY          TAG         IMAGE ID        CREATED         SIZE
 190 opendaylight/odl    4.1.0       8c9e8c24081e    2 days ago      1.408 GB
 191 ```
 192
 193 Use `docker run` to start a container. Point it at the Karaf executable
 194 to run OpenDaylight as the container's process.
 195
 196 ```
 197 $ docker run -ti opendaylight/odl:4.1.0 /opt/opendaylight/bin/karaf
 198 ```
 199
 200
 201 [1]: https://www.packer.io/
 202 [2]: https://www.packer.io/intro/getting-started/setup.html
 203 [3]: https://github.com/dfarrell07/ansible-opendaylight
 204 [4]: https://atlas.hashicorp.com/opendaylight/boxes/odl
 205 [5]: https://hub.docker.com/r/dfarrell07/odl/tags/
 206 [6]: https://wiki.opendaylight.org/view/User:Dfarrell07
 207 [7]: https://hub.docker.com/r/opendaylight/