eryph
by

References

References: Powershell commands

Installation

If you install eryph-zero the powershell modules will be installed automatically.

The eryph powershell modules can also be installed from the powershell gallery:

Both Compute Client and Identity Client depend on Client Configuration and will be installed with them.

This reference covers Eryph.ComputeClient 0.17, Eryph.IdentityClient 0.10 and Eryph.ClientRuntime.Configuration 0.10. Commands marked with (API 1.2) require eryph-zero 0.5 or later.

Catlet Commands

Commands for managing catlets (virtual machines).

Commands that act on an existing catlet take its id or its name in -Id (alias -Name). A catlet name is only unique within a project and environment, so use -ProjectName and -Environment to select the catlet when looking it up by name.

Get-Catlet - Gets one or more catlets, or their configuration

Get-Catlet [[-Name] <string>] [-ProjectName <string>] [-Environment <string>] [<CommonParameters>]
Get-Catlet [-Id <string[]>] [<CommonParameters>]
Get-Catlet [[-Id] <string[]>] -Config [<CommonParameters>]

New-Catlet - Creates a new catlet from a catlet specification file or a parent gene

New-Catlet [-InputObject] <string[]> [-NoWait] [-ProjectName <string>] [-Name <string>] [-Variables <hashtable>] [-SkipVariablesPrompt] [<CommonParameters>]
New-Catlet -Config <string> [-NoWait] [-ProjectName <string>] [-Name <string>] [-Variables <hashtable>] [-SkipVariablesPrompt] [<CommonParameters>]
New-Catlet [-Parent <string>] [-NoWait] [-ProjectName <string>] [-Name <string>] [-Variables <hashtable>] [-SkipVariablesPrompt] [<CommonParameters>]

Start-Catlet - Starts one or more catlets

Start-Catlet [-Id] <string[]> [-Force] [-NoWait] [-ProjectName <string>] [-Environment <string>] [<CommonParameters>]

Stop-Catlet - Stops one or more catlets

Stop-Catlet [-Id] <string[]> [-Force] [-NoWait] [-Mode <CatletStopMode>] [-ProjectName <string>] [-Environment <string>] [<CommonParameters>]

Remove-Catlet - Removes one or more catlets

Remove-Catlet [-Id] <string[]> [-Force] [-PassThru] [-NoWait] [-ProjectName <string>] [-Environment <string>] [<CommonParameters>]

Update-Catlet - Updates the configuration of an existing catlet

Update-Catlet [-Id] <string[]> [-Config <string>] [-NoWait] [-ProjectName <string>] [-Environment <string>] [<CommonParameters>]

Fodder and variables cannot be changed by an update; they are ignored with a warning.

Test-Catlet - Expands and validates a catlet configuration without creating a catlet

Test-Catlet [-InputObject] <string[]> [-NoWait] [-ProjectName <string>] [-Name <string>] [-Variables <hashtable>] [-SkipVariablesPrompt] [-ShowSecrets] [<CommonParameters>]
Test-Catlet [-InputObject] <string[]> -Quick [<CommonParameters>]
Test-Catlet -Config <string> [-NoWait] [-ProjectName <string>] [-Name <string>] [-Variables <hashtable>] [-SkipVariablesPrompt] [-ShowSecrets] [<CommonParameters>]
Test-Catlet -Config <string> -Quick [<CommonParameters>]
Test-Catlet -Parent <string> [-NoWait] [-ProjectName <string>] [-Name <string>] [-Variables <hashtable>] [-SkipVariablesPrompt] [-ShowSecrets] [<CommonParameters>]

Get-CatletIp - Gets the IP addresses of catlets

Get-CatletIp [[-Name] <string>] [-ProjectName <string>] [-Environment <string>] [-InternalIp] [-Network <string>] [<CommonParameters>]
Get-CatletIp [-Id <string[]>] [-InternalIp] [-Network <string>] [<CommonParameters>]

Catlet Specification Commands

(API 1.2) Commands for managing catlet specifications: versioned catlet configurations which are stored in a project and deployed into one or more environments.

