Configuration YAML file

Site Planner is configured through a YAML formatted file which must be read on start-up from /run/secrets/configuration.yaml. This file is generated by mounting a secret on the pod.

Required orchestration properties

Site Planner must be configured with access credentials for your orchestration environment. The orchestration properties deliberately match those used in LMCTL. The only difference being they are uppercased and prefixed with TNCO_.

All properties supported by LMCTL may be set however, a short list of the most common properties required to configure access is as follows:

Name Default Description
TNCO_ADDRESS - The address of the orchestration API gateway (Ishtar). Do NOT include any paths on the end of this address. E.g. if Ishtar is installed in the same namespace as site planner then you can likely use https://cp4na-o-ishtar:8280, where cp4na-o-ishtar is the name of the internal Kubernetes service.
TNCO_USERNAME - Name of the Zen user to be used when authenticating API requests
TNCO_API_KEY - Zen API key for the mentioned user

In addition, the following property should be set to ensure the Site Planner UI can display valid links to the network automation UI where necessary.

Name Default Description
TNCO_UI_ADDRESS - Base address used to access the network automation UI.
Name Default Description
ZEN_MODE False. When deployed as part of IBM® Cloud Pak for Network Automation on OCP this will be True. Enable/disable the use of Zen users for authentication
ZEN_FRONT_DOOR_URL - The URL of the Zen front door where a user is expected to login. The Site Planner will redirect unauthenticated users attempting to access the UI to this URL.
ZEN_JWT_PUB_KEY_ENDPOINT https://internal-nginx-svc:12443/auth/jwtpublic The address of the Zen endpoint used to load the public key used to verify the signature of Zen user access tokens
ZEN_CERT_PATH /var/certs/zenkeystore/ca.crt (file expected to be mounted at installation time) File path to the Zen CA cert, required to verify connection to the ZEN_JWT_PUB_KEY_ENDPOINT
ZEN_AUDIENCE DSX The intended recipient of the token, required to decode Zen JWT tokens

Required database connection details

Set the Postgres database connection details.

Name Default Description
DB_NAME netbox Name of the existing Postgres database to use
DB_HOST localhost Hostname or IP address of the Postgres service
DB_PORT 5432 TCP port of the PostgreSQL service
DB_USER - Username for authentication
DB_PASSWORD - Password for authentication
DB_CONN_MAX_AGE 300 Maximum age for any persistent database connection (to reduce re-connection on each request)
DB_SSLMODE prefer Valid Postgres SSL connection mode, which determines if SSL is required

Required secret key

This key will be used to in the creation of new cryptographic hashes for encrypting passwords and HTTP cookies. This key should remain a secret and not be shared.

It's recommended that this key is at least 50 characters in length and features a mixture of digits, letter and symbols.

Changing the SECRET_KEY will invalidate all existing sessions.

Required Redis database connection details

Note: The Redis database connection settings are no longer used by the site-planner image. These settings are ignored and only exist for legacy reasons.

Set the Redis connection details. Site Planner requires two independent Redis databases, one is used for the background task/webhook feature whilst the other is used for caching. Note: you can use two different Redis clusters or one Redis cluster, as one can support multiple databases.

