Skip to main content

Parameters

Parameters allow you to pass information to your application to configure its runtime behaviour.

Some typical use cases are:

  • change the application's behavior depending on the scope type (eg: region, read vs write, etc)
  • let the application know its slug / identifier to retrieve configuration
  • load application parameters (eg: blocked users),
  • configure 3rd party software (eg: configuration files)

How parameters work​

Environment variables vs. files​

Parameters can be delivered to your applications as environment variables or files (server-based scopes only).

Files can be delivered to any directory you choose and by default are delivered to the /app-data/ directory.

Environment variables are limited to 4K in size while files can be up to 1 MB in size.

Parameter level: application, dimension & scope​

In nullplatform, parameters can be set at either application-level, using dimensions or at scope-level. This means that you can set a value for the whole application, but you can also customize it for specific scopes. We can also set a value for a group of scopes, by setting dimensions.

Here's an example of Application level vs Scope level:

Let's now consider this topology:

We have four scopes, three of them are development environments and one is a production environment

Based on what we know so far, by having only Application level and Scope level way of defining parameters, we can either set a parameter at:

  • Application level: this will affect all scopes
  • Scope level: this will affect only the scope where the parameter is set

We can have a way of defining a parameter that can affect for example, all development environments, i.e., 3 scopes at once, with the same value. This is where dimensions come into play.

When setting the parameter values, if we set environment=development, the parameter will be applied to all scopes that have the environment dimension set to development. In the following diagram we can find an example of this:

Another example: in case of needing to set a parameter value only for our services deployed in the US. We can set the dimension country=us and the parameter will be applied to all scopes that have the country dimension set to us.

NB. Here we are setting a param value for multiple scopes at once. For the rest of the scopes we can either use another dimension or set the value at Application level or Scope level.

Order of precedence​

Let's recall that we can have parameter values at three levels:

  • Application: the most extensive one, meaning that it will affect all scopes
  • Dimension: an intermediate level, meaning that it will affect all scopes that have the dimension set to the value we set the value for
  • Scope: the most specific one, meaning that it will only affect the scope that we set it for

When we have a parameter value set at multiple levels, the order of precedence is the following:

The order of precedence means that, in case of having a parameter at application level, if we then set a value for the same parameter at scope level, the scope level value will be applied.

If we set a parameter value for a dimension, and then we set a value for the same parameter at scope level, the scope level value will be applied.

Let's suppose we set the following parameter values:

  • Environment variable TIMEOUT
    • For the dimension environment=development the value is 1000
    • For the scope development_us the value is 2000

Then:

  • an application deployed on the scope development_us will get the value 2000
  • an application deployed on the scope development_rest with dimension environment=development will get the value 1000

Secrets​

If you want to store sensitive information such as database passwords, you have to mark the parameter as secret.

Secret parameter can be overwritten but cannot be read again.

Read only​

Certain roles are allowed to create read only parameters that can only be modified only by roles with a specific permission.

How parameters are applied​

To keep environments predictable we favor immutability, therefore we do not hot-reload parameters and any change will require a new deployment.

Whenever you roll back a deployment, we apply the set of parameters that were originally present on that deployment, thus guaranteeing a safe rollback process.

Versioning​

Parameters values are versioned, meaning that every change to its values will generate a new incremental version.

Previous versions & Roll backs. You can query old versions of parameters and roll back to them (this actually creates a new version with the values from the corresponding version). It is also possible to create a new version based on an older version plus new values / changes that you want to introduce.

Packing changes. The same way you commit several files at once in Git, you can commit several changes at once in a parameter, packing multiple changes in a single new version of the parameter.

This graph explains a possible lifecycle for a parameter:

Some things to note here are:

  • When the parameter is created, there's no version assigned. The version is only assigned once the first value is added.
  • Note that the step #4 is packing 2 changes at once, creating a single new version for the parameter.

API​

All the operations done on parameters are accessible trough our API, check the API section for more information.