diff options
Diffstat (limited to 'spec.mdwn')
| -rw-r--r-- | spec.mdwn | 40 |
1 files changed, 16 insertions, 24 deletions
@@ -1,4 +1,4 @@ -[[!meta title="Baserock definitions format"]] +Title: Baserock definitions format The Baserock definitions format =============================== @@ -6,29 +6,19 @@ The Baserock definitions format This page describes the Baserock definitions format (morph files). It is intended to be useful as an *informal* specification. It is not guaranteed to be accurate or exhaustive. -If you are just getting started with Baserock, the [[quick-start]], [[devel-with]] and [[guides]] pages provide a more practical introduction. +If you are just getting started with Baserock, the wiki pages [quick-start](http://wiki.baserock.org/quick-start), [devel-with](http://wiki.baserock.org/devel-with) and [guides](http://wiki.baserock.org/guides) pages provide a more practical introduction. -The allowed YAML constructs are described in json-schema format here: <http://git.baserock.org/cgi-bin/cgit.cgi/baserock/baserock/definitions.git/tree/schemas>. +The allowed YAML constructs are described in json-schema format here: <http://git.baserock.org/cgit/baserock/baserock/spec.git/tree/schemas>. -The data model is described using OWL here: <http://git.baserock.org/cgi-bin/cgit.cgi/baserock/baserock/definitions.git/tree/schemas/baserock.owl>. +The data model is described using OWL here: <http://git.baserock.org/cgit/baserock/baserock/spec.git/tree/schemas/baserock.owl>. -The source code of [[Morph]] and [[YBD]] might be more useful if you need a completely accurate description of how the current Baserock definition format is used in practice. - -[[!toc startlevel=2 levels=2]] +The source code of [Morph] and [YBD] might be more useful if you need a completely accurate description of how the current Baserock definition format is used in practice. Versioning ---------- The current version of the definitions format is version 7. -See also: the [[planned]] versions, and the [[historical]] versions of the -format. - -Please propose changes to the format described here on the -[[baserock-dev@baserock.org mailing list|mailinglist]]. Ideally, provide a -patch for this file against the <git://baserock.branchable.com/> repo, but just -describing the change you want to make is also fine. - Definitions repository ---------------------- @@ -46,7 +36,7 @@ well, such as configuration data and documentation. The Baserock Project maintains a set of 'reference system definitions' at [git://git.baserock.org/baserock/baserock/definitions] (which can also be referred to as [baserock:baserock/definitions], when using the repo aliasing -feature of [[Morph]]). That repo contains systems that can be built and +feature of [Morph]). That repo contains systems that can be built and deployed as-is, but it is important that users can fork this repo as well, and work on systems in their version using `git merge` or `git rebase` to keep up to date with changes from upstream. @@ -55,8 +45,8 @@ Baserock tooling should not mandate anything about the definitions repo that the user wants to process, other than the rules defined below. -[git://git.baserock.org/baserock/baserock/definitions]: http://git.baserock.org/cgi-bin/cgit.cgi/baserock/baserock/definitions.git -[baserock:baserock/definitions]: http://git.baserock.org/cgi-bin/cgit.cgi/baserock/baserock/definitions.git +[git://git.baserock.org/baserock/baserock/definitions]: http://git.baserock.org/cgit/baserock/baserock/definitions.git +[baserock:baserock/definitions]: http://git.baserock.org/cgit/baserock/baserock/definitions.git ### Structure @@ -95,7 +85,7 @@ The toplevel entity in a definition is a dict, in all cases. Any syntax errors or type errors (such the toplevel entity being a number, or something) should be reported to the user. -The [[Morph]] tool raises an error if any unknown dictionary keys are found in +The [Morph] tool raises an error if any unknown dictionary keys are found in the definition, mainly so that it reports any spelling errors in key names. ### Common fields @@ -276,10 +266,10 @@ Example system: ### Deployment definitions: Clusters **NOTE**: The deployment mechanism specified here is quite abstract. Most of -the code used to do real-world deployments is currently tied to [[Morph]] and +the code used to do real-world deployments is currently tied to [Morph] and kept in [morph.git]. -For 'deployment', [[Morph]] defines an API for running 'extensions'. The +For 'deployment', [Morph] defines an API for running 'extensions'. The 'cluster' and 'system' definitions together describe what extensions should be run, and what should be set in their environment, in order to deploy the system. See the "Deployment extension API" section below for how to find and @@ -449,7 +439,7 @@ of the definitions.git repo. Configure extensions have the extension `.configure`, check extensions have the extension `.check`, and write extensions have the extension `.write`. -[[Morph]] will look for extensions inside the 'morphlib' Python package, in the +[Morph] will look for extensions inside the 'morphlib' Python package, in the `exts/` dir, before looking in the definitions.git repo. An extension must be executable using the [POSIX `exec()` system call]. We @@ -457,7 +447,7 @@ encourage writing them as Python scripts and using a `#!/usr/bin/env python` [hashbang], but any executable code is permitted. The 'execution environment' for an extension is sadly unspecified at the moment. -[[Morph]] runs extensions without any kid of chroot environment, but each one +[Morph] runs extensions without any kid of chroot environment, but each one is run in a separate [mount namespace]. Running extensions chrooted into the system being deployed does not make sense, as it may not contain the right dependencies for the extensions to work, and it may expect to run on a @@ -490,7 +480,7 @@ Extensions are expected to write status information to 'stdout', and any error messages to 'stderr'. This is for user feedback ONLY, deployment tools should not do anything with this data other than log and/or display it. -[[Morph]] sets an extra environment variable `MORPH_LOG_FD` which is a file +[Morph] sets an extra environment variable `MORPH_LOG_FD` which is a file descriptor that the extension can write log messages to, in order for them to appear in morph.log but not on stdout or stderr. @@ -514,5 +504,7 @@ following content: Fill me in! +[Morph]: http://wiki.baserock.org/Morph/ +[YBD]: http://wiki.baserock.org/ybd/ [morph.git]: git://git.baserock.org/cgi-bin/cgit.cgi/baserock/baserock/morph [YAML]: http://yaml.org/ |