If you are using Redis sentinels, then you should set the *__SENTINELS and *_SENTINEL_SERVICE properties instead of *_HOST/*_PORT.

Background task/webhook properties:

Name Default Description
REDIS_SENTINELS - Comma separated list of Redis sentinel hostname/port pairs e.g. (sentinel1:26379, sentinel2:26379)
REDIS_SENTINEL_SERVICE localhost Name of the master service to connect to
REDIS_HOST localhost Hostname or IP address of the Redis service (if not using Sentinels)
REDIS_PORT 6379 TCP port of the Redis service (if not using Sentinels)
REDIS_PASSWORD - Password for authentication
REDIS_DATABASE 0 Numeric database ID to connect to
REDIS_TIMEOUT 300 Max connections timeout
REDIS_SSL False Use SSL connection

For caching, the properties are the same but are instead prefixed with REDIS_CACHE instead of REDIS_:

  • REDIS_CACHE_SENTINELS
  • REDIS_CACHE_SENTINEL_SERVICE
  • REDIS_CACHE_HOST
  • REDIS_CACHE_PORT
  • REDIS_CACHE_PASSWORD
  • REDIS_CACHE_DATABASE
  • REDIS_CACHE_TIMEOUT
  • REDIS_CACHE_SSL

When a REDIS_CACHE_* property is not set, the values from REDIS_* is used instead. The only exception to this is REDIS_CACHE_DATABASE, which defaults to 1.

Optional ALLOWED_HOSTS list

A list of fully-qualified domain names (FQDNs) and/or IP addresses that can be used to reach Site Planner.

If set, access to Site Planner is not permitted via any domain name or IP address not in this list, to guard against HTTP Host header attackes.

The list should be provided as a comma separated list: hostname1, hostname2, hostname3

Default: * (all)

Optional BASE_PATH setting

The base URL path used when accessing Site Planner. If you intend to access Site Planner from a sub-path, for example, https://example.com/site-planner/, then set this value to site-planner/

Default: ''

Optional CACHE_TIMEOUT property

The time, in seconds, which entries remain in the Redis based cache before expiring. Setting this value to 0 will disable caching.

Default: 900

Optional CHANGELOG_RETENTION property

Maximum amount of time, in days, to retain changelog entries before they may be removed. Setting this value to 0 will result in the retention of all entries indefinitely but may result in the database exceeding it's maximum capacity over time.

Default: 90

Optional CORS_ORIGIN_ALLOW_ALL sharing requests property

Decide if cross origin resource sharing (CORS) requests from all origins should be allowed. Set this value to True to enable them, otherwise the CORS_ORIGIN_WHITELIST and CORS_ORIGIN_REGEX_WHITELIST values will be used.

Default: False

Optional CORS_ORIGIN_WHITELIST property

A comma separated list of origins that are authorized to make cross-site API requests. For example:

CORS_ORIGIN_WHITELIST: https://example1.com,https://example2.com

Optional CORS_ORIGIN_REGEX_WHITELIST property

A comma separated list of regex patterns that are authorized to make cross-site API requests. For example:

Optional date format properties

The following properties may be used to configure how date/times are displayed:

Property Name Default Description
DATE_FORMAT 'N j, Y' Format used for dates e.g. May 23, 2020
SHORT_DATE_FORMAT 'Y-m-d' Format used for short dates e.g. 2020-05-23
TIME_FORMAT 'g:i a' Format used for times e.g. 3:47 p.m
SHORT_TIME_FORMAT 'H:i:s' Format used for short times e.g. 15:47:00
DATETIME_FORMAT 'N j, Y g:i a' Format used for date time strings e.g. May 23, 2020 3:47 p.m
SHORT_DATETIME_FORMAT 'Y-m-d H:i' Format used for short date time strings e.g. 2020-05-23 15:47

The following tables show the supported format options.

Table 1. Days
Character Description Examples
d 2 digit day of the month 01, 02, ... 31
j 1 or 2 digit day of the month 1, 2, ... 31
D 3 letter representation for day of the week Mon
l Longer text representation for day of the weel Monday
S Ordinal suffix for day of the month st, nd, rd, th
w Single digit day of the week from Sunday 0 to Saturday 6 0, 1, ... 6
z Day of the year 1, 2, ..., 10, 11, ..., 366
Table 2. Weeks
Character Description Examples
W ISO-8601 Week number of year (weeks starting on Monday) 1, 2, ..., 53
Table 3. Months
Character Description Examples
m 2 digit month of the year 01, 02, ... 12
n 1 or 2 digit month of the year 1, 2, ... 12
M 3 letter representation for month of the year Jan
b Lowercase 3 letter representation for month of the year jan
F Longer text representation for month of the year January
t Number of days in the month 28, 29, 30, 31
Table 4. Years
Character Description Examples
y 2 digit year 19, 20
Y 4 digit year 2019, 2020
L Leap year boolean True, False
o ISO-8601 week-numbering year 1999
Table 5. Time
Character Description Examples
g Hours in 12 hour format 1, 2, ..., 12
G Hours in 24 hour format 0, 1, ..., 23
h 2 digit hours in 12 hour format 01, 02, ..., 12
H 2 digit hours in 24 hour format 00, 01, ..., 23
i 2 digit minute of the hour 00, 01, ..., 59
s 2 digit seconds 00, 01, ..., 59
u Microseconds 000000, 000001, ..., 999999
a 'a.m.' or 'p.m.' 'a.m.' or 'p.m.'
A 'AM' or 'PM' 'AM' or 'PM'
f Time in hours and minutes, using 12 hour format. Minutes remain if zero. 5, 5:15
P Time in hours, minutes and 'a.m.' or 'p.m.'. Using 12 hour format. Minutes remain if zero. Special strings midnight and noon are used at those times 5 p.m., 5:15p.m., midnight
Table 6. Time zones
Character Description Examples
e Timezone name (may return empty) '', GMT, US/Eastern
I Whether Daylight Savings Time is in effect 1, 0
O Difference to Greenwich time in hours +0300, +0400
T Timezone of the system EST
Z Timezone offset, in seconds, of the system -43200, ..., 43200
Table 7. Date and time
Character Description Examples
c ISO 8601 format 2020-05-06T11:45:00.000456+04:00
r RFC 5322 formatted date Fri, 19 Feb 2021 16:47:07 +0200
U Seconds since the Unix Epoch (January 1 1970 00:00:00 UTC) 1614098869

Optional ENFORCE_GLOBAL_UNIQUE property

By default, Prefixes and IP addresses are only unique per-VRF. Any Prefix/IP addresses created without a VRF may be duplicated. Set this property to True if you would prefer global uniqueness.

Default: False

Optional EXEMPT_VIEW_PERMISSIONS property

Comma separated list of models which should not enforce read permissions, meaning all users (authenticated or anonymous) can view these objects.

EXEMPT_VIEW_PERMISSIONS: nfvo_automation.networkservice,dcim.device

Default: ''

Optional LOGIN_REQUIRED property

Set this to False if you'd like to allow anonymous users to access Site Planner. Users will only be able to access models listed in EXEMPT_VIEW_PERMISSIONS.

Default: True

Optional MAX_PAGE_SIZE property

The maximum value allowed for the limit parameter on API requests. Setting this value 0 will allow a client to request all objects by specifying limit=0

Default: 1000

Optional METRICS_ENABLED property

Set to True to enable Prometheus-compatible metrics at /metrics

Default: False

Optional PAGINATE_COUNT property

The default number of objects to display per page when listing objects in the UI.

Default: 50

Optional PREFER_IPV4 property

Set to True, if IPv6 is preferred over IPv4 by default, when choosing the primary IP of a device.

Default: False

Optional TIME_ZONE property

Time zone used by Site Planner.

Default: UTC

Logging

Site Planner is configured to direct all logs to the stdout/stderr stream.

The application is organized by modules and each module may be configured with different a log level, in order to limit the messages included in the log stream. The default log level for the core modules of Site Planner is INFO.

The level may be changed by adding entries to a LOGGERS configuration property. The following shows an example of updating the level for the nfvo_automation module:

LOGGERS:
  nfvo_automation:
    level: DEBUG

The following log levels are supported:

  • DEBUG: Detailed information normally used by developers to diagnose issues
  • INFO: Basic information covering the normal operation of the application
  • WARNING: Details an unexpected or unwarranted behavior that may indicate a problem but the application continues to work as expected
  • ERROR: Details of any error scenarios that have occurred
  • CRITICAL: Details of a more serious error that may result in the application halting

The listed levels are in severity order, lowest first. Any level will inherit logs sent with a higher level. For example, when using the INFO level, all logs sent out with a WARNING, ERROR or CRITICAL level will still be included in the log stream.

There are 100s of modules used within Site Planner, the following table shows a list of modules we consider the most relevant to anyone looking to change the default log levels:

Module Description
netbox.auth Authentication events
netbox.dcim Events related to models such as Site, Rack, Device
netbox.circuits Events related to models such as Circuits and Providers
netbox.ipam Events related to models such as IPAddress and VRFs
netbox.tenancy Events related to models such as Tenants
netbox.virtualization Events related to models such as Cluster and Virtual Machine
netbox.graphql_engine GraphQL functionality
netbox.api.views Additional common events related to Rest API requests
netbox.views Additional common events related to UI view requests
nfvi_management Events related to models such as Virtual Infrastructure and External Service
nfvi_automation Events related to Automation Context models and any build/teardown requests on infrastructure models
nfvo_automation Events related to Network Services, including build/teardown requests
nfvi_common Common events of the NFVI/NFVO modules
lmctl Events related to communication with the orchestration engine
gunicorn Events related to the handling, by the uWSGI container, of incoming requests
django.request Events related to the handling of HTTP requests