Get-CatletSpecification - Gets catlet specifications, or their configuration

Get-CatletSpecification [[-Name] <string>] [-ProjectName <string>] [-Config] [<CommonParameters>]
Get-CatletSpecification [-Id <string[]>] [-Config] [<CommonParameters>]

New-CatletSpecification - Creates a catlet specification from a catlet configuration

New-CatletSpecification [-InputObject] <string[]> [-Comment <string>] [-ProjectName <string>] [-Json] [-Architectures <string[]>] [-NoWait] [<CommonParameters>]
New-CatletSpecification -Config <string> [-Comment <string>] [-ProjectName <string>] [-Json] [-Architectures <string[]>] [-NoWait] [<CommonParameters>]

Update-CatletSpecification - Adds a new version to an existing catlet specification

Update-CatletSpecification [-InputObject] <string[]> -Id <string> [-Comment <string>] [-Json] [-Architectures <string[]>] [-NoWait] [-ProjectName <string>] [<CommonParameters>]
Update-CatletSpecification -Config <string> -Id <string> [-Comment <string>] [-Json] [-Architectures <string[]>] [-NoWait] [-ProjectName <string>] [<CommonParameters>]

Get-CatletSpecificationVersion - Gets the versions of a catlet specification, or the configuration of a version

Get-CatletSpecificationVersion -SpecificationId <string> [<CommonParameters>]
Get-CatletSpecificationVersion [-VersionId] <string[]> -SpecificationId <string> [<CommonParameters>]
Get-CatletSpecificationVersion [[-VersionId] <string[]>] -SpecificationId <string> -Config [<CommonParameters>]

Remove-CatletSpecification - Removes catlet specifications

Remove-CatletSpecification [-Id] <string[]> [-RemoveCatlet] [-Force] [-PassThru] [-NoWait] [-ProjectName <string>] [<CommonParameters>]

Submit-CatletDeployment (alias Deploy-Catlet) - Deploys a catlet specification version into an environment

Submit-CatletDeployment -SpecificationId <string> -SpecificationVersionId <string> [-Architecture <string>] [-Environment <string>] [-Variables <hashtable>] [-Redeploy] [-SkipVariablesPrompt] [-Force] [-NoWait] [<CommonParameters>]
Submit-CatletDeployment [-Version] <CatletSpecificationVersion> [-Architecture <string>] [-Environment <string>] [-Variables <hashtable>] [-Redeploy] [-SkipVariablesPrompt] [-Force] [-NoWait] [<CommonParameters>]
Submit-CatletDeployment [-Specification] <CatletSpecification> [-Architecture <string>] [-Environment <string>] [-Variables <hashtable>] [-Redeploy] [-SkipVariablesPrompt] [-Force] [-NoWait] [<CommonParameters>]

A piped specification deploys its latest version, e.g. Get-CatletSpecification -Name my-catlet | Deploy-Catlet. A specification has one deployment per environment; deploying again into the same environment requires -Redeploy.

Guest Services and Provisioning Commands

(API 1.2) Commands for the eryph guest services running inside a catlet and for the provisioning state of catlets.

Get-CatletProvisioningStatus - Gets the provisioning status of catlets

Get-CatletProvisioningStatus [[-Name] <string>] [-ProjectName <string>] [-Environment <string>] [<CommonParameters>]
Get-CatletProvisioningStatus [-Id <string[]>] [<CommonParameters>]

Get-CatletProvisioningLog - Gets the provisioning log of catlets, as structured events or as text

Get-CatletProvisioningLog [[-Name] <string>] [-ProjectName <string>] [-Environment <string>] [-AsText] [<CommonParameters>]
Get-CatletProvisioningLog [-Id <string[]>] [-AsText] [<CommonParameters>]

Get-CatletGuestServiceStatus - Gets the state reported by the guest services of catlets

Get-CatletGuestServiceStatus [[-Name] <string>] [-ProjectName <string>] [-Environment <string>] [<CommonParameters>]
Get-CatletGuestServiceStatus [-Id <string[]>] [<CommonParameters>]

