This is the multi-page printable view of this section. Click here to print.

Return to the regular view of this page.

General Configuration

Initial Configuration

A single configuration file config.yaml is required to run Anchore - by default, this file is embedded in the Enterprise container image, located in /config/config.yaml. The default configuration file is provided as a way to get started, which is functional out of the box, without modification, when combined with either the Helm method or docker compose method of installing Enterprise. The default configuration is set up to use environment variable substitutions so that configuration values can be controlled by setting the corresponding environment variables at deployment time (see Using Environment Variables in Anchore.

Each environment variable (starting with ANCHORE_) in the default config.yaml is set (either the baseline as set in the Dockerfile, or an override in docker compose or Helm or through a system default) to ensure that the system comes up with a fully populated configuration.

Some examples of useful initial settings follow.

Default admin credentials: A default admin email and password is required to be defined in the catalog service for the initial bootstrap of enterprise to succeed, which are both set through the default config file using the ANCHORE_ADMIN_PASSWORD and ANCHORE_ADMIN_EMAIL environment variables respectively. The system defines a default email admin@myanchore, but does not define a default password. If using the default config file, the user must set a value for ANCHORE_ADMIN_PASSWORD in order to succeed the initial bootstrap of the system. To set the default password or to override the default email, simply add overrides for ANCHORE_ADMIN_PASSWORD and ANCHORE_ADMIN_EMAIL environment variables, set to your preferred values prior to deploying Anchore Enterprise. After the initial bootstrap, this can be removed if desired.

default_admin_password: '${ANCHORE_ADMIN_PASSWORD}'
default_admin_email: '${ANCHORE_ADMIN_EMAIL}'

Log level: Anchore Enterprise is configured to run at the INFO log level by default. The full set of options are CRITICAL, ERROR, WARNING, INFO, and DEBUG (in ascending order of log output verbosity). Admin accounts can set the system log level through the dashboard, the dashboard allows differing per-service log levels. Changes through the dashboard do not require a system restart. The log level can also be set globally (across all services) with an override for ANCHORE_LOG_LEVEL prior to deploying Anchore Enterprise, this approach requires a system restart to take effect.

log_level: '${ANCHORE_LOG_LEVEL}'

Postgres Database: Anchore Enterprise requires access to a PostgreSQL database to operate. The database can be run as a container with a persistent volume or outside of your container environment (which is set up automatically if the example docker-compose.yaml is used). If you wish to use an external Postgres Database, the elements of the connection string in the config.yaml can be specified as environment variable overrides. The default configuration is set up to connect to a postgres DB that is deployed alongside Anchore Enterprise Services when using docker-compose or Helm, to the internal host anchore-db on port 5432 using username postgres with password mysecretpassword and db postgres. If an external database service is being used then you will need to provide the use, password, host, port and DB name environment variables, as shown below.

db_connect: 'postgresql://${ANCHORE_DB_USER}:${ANCHORE_DB_PASSWORD}@${ANCHORE_DB_HOST}:${ANCHORE_DB_PORT}/${ANCHORE_DB_NAME}'

Manual Configuration File Override

While Anchore Enterprise is set up to run out of the box without modifications, and many useful values can be overriden using environment variables as described above, one can always opt to have full control over the configuration by providing a config.yaml file explicitly, typically by generating the file and making it available from an external mount/configmap/etc. at deployment time. A good method to start if you wish to provide your own config.yaml is to extract the default config.yaml from the Anchore Enterprise container image, modify it, and then override the embedded /config/config.yaml at deployment time. For example:

Extract the default config file from the anchore/enterprise container image:

# docker pull docker.io/anchore/enterprise:v5.X.X
# docker create --name ae docker.io/anchore/enterprise:v5.X.X
# docker cp ae:/config/config.yaml ./my_config.yaml
# docker rm ae

Modify the configuration file to your liking.
Set up your deployment to override the embedded /config/config.yaml at run time (below example shows how to achieve this with docker compose). Edit the docker-compose.yaml to include a volume mount that mounts your my_config.yaml over the embedded /config/config.yaml, resulting in a volume section for each Anchore Enterprise service definition.

...
  api:
...
    volumes:
     - /path/to/my_config.yaml:/config/config.yaml:z
...
  catalog:
...
    volumes:
     - /path/to/my_config.yaml:/config/config.yaml:z
...
  simpleq:
...
    volumes:
     - /path/to/my_config.yaml:/config/config.yaml:z
...
  policy-engine:
...
    volumes:
     - /path/to/my_config.yaml:/config/config.yaml:z
...
  analyzer:
...
    volumes:
     - /path/to/my_config.yaml:/config/config.yaml:z
...

Now, each service will come up with your external my_config.yaml mounted over the embedded /config/config.yaml.

1 - API Accessible Configuration

Anchore Enterprise provides the ability to view the majority of system configurations via the API. A select number of configurations can also be modified through the API, or through the System Configuration tab from the UI. This enables control of system behaviours and characteristics in a programmatic way without needing to restart your deployment.

Note

⚠️ At this time, only a few configurations are modifiable through this new API-backed mechanism yet. Full configuration continues to be achievable through the existing config file mechanism.

Configuration Provenance

Configuration values are established by a priority system which derives the final running value based on the location from which the value was read. This provenance priority mechanism enables backwards compatibility and increased security for customers wishing tighter control of their systems runtime.

1. Config File Source

Any configuration variable which is declared within an on-disk configuration file will be honored first (ie. via a Helm values.yaml). These configuration variables will be read-only through the API and UI. Any configuration that is currently set for your deployment will be preserved.

Note

⚠️ The use of environment variables for configuration values are treated with the same provenance as config file.

2. API Config Source

When a configuration variable is not declared in a config file and is one of the select few that are allowed to be modified via the API, its value will be stored in the system database. These configuration variables can be modified via the API and the changes will be reflected within the deployment within a short time without having to restart your deployment.

The following configuration variables are modifiable through the API:

services.analyzer.analyzer_scanner_config.malware.clamav.enabled
logging.log_level
services.apiext.logging.log_level
services.analyzer.logging.log_level
services.catalog.logging.log_level
services.policy_engine.logging.log_level
services.simplequeue.logging.log_level
services.notifications.logging.log_level
services.data_syncer.logging.log_level
services.reports.logging.log_level
services.reports_worker.logging.log_level

3. Anchore Enterprise Defaults

If a configuration variable has not been declared by any other source it inherits the default system value. These are values chosen by Anchore as safe and functional defaults.

For the majority of deployments we recommend you simply use the default settings for most values as they have been calibrated to offer the best experience out of the box.

⚠️ Note: These values may change from release to release. Notable changes will be communicated through Release Notes. Significant system behaviour changes will not be performed between minor releases. If you wish to ensure a default is not changed, “pin” the value either by providing it explicitly in the config file or setting it directly via the API (when available).

Blocked by Config File

Attempts to set a configurations through the API may return a blocked_by_config_file error. This error is raised when a configuration variable is not API editable as it is set in a config file.

Locations to inspect for a pinned config value are:

the Helm attached values.yaml file (continue reading for further instructions)
the compose attached config.yaml file
the environment variables being passed into the container

Disabling Helm Chart Configs

For Helm users, to make a value configurable through the API, set the value in the attached values.yaml to "<ALLOW_API_CONFIGURATION>"

As an example:

services:
  analyzer:
      malware:
        clamav:
          enabled: "<ALLOW_API_CONFIGURATION>"

API Configurations Refresh

Each running container will refresh its internal configuration state approximately every 30 seconds. After making a change please allow a minute to elapse for the changes to flush out to all running nodes.

Config File Configurations Refresh

Changes made to a mounted config file will be detected and will cause a system configuration refresh. If a configuration variable that is changed requires a system restart a log message will be printed to that effect. If a system is pending restart, none of the changes will take effect until this is performed. This config file watcher includes a mounted .env file if in use.

Configu Validation

In a future major release of Anchore Enterprise, we will be enabling a strict mode type and data validation for the configuration. This will result in any non-compliant Enterprise deployments failing to boot. For now this is not enforced.

For awareness, validation of your configuration variables and values will occur during system boot. If any configuration fails this validation, a log message mentioning lenient mode will be published. This will be accompanied by details on which entries have failed. To avoid system downtime in a future major release, consider resolving these issues today.

Secret Values

Secret values cannot be read through the API, they will return as the string <redacted> it is however possible to update them. It is not possible to set any secret value to the string <redacted>.

Security Permissions

Config file permissions have not changed, they are editable by the system deployer. API requests to make changes to configuration will only be accepted if coming from an Anchore User with system-admin permissions.

2 - Environment Variables

Environment variable references may be used in the Anchore config.yaml file to set values that need to be configurable during deployment.

Using this mechanism a common configuration file can be used with multiple Anchore instances with key values being passed using environment variables.

The config.yaml configuration file is read by Anchore and any references to variables prefixed with ANCHORE will be replaced by the value of the matching environment variable.

For example in the sample configuration file the host_id parameter is set be appending the ANCHORE_HOST_ID variable to the string dockerhostid

host_id: 'dockerhostid-${ANCHORE_HOST_ID}'

Notes:

Only variables prefixed with ANCHORE will be replaced
If an environment variable is referenced in the configuration file but not set in the environment then a warning will be logged
It is recommend to use curly braces, for example ${ANCHORE_PARAM} to avoid potentially ambiguous cases

Passing Environment Variables as a File

Environment Variables may also be passed as a file contained key value pairs.

ANCHORE_HOST_ID=myservice1
ANCHORE_LOG_LEVEL=DEBUG

The system will check for an environment variable named ANCHORE_ENV_FILE if this variable is set then Anchore will attempt to read a file at the location specified in this variable.

The Anchore environment file is read before any other Anchore environment variables so any ANCHORE variables passed in the environment will override the values set in the environment file.