App Metadata (`metadata.yaml`)

This document explains how Watchgrid reads app metadata, how manifest templating works, and which fields are configurable in the App Manager UI.

Overview

Each app directory in apps/ must contain:

metadata.yaml (or metadata.yml) for app metadata
One or more Kubernetes manifest files (.yaml / .yml)

metadata.yaml is the canonical metadata source. app.json is no longer used.

Minimal Example

name: "Hello Web"
description: "Minimal HTTP echo site for Open Web Interface testing"
version: "1.0.0"
namespace: "default"
author: "Watchgrid System"
tags:
  - "web"
  - "demo"

Full Example With Configurable Fields

name: "Hello Web"
description: "Minimal HTTP echo site for Open Web Interface testing"
version: "1.0.0"
namespace: "default"
author: "Watchgrid System"
tags:
  - "web"
  - "demo"
  - "test"
min_replicas: 1
max_replicas: 5
default_replicas: 1
config_fields:
  - name: "WELCOME_MESSAGE"
    type: "string"
    description: "Message shown by the hello-web page"
    default: "Watchgrid hello-web is running"
    required: true

Supported Metadata Fields

Field	Type	Required	Notes
`name`	string	yes	Display name in app catalog
`description`	string	no	Shown in app details
`version`	string	no	App version label
`namespace`	string	no	Default deployment namespace (`default` if omitted)
`author`	string	no	Informational
`tags`	list[string]	no	Used for filtering/search
`min_replicas`	int	no	Informational/app policy metadata
`max_replicas`	int	no	Informational/app policy metadata
`default_replicas`	int	no	Informational/app policy metadata
`config_fields`	list[object]	no	Defines fields shown in config modal

`config_fields` Schema

Each entry supports:

Field	Type	Required	Notes
`name`	string	yes	Key used in template replacement
`type`	string	yes	`string`, `secret`, or `boolean`
`description`	string	no	UI help text
`default`	string	no	Pre-filled/default value
`required`	bool	no	Marks field as required in UI

UI behavior: - string => text input - secret => password input (masked) - boolean => true/false select

How Template Substitution Works

During install/deploy, Watchgrid substitutes field values into manifests.

Primary template format:

args:
  - "-text=${WELCOME_MESSAGE}"

Watchgrid also updates common YAML patterns: - Secret stringData keys matching the config field name - Environment variables where - name: FIELD_NAME is followed by value: ...

App Directory Layout

apps/
  hello-web/
    metadata.yaml
    deployment.yaml

All .yaml / .yml files except metadata.yaml / metadata.yml are treated as deployable manifests.

Validation Checklist

Before committing an app:

metadata.yaml exists and parses as valid YAML.
config_fields[].name values match placeholders used in manifests.
At least one manifest file exists besides metadata.
Run app sync in Watchgrid and verify fields appear in Configure modal.

App Metadata (metadata.yaml)