Get-CatletGuestServiceConfig - Gets the guest services configuration of catlets

Get-CatletGuestServiceConfig [[-Name] <string>] [-ProjectName <string>] [-Environment <string>] [<CommonParameters>]
Get-CatletGuestServiceConfig [-Id <string[]>] [<CommonParameters>]

Set-CatletGuestServiceConfig - Sets the shell used for interactive SSH sessions into catlets

Set-CatletGuestServiceConfig [-Id] <string[]> [-ProjectName <string>] [-Environment <string>] [-Shell <string>] [-ShellArgs <string>] [-Force] [-NoWait] [<CommonParameters>]

An empty string clears the setting; an omitted parameter leaves the current value unchanged.

Remove-CatletGuestServiceAccessKey - Revokes your SSH access key from catlets

Remove-CatletGuestServiceAccessKey [-Id] <string[]> [-ProjectName <string>] [-Environment <string>] [-Force] [-PassThru] [-NoWait] [<CommonParameters>]

Gene Commands

Commands for managing the genes in the local gene pool.

Get-CatletGene - Gets genes from the local gene pool

Get-CatletGene [[-GeneSet] <string>] [-Name <string>] [-Architecture <string>] [<CommonParameters>]
Get-CatletGene [-Id <string[]>] [<CommonParameters>]

Remove-CatletGene - Removes genes from the local gene pool

Remove-CatletGene [-Id] <string[]> [-Force] [-PassThru] [-NoWait] [<CommonParameters>]
Remove-CatletGene -Unused [-Force] [-PassThru] [-NoWait] [<CommonParameters>]

Disk Commands

Commands for managing catlet disks.

Get-CatletDisk - Gets catlet disks

Get-CatletDisk [[-Name] <string>] [-ProjectName <string>] [-Environment <string>] [-Location <string>] [-DataStore <string>] [<CommonParameters>]
Get-CatletDisk [-Id <string[]>] [<CommonParameters>]

New-CatletDisk - Creates a new empty disk

New-CatletDisk -Name <string> -Size <int> -ProjectName <string> -Location <string> [-Store <string>] [-Environment <string>] [-NoWait] [<CommonParameters>]

Remove-CatletDisk - Removes catlet disks

Remove-CatletDisk [-Id] <string[]> [-Force] [-PassThru] [-NoWait] [<CommonParameters>]

Project Commands

Commands for managing projects and project members.

Get-EryphProject - Gets eryph projects

Get-EryphProject [[-Name] <string>] [<CommonParameters>]
Get-EryphProject [-Id <string[]>] [<CommonParameters>]

New-EryphProject - Creates a new project

New-EryphProject [-Name] <string> [-NoWait] [<CommonParameters>]

Remove-EryphProject - Removes projects

Remove-EryphProject [-Id] <string[]> [-Force] [-NoWait] [<CommonParameters>]

Get-EryphProjectMemberRole - Gets the member roles of a project

Get-EryphProjectMemberRole [[-Id] <string[]>] -ProjectName <string> [<CommonParameters>]

Add-EryphProjectMemberRole - Assigns a role in a project to a member

Add-EryphProjectMemberRole [-MemberId] <string> -ProjectName <string> -Role <BuildInRole> [-NoWait] [<CommonParameters>]
Add-EryphProjectMemberRole [-MemberId] <string> -ProjectName <string> -RoleId <string> [-NoWait] [<CommonParameters>]

Remove-EryphProjectMemberRole - Removes member role assignments from a project

Remove-EryphProjectMemberRole [-Id] <string[]> -ProjectName <string> [-NoWait] [<CommonParameters>]

Network Commands

Commands for managing the virtual networks of projects.

Get-VNetwork - Gets virtual networks, or the network configuration of a project

Get-VNetwork [[-Name] <string>] [-Environment <string>] [-ProjectName <string>] [<CommonParameters>]
Get-VNetwork [-Id <string[]>] [-ProjectName <string>] [<CommonParameters>]
Get-VNetwork -Config -ProjectName <string> [<CommonParameters>]

