Using eryph powershell client

The eryph powershell client is installed with eryph-zero and is currently the only client we support for eryph.
This guide provides some general information about using the Powershell client.
A complete reference of commands can be found here.

General Information

Eryph provides a REST based API to interact with it. Eryph-zero has two separate APIs:

• Identity API
• Compute API

The Identity API is used to manage identity clients. See Security for details.

The Compute API is used to manage compute resources such as catlets, disks, and additionally projects and networks.

Operations
Most commands in the compute API that modify a resource return an operation. Operations are long-running tasks that can contain multiple steps and provide a log of the progress of the command.

Copy# list all operations
Get-EryphOperation

# Get a single operation with it's logs
Get-EryphOperation [Id] -WithLogs

However, you don't normally need to worry about operations, as almost all commands that perform an operation in eryph internally wait for the operation status and also provide logging in the verbose output. If you use the NoWait option on these commands, the started operation is returned instead, which you can use to implement your own monitoring.

Credentials
All eryph client commands have a Credentials argument that accepts the response from the Get-EryphClientCredentials command. If you don't specify credentials, the command will look up the default client configuration ( see Client Configuration ) or, if available, try to look up the system client.

The system client is a built-in client available only to local administrators of the eryph-zero host. Therefore, by default, you must run PowerShell in an elevated PowerShell prompt to access the system client if no client configuration has been configured.

See Security for information about how to create a custom client to provide access for non-admins.

Basic catlet operations

Get catlets / Pipeline input

To get catlets you use the Get-Catlet command.

Copy# list all catlets
Get-Catlet

# get a single catlet
Get-Catlet [Id]  

# get catlet by name 
$catletName = "[name]"
Get-catlet | where Name -eq $catletName

The output of the Get-Catlet command can also be used as pipeline input for all commands that operate on a catlet:

Copyget catlet by name and starts it
$catletName = "[name]"
Get-catlet | where Name -eq $catletName | Start-Catlet

Create and remove catlets

Catlets can be created with the command New-Catlet.
This command expects a JSON or YAML catlet specification as input.

Copy$spec = "[catlet spec content]"
New-Catlet -InputObject $spec

# or to read from file
gc catlet.yaml | New-Catlet

To remove a catlet you have to provide the existing catlet or it's id as input:

Copyget catlet by name and starts it
$catletName = "[name]"
Get-catlet | where Name -eq $catletName | Remove-Catlet

# or by id
Remove-Catlet [Id]

Update catlets

Updating catlets requires both the catlet specification and catlet id as input. Therefore the specification cannot be passed from the pipeline:

Copy$catletName = "[name]"
$spec = gc spec.yaml -Raw #use raw to load file as string
Get-catlet | where Name -eq $catletName | Update-Catlet -Config $spec

To update a catlet from the current configuration you can lookup the current configuration of a catlet with following command:

CopyGet-Catlet -Config

Projects & Networks

Projects in eryph are used to isolate catlets of different projects from each other. Catlets and volumes assigned to a project can only be accessed by users that are project members in the project.
In addition projects provide virtual networks visible only within the project.

Create projects and members

Projects can be created with the New-EryphProject command. If you create a project your user will be automatically added as owner of the project, except if it is the system-client which always has access to all projects. To add additional members use the Add-EryphProjectMemberRole command. However, as this command requires the member id as input, you also have to lookup the member id first. Here a full example:

CopyGet-EryphClient # list clients to find out client id

$clientId = '[clientId]'

New-EryphProject myProject
Add-EryphProjectMemberRole `
    -MemberId $clientId `
    -ProjectName myProject `
    -Role Contributor  # or owner/reader

Deleting projects

Projects can be deleted with the Remove-EryphProject command.
Please note that all resources within the project will be deleted with the project, including catlets and disks!

Project networks

Virtual networks in eryph are always bound to a project.
When a project is created a default network will be created for the project. So there is no need to create networks.

In case you would like to modify a project network you can read it with the Get-VNetwork -Config command and update it with Set-VNetwork command:

Copy$projectName = "myProject"
$network = Get-VNetwork -Config `
    -ProjectName $projectName

# after changing network import it again
$network | Set-VNetwork -ProjectName $projectName

Client Configuration

Client configurations store used credentials and endpoints for eryph services.

By default, there is no client configuration, so the powershell commands always fall back to the system client, which is fine if you are working with admin credentials anyway.

However, a more secure way to work with eryph is to use dedicated clients. This is required for remote access.

Client configurations are managed with the commands Get-EryphClientConfiguration, Add-EryphClientConfiguration, Set-EryphClientConfiguration and Remove-EryphClientConfiguration.

Please read the following explanations of how these commands work.

Configurations

Eryph client settings are grouped into Configurations. You can create as many configurations as you need. However, there are 2 configurations that have a special meaning:

• zero
  This is a special configuration group used only for eryph-zero hosts. It doesn't store the endpoints for eryph in the configuration. Instead, endpoints are always looked up from the running zero instance on the same host.
• default
  This is the configuration where clients will try to look up credentials first. Use this group for clients with remote access to eryph-zero hosts.

Configuration Stores

Eryph client supports 3 configuration storage locations that can be used in parallel:

• System store
  System-wide client configurations. These are available to every user on your system. You can use the system-wide configuration to set up preconfigured endpoints for all your users.
• User Store
  This is the default configuration store that stores credentials and endpoints in the user profile.
• Directory Store
  This is a store limited to the current directory. This type of configuration store is useful if you are already working with a repository and want to store endpoint configurations with the repository, excluding credentials.

The effective configuration for a client will be merged automatically from all 3 stores in the order above.

To work with configuration stores, you can use the Set-EryphConfigurationStore command, which allows you to configure where you want to store which settings. The command has the arguments Clients, Endpoints or Defaults. For each of these arguments, you can change the preferred configuration store.

Default configurations

You can store multiple credentials in the same configuration store. One of these credentials can be set as the default credential. You can use the `Set-EryphClientConfiguration' commands to change the default configuration.

Creating eryph-zero configurations

To create a local client configuration for eryph-zero you first need a identity client and its credentials. The New-EryphClient command has a shortcut option to directly write a new created client to the current store:

Copy
# assuming that we would like to create a 
# client for a repository folder we can create the client
# configuration directly from New-EryphClient 

# first configure store to local directory
Set-EryphConfigurationStore -All CurrentDirectory
New-EryphClient repo-client `
  -AllowedScopes compute:write `
  -AddToConfiguration -AsDefault

The current folder now contains a directory .eryph that contains both the client settings and the private key of the client.

Now we use the same folder, however this time, we store the client in user profile and only the default settings in the folder:

Copy
# first remove existing folder
Remove-Item .eryph -Recurse -ErrorAction SilentlyContinue

# switch back to user store first
Set-EryphConfigurationStore -All User

# use local directory only for defaults
Set-EryphConfigurationStore -Defaults CurrentDirectory
New-EryphClient repo-client2 `
  -AllowedScopes compute:write `
  -AddToConfiguration -AsDefault

The .eryph directory will now contain only the zero.config file that sets the configuration as default.