Catalog sources

A catalog source is a git repository your boundary publishes its own blueprints from. Its blueprints appear in this boundary's catalog only, next to the platform's, and are kept in step with the repository. Managing sources needs blueprints/templates/write on the boundary; Owners, Contributors and Blueprints Operators have it.

Caution

Whoever can push to a source's branch decides what this boundary's deployers run. A blueprint's images run with read access to the instance vault, granted with the deployer's permissions. Connect only repositories whose write access you trust with that, and review a template from a catalog source before you deploy it — see How a deploy runs.

Before you start

• Lay the repository out as one directory per blueprint, each with a template.yaml, under a common folder — see Repository layout. Validate each template before you push it: a template that does not parse is skipped on every sync without a warning — see Validate a template.
• For a private repository, connect its GitHub, GitLab or Azure DevOps account to the boundary first — see Add a deployment source. A public repository on any git host needs nothing connected.

Add a source

1. In the portal at https://portal.example.com, open Blueprints and choose Blueprint repositories. The button is shown only to people who can manage sources. The sheet lists the boundary's sources.
2. Choose Connect a repository, and choose where the repository is:
   • A connected deployment source — pick the Deployment source (only GitHub, GitLab and Azure DevOps accounts are offered), then the Repository, then the Branch, which is prefilled with the repository's default branch. Works for private repositories: each sync clones with a short-lived token from the deployment source, and nothing is stored with the catalog source, so a rotated credential keeps working.
   • A public repository URL — enter the Repository URL, the repository's HTTPS clone URL, and the Branch (main unless you change it). The repository is cloned without credentials, so it must be public. A URL that is not https:// or carries a username or password is refused, and so is one whose host is written as a private or link-local IP address or is an in-cluster or local name. The check reads the URL as written: a public-looking name is not resolved, so it is not refused when it leads to a private address.
3. Folder — the folder that holds one directory per blueprint, blueprints unless you change it. Leave it empty when the blueprint directories are at the repository root.
4. Choose Connect.

The source is synced once straight away. From then on it is synced on the platform's schedule — every hour unless your platform administrator has changed it — and whenever you choose Sync now.

• A boundary can connect a repository and folder only once.
• Branch must name a branch. A tag or a commit cannot be cloned, so every sync of such a source fails.
• When the first sync fails, the source is still added, with the failure shown on it; fix the cause and sync again.

Sync status

Each source shows its repository, branch and folder, the number of blueprints it published, and the outcome of its last sync:

Status	Meaning
Not synced yet	No sync has run
Synced	Every template in the repository that parses is in the catalog
Synced with warnings	Everything synced except the blueprints named in the message — typically a directory whose name is already the slug of a blueprint in the platform catalog or of another blueprint in this boundary. Rename the directory
Unreachable	The repository could not be fetched — the deployment source is no longer connected, the branch is gone, or the host did not answer. The blueprints from the last successful sync stay as they were

A sync adds new blueprints, updates changed ones, and removes those that are no longer in the repository. A blueprint whose template.yaml does not parse keeps the version from the last sync that could read it, and a new one does not appear at all.

Sync now

Choose Sync now on a source. The result says what was added, updated and removed, Already up to date, or Could not reach the repository.

Remove a source

Choose Remove on the source and confirm with Remove. Its blueprints leave the catalog; any instance already deployed from them keeps running.

With the API

The portal adds, syncs and removes sources. The API can also change a source's branch or folder, or pause its syncing:

Method and route	Does
GET /boundaries/{boundaryId}/resources/blueprints/sources	List the boundary's sources
POST /boundaries/{boundaryId}/resources/blueprints/sources	Add a source: repositoryUrl, or provider, installationId and repositoryId; with ref and path
PATCH /boundaries/{boundaryId}/resources/blueprints/sources/{sourceId}	Change ref or path, or pause and resume with enabled
POST /boundaries/{boundaryId}/resources/blueprints/sources/{sourceId}/sync	Sync now
DELETE /boundaries/{boundaryId}/resources/blueprints/sources/{sourceId}	Remove the source and its blueprints

Listing needs blueprints/read; everything else needs blueprints/templates/write. Calling the API is described in Platform API.

Important

The token a sync clones with is issued to the Blueprints service, not to you. Adding a source through the API accepts any repository of any account connected to the boundary without checking that you may read the boundary's deployment sources, so blueprints/templates/write alone is enough to publish the templates in such a repository to the boundary's catalog.

Refresh the platform catalog

When the platform catalog is pulled from a repository, the line above the catalog names it — Catalog from <repository> @ <branch> — and when it was last synced. The platform pulls it on the same schedule as catalog sources. Refresh catalog, next to that line, pulls it now and says what was added, updated or removed; it is shown to people with blueprints/templates/write.

If the repository cannot be reached, the catalog stays as it was and every blueprint in it can still be deployed. A platform with no catalog repository shows only the blueprints shipped with its release, and no line. Your platform administrator chooses the repository — see Platform catalog repository.