Skip to main content

Parameters

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

Some typical use cases include:

  • Change the application's behavior depending on the scope type (e.g., region, read vs. write)
  • Provide the application with its slug/identifier to retrieve configuration
  • Load application-specific parameters (e.g., blocked users)
  • Configure third-party software (e.g., 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; by default, they are placed in the /app-data/ directory.

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

File support limitations​

While parameters can be delivered as files, it’s important to note that only text-based files are supported. Binary formats such as PDFs or images may not work correctly due to internal processing applied to the content.

Specifically:

  • Uploaded files are not delivered “as-is” — they are processed as UTF-8 encoded text.
  • This means binary formats like PDFs may get corrupted or become unusable by the application.

If you’re unsure whether a file format is supported, try opening it in a UTF-8 text editor — if it’s unreadable, it’s not a good candidate for file parameters.

Using PDFs as parameters​

The parameter system is not designed for binary files like PDFs. Attempting to upload one may result in encoding issues that corrupt the content.

Upload the PDF to object storage (e.g., S3) and pass its URL as a parameter. This allows your application to fetch the file at runtime without encoding issues.

Example:

destination_path: "https://my-bucket.s3.amazonaws.com/help-doc.pdf"

Note: See our Parameters API docs for more info.

Parameter levels: application, dimension, and scope​

In nullplatform, parameters can be set at the application level, at the scope level, or by using dimensions. This means you can:

  • Set a value for the whole application
  • Override it for specific scopes
  • Group scopes using shared dimensions and apply values to all of them

Here’s an example comparing application-level vs. scope-level parameters:

Let’s now consider this topology:

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

With only application-level and scope-level parameters, we can:

  • Set a value at the application level, which affects all scopes
  • Set a value at the scope level, which affects only that scope

But what if we want to set the same value for all development environments (i.e., multiple scopes at once)? That’s where dimensions come into play.

By assigning a dimension like environment=development, the parameter will apply to all scopes that share that dimension:

Another example: if you want to apply a parameter only to services deployed in the US, you can use the dimension country=us. This value will apply to all scopes that have that dimension.

Note: In this case, you're applying the same parameter value to multiple scopes. For all other scopes, you can use another dimension or set values at the application or scope level.

Order of precedence​

You can define parameter values at three levels:

  • Application – the broadest level, applies to all scopes
  • Dimension – an intermediate level, applies to scopes with matching dimension values
  • Scope – the most specific level, overrides all others

The order of precedence is:

  1. Scope
  2. Dimension
  3. Application

If a parameter is set at multiple levels, the most specific one is applied.

Example:

  • TIMEOUT is defined as:
    • 1000 for the dimension environment=development
    • 2000 for the scope development_us

Then:

  • A deployment in development_us gets 2000
  • A deployment in another development scope gets 1000

Secrets​

If you want to store sensitive information (e.g., database passwords), mark the parameter as secret.

  • Secret parameters can be overwritten
  • Reading secret values requires specific permissions

Note: See Accessing secret values for more information.

Read-only parameters​

Certain roles can create read-only parameters, which can only be modified by roles with specific permissions.

How parameters are applied​

To keep environments predictable, we favor immutability: parameters are not hot-reloaded. Any change to parameter values requires a new deployment.

If you roll back a deployment, we automatically restore the parameter values that were present at the time of that deployment — ensuring safe and consistent rollbacks.

Versioning​

Parameter values are versioned. Every time you change the value of a parameter, a new version is created.

Previous versions & rollbacks​

  • You can query old versions of parameters
  • You can roll back to a previous version, which creates a new version with the previous values
  • You can also start from a previous version and apply new changes on top

Packing changes​

Just like committing multiple files in Git, you can batch multiple changes into a single new parameter version.

Example lifecycle:

Some things to note here:
  • A new parameter has no version until values are added.
  • You can apply multiple updates in one commit to create a single version.

API and CLI​

All parameter operations can be performed through the API or the CLI, depending on your preferred workflow.

You can use them to:

  • Create, update, or delete parameters
  • Retrieve current values or past versions
  • Roll back to previous versions
  • Apply values at application, scope, or dimension level
  • Mark parameters as secrets or read-only

Note: See the API reference for API and CLI details and usage examples.