eryph references: genepool files

Geneset Manifest

Gensets manifests are used to provide description and metadata for a set of genes. Within a geneset multiple tags can exists that contains different content. Geneset manifests are JSON files, using snake case for property names. These files are only used with eryph-packer, and not in the local genepool.

Property	Description
version	version of geneset manifest. Current version is 1.1
geneset	The name of the geneset. Required name format: `<org>/<geneset>`.
public	Configures whether the geneset should be public. This is a boolean value (true/false). Public genesets can be accessed by everyone, private genesets only within the organization.
short_description	Short description of the geneset. String value not longer than 90 characters. Used in the genepool as a short display name.
description	Description of the geneset in plain text. String value not longer than 200 characters. Used in the genepool as description in lists and general description if no markdown description is defined.
description	Geneset description in plain text. String value not longer then 200 characters. Used in the genepool as description in lists and general description if no markdown description is defined.
description_markdown	Geneset description in markdown format. String value cannot be larger than 2 MiB (megabytes). With this setting, the markdown description is defined directly in the geneset manifest.
description_markdown_file	The filename of the markdown description file. File size cannot exceed 2 MiB (megabytes). With this setting, the markdown description is read from the specified file (e.g. a README.MD).
metadata	A key value list of metadata for the geneset. Two types of metadata values are supported: Values starting with an underscore _ are metadata values used in the genepool to classify the geneset for searching. All other values are free to be used for any type of metadata. The following restrictions apply to metadata max key count: 50 max key name length: 40 characters max value length: 500 characters

List of predefined metadata:

Key	Description
_categories	Category of the geneset. Reserved for future use.
_tags	Search tags of the geneset. List of tags seperated by a column ','. Up to 3 tags are allowed.
_os_types	Operating system types in the geneset. List of os names seperated by a column ','. Allowed os names: windows, linux, openbsd

Key

Description

_categories

Category of the geneset.

Reserved for future use.

_tags

Search tags of the geneset.

List of tags seperated by a column ','.
Up to 3 tags are allowed.

_os_types

Operating system types in the geneset.

List of os names seperated by a column ','.
Allowed os names: windows, linux, openbsd

Geneset Tag Manifest

Geneset tags holds the references to genes. They are used to address the genes within a catlet or fodder spec. Geneset tags are specified in geneset manifests, which are JSON files with following properties:

Property	Description
version	version of geneset tag manifest. Current version is 1.1
geneset	The name of the geneset with tag. Required name format: `<org>/<geneset>/<tag>`.
ref	Sets this geneset tag as a reference. Value has to be the name of another geneset. References are most used for versioning and with the default tag `latest`. Reference tags are always resolved when they are used in a catlet or fodder gene reference. So they allow consumers to to reference current version of a geneset tag and authors to control when a geneset tag should be the default version. Geneset references cannot declare further genes, but metadata.
volumes	Array of genes references for volumes. This property defines the volume genes available in this geneset tag. See below for gene reference format.
fodder	Array of genes references for fodder. This property defines the fodder genes available in this geneset tag. See below for gene reference format.
catlet	Gene reference to catlet in this geneset tag. Required format: `<sha256>:<hash>` A geneset tag can contain a single catlet specification which declares it as catlet geneset. Catlet genesets can be used as parent in other catlets.
parent	Parent of catlet geneset Required format: `<org>/<geneset>/<optional tag>` Required if geneset tag contains a catlet that itself has a parent. Used for reference tracking on the genepool.
metadata	A key value list of metadata for the geneset tag. Two types of metadata values are supported: Values starting with an underscore _ are metadata values used in the genepool to classify the geneset tag for searching. All other values are free to be used for any type of metadata. The following restrictions apply to metadata max key count: 50 max key name length: 40 characters max value length: 500 characters

List of predefined tag metadata:

Key	Description
_os_type	Operating system type in the geneset tag. One of: windows, linux, openbsd
_os_name	Operating system name. Free text that should be filled with the operating system name. Samples: Windows Server 2022 StandardCore ubuntu 22.04

Key

Description

_os_type

Operating system type in the geneset tag.

One of: windows, linux, openbsd

_os_name

Operating system name.

Free text that should be filled with the operating system name.
Samples:

Windows Server 2022 StandardCore
ubuntu 22.04

Gene references:

Gene references define with genes are provided in the geneset. They always have to contain gene name, gene hash and the gene architecture:

Property Description

name The name of the gene. See the gene manifest for details on gene names.

Property	Description
name	The name of the gene. See the gene manifest for details on gene names.
hash	The hash of the gene. The gene hash is the sha256 hash of the gene set manifest. It must be in the format `sha256:<hash>`.
arch	The architecture of the gene. See gene manifest for details on gene architecture.

hash

The hash of the gene.

The gene hash is the sha256 hash of the gene set manifest.
It must be in the format sha256:<hash>.

arch The architecture of the gene.
See gene manifest for details on gene architecture.

Gene manifest

Genes defines the artifacts from which a catlet is built. Genes consists of a gene manifest file in JSON format with the following properties:

Property	Description
version	Version of gene manifest. Current version is 1.1.
name	Name of the gene. Genes can be referenced by consumers using the gene name. E.g. catlets can reference volumes by gene name in disk source setting. Also fodder genes can be referenced by their name. When a gene is resolved for breeding, both name and architecture are considered, so a geneset tag can contain multiple genes with the same name but different architectures.
arch	Architecture of the gene. The gene architecture defines the hypervisor and processor type with which the gene is compatible. A geneset can contain multiple genes with the same name but different architectures. Currently, eryph only supports Hyper-V as a hypervisor and amd64 (x64) as a processor type. Thus, the architecture is intended for future extensions for additional processor types and architectures. An architecture is defined in the format `<hypervisor>/<processortype>`, except for the architecture `any` which is used for an architecture compatible with any hypervisor and processor type. You can also use `<hypervisor>/any` for a gene that is compatible with any processor type. Currently supported values: any hyperv/any hyperv/amd64
type	Gene type One of: catlet, fodder, volume The gene type defines what kind of content the gene contains: catlet genes These are catlet specification files (JSON format). volume genes Disk volumes to be used in genes. fodder genes These are fodder specification files (JSON format).
format	Gene file format One of: plain, zip, gz The format determines how the gene is compressed. Plain is uncompressed. ZIP compressed genes are entire folders that can contain multiple files.
filename	The filename of the gene after it has been extracted to the local genepool. Used only for plain and gz formats, genes in ZIP format contain the filename in the ZIP container.
parts	String array of hashes for gene part files. Format: `sha1:<part_hash>` Genes larger then 80 MB have to be splitted into part files. Each part has to be hashed with sha1.
size	Compressed size of the gene.
original_size	Uncompressed size of the gene.