ArenaTemplateSource CRD

Enterprise Feature

ArenaTemplateSource is an enterprise feature. The Arena CRDs come from the omnia-crds chart, which installs them by default; the Arena controllers run only when enterprise.enabled=true in the app chart’s values. See Installing a License for details.

The ArenaTemplateSource custom resource defines a source for discovering and fetching project templates. Templates are PromptKit projects that can be customized with variables and rendered to create new Arena projects.

See Arena templates for how discovery and rendering work, and Create a template source for setup steps and complete examples.

API version

apiVersion: omnia.altairalabs.ai/v1alpha1
kind: ArenaTemplateSource

Short name: ats (e.g. kubectl get ats).

Spec fields

type

The source type for fetching templates.

Value	Description	Use Case
git	Git repository	Version-controlled templates
oci	OCI registry	Container registry storage
configmap	Kubernetes ConfigMap	Simple in-cluster storage

spec:
  type: git

syncInterval

The interval between sync operations. Uses Go duration format (pattern ^([0-9]+(\.[0-9]+)?(ms|s|m|h))+$). Default: 1h.

spec:
  syncInterval: 30m

templatesPath

The path within the source where templates are located. Default: templates/. If the default directory does not exist in the fetched content, the whole source is scanned from its root. A path you set that does not exist puts the source in the Error phase.

spec:
  templatesPath: my-templates/

git

Configuration for Git repository sources. Required when type: git.

