paas-config.yaml

The paas-config.yaml file is an optional configuration file that charm developers can include in their charm to customize runtime behavior of 12-factor app charms.

When used, the paas-config.yaml file must be placed in the charm root directory alongside your charmcraft.yaml file and included in the packed charm file. The file and all of its keys are optional. Omitted settings use the defaults of the selected framework.

File structure

The paas-config.yaml file uses YAML format and follows a structured schema. It supports generic application settings in addition to the prometheus and framework_logging_format top-level keys.

Application settings

Use the following keys to configure the framework server and its metrics endpoint:

Key

Type

Default

Description

port

Integer

Framework-specific

Port on which the application server listens.

metrics-port

Integer

Framework-specific

Port on which the workload serves metrics.

metrics-path

String

Framework-specific

Absolute HTTP path on which the workload serves metrics.

For example:

port: 8080
metrics-port: 8080
metrics-path: /metrics

Ports must be between 1 and 65535. metrics-path must start with / and identify a non-root endpoint. These values are packaged with the charm and cannot be changed with juju config. Omitted values use the framework defaults.

The default application port is 8000 for Flask, Django, and FastAPI, and 8080 for ExpressJS, Go, and Spring Boot. The resolved port is always written to the workload environment when the framework uses an application port environment variable. Go uses PORT; Flask and Django configure the port directly in Gunicorn instead.

The charm always passes the resolved metrics-port and metrics-path values to the workload. Workload code is responsible for consuming this configuration and exposing the corresponding endpoint. Flask and Django receive framework-prefixed METRICS_PORT and METRICS_PATH variables. FastAPI, ExpressJS, and Go receive variables without framework prefixes. Spring Boot receives native management.* properties.

Flask and Django default to 9102 and /metrics. Go default to 8080 and /metrics, Spring Boot, which uses 8080 and /actuator/prometheus, and ExpressJS and FastAPI default to 9464 and /metrics.

The charm publishes a Prometheus scrape job for the resolved metrics-port and metrics-path. Additional scrape jobs can be configured independently under prometheus.scrape_configs. Their targets must match endpoints that the workload actually serves.

See Prometheus configuration for detailed Prometheus configuration options. See Structured logging configuration for detailed structured logging options.

Validation

The paas-config.yaml file is validated when the charm is deployed. If validation fails, the charm will go into error state and will not work. The paas-config.yaml file has to be fixed and the charm packed and deployed again.

Common validation errors include:

  • Invalid YAML syntax

  • Unknown fields

  • Missing required fields in nested configuration sections

  • Invalid field values

Functionality provided

The file paas-config.yaml allows you to:

  • Configure the application server port

  • Configure the workload metrics endpoint

  • Define custom Prometheus scrape targets for metrics collection

  • Enable structured framework logs in JSON format

For the detailed configuration schema and detailed examples, see: