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
- Sets the UserName of an application pool and will override the Application Pool Identity to
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 [email protected]: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:
- Build the executable (win_iis.exe)
- Spin up a vagrant VM (
vagrant up) if it's not already running. - Provision your changes into the VM (
vagrant provision)
Once you are in the VM:
- nomad-driver-iis codebase (hostpath) is mounted at
C:\vagrantin the VM. - Plugin (executable) is available at
C:\ProgramData\nomad\plugin - Logs are available at
C:\ProgramData\nomad\logs. - Tail on logs in powershell:
$ Get-Content -path "C:\ProgramData\nomad\logs\nomad-output.log" -wait - Launch an example IIS website:
$ nomad job run C:\vagrant\examples\iis-test.nomad
License
Copyright 2020 Roblox Corporation
Licensed under the Apache License, Version 2.0 (the "License"). For more information read the License.