Skip to content
Stackship documentation Svenska

BlueprintsAdministrators

Platform catalog repository

Where the platform-wide blueprint catalog is pulled from, how often, what a pull changes, and what happens when the repository cannot be reached.

Every boundary sees the platform catalog: the blueprints shipped inside the Blueprints service's image, plus those pulled from a git repository. Which repository, which branch and how often are chosen when the platform is installed.

Settings

The installer asks for the first three among the Blueprints module's settings, under Blueprint catalog. They reach the service as environment variables from the ConfigMap module-blueprints-config in stackship-system, and are read when it starts.

Environment variable In the installer Default Meaning
Blueprints__Catalog__RepositoryUrl Blueprint catalog repository https://github.com/Stackship-AB/blueprints.git The repository to clone, as an http or https URL. It is cloned without credentials. Empty: no repository — the catalog is only what ships with the release
Blueprints__Catalog__Ref Branch or tag main The branch to clone. It must be a branch: a tag or a commit cannot be cloned, and every pull fails
Blueprints__Catalog__RefreshIntervalSeconds Refresh interval (seconds) 3600 How often to pull. Values below 60 count as 60
Blueprints__Catalog__Path Not asked blueprints The folder in the repository whose directories are the blueprints

Important

Use an https URL. An http repository is accepted, but it is cloned without transport security, so anyone on the network path can change what it serves, and every boundary deploys from this catalog. Whoever can push to the repository's branch decides what every boundary's deployers run — see How a deploy runs.

The repository's layout is described in Repository layout.

What a pull does

  • When the service starts, it loads the blueprints shipped in its image, then pulls the repository; after that it pulls on every interval. The boundaries' catalog sources are synced in the same pass.
  • A pull adds the repository's new blueprints and updates changed ones. A repository blueprint with the slug of a shipped one replaces it.
  • A blueprint that has left the repository is removed from the catalog, except those shipped with the release, which always stay. A blueprint whose template no longer parses keeps its last good version.
  • Blueprints that boundaries published themselves are never touched.
  • Instances already deployed from a removed blueprint keep running.
  • Submodules are not cloned, and a clone that takes longer than two minutes is abandoned.

When the repository cannot be cloned — unreachable, a wrong branch or folder, a timeout — the catalog stays exactly as it was and every blueprint in it can still be deployed. The service logs Blueprint catalog could not be fetched; keeping the catalog as it is. with the cause just before. The time the portal shows next to Catalog from is that of the last attempt, whether or not it succeeded.

In a template, {{domain_suffix}} becomes the platform's app domain and {{cert_issuer}} the certificate issuer chosen at installation.

Pull now

Anyone with blueprints/templates/write on a boundary can pull the platform catalog at once with Refresh catalog — see Refresh the platform catalog.