Environment variables simplify the process of container management because you can make
all of your configuration changes in one place.
Important:
If you're running PingAccess
in a clustered deployment, you must apply environment variable changes to each
cluster node individually. PingAccess can't replicate property files, and by extension,
environment variables, from the administrative node.
When PingAccess starts, it
overrides property values in the configuration files with the values of the environment
variables. During startup, PingAccess also logs environment variables that start with
PA_
in the pingaccess.log file. Some
initialization items might go to system.out.
Important:
If a utility uses a configuration file that's been modified by an environment
variable, the utility also inherits any changes made by that environment
variable.
For example, the obfuscate.sh
script uses properties from the
pa.jwk.properties file. If you create an environment
variable that overrides a property in that file, obfuscate.sh
also
uses that modified property value.
Naming convention
To set your environment variables, use a deployment tool of your choice, such as
Kubernetes or Docker Compose. Use the format
PA_<FILE_NAME_WITHOUT_EXTENSION>_<PROPERTY_NAME>
,
where:
PA
is short for PingAccess. You must begin all environment variables with this
phrase.
- <FILE_NAME_WITHOUT_EXTENSION> is the name of the file
containing the property that you want to modify. Leave out the file
extension.
- <PROPERTY_NAME> is the name of the property that you
want to modify.
When naming an environment variable:
- Replace any periods in the file or property name with a single underscore.
- Replace any dashes with two underscores.
- Only use letters and underscores. Leave out any separators, such as parenthesis,
braces, brackets, commas, or semicolons.
- Write the whole environment variable in upper case.
Note:
Make sure that you use consistent case and spelling when setting
environment variables to avoid unexpected behavior. If you have multiple
references to the same property but case varies between those
references, PingAccess can only use one version.
Examples
- The environment variable for the
pa.hostkey.keyId
property in
the pa.jwk.properties file is
PA_PA_JWK_PA_HOSTKEY_KEYID.
- The environment variable for the
maxIdle
property in the
log4j2.db.properties file is
PA_LOG4J2_DB_MAXIDLE.
- The environment variable for the
admin.header.X-Content-Type-Options
property in the
run.properties file is
PA_RUN_ADMIN_HEADER_X__CONTENT__TYPE__OPTIONS.
- The environment variable for the
engine.httptransport.socketTimeout
property in the
run.properties file is
PA_RUN_ENGINE_HTTPTRANSPORT_SOCKETTIMEOUT.
Modifiable properties
You can override the value of any property defined in one of the property files from
the <pa>/conf directory. These
property files include:
- engine-registration.properties
- fips-mode.properties
- log4j2.db.properties
- pa.jwk.properties
- run.properties
Note:
It was already possible to override settings in the
engine-registration.properties file with the
ENGINE_NAME environment variable. You can continue to
use the ENGINE_NAME environment variable, or you can update
all instances to the new format for consistency.
Don't create environment variables for properties defined in:
- Files outside of the /conf directory
- .properties files from the
/conf/localization directory.