Skip to content

Filesystem Configuration

Jump to bottom
Jason Mueller edited this page Mar 2, 2015 · 8 revisions

A file-based configuration repository is a simple way to start if you don't already have a system in place and it lends itself well to versioning using the tools you already use (Git, Mercurial, etc.) and Powerdeploy includes support for using a filesystem structure as a configuration source.

Format

Configuration variables are stored in a collection of settings.pson files containing PowerShell hash tables with key / value pairs for the variables in the configuration.

@{
    'HostUrl' = 'http://localhost:8888'
    'DebugLevel' = 'Verbose'
    'OtherServiceUrl' = 'http://otherhost:8122/getvalues'
    'ApiVersion' = '1.0.0'
    'DbConnection' = '${env:SqlDatabase}'
}

Structure

The relative location and names of the configuration files determine the scope to which the variables will apply. Configuration can be applied based on application version, environment, and target computer.

/
|-- app/
    |-- MyWebsite/
        |-- 1.0.0/
            |-- development.settings.pson
            |-- integration.settings.pson
            |-- production.settings.pson
            |-- settings.pson
|-- env/
    |-- development.settings.pson
    |-- integration.settings.pson
    |-- production.settings.pson
    |-- webserver01.production.settings.pson
    |-- webserver02.production.settings.pson

The structure has changed dramatically from earlier versions of Powerdeploy to improve maintainability of the files and to make comparison of different environments easier (through the use of whatever diff tool you are familiar with).

Scoping

There are two primary scopes for variables, application and environment.

Managing Configuration by Application

Application variables provide targeted configuration of specific values during application deployment. These variables are the primary means of configuring an application at deployment time and are designed to meet the needs of specific versions of an application.

When variables are requested, they are located based on

  • the application name
  • the application version
  • the target environment

Including the version number allows the configuration to vary over time as changes to the application drive the need for different configuration values.

Application variables are retrieved from the app\<application-name>\<application-version>\<environment-name>.settings.pson file where your configuration is stored.

Note: the environment name part of the filename must contain only the following characters or the file will not be parsed: letters, numbers, hyphen (-), underscore (_), and hash/pound (#).

Environment Fallback

Variables for each environment to which an application will be deployed are specified in individual settings files (integration.settings.pson for example), one for each environment. In cases where an application will have identical values regardless of environment or where a specific value will have a default with overrides for some environments, you can add values to a settings.pson without an environment prefix.

Version Fallback

Creating a version directory for every version of your application would be tedious and error prone and applications are not likely to change configuration requirements with every new version (especially in high frequency deployment environments).

Rather than require a directory for each version, Powerdeploy will locate the settings files starting with an exact version match and then fall back to the most recent previous version prior to the version requested, according to Semantic Versioning precedence rules. Note that Powerdeploy does not currently support the use of pre-release version components.

Managing Configuration by Environment#

Environment variables are useful for values that version and change with the environment and not with versions of the application. Two common scenarios where variables are likely to change with the environment, at a different rate than the application, are the location of other services in the environment and the context in which your application will run.

Advertising Environment Services

Often, multiple applications or other dependencies will be available in an environment and you'd like to advertise the location of these dependencies for every application and version that might require them.

You can use environment variables to make these available. Common shared dependencies might be:

  • Databases (connection strings)
  • Web services (URLs)
  • Message queues (queue paths)
  • File shares (file system paths)

Managing Context

Many times you will need to configure a specific application but the actual value of the variable is under the control of an infrastructure team or is expected to change at a different rate or at different times than application releases. Common uses are:

  • API keys
  • User IDs
  • Passwords (make sure you encrypt these)
  • Internal Web APIs (URLs)

Environment Variable Applicability

Note that either scenario works the same from a configuration perspective. You specify variables at the environment level and they can be used by applications when they are deployed. Environment variables are never used unless they are explicitly referenced by application variables. The variables used to configure an application are always under control of the application (and version). Environment variables are just a convenient way to reduce the management burden of configuration.

Remember that these are deployment-time configuration variables. They won't change running applications when they are updated. If you update an environment setting due to a change in the environment (relocating a database, changing a password, moving a web service), you'll need to redeploy the application for the settings to be effective.

Environment variables are retrieved from the env\<environment-name>\settings.pson file where your configuration is stored.

Note: the environment name part of the filename must contain only the following characters or the file will not be parsed: letters, numbers, hyphen (-), underscore (_), and hash/pound (#).

Placeholders

Since environment-scoped variables are no longer applied implicitly (as they were with earlier versions of Powerdeploy < 1.0), applications must have a way to explicitly reference them.

Application-scoped variables can use a placeholder that will resolve to an environment-specific value using the ${env:<variable-name>} syntax as the value of variable. For example, to resolve a DbConnection variable the value of a SqlDatabase variable specified in the environment settings:

# settings\app\MyWebsite\1.0.0\acceptance\settings.pson
@{
  'DbConnection' = '${env:SqlDatabase}'
}

Example

It's probably helpful to see what happens when variables are requested given some files with variables in them. The example files are located in the Examples\Variables folder with the Powerdeploy module.

Assume that we have specified settings for the acceptance environment.

# settings\env\acceptance\settings.pson
@{
    'PaymentServiceUrl' = 'http://paymentsite.local/uat'
    'SqlDatabase' = 'Data Source=DBServer\uat;Initial Catalog=AppData;Integrated Security=True;'
}

Also assume that we've specified settings for version 1.0.0 of the MyWebSite application

# settings\app\MyWebsite\1.0.0\settings.pson
@{
    'HostUrl' = 'http://localhost:8888'
    'DebugLevel' = 'Verbose'
    'OtherServiceUrl' = 'http://otherhost:8122/getvalues'
    'ApiVersion' = '1.0.0'
    'DbConnection' = '${env:SqlDatabase}'
}

and settings for the acceptance environment for the application.

# settings\app\MyWebsite\1.0.0\acceptance.settings.pson
@{
    'DebugLevel' = 'Warn'
    'OtherServiceUrl' = 'http://otherhost:8124/getvalues'
}

When Powerdeploy resolves the variables for MyWebsite version 1.0.0 going to the acceptance environment, the resultant variables would be:

# settings\app\MyWebsite\1.0.0\settings.pson
@{
    'HostUrl' = 'http://localhost:8888'
    'DebugLevel' = 'Warn'
    'OtherServiceUrl' = 'http://otherhost:8124/getvalues'
    'ApiVersion' = '1.0.0'
    'DbConnection' = 'Data Source=DBServer\uat;Initial Catalog=AppData;Integrated Security=True;'
}

Note how the variables are merged together:

  • HostUrl is specified only in the environment-agnostic application variables and is used from there as a default.
  • ApiVersion is specified only in the environment-agnostic application variables and is used from there as a default.
  • DebugLevel is specified in the environment-agnostic file but it is also in the environment-specific file, so the specific one is used.
  • OtherServiceUrl is specified in the environment-agnostic file but it is also in the environment-specific file, so the specific one is used.
  • DbConnection is specified only in the environment-agnostic file and is pulled from there, but it uses a placeholder to reference a variable in the environment configuration, so the environment configuration is used.

Clone this wiki locally