Code refactoring

oracle-linux-image-tools/.gitignore

@@ -0,0 +1,3 @@
+# Ignore custom property files
+env.properties.*
+!env.properties.defaults

oracle-linux-image-tools/CONTRIBUTING.md

@@ -0,0 +1,38 @@
+# Contributing
+
+Oracle welcomes contributions to this repository from anyone. If you want to submit a pull request to fix a bug or enhance code, please first open an issue and link to that issue when you submit your pull request. If you have any questions about a possible contribution, feel free to open an issue too.
+
+## Contributing to the ol-sample-scripts repository
+
+Pull requests can be made under
+[The Oracle Contributor Agreement](https://www.oracle.com/technetwork/community/oca-486395.html) (OCA).
+
+For pull requests to be accepted, the bottom of your commit message must have
+the following line using your name and e-mail address as it appears in the
+OCA Signatories list.
+
+```
+Signed-off-by: Your Name <you@example.org>
+```
+
+This can be automatically added to pull requests by committing with:
+
+```
+git commit --signoff
+```
+
+Only pull requests from committers that can be verified as having
+signed the OCA can be accepted.
+
+### Pull request process
+
+1. Fork this repository
+1. Create a branch in your fork to implement the changes. We recommend using
+the issue number as part of your branch name, e.g. `1234-fixes`
+1. Ensure that any documentation is updated with the changes that are required
+by your fix.
+1. Ensure that any samples are updated if the base image has been changed.
+1. Submit the pull request. *Do not leave the pull request blank*. Explain exactly
+what your changes are meant to do and provide simple steps on how to validate
+your changes. Ensure that you reference the issue you created as well.
+We will assign the pull request to 2-3 people for review before it is merged.

oracle-linux-image-tools/README.md

@@ -1,33 +1,108 @@
-# Description
-This repository provides tools to build Oracle Linux images for deployment in Microsoft Azure cloud and Oracle VM Server. 
-The images built by these tools contain a minimal installation with a set of pre-installed packages and target packages. 
-Image building is accomplished using Packer to build images from the Oracle Linux ISO using Oracle VM VirtualBox. 
-Images built for Oracle VM Server are OVA format. Images for Azure are VHD format.
-
-Target packages for Azure: WALinuxAgent
-
-Target packages for OVM: oracle-template-config + vmapi
+Oracle Linux image tools
+========================
 
-### Environment Properties
-
-Setup env.properties file in your workspace directory with appropriate settings. A sample file can be found in the repo.
+# Description
+This repository provides tools to build Oracle Linux images for cloud deployment.
 
-### Build instructions
+The images built by these tools are based on distribution flavours and target packages.
+Image building is accomplished using Packer to build images from the Oracle Linux ISO using Oracle VM VirtualBox.
 
-1) Install packer and VirtualBox: `yum --enablerepo=ol7_developer install packer VirtualBox-6.0`
+The tool currently supports:
+- Distributions:
+ - Oracle Linux 7 update 7 -- Slim 
+ A minimal set of packages is installed
+- Clouds:
+ - Microsoft Azure cloud 
+ Target packages: WALinuxAgent 
+ Image format: VHD
+ - Oracle VM Server 
+ Target packages: oracle-template-config + vmapi 
+ Image format: OVA
+ - Generic (No cloud setup) 
+ Target packages: none 
+ Image format: OVA
 
-2) Clone this repo to the build system: `git clone https://github.com/oracle/ol-sample-scripts`
+# Build instructions
+1. Install packer and VirtualBox: 
+ `yum --enablerepo=ol7_developer install packer VirtualBox-6.0`
+1. Clone this repo: 
+ `git clone https://github.com/oracle/ol-sample-scripts.git`
+1. The build script need root privileges during the build.
+ Ensure `sudo` is properly configured for your build user
+1. Set up a separate workspace directory where the image will be built.
+ Ensure there is enough free space in the workspace partition, the builder will need up the two times the image size.
+1. Configure your build environment in the `env.properties` file (or in a copy). 
+ Minimal configuration:
+ - `WORKSPACE`: path of your workspace directory
+ - `ISO_URL`: location of the Oracle Linux distribution ISO
+ - `ISO_SHA1_CHECKSUM`: SAH1 checksum for the ISO file
+ - `CLOUD`: cloud target (azure, ovm or none)
+1. Run the buider: 
+ `./bin/build-image.sh --env ENV_PROPERTY_FILE`
 