Set-VNetwork - Applies a network configuration to a project

Set-VNetwork [-InputObject] <string[]> -ProjectName <string> [-Force] [-NoWait] [<CommonParameters>]
Set-VNetwork -Config <string> -ProjectName <string> [-Force] [-NoWait] [<CommonParameters>]

Operation Commands

Commands for inspecting and cancelling operations.

Get-EryphOperation - Gets operations, optionally with their logs, resources, tasks and projects

Get-EryphOperation [[-Id] <string[]>] [-WithLogs] [-WithResources] [-WithTasks] [-WithProjects] [<CommonParameters>]

Stop-EryphOperation - (API 1.2) Cancels running operations

Stop-EryphOperation [-Id] <string[]> [-Force] [-PassThru] [<CommonParameters>]

Identity Commands

Commands for managing identity clients (Eryph.IdentityClient).

Get-EryphClient - Gets identity clients

Get-EryphClient [[-Id] <string[]>] [<CommonParameters>]
Get-EryphClient [[-Name] <string[]>] [<CommonParameters>]

New-EryphClient - Creates a new identity client

New-EryphClient [-Name] <string[]> [-AllowedScopes] <string[]> [-IsSuperAdmin] [<CommonParameters>]
New-EryphClient [-Name] <string[]> [-AllowedScopes] <string[]> [-IsSuperAdmin] [-AddToConfiguration] [-AsDefault] [<CommonParameters>]

Set-EryphClient - Updates the name and scopes of an identity client

Set-EryphClient [-Id] <string> -Name <string> -AllowedScopes <string[]> [<CommonParameters>]

New-EryphClientKey - Creates a new key for an identity client

New-EryphClientKey [-Id] <string[]> [-SharedKey] [<CommonParameters>]

Remove-EryphClient - Removes identity clients

Remove-EryphClient [-Id] <string[]> [-Force] [<CommonParameters>]

Configuration Commands

Commands for managing the local client configuration and credentials (Eryph.ClientRuntime.Configuration). These commands do not take -Credentials.

Get-EryphClientConfiguration - Gets the clients stored in a client configuration

Get-EryphClientConfiguration [[-Id] <string[]>] [-Configuration <string>] [<CommonParameters>]
Get-EryphClientConfiguration -Default [-Configuration <string>] [<CommonParameters>]

Add-EryphClientConfiguration - Adds client credentials to a client configuration

Add-EryphClientConfiguration [-Id] <string> [[-Name] <string>] -Credentials <ClientCredentials[]> [-AsDefault] [-Configuration <string>] [-WhatIf] [-Confirm] [<CommonParameters>]

Set-EryphClientConfiguration - Updates a client in a client configuration

Set-EryphClientConfiguration [-Id] <string[]> [[-Name] <string>] [-IsDefault <bool>] [-Credentials <ClientCredentials>] [-PassThru] [-Configuration <string>] [-WhatIf] [-Confirm] [<CommonParameters>]

Remove-EryphClientConfiguration - Removes clients from a client configuration

Remove-EryphClientConfiguration [-Id] <string[]> [-Force] [-PassThru] [-Configuration <string>] [-WhatIf] [-Confirm] [<CommonParameters>]

Get-EryphClientCredentials - Gets client credentials from a client configuration

Get-EryphClientCredentials [[-Id] <string[]>] [-Configuration <string>] [<CommonParameters>]
Get-EryphClientCredentials [-Name <string>] [-Configuration <string>] [<CommonParameters>]
Get-EryphClientCredentials [-SystemClient] [-Configuration <string>] [<CommonParameters>]

New-EryphClientCredentials - Creates client credentials from a client private key

New-EryphClientCredentials [-InputObject] <Object[]> -Id <string> -IdentityEndpoint <uri> -Configuration <string> [<CommonParameters>]

Set-EryphSessionCredentials - Sets the credentials used by all eryph commands in the current PowerShell session

Set-EryphSessionCredentials -Credentials <ClientCredentials> [<CommonParameters>]

Clear-EryphSessionCredentials - Clears the session credentials

Clear-EryphSessionCredentials [<CommonParameters>]

Get-EryphAccessToken - Gets an access token for the eryph APIs

Get-EryphAccessToken [-Scopes <string[]>] [-AsPlainText] [-Credentials <ClientCredentials>] [<CommonParameters>]

Set-EryphConfigurationStore - Sets the storage location of a client configuration

Set-EryphConfigurationStore [[-All] <string>] [-Configuration <string>] [<CommonParameters>]
Set-EryphConfigurationStore [-Clients <string>] [-Endpoints <string>] [-Defaults <string>] [-Configuration <string>] [<CommonParameters>]

Common Parameters

All compute and identity commands accept -Credentials to use specific client credentials instead of the default credentials (see Get-EryphClientCredentials and Set-EryphSessionCredentials). It is omitted from the syntax above for brevity.

In addition, all commands support the PowerShell common parameters such as -Verbose, -Debug, -ErrorAction, -WarningAction and -OutVariable.

Parameter Reference

-Id - Identifier of the resource. For commands which act on catlets, the catlet name can be used as well (alias -Name). Accepts pipeline input.

-Name - Resource name. Used for creation and for lookups by name.

-ProjectName - The project of the resource. Defaults to the default project.

-Environment - The environment of the resource. Catlet, disk and network names are unique only per project and environment, so use it to select a resource by name. For Submit-CatletDeployment, the environment to deploy into (default: default).

-Config - Configuration in YAML or JSON format. For Get commands, returns the configuration instead of the resource.

-InputObject - Configuration from pipeline input, e.g. Get-Content catlet.yaml | New-Catlet.

-Parent - Parent gene the new catlet inherits from.

-Variables - Hashtable of values for the variables of a catlet configuration.

-SkipVariablesPrompt - Does not prompt for variables without a value.

-Architectures / -Architecture - Catlet architectures such as hyperv/amd64. A specification is built for each of its architectures; a deployment selects one of them.

-Comment - Comment stored with a new specification version.

-Json - The specification content is JSON instead of YAML.

-Redeploy - Replaces the existing deployment of the specification in the target environment. An existing catlet might be deleted.

-RemoveCatlet - Also removes the catlets deployed from the specification.

-NoWait - Returns the operation immediately without waiting for its completion.

-Force - Skips confirmation prompts.

-PassThru - Returns the affected resource.

-Mode - Stop mode for Stop-Catlet: Shutdown (graceful shutdown of the guest), Hard (turn off) or Kill (forcefully terminate the VM).

-Role - Built-in project role: Owner, Contributor or Reader.

-ShowSecrets - Shows secret values in the expanded configuration.

-Quick - Only validates the configuration on the server, without starting an operation.

-Unused - Selects genes which are not used by any catlet or disk.

-InternalIp - Returns the internal (project network) IP addresses instead of the floating addresses.

-AsText - Returns the provisioning log as human readable text instead of structured events.

-WithLogs, -WithResources, -WithTasks, -WithProjects - Includes the logs, resources, tasks or projects of the operation.

-Configuration - Name of the client configuration: default, zero (eryph-zero on this machine) or local.

-SystemClient - Selects the eryph-zero system client. Requires administrative privileges.

-AllowedScopes - Scopes granted to an identity client.

-IsSuperAdmin - Grants the identity client super admin rights.

-AddToConfiguration / -AsDefault - Stores the new client in the client configuration, optionally as default client.

Notes

  • Commands which act on catlets accept the catlet id or name in -Id or from the pipeline.
  • Use -Force with removal commands to avoid interactive prompts.
  • Most modification commands support -NoWait for asynchronous operations; use Get-EryphOperation to follow up and Stop-EryphOperation to cancel.
  • Pipeline support enables command chaining, e.g. Get-Catlet -ProjectName test | Stop-Catlet -Force.