Catlet specifications

Catlet specifications store a catlet configuration in eryph as a versioned, reusable resource. You save a catlet configuration file once as a specification and deploy it into one or more environments. Every change creates a new version, so you always know which configuration a catlet was deployed from.

Specifications or New-Catlet?

New-Catlet creates a catlet directly from a catlet configuration. The configuration is resolved when the catlet is created and is not stored as a template in eryph. This is still the quickest way for one-off catlets.

A catlet specification is useful when you want to:

• keep the configuration of a catlet in eryph instead of a local file,
• deploy the same configuration into several environments, for example dev and test,
• deploy exactly the same genes again later, even if newer genes have been published in the meantime,
• track changes of the configuration as versions with comments.

Lifecycle

1. Create a specification from a catlet configuration file (New-CatletSpecification). This creates the first version.
2. Deploy a version into an environment (Deploy-Catlet). The deployment creates a catlet.
3. Update the specification (Update-CatletSpecification). This adds a new version. Existing catlets are not changed.
4. Redeploy the new version into an environment (Deploy-Catlet -Redeploy). This replaces the existing catlet.
5. Remove the specification (Remove-CatletSpecification).

Create a specification

Create a specification from a catlet configuration file:

CopyGet-Content .\webserver.yaml | New-CatletSpecification -ProjectName my-project -Comment "initial version"

# or pass the content directly
New-CatletSpecification -Config (Get-Content .\webserver.yaml -Raw) -ProjectName my-project

The name of the specification is taken from the name of the catlet configuration (catlet if no name is set). Specification names must be unique within a project. If the project is omitted, the default project is used.

The content is read as YAML. Use -Json if your catlet configuration is JSON.

What eryph builds for each version

When a version is saved, eryph resolves the configuration against the genepool and stores the result together with the content you provided:

• gene set references such as dbosoft/ubuntu-22.04/latest are resolved to a specific gene set version,
• the parent catlets are bred into the configuration and the fodder from fodder genes is expanded,
• every gene used by the catlet is pinned by its hash.

A deployment uses the pinned genes of the version and does not resolve gene set tags again. Deploying a version again later therefore results in the same catlet, even if the gene set has been updated in the genepool since.

Variables are not resolved when the specification is saved. Their values are provided when the specification is deployed (see Deploy).

Architectures

Each version is built for one or more architectures, for example hyperv/amd64. The built configuration of an architecture is called a variant. If you do not specify the architectures, the specification is built for hyperv/amd64.

CopyGet-Content .\webserver.yaml | New-CatletSpecification -Architectures hyperv/amd64

eryph-zero deploys catlets on Hyper-V, so only Hyper-V architectures (or any) can be deployed.

Update a specification

Update-CatletSpecification adds a new version to an existing specification. Versions are never changed once they have been created.

CopyGet-Content .\webserver.yaml | Update-CatletSpecification -Id webserver -ProjectName my-project -Comment "added nginx fodder"

-Id accepts the id or the name of the specification. Updating a specification does not change any deployed catlet. To apply the new version to a catlet, redeploy it (see Redeploy).

Inspect specifications and versions

Copy# list all specifications of a project
Get-CatletSpecification -ProjectName my-project

# get a specification by name
Get-CatletSpecification webserver -ProjectName my-project

# get the configuration content of the latest version
Get-CatletSpecification webserver -ProjectName my-project -Config

The specification shows its latest version and its deployments, one per environment it is deployed into, together with the id of the deployed catlet.

To inspect the versions of a specification:

Copy$spec = Get-CatletSpecification webserver -ProjectName my-project

# list all versions
Get-CatletSpecificationVersion -SpecificationId $spec.Id

# get a single version including its variants
Get-CatletSpecificationVersion -SpecificationId $spec.Id -VersionId [version id]

# get the configuration content of a version
Get-CatletSpecificationVersion -SpecificationId $spec.Id -VersionId [version id] -Config

Each variant of a version contains the built configuration, the variables of the catlet and the pinned genes.

Deploy a specification

Submit-CatletDeployment (alias Deploy-Catlet) deploys a version of a specification as a catlet. If you pipe a specification, its latest version is deployed:

Copy# deploy the latest version into the default environment
Get-CatletSpecification webserver -ProjectName my-project | Deploy-Catlet

# deploy into another environment
Get-CatletSpecification webserver -ProjectName my-project | Deploy-Catlet -Environment test

# deploy a specific version
Get-CatletSpecificationVersion -SpecificationId $spec.Id -VersionId [version id] | Deploy-Catlet

The catlet gets the name of the specification and is created in the project of the specification.

Environments
The environment is part of the deployment, not of the specification. The -Environment of the deployment overrides an environment set in the catlet configuration. If you omit it, the catlet is deployed into the default environment.

A specification can be deployed into each environment once. Deploying it into the same environment again fails unless you use -Redeploy. The deployment also fails if a catlet with the same name already exists in the environment of the project.

Variables
If the catlet configuration declares variables, the command prompts for their values. Secret variables are entered masked. Use -Variables to provide the values and -SkipVariablesPrompt to skip the prompt:

CopyGet-CatletSpecification webserver | Deploy-Catlet -Variables @{ password = "..." } -SkipVariablesPrompt

Architecture
If a version contains more than one variant, select the architecture to deploy with -Architecture.

Redeploy

-Redeploy replaces the catlet of the specification in the target environment with a new catlet built from the selected version.

CopyGet-CatletSpecification webserver -ProjectName my-project | Deploy-Catlet -Environment test -Redeploy

Deployments in other environments are not affected.

Catlets deployed from a specification

A catlet deployed from a specification is a normal catlet. You can start, stop and remove it with the usual commands. Get-Catlet shows the specification and the version the catlet was deployed from.

Update-Catlet can still be used to change a deployed catlet. However, such a change is not stored in the specification and is lost when the catlet is redeployed. To change the catlet permanently, update the specification and redeploy it.

Remove a specification

A specification cannot be removed while it is deployed in any environment. Remove the deployed catlets first, or use -RemoveCatlet to remove them together with the specification:

CopyGet-CatletSpecification webserver -ProjectName my-project | Remove-CatletSpecification -RemoveCatlet

Removing a specification also removes all of its versions. The command asks for confirmation unless you use -Force.

Specifications in the eryph App

The eryph App shows the specifications of your projects on the Specifications tab. You can create and update specifications, browse their versions and deploy them into environments from there.