PingAM 8.0.0

Store configuration data in JSON files

AM can read its configuration from JSON files instead of directory servers. Configuration stored in JSON files is called file-based configuration (FBC).

File-based configuration (FBC) is best-suited to a DevOps-style deployment, with the associated tools and practices of that approach.

Static FBC data is written to configuration files in the file system and checked into a source control system, such as Git.

AM instances are created as Docker images, with the FBC incorporated into the image.

Kubernetes deployment using file-based configuration.

You can insert variables into these configuration files before you check them into source control. The variables are substituted with the appropriate values at runtime when you start the Docker container. Using variables lets you reuse the same base configuration files for multiple instances, and different staging environments. For example, development, QA, or pre-production, which are then promoted to production.

In an existing deployment, you can migrate to FBC after you’ve upgraded to AM 8.

If you’re setting up an AM deployment from scratch, read Passive install with FBC to create a file-based configuration store.

How AM reads FBC

An initial startup with FBC enabled writes configuration files with the following structure:

noninteractive-install.properties

You specify a limited set of environment variables on startup. AM writes these environment variables to a configuration properties file, /path/to/am/config/config/services/noninteractive-install.properties, when the server starts.

The values in the noninteractive-install.properties file are used on subsequent startups, unless you set these properties in the deployment configuration layer.

Baseline configuration layer

The baseline configuration files are read-only and are located under /path/to/am/config/baseline/config/services.

These files include placeholders that are resolved with values of environment variables. The baseline layer lets you define a configuration that works across different environments, with a few distinct parameters that are specific to each server instance.

For example, three instances might have the same configuration but different keystore locations and URLs. Those differences are resolved with environment variables at startup.

Deployment configuration layer

The deployment configuration files are read/write and are located under /path/to/am/config/config/services.

Changes made through the AM admin UI and REST API are written to the deployment configuration layer.

This layer overrides the baseline configuration on a file-by-file basis. In other words, AM reads its configuration from the baseline configuration until you add corresponding files to the deployment configuration layer.

In summary, AM looks for its configuration in the following order:

  1. Deployment configuration layer

  2. Baseline configuration layer

  3. noninteractive-install.properties

FBC and AM sites

A site refers to multiple AM servers that share a single configuration store.

When your configuration is stored in files, you don’t need to group AM servers into sites because each AM server has its configuration stored locally.

Instead of pointing at a shared configuration store, servers using FBC are exact copies of each other. Each server is assumed to be in its own discrete site, along with its configuration.

The following diagram illustrates the difference between configuration stored in an LDAP store and configuration stored in files on the file system:

File-based configuration vs LDAP configuration store

If you migrate to FBC from an LDAP configuration store, the migration utility enforces a single site and a single server instance. If your deployment has more than one server or more than one site, the migration retains the first site and uses this site in the resulting output configuration. If your deployment has no sites configured, a single site is added.