Skip to content
ALTAIRA LABS
DocsBlog
OmniaOmnia

Arena templates

An ArenaTemplateSource fetches a Git repository, OCI artifact, or ConfigMap that holds one or more Arena project templates, and makes them available in the dashboard’s New project gallery. This page explains what a template is, how the controller finds templates inside a source, and how a template becomes a project.

Overview

Section titled “Overview”

A template source is a location the controller checks at spec.syncInterval. On each check it asks the source for its latest revision, and it fetches and re-discovers templates only when that revision differs from the one it stored. What it finds are directories, each a candidate template, discovered one of two ways and rendered with the variables you supply. Discovery, structure, and periodic sync are the same whether the source is Git, OCI, or a ConfigMap; only fetching differs, and that is where credentials apply.

Template discovery

Section titled “Template discovery”

Each template is a directory containing a template.yaml file; see the ArenaTemplateSource reference for its fields.

The controller finds templates one of two ways. If .template-index.yaml exists at the source root or in templatesPath, only the templates it lists (templates: [{name, path}], paths relative to the index file) are loaded. Otherwise every template.yaml under templatesPath is loaded.

Variables use Go template syntax in the files marked render: true.

How a template becomes a project

Section titled “How a template becomes a project”

The diagram follows one sync of an ArenaTemplateSource from fetch to a ready set of templates.

flowchart LR
    ATS[ArenaTemplateSource] --> Fetch --> Discover --> Ready["Templates ready"]
    Discover --> Meta["template.yaml metadata"]

An ArenaTemplateSource names a source location. The controller fetches its content and stores it as a version on the workspace content volume, the same versioned shape every other workspace-content subtree uses. It then discovers templates, reading the index file or scanning for template.yaml files, and writes a template index for the dashboard to read. From there, the templates appear as cards in the New project gallery. Choosing one opens a form for the variables the template declares, then a review of the files the render will write. Nothing is created until you click Create project.

Trade-offs

Section titled “Trade-offs”

The index file and the directory scan answer different needs. Scanning needs no extra file: drop a directory with a template.yaml under templatesPath and it is a template. The cost is that everything in the tree is published. An index file lets one repository hold templates that are not meant to be offered, at the price of a second file to keep in step with the directories.

Checking the revision before fetching keeps a one-hour default interval cheap, because an unchanged source costs one revision lookup. An unchanged sync keeps the stored version, the template index and templateCount as the last changed sync wrote them. The consequence is that a change to the source shows up at the next interval, not immediately.

Section titled “Related”