Star Quix Streams

 Install Quix Streams

 Edit on GitHub

Application YAML Descriptor (app.yaml)

The app.yaml file is used to define the configuration of a Quix application. This file serves as a contract for the application, outlining its variables and settings. It is similar to deployment configurations, but specific to the application itself.

Structure of app.yaml

1. Application Metadata

name: Slack Alerts
language: python

Explanation:

• name: The name of the application. This should be a clear and descriptive identifier that reflects the application's purpose.

• language: Specifies the programming language used by the application. This information helps in understanding the environment and dependencies required for the application.

2. Variables

The variables section defines the inputs and settings that the application may require to function correctly. These variables can include topics, secrets, and free text inputs.

Example Variables

variables:
  - name: input
    inputType: InputTopic
    description: Name of the input topic to listen to.
    defaultValue: enriched-click-data
    required: true
  - name: webhook_url
    inputType: ProjectVariable
    description: The webhook url to send notifications to
    secret: true
    defaultValue: webhook_url
    required: true
  - name: timeout
    inputType: FreeText
    description: Get alerts if we have not received data in this timeout (seconds)
    defaultValue: 3600
    required: false
  - name: notification_interval
    inputType: FreeText
    description: Send alerts at most every x seconds (default 10 minutes)
    defaultValue: 600
    required: false
  - name: content_store
    inputType: Options
    description: Where to store the content
    defaultValue: mongo
    required: false
    options:
      - label: MongoDB
        value: mongo
      - label: File System
        value: file

Explanation:

• name: The name of the variable, which identifies it within the application.

• inputType: Defines the type of input expected. This can be:

  • InputTopic: Refers to a topic that the application will consume data from.

  • OutputTopic: Refers to a topic where the application will produce data.

  • FreeText: A flexible text input that can be used for various settings or parameters.

  • HiddenText: A text input masked in the UI. It is not a managed secret — use ProjectVariable with secret: true for sensitive values.

  • Options: A selection from a predefined list of values. Requires an options array where each entry has a label (display text) and value (actual value).

  • ProjectVariable: A value looked up from the project's variables store, resolved per environment. Set secret: true to store a sensitive value such as an API key or webhook URL — the modern replacement for the legacy Secret type.

  • VariableGroup: A reference to an organization-level variable group; the group's variables are injected together at deploy time.

• options: An array of predefined choices, required when inputType is Options. Each entry contains:

• label: The human-readable text displayed in the UI dropdown.

• value: The actual value assigned to the environment variable.

• description: A brief explanation of the variable's purpose and how it should be used.

• defaultValue: The default value assigned to the variable. This value will be used unless explicitly overridden during deployment.

• required: A boolean value indicating whether this variable is mandatory (true) or optional (false) for the application's operation.

• secret: When true (with inputType: ProjectVariable), the value is treated as sensitive — encrypted at rest and masked in the UI.

3. Docker and Entry Points

dockerfile: dockerfile
runEntryPoint: main.py
defaultFile: main.py

Explanation:

• dockerfile: The path to the Dockerfile that will be used to build the application's container.

• runEntryPoint: Specifies the main entry point script that will be executed when the application starts. This is typically the main file that kicks off the application's logic.

• defaultFile: Refers to the default file or file of the application, mostly for ide purposes, most of the times it will be the same as runEntryPoint.

4. Included Folders

includedFolders:
  - src-folder
  - config-folder
  - assets-folder

Explanation:

• includedFolders: Lists any directories to be packaged and deployed alongside the application. If omitted, only the main application files (e.g., main.py) are included.
• Paths: These paths are specified relative to the root of your Git repository, ensuring the intended folder structure is maintained during deployment.
• Default Behavior: Without this section, only the essential application files are deployed, leaving out additional directories containing source code, configurations, or other assets.

For further details on how these folders are incorporated during the Docker build process, refer to the Dockerfile explanation.

How to Use the app.yaml File

This file defines the application's configuration and can be used to maintain consistency across different deployments. By defining variables, you ensure that the application has all the necessary inputs and settings to function correctly in any environment.

Modifying and Updating

Changes to the app.yaml file should be made thoughtfully, as they can affect all deployments of the application. However, the contents of this file can be adjusted or made optional as project requirements evolve.

Best Practices

• Consistent Naming: Ensure that variable names are clear and descriptive to avoid confusion during deployment.

• Security: Store sensitive values as a ProjectVariable with secret: true so they are encrypted and masked, rather than as plain text.

• Documentation: Keep the description field updated to accurately reflect the purpose and usage of each variable.

By managing your app.yaml file effectively, you can ensure that your application is deployed consistently and operates reliably in various environments, while retaining the flexibility to adapt or remove elements as needed.