Site creation templates¶

A Site creation template is a YAML file that fills in the Hub create-Site form. The Site Template selector in the create form lists each template next to No Template. Creation through the Hub API applies a template with the template parameter of POST /hub/api/v2/sites/. Staff users can read templates. Only platform administrators can create and delete them.

This page describes the template sources, the siteTemplates chart value, and the template file format. The procedures to manage ad-hoc templates are in Operations.

Template sources¶

The Hub reads templates from two sources:

Use platform templates for templates that all environments of a deployment share. They are part of the Helm release. They follow the deployment through Git review, upgrades, and rollbacks, and they need no separate backup. Use ad-hoc templates for short-term or environment-specific needs.

The Hub reads the files from both sources on each request. It does not cache them.

Precedence¶

The platform source wins a name collision. The Hub lists and applies the platform template, and the ad-hoc file with the same name is shadowed. The Hub writes a warning to its log once per Hub process for each shadowed file. It never deletes the shadowed file. The Hub API answers 403 to a PUT or a DELETE on the name of a platform template.

Template names¶

The template name is the file name without the .yaml extension. The effective name is lowercase and must match ^[a-z0-9][a-z0-9._-]{0,63}$:

• Lowercase letters, digits, ., _, and -.
• The first character is a letter or a digit.
• At most 64 characters.

The Hub API changes a name to lowercase before it checks it. The Hub ignores these files and writes a warning to its log:

• A file with an invalid name, or with uppercase letters in its name.
• A file that is a symbolic link to a location outside its template directory.

The siteTemplates chart value¶

The chart renders each entry to the key <name>.yaml in the sites-templates ConfigMap. The Hub mounts the ConfigMap read-only at /sites-templates/.

siteTemplates:
  project-default:
    _meta:
      description: Shared project site
    description: Shared project site.
    quota: 10
  file-share: |
    # File sharing website
    applications: "site-webdav"
    access_users: ["{{ owner }}"]

Use the string form when you need a first-line # comment or Jinja control blocks. Helm does not render Jinja expressions in values, so {{ owner }} reaches the Hub unchanged.

The chart stops the rendering with an error in these cases:

Apply changes¶

A changed ConfigMap reaches the Hub without a restart. The kubelet updates the mounted files after its sync period, usually within one or two minutes. The Hub then reads the new files on the next request. When you set siteTemplates for the first time, or remove it completely, the Hub pod specification changes and Kubernetes restarts the Hub pod.

Template file format¶

A template is a YAML mapping from create-form field names to values:

# Departmental data exchange site
site_name: data-exchange
quota: 10
description: Shared data exchange for the department.
access_groups: ["dept-data", "dept-staff"]

Fields¶

• Use create-form field names as keys, for example description, custom_space, site_name, quota, access_groups, or applications.
• List-type fields accept YAML lists, for example a list of groups.
• The Hub ignores unknown field names. A PUT through the Hub API with unknown field names succeeds and returns a warning in the message.

Description¶

The selector shows a description for each template. The Hub uses the first of these that exists:

1. The _meta.description value.
2. The first line of the file, when it is a # comment.
3. The template name.

The reserved top-level key _meta holds template metadata. The Hub never applies it to a form field. The Hub reads _meta from the file before it renders Jinja, so do not use Jinja in _meta.

Jinja rendering¶

The Hub renders the file with a sandboxed Jinja environment before it reads the values. You can reference the current form data by field name, for example {{ owner }}. Put a Jinja expression in quotes when it is a YAML value, for example ["{{ owner }}"].

Rules when the Hub applies a template¶

• A template sets only a field that the user has not filled in.
• A template sets only a field that the user is allowed to change. Owner, site type, monitoring, and resource limits stay fixed for users who are not platform administrators. A template cannot set them for such a user.

Invalid files¶

A file that fails to render, fails to parse, or is not a YAML mapping is skipped. The Hub writes an error to its log. The other templates and the create form continue to work.

The Hub API checks a template before it saves it. It answers 400 for an invalid name, for content larger than 500 KiB, and for a document that is not a YAML mapping. A file that you copy into the ad-hoc directory by other means gets no such check. Use the Hub API, so the Hub reports problems at once.