Chapter 6: Writing YAML

This runbook provides guidance on writing YAML files for custom resources in the Facets platform. It explains the structure, fields, and conventions required to define new resources, ensuring clarity and consistency across implementations.

Writing New YAML Files

To add support for new resources in Facets, you need to create YAML files with the following components:

Intent, Flavor, and Metadata:
- Define the intent (e.g., "redis" or "postgres") to represent the type of resource.
- Specify the flavor (e.g., "k8s" or "aurora") for its implementation.
- Add metadata like version, description, and clouds (supported platforms).
Spec Section:
- Define the spec properties using JSON Schema for validation.
- Include fields like type, properties, required, and validation rules (e.g., enum, pattern).
Sample Section:
- Provide a sample configuration to serve as a default template when the resource is created in the UI.
Custom UI Fields:
- Use x-ui-* fields to customize the behavior and presentation of the resource in the Facets UI.

By adhering to this structure, YAML files can effectively define new resources and their configurations in the Facets platform.

Understanding the Spec Section

The spec section is a critical part of the YAML file. It uses JSON Schema to define properties, data types, and validation rules, ensuring consistency and clarity.

Key JSON Schema Elements:

type: Specifies the data type (e.g., string, boolean, object).
properties: Lists the sub-properties of an object.
items: Defines the schema for array elements.
title: Provides a human-readable name for the property.
description: Explains the property’s purpose.
enum: Limits values to a predefined set.
minimum/maximum: Sets numerical constraints.
pattern: Uses regular expressions for string validation.
required: Marks mandatory fields.

Example Spec Section:

spec:
  title: Redis Configuration
  type: object
  properties:
    redis_version:
      type: string
      title: Redis Version
      description: Specifies the version of Redis.
      enum:
        - "6.2"
        - "7.0"
    persistence_enabled:
      type: boolean
      title: Persistence Enabled
      description: Enable persistence across restarts.
    size:
      type: object
      title: Size Configuration
      properties:
        cpu:
          type: string
          title: CPU
          pattern: "^([1-9]|[12][0-9])$"
          description: Number of CPU cores.
          x-ui-placeholder: "e.g., '2'"
        memory:
          type: string
          title: Memory
          pattern: "^(1|2|4|8)G$"
          description: Memory size.
  required:
    - redis_version
    - persistence_enabled

Custom UI Fields (x-ui-* Fields)

Facets extends JSON Schema with custom x-ui-* fields to enhance the user interface. These fields control the behavior and display of resource properties in the Facets UI.

Common x-ui-* Fields:

x-ui-api-source: Fetches dynamic data for dropdowns from an API.
x-ui-placeholder: Provides placeholder text in input fields.
x-ui-validation: Adds custom validation rules.
x-ui-visible-if: Toggles visibility based on another field’s value.
x-ui-order: Specifies the display order of properties.
x-ui-skip: Hides certain properties from the UI.
x-ui-command: Indicates that the values within an array represent executable commands.
x-ui-disable-tooltip: Provides a message for a disabled tooltip.
x-ui-dynamic-enum: Dynamically generates enum options based on another field.
x-ui-error-message: Custom error message for validation failures.
x-ui-lookup-regex: Defines regex to extract values for API requests.
x-ui-no-sort: Prevents automatic sorting of dropdown options.
x-ui-override-disable: Prevents users from overriding certain properties in the UI.
x-ui-overrides-only: Displays only overridden fields in the UI.
x-ui-toggle: Renders a property as a toggle switch.
x-ui-yaml-editor: Enables YAML editor for complex structured inputs.

Example with Custom UI Fields:

spec:
  title: Redis Configuration
  type: object
  properties:
    redis_version:
      type: string
      title: Redis Version
      description: Specifies the version of Redis.
      enum:
        - "6.2"
        - "7.0"
      x-ui-placeholder: "Select Redis version"
    size:
      type: object
      title: Size Configuration
      properties:
        cpu:
          type: string
          title: CPU
          pattern: "^([1-9]|[12][0-9])$"
          description: Number of CPU cores.
          x-ui-placeholder: "e.g., '2'"
          x-ui-error-message: "Value must be between 1 and 32."
        memory:
          type: string
          title: Memory
          pattern: "^(1|2|4|8)G$"
          description: Memory size.
          x-ui-placeholder: "e.g., '4G'"
          x-ui-dynamic-enum: "size_options"
  required:
    - redis_version

Sample YAML File: Redis Resource

Here is a complete YAML file for a Redis resource using the Kubernetes flavor:

intent: redis
flavor: k8s
version: "0.1"
description: Adds Redis module for Kubernetes flavor
clouds:
  - aws
  - azure
  - gcp
  - kubernetes
spec:
  title: Redis Configuration
  type: object
  properties:
    redis_version:
      type: string
      title: Redis Version
      description: Specifies the version of Redis.
      enum:
        - "6.2"
        - "7.0"
    persistence_enabled:
      type: boolean
      title: Persistence Enabled
      description: Enable persistence across restarts.
    size:
      type: object
      title: Size Configuration
      properties:
        cpu:
          type: string
          title: CPU
          pattern: "^([1-9]|[12][0-9])$"
          description: Number of CPU cores.
          x-ui-placeholder: "e.g., '2'"
        memory:
          type: string
          title: Memory
          pattern: "^(1|2|4|8)G$"
          description: Memory size.
  required:
    - redis_version
    - persistence_enabled
sample:
  redis_version: "7.0"
  persistence_enabled: true
  size:
    cpu: "2"
    memory: "4G"

By following this runbook, you can create robust YAML definitions for custom resources in the Facets platform, ensuring consistency, usability, and compliance with platform standards.