---
title: Questions.yaml
---

:::danger

TrueNAS SCALE Apps are considered Deprecated. We heavily recommend using a more mature Kubernetes platform such as "TalosOS" instead, and no longer offer an apps/charts catalogue for SCALE users to install. The below docs exist purely as historical references and may be removed at any time.

:::

Questions.yaml is the file which get rendered by TrueNAS to create the UI. When not creating new charts, most of what this project does is stitching together questions.yaml files to turn existing Helm Charts into Apps.

## Syntax

In this document we give you a short reference guide (ported from IX Official) which lays out the settings available in questions.yaml.

### Question Variable Reference

| Variable                    | Type          | Required | Description                                                                                                                                                                                                                                                                                     |
| --------------------------- | ------------- | -------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| variable                    | string        | true     | define the variable name specified in the `values.yaml`file.                                                                                                                                                                                                                                    |
| label                       | string        | true     | define the UI label.                                                                                                                                                                                                                                                                            |
| description                 | string        | false    | specify the description of the variable.                                                                                                                                                                                                                                                        |
| group                       | string        | false    | group questions by input value.                                                                                                                                                                                                                                                                 |
| schema                      | dictionary    | true     | specify schema details for the `variable`                                                                                                                                                                                                                                                       |
| schema.type                 | string        | true     | specify type of value for `variable` (current supported types are string, int, boolean, path, hostpath, list, dict, ipaddr, and cron).                                                                                                                                                          |
| schema.required             | bool          | false    | define if the variable is required or not (true \ false), defaults to false                                                                                                                                                                                                                     |
| schema.default              | object        | false    | specify the default value.                                                                                                                                                                                                                                                                      |
| schema.min_length           | int           | false    | min character length for string type variable.                                                                                                                                                                                                                                                  |
| schema.max_length           | int           | false    | max character length for string type variable.                                                                                                                                                                                                                                                  |
| schema.min                  | int           | false    | min integer length.                                                                                                                                                                                                                                                                             |
| schema.max                  | int           | false    | max integer length.                                                                                                                                                                                                                                                                             |
| schema.enum                 | []dictionary  | false    | specify the options when the variable type is `string`, for example,<br /><br />enum:<br />- value: "RollingUpdate"<br />&nbsp;&nbsp;description: "Create new pods and then kill old ones"<br />- value: "Recreate"<br />&nbsp;&nbsp;description: "Kill existing pods before creating new ones" |
| schema.valid_chars          | string        | false    | regular expression for input chars validation.                                                                                                                                                                                                                                                  |
| schema.subquestions         | []subquestion | false    | add an array of subquestions.                                                                                                                                                                                                                                                                   |
| schema.show_if              | string        | false    | show current variable if condition specified is true, for example `show_if: [["workloadType", "=", "CronJob"]]`                                                                                                                                                                                 |
| schema.show_subquestions_if | string        | false    | show subquestions if is true or equal to one of the options. for example `show_subquestion_if: "static"`. system will convert this to the filters format specified for `schema.show_if` automatically.                                                                                          |
| schema.attrs                | []variables   | false    | specified when `schema.type` is dictionary to declare attributes allowed in the dictionary.                                                                                                                                                                                                     |
| schema.items                | []variables   | false    | specified when `schema.type` is list to declare attributes allowed in the list.                                                                                                                                                                                                                 |
| schema.private              | bool          | false    | specified for declaring information sensitive fields.                                                                                                                                                                                                                                           |
| schema.null                 | bool          | false    | specifies if the value for the variable can be null. defaults to false.                                                                                                                                                                                                                         |

#### Subquestions

`subquestions[]` cannot contain `subquestions` or `show_subquestions_if` keys, but all other keys in the above table are supported. Also variables having `schema.type` list do not support `subquestions`.

#### Special Questions

There are some novel cases where we would like to provide ability to configure / manage resources for workloads with getting some data from system dynamically.
So a chart can specify certain actions to be performed by the system for a variable by defining a reference. An example better illustrates this concept:

```yaml
- variable: volume
  label: "Volume"
  schema:
    type: dict
    $ref:
      - "normalize/ixVolume"
    attrs:
      - variable: mountPath
        label: "Mount Path"
        description: "Path where the volume will be mounted inside the pod"
        schema:
          type: path
          required: true
      - variable: datasetName
        label: "Dataset Name"
        schema:
          type: string
          required: true
```

In the above variable we define a `$ref` in schema which specifies that the system should take some action for normalizing the value specified for the variable.
In this specific case, `ix_volume` is a concept introduced where we recommend using a volume which we are able to rollback automatically on chart release rollback. In essence,
it is just a `hostPath` volume for which the system automatically creates the dataset specified.
We have following types of actions supported in `$ref` right now:

1. definitions
2. normalize
   For (1), system will automatically update schema for a particular definition. For example,

```yaml
- variable: hostInterface
  description: "Please specify host interface"
  label: "Host Interface"
  schema:
    type: string
    required: true
    $ref:
      - "definitions/interface"
```

System will automatically populate available interfaces for the user based on what interfaces are available on the system.
For (2), system will normalize values or perform some actions as discussed above.

#### Standardized questions.yaml sections

To minimize the maintenance load of our App collection, we always aim to standardize as much as possible. The same goes for questions.yaml. Included here are some code standardized code-snippets that are expected to be included in every App.
Be aware that sometimes specific functions might or might not completely function. However, omitting them would significantly increase the maintenance burden and this functionality is often incorporated into the common-chart anyway.

#### Groups

To make sure all apps stay somewhat the same, we use a list of standardized groups for the groups section. Please make sure to use these groups in your Apps:

```yaml
groups:
  - name: "Container Image"
    description: "Image to be used for container"
  - name: "Workload Configuration"
    description: "Configure workload deployment"
  - name: "Configuration"
    description: "additional container configuration"
  - name: "Networking"
    description: "Configure Network and Services for container"
  - name: "Storage"
    description: "Persist and share data that is separate from the lifecycle of the container"
  - name: "Resources and Devices"
    description: "Specify resources/devices to be allocated to workload"
  - name: "Ingress Configuration"
    description: "Ingress Configuration"
  - name: "Security"
    description: "Configure security context"
  - name: "Advanced"
    description: "Advanced Configuration"
  - name: "WARNING"
    description: "WARNING"
```

#### General Configuration options

These options are always\* included because almost every chart (eventually) has a use for them and/or other parts of the common chart depend on them.
They are called general options, because they affect the basic functionalities of a chart. For example: Custom User environment variables, permissions and timezones.

\*`PUID`, `PGID`, `UMASK` are only included when they are needed.

```yaml
- variable: env
  group: "Configuration"
  label: "Image Environment"
  schema:
    additional_attrs: true
    type: dict
    attrs:
      - variable: TZ
        label: "Timezone"
        schema:
          type: string
          default: "Etc/UTC"
          $ref:
      - "definitions/timezone"
      - variable: PUID
        label: "PUID"
        description: "Sets the PUID env var for LinuxServer.io (compatible) containers"
        schema:
          type: int
          default: 568
      - variable: PGID
        label: "PGID"
        description: "Sets the PGID env var for LinuxServer.io (compatible) containers"
        schema:
          type: int
          default: 568
      - variable: UMASK
        label: "UMASK"
        description: "Sets the UMASK env var for LinuxServer.io (compatible) containers"
        schema:
          type: string
          default: "002"

# Configure Custom Environment Variables
- variable: environmentVariables
  label: "Image environment"
  group: "Configuration"
  schema:
    type: list
    default: []
    items:
      - variable: environmentVariable
        label: "Environment Variable"
        schema:
          type: dict
          attrs:
            - variable: name
              label: "Name"
              schema:
                type: string
            - variable: value
              label: "Value"
              schema:
                type: string
```

#### Security Context Configuration options

```yaml
# Enable privileged
- variable: securityContext
  group: "Security"
  label: "Security Context"
  schema:
    additional_attrs: true
    type: dict
    attrs:
      - variable: privileged
        label: "Enable privileged mode for Common-Chart based charts"
        schema:
          type: boolean
          default: false
# Set Pod Security Policy
- variable: podSecurityContext
  group: "Security"
  label: "Pod Security Context"
  schema:
    additional_attrs: true
    type: dict
    attrs:
      - variable: runAsNonRoot
        label: "runAsNonRoot"
        schema:
          type: boolean
          default: true
      - variable: runAsUser
        label: "runAsUser"
        description: "The UserID of the user running the application"
        schema:
          type: int
          default: 568
      - variable: runAsGroup
        label: "runAsGroup"
        description: The groupID this App of the user running the application"
        schema:
          type: int
          default: 568
      - variable: fsGroup
        label: "fsGroup"
        description: "The group that should own ALL storage."
        schema:
          type: int
          default: 568
      - variable: fsGroupChangePolicy
        label: "When should we take ownership?"
        schema:
          type: string
          default: "OnRootMismatch"
          enum:
            - value: "OnRootMismatch"
              description: "OnRootMismatch"
            - value: "Always"
              description: "Always"
```