Field	Type	Required	Description
url	string	Yes	Repository URL (must match `^(https?
ref.branch	string	No	Branch to checkout (takes precedence over tag and commit)
ref.tag	string	No	Tag to checkout (takes precedence over commit)
ref.commit	string	No	Specific commit SHA
path	string	No	Path within repository (default: root)
secretRef	object	No	Credentials for private repos
connectionRef	object	No	Name of a Connection in the same namespace to fetch with, instead of secretRef. Set at most one of secretRef and connectionRef

A connectionRef Connection must list the repository’s host and the URL must use https on port 443 or ssh on port 22. A secret Connection supplies its Secret with the same keys as secretRef, and a none Connection fetches anonymously. Connections of any other credential kind (browserSession, gitHost) are refused.

spec:
  type: git
  git:
    url: https://github.com/acme/arena-templates
    ref:
      branch: main

See Create a template source for HTTPS and SSH credential setup.

oci

Configuration for OCI registry sources. Required when type: oci.

Field	Type	Required	Description
url	string	Yes	OCI artifact URL (must start with oci://)
secretRef	object	No	Registry credentials: username/password keys, or a .dockerconfigjson key
insecure	boolean	No	Connect without TLS verification (default: false)

spec:
  type: oci
  oci:
    url: oci://ghcr.io/acme/templates:v1.0.0

configMap

Configuration for ConfigMap sources. Required when type: configmap. Every key in the ConfigMap is written out as a file named after the key, with __ in a key name becoming /.

Field	Type	Required	Description
name	string	Yes	ConfigMap name

spec:
  type: configmap
  configMap:
    name: my-templates

suspend

When true, prevents the source from being reconciled: any in-progress fetch is cancelled and Ready is set False with reason Suspended.

spec:
  suspend: true

timeout

Timeout for fetch operations. Default: 60s.

spec:
  timeout: 120s

trust

The source’s trust tier: official, partner or community. Default: community. The New project gallery badges every template with its source’s tier, lists official templates first, then partner, then community, and offers the tier as a filter.

The tier is a claim made to everyone in the workspace about who stands behind the templates, so the person who adds or edits a source cannot make it. On a source that would be above community, two writes need the curate verb on arenatemplatesources in the source’s namespace:

• raising the tier (above community on create, above its current value on update);
• changing where the content comes from: type, git (any field: url, ref, path, secretRef, connectionRef), oci, configMap or templatesPath. Without this an editor could repoint an official source at their own repository and have it badged Official.

No workspace role grants curate; cluster-admin holds it through *. Keeping or lowering the tier, any other edit (such as syncInterval or featured), and any edit of a community source need only the editor’s write. To repoint an official source without curate, drop it to community in the same write.

A configmap source cannot be above community, whoever asks: every workspace editor can change the ConfigMap itself, so its tier would vouch for nothing.

Three layers enforce the rule. The chart installs a ValidatingAdmissionPolicy that the API server applies to every writer, kubectl included, on clusters that serve admissionregistration.k8s.io/v1 ValidatingAdmissionPolicy (Kubernetes 1.30 and later). The arena-controller admission webhook, when webhook.enabled is set, checks the same rule with a SubjectAccessReview. management-api refuses such a write from the dashboard (403, or 400 for a ConfigMap source) before it reaches the API server. On an older cluster with webhooks off, only management-api’s check applies, so a workspace editor with kubectl access can set a tier there.

To let a group vouch for sources without cluster-admin, bind it a role such as:

apiVersion: rbac.authorization.k8s.io/v1
kind: ClusterRole
metadata:
  name: arena-template-curator
rules:
  - apiGroups: ["omnia.altairalabs.ai"]
    resources: ["arenatemplatesources"]
    verbs: ["curate", "get", "update", "patch"]

spec:
  trust: partner

featured

Names of this source’s templates that the gallery lists first within the source’s tier, under its default “Featured” sort, and marks as featured. At most 50. Names match case-insensitively; a name the source does not publish is ignored. Changing the list while someone is paging through the gallery reorders what is left, so their next “Load more” can repeat or skip a template. It is the source administrator’s curation: a template cannot feature itself, since a field in a third party’s template would let any author promote their own work.

spec:
  featured:
    - eval-scenarios

Status fields

phase

Value	Description
Pending	Source has not been fetched yet
Fetching	Fetching from source and discovering templates
Ready	Successfully fetched and templates discovered
Error	Fetch or discovery failed, the licence does not allow the source, or workspace content storage is disabled

templateCount

Number of templates discovered in the source.

headVersion

The content version of the synced content: the first 12 hex characters of its SHA-256, the same value as artifact.version. The source revision (for example a Git commit) is in artifact.revision.

artifact

Information about the fetched content.

Field	Description
contentPath	Path of the synced version, relative to the workspace content volume root: arena/template-sources/{name}/.arena/versions/{version}
version	First 12 hex characters of the content’s SHA-256
revision	Source revision identifier
checksum	SHA256 checksum of the fetched content
size	Size in bytes
lastUpdateTime	When artifact was last updated

conditions

Type	Description
Ready	Overall readiness of the source
Fetching	Fetching from source
TemplatesScanned	Template discovery completed; the message gives the count
ArtifactAvailable	Synced content is available on the workspace volume

lastFetchTime

Timestamp of the last fetch attempt.

nextFetchTime

Scheduled time for the next fetch.

message

Additional details about the current state.

The discovered templates are not listed in status. The controller writes them to an index file at arena/template-indexes/{name}.json in the namespace’s workspace content directory, which management-api reads for the dashboard.

Variable types

Each variable in a template’s variables list has one of these types, which sets its validation fields.

Type	Description	Validation Fields
string	Text value	pattern (regex)
number	Numeric value	min, max
boolean	True/false	-
enum	Predefined options	options (required)

template.yaml format

Each template is a directory containing a template.yaml file.

template.yaml

metadata:
  name: basic-chatbot
  version: 1.0.0
spec:
  displayName: Basic Chatbot
  description: A simple conversational chatbot using PromptKit
  tags:
    - beginner
    - conversation

  variables:
    - name: agentName
      type: string
      description: Name of the agent
      required: true
      default: "Assistant"

    - name: temperature
      type: number
      description: Model temperature (0.0-1.0)
      default: "0.7"
      min: "0"
      max: "1"

    - name: provider
      type: enum
      description: LLM provider to use
      options:
        - openai
        - anthropic
        - ollama
      default: openai

  files:
    - path: prompts/
      render: true
    - path: config.arena.yaml
      render: true
    - path: static/
      render: false

Field	Description
metadata.name	Required. A template.yaml without it is skipped.
spec.displayName	Defaults to metadata.name.
spec.variables	See Variable types above.
spec.files	When omitted, every non-hidden entry in the template directory (other than template.yaml) is included. Files ending in .yaml, .yml, .json, .txt or .md are rendered; everything else is copied as-is.

Top-level apiVersion and kind fields are accepted but not read.

Symlinks in template sources

Rendering never follows a symlink. The controller renders from a private copy of the template directory that holds only regular files and directories, so a files[].source (or a template.yaml) that is a symlink is treated as missing and the render reports an error for it, wherever the link points. Commit the file itself rather than a link to it.

When a source is synced, a symlink whose target is absolute or climbs out of the fetched tree is dropped from the synced version. Relative links that stay inside the tree are kept, except that a target with .. after a name (such as dir/../file) is also dropped, because it cannot be checked without following links.

Related resources

• ArenaProject: For fetching PromptKit bundles (not templates)
• ArenaJob: Run tests against Arena projects
• Create an Arena project: Create projects from templates
• Arena templates: How template discovery and rendering work
• Create a template source: Setup steps and complete examples