Nomad IIS Driver

A driver plugin for nomad to orchestrate windows IIS website tasks.

A "Website" is a combination of an application pool and a site (app, vdir, etc.).
Each allocation will create an application pool and site with the name being the allocation ID (guid).

This driver is heavily tested on Windows 2016+ and does not guarantee compatibility with older versions of Windows/IIS. IIS version and Windows versions are locked together and can be seen here. Each feature/config has a minimum IIS version associated so that one can dance around them to have nomad and the IIS driver work on an older machine. The easiest way to utilize unique features for a given IIS version should be to use the application pool and site config imports provided by the task config.

Configuration

Driver Config

Option	Type	Required	Default	Description
enabled	bool	no	true	Enable/Disable task driver.
stats_interval	string	no	1s	Interval for collecting `TaskStats`

Task Config

Option	Type	Required	Default	Min. IIS Version	Description
path	string	yes	nil	6.0	Path to IIS Compatible website directory.
apppool_config_path	string	no	nil	6.0	Path to App Pool XML Configuration File.
site_config_path	string	no	nil	6.0	Path to Site XML Configuration File.
apppool_identity	string	no	ApplicationPoolIdentity	6.0	Application Pool Identity e.g. ('SpecificUser', 'ApplicationPoolIdentity', etc..)
bindings	block list	no	nil	7.0	This is needed to tie IIS Bindings to Nomad's `resources`->`network` ports to IIS as well as specify IIS Binding specific settings

Bindings Block Config

A resource_port OR a port must be provided. Due to a current limitation, we can not force at least 1 required option between multiple options. There are plans to revisit combining port options to improve UX.

Option	Type	Required	Default	Min. IIS Version	Description
hostname	string	no	nil	7.0	HostName attribute for a given binding.
ipaddress	string	no	*	7.0	IPAddress attribute for a given binding.
port	string	yes	0	7.0	Tie a `resources`->`network` port label to the binding. This allows us to use a dynamic port given by Nomad.
type	string	yes	nil	7.0	Type is the binding's protocol e.g. ('http', 'https', etc..)
cert_hash	string	no	nil	7.0	Hash of a cert that exists prior to nomad allocating an IIS website. This must be set for SSL bindings.

For more info on IIS Bindings, you can go here

Environment Variables

Environment variables can be set like any other Nomad task via env or template stanzas. Environment variables are only supported for IIS 10.0+.

Meta Environment Variables

These meta env vars do not persist to the process/task. They are pulled from the env var list that is passed to the IIS application pool. These do not require a minimal IIS version as they are not used as env vars by IIS.

NOMAD_APPPOOL_USERNAME
- Sets the UserName of an application pool and will override the Application Pool Identity to SpecificUser
NOMAD_APPPOOL_PASSWORD
- Sets the Password of an application pool's specific user account

Why meta env vars?

Nomad currently doesn't have a clean way to use credentials to be used by the nomad job spec itself. To get around this and not provide the user/pass credentials in plain text on the nomad job spec is to have them passed by env vars and this allows users to utilize consul/vault via the template stanza to promote better security. Here is the respective Nomad issue.

Build & Test

Requirements

Nomad >=v1.0
- The driver will try to be backwards compatible with v0.11-v1.0 versions of Nomad, but tests will focus around v1.0 for ensuring stability with modern Nomad.
Go >=v1.15 (to build the provider plugin)
Vagrant >=v2.2
VirtualBox v6.0 (or any version vagrant is compatible with)

Building the driver

$ mkdir -p $GOPATH/src/github.com/Roblox
$ cd $GOPATH/src/github.com/Roblox
$ git clone git@github.com:Roblox/nomad-driver-iis.git
$ cd nomad-driver-iis
$ make build (This will build your nomad-driver-iis executable)

Tests

$ make test

This will run nomad-driver-iis tests in the provisioned vagrant VM.

Cleanup

   make clean

This will destroy your vagrant VM (along with all your changes) and remove the executable (win_iis.exe).

Contributing

Want to fix a bug, update documentation or add a feature?
PR's are welcome!!
Test your changes locally before contributing.

The easiest way to test your changes is make converge.
make converge will:

1) Build the executable (win_iis.exe)
2) Spin up a vagrant VM (vagrant up) if it's not already running.
3) Provision your changes into the VM (vagrant provision)

Once you are in the VM:

1) nomad-driver-iis codebase (hostpath) is mounted at C:\vagrant in the VM.
2) Plugin (executable) is available at C:\ProgramData\nomad\plugin
3) Logs are available at C:\ProgramData\nomad\logs.
4) Tail on logs in powershell:

   $ Get-Content -path "C:\ProgramData\nomad\logs\nomad-output.log" -wait

5) Launch an example IIS website:

   $ nomad job run C:\vagrant\examples\iis-test.nomad

License

Licensed under the Apache License, Version 2.0 (the "License"). For more information read the License.

Roblox / nomad-driver-iis

readme