-3) Set up a separate workspace directory where the image will be built. Export WORKSPACE environment variable with the workspace directory:
+# Advanced configuration
+For a given Oracle Linux distribution and target Cloud, the following properties are taken in consideration:
+- Global `env.properties.default` file
+- Distribution `env.properties` file
+- Cloud `env.properties` file
+- Cloud distribution specific `env.properties` file
+- Local `env.properties` file (passed as parameter to the builder)
 
- `export WORKSPACE=/Image-build`
+Files are processed in that order. 
+As user you should only make changes in your local `env.properties` where you can override any definition from the previous property files. 
+Relevant parameters are documented in the distributed [`env.properties`](env.properties) file.
 
-4) Copy Kickstart Config files `azure.cf` and `ol.cf` to a http server that is accessible from the build system.
+# Builder architecture
+## Directory structure
+The `build-image` script relies on the following directory structure:
+- distr: directory for all Oracle Linux distribution
+ - _distribution name_
+ - env.properties: distribution parameters
+ - _name_-ks.cfg: kickstart file for the distribution
+ - provision.sh: provisioning script which is run in the VM after installation
+ - image-scripts: parameter validation, kickstart customisation and image cleanup scripts run on the host
+ - files (directory): all files in this directory will be copied in the VM during provisioning
+- cloud: directory for all target clouds
+ - _cloud name_
+ - env.properties: cloud parameters
+ - provision.sh: provisioning script which is run in the VM after installation
+ - image-scripts: parameter validation and image cleanup and packaging scripts run on the host
+ - files (directory): all files in this directory will be copied in the VM during provisioning
+ - _distribution name_: in case a a distribution specific action needs to be done for this cloud target, it can be defined in this directory.
 
-5) OVM images require `mkovf`, which is provided by the `open-ovf` package on the Oracle VM Server ISO or from upstream.
+Most of the files are optional, only define what is needed.
 
-6) Copy the Azure license file provided in the repo to a http server.
+## Build process
+The builder will process the directories in the following order:
+1. Read properties files as described in [advanced configuration](#advanced-configuration). 
+ The properties are available in all scripts, on the host and in the VM during provisioning. 
+ Properties can be validated at distribution / cloud level:
+ - distr::validate
+ - cloud::validate
+ - cloud_distr::validate
+1. Select a kickstart file from _distr_ and customise it. The following hooks are called if defined:
+ - distr::kickstart
+ - cloud_distr::kickstart
+1. Stage files from the _files_ directories. These files are copied during provisioning in `/tmp/packer_files` in the VM.
+1. Run packer to provision the VM image.
+ During provisioning the `provision.sh` scripts run in the following order:
+ - distr::provision
+ - cloud::provision
+ - cloud_distr::provision
+ - cloud_distr::cleanup
+ - cloud::cleanup
+ - distr::cleanup
+1. Image cleanup: the generated image is mounted on the host and the `image-scripts` scripts are run:
+ - cloud_distr::cleanup
+ - cloud::cleanup
+ - distr::cleanup
+1. Image packaging: the generated image is packaged in its final format.
+ Only the first script found is executed:
+ - cloud_distr::image_package
+ - cloud::image_package
 
-7) Build the image: `sh -x packer_builder.sh`
+# Feedback
+Please provide feedback of any kind via GitHub issues on this repository.
 
-8) Image will copied to: `$WORKSPACE/vm_images`
+# Contributing
+See [CONTRIBUTING](CONTRIBUTING.md) for details.