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 build OpenDaylight's Vagrant base boxes and Docker images 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.json -var-file=vars/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.json -var-file=vars/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.json -var-file=vars/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 Up-to-date Docker images can be pulled from [OpenDaylight's DockerHub][5].
 111
 112 Download the latest image and start a container with ODL running:
 113
 114 ```
 115 $ docker run -ti opendaylight/odl /opt/opendaylight/bin/karaf
 116 ```
 117
 118 To run a specific version, include a tag:
 119
 120 ```
 121 $ docker run -ti opendaylight/odl:4.1.0 /opt/opendaylight/bin/karaf
 122 ```
 123
 124 ### Locally Built
 125
 126 This section documents how to run locally-built OpenDaylight Vagrant base boxes
 127 and Docker images. Users not interested in building their own artifacts should
 128 see the Pre-Built section above.
 129
 130 #### Vagrant Base Boxes
 131
 132 The `vagrant` post-processor outputs built .box files into the current
 133 working directory.
 134
 135 ```
 136 <snip>
 137 Build 'qemu' finished.
 138
 139 ==> Builds finished. The artifacts of successful builds are:
 140 --> qemu: 'qemu' provider box: opendaylight-4.1.0-centos-7.2.1511-libvirt.box
 141 $ ls -rc | tail -n 1
 142 opendaylight-4.1.0-centos-7.2.1511-libvirt.box
 143 ```
 144
 145 Import the local box into Vagrant with:
 146
 147 ```
 148 $ vagrant box add --name "odl" opendaylight-4.1.0-centos-1511.box --force
 149 ==> box: Adding box 'odl' (v0) for provider:
 150     box: Downloading: file:///home/daniel/packaging/packer/opendaylight-4.1.0-centos-1511.box
 151 ==> box: Successfully added box 'odl' (v0) for 'virtualbox'!
 152 ```
 153
 154 To connect to your new box, you'll need a trivial Vagrantfile:
 155
 156 ```
 157 $ vagrant init -m odl
 158 $ cat Vagrantfile
 159 Vagrant.configure(2) do |config|
 160   config.vm.box = "odl"
 161 end
 162 ```
 163
 164 Boot the box and connect:
 165
 166 ```
 167 $ vagrant up
 168 $ vagrant ssh
 169 ```
 170
 171 OpenDaylight will already be installed and running:
 172
 173 ```
 174 $ sudo systemctl is-active opendaylight
 175 active
 176 ```
 177
 178 To connect to the Karaf shell:
 179
 180 ```
 181 $ ssh -p 8101 karaf@localhost
 182 # password: karaf
 183 ```
 184
 185 #### Docker Images
 186
 187 The `docker-tag` post-processor imports the built Docker image into your local
 188 image repository.
 189
 190 ```
 191 $ docker images
 192 REPOSITORY          TAG         IMAGE ID        CREATED         SIZE
 193 opendaylight/odl    4.1.0       8c9e8c24081e    2 days ago      1.408 GB
 194 ```
 195
 196 Use `docker run` to start a container. Point it at the Karaf executable
 197 to run OpenDaylight as the container's process.
 198
 199 ```
 200 $ docker run -ti opendaylight/odl:4.1.0 /opt/opendaylight/bin/karaf
 201 ```
 202
 203 [1]: https://www.packer.io/
 204
 205 [2]: https://www.packer.io/intro/getting-started/setup.html
 206
 207 [3]: https://git.opendaylight.org/gerrit/gitweb?p=integration/packaging/ansible-opendaylight.git
 208
 209 [4]: https://atlas.hashicorp.com/opendaylight/boxes/odl
 210
 211 [5]: https://hub.docker.com/r/opendaylight/