Configuration

This page is still a work-in-progress. Some options might be missing, or information incorrect.

This page will serve as a reference to the configuration of the UCloud Integration Module.

The configuration is split up to several files.

server.yml: Communication and internal database configuration for the UCloud Integration Module.
secrets.yml: Secret configuration, such as account details, for integrated services.
config.yml: Configuration related to your HPC system, services, etc.

In the following sections we present examples of each configuration file along with possible options for each parameter.

Server configuration

refreshToken: "<token-goes-here>"
database:
  embedded: false
  username: postgres
  password: postgrespassword
  database: postgres
  ssl: false
  host:
    address: go-slurm-postgres

Example server.yml file.

The server.yml file contains the refresh token, used to renew the access tokens for the communication from UCloud/Core, along with credentials for the internal Integration Module database, which contains the current state.

The contents of server.yml could be used to access data stored by the UCloud Integration Module on the local HPC system. It is strongly recommended that the file permissions for this file is set, such that only the ucloud user can access it.

refreshToken: The refresh token is used to renew the (short-lived) access token, which is used by the UCloud/Core to make authorized calls to the UCloud Integration Module.

database optional

This section defines connection information for the database used by the UCloud Integration Module to store internal data. If this is not defined, the UCloud Integration Module will use its own embedded database.

embedded

Defines if the integration module should use its own internal (embedded) database for storing data or not. In case the database section is not defined, this will default to true. If set to false, the Integration Module will use the database and credentials defined by the following parameters.

username

The username for the database, in case embedded is set to false. Note that the user needs to have both read and write access to the database.

password

The password for the database, in case embedded is set to false.

database

The name of the database to connect to, in case embedded is set to false.

ssl

If set to true the Integration Module will only connect to the database using SSL.

If set to false the Integration Module will connect to the database without SSL.

The parameter is only used if embedded is set to false.

host

The host information used for connecting to the database. See Host information. The port will default to 5432 if not defined.

Secrets configuration

freeipa:
  url: https://ipa.ucloud
  username: admin
  password: adminadmin
  verifyTls: true

gpfs:
  storage: # This is the product category name
    username: gpfs
    password: gpfspassword
    verifyTls: false
    host:
      address: localhost
      port: 62394
      scheme: http
    mapping:
      home: # This is a locator name
        fileSystem: "gpfs"
        parentFileSet: "home"
        fileSetPattern: "home-#{localUsername}" # This has the same variables as the drive locator has
      projects:
        fileSystem: "gpfs"
        parentFileSet: "work"
        fileSetPattern: "work-#{localGroupName}-#{gid}"

Example file showing the format of secrets.yml.

Provider and Services configuration

provider:
  id: go-slurm

  hosts:
    ucloud:
      address: backend
      port: 8080
      scheme: http
    self:
      address: go-slurm
      port: 8889
      scheme: http
    selfPublic:
      address: go-slurm.localhost.direct
      port: 443
      scheme: https
    ucloudPublic:
      address: ucloud.localhost.direct
      port: 443
      scheme: https

  ipc:
    directory: /var/run/ucloud

  logs:
    directory: /var/log/ucloud
    rotation:
      enabled: true
      retentionPeriodInDays: 180

  envoy:
    directory: /var/run/ucloud/envoy
    executable: /usr/bin/envoy
    funceWrapper: false

services:
  type: Slurm

  identityManagement:
    type: FreeIPA

  fileSystems:
    storage:
      management:
        type: GPFS

      payment:
        type: Resource
        unit: GB

      driveLocators:
        home:
          entity: User
          pattern: "/gpfs/home/#{localUsername}"
          title: "Home"
          freeQuota: 10

        projects:
          entity: Project
          pattern: "/gpfs/work/#{localGroupName}-#{gid}"
          title: "Work"

  ssh:
    enabled: true
    installKeys: true
    host:
      address: frontend.localhost.direct
      port: 22

  slurm:
    fakeResourceAllocation: true

    accountManagement:
      accounting: # Usage and quota management
        type: Automatic

      accountMapper:
        type: Pattern
        users: "#{localUsername}_#{productCategory}"
        projects: "#{localGroupName}_#{productCategory}"

    web:
      enabled: true
      prefix: "goslurm-"
      suffix: ".localhost.direct"

    machines:
      u1-standard:
        partition: normal
        qos: standard

        nameSuffix: Cpu

        cpu: [ 1, 2, 4 ]
        memory: [ 1, 2, 4 ]

        cpuModel: Model
        memoryModel: Model

        payment:
          type: Resource
          unit: Cpu
          interval: Minutely

Example config.yml file

`provider`

id

The ID for your provider.

hosts

ucloud

The host information for the UCloud/Core the Integration Module should communicate with. For example the host name for the sandbox system, sandbox.dev.cloud.sdu.dk. See Host information for more information.

self

The host information for this HPC system. See Host information for more information.

selfPublic

Public entry-point to this HPC system. See Host information for more information.

ucloudPublic optional

Public entry-point to the UCloud/Core system the Integration Module should communicate with. If not defined, this will default to the same as hosts → ucloud.

See Host information for more information.

ipc

directory: The path to the directory used for IPC, e.g. /var/run/ucloud.

logs

This section specifies information about where the Integration Module is allowed to save log files.

directory

The path to the directory where logs will be stored. For example /var/log/ucloud.

rotation optional

enabled

Defines if log rotation should be enabled (true) or not (false). If log rotation is enabled, the Integration Module will write logs to the main log file for a specified number of days, defined by retentionPeriodInDays. Afterwards, the log file will be compressed automatically, and a new main log file will be used for further logs until the retention period has been reached again.

If rotation is not defined, this will default to false.

retentionPeriodInDays

This defines the retention period as a number of days.

envoy

directory: The path to the directory that envoy will use for keeping internal state. For example var/run/ucloud/envoy.
managedExternally optional: true or false. Defaults to false.
executable: The path to the executable of envoy.
funceWrapper: true or false. Defaults to false.
internalAddressToProvider optional: The address (URL or IP) to provider. Defaults to 127.0.0.1.

`services`

type

Type of system/services provided by the HPC system. Possible values are Slurm, Kubernetes and Puhuri.

identityManagement

type: Type of system used for identity management, i.e. user and project management. Possible values are Scripted, FreeIPA, and None.

fileSystems

Defines one or more file systems. Read more under File systems.

ssh

enabled: Informs the Integration Module whether SSH is enabled (true) or not (false).
installKeys
host: The host used for SSH. See Host information for more information.

licenses

enabled: Whether the license product type is available for this provider or not.

slurm

fakeResourceAllocation

accountManagement optional

accounting

type: Type of accounting to use. Possible values are Automatic, Scripted and None.

accountMapper

type: Technique used for account mapping. Possible values are Pattern, Scripted or None.
users (required if type is Pattern): Pattern for mapping UCloud accounts to local accounts.
projects (required if type is Pattern): Pattern for mapping UCloud projects to local projects.
script (required if type is Scripted): Script for mapping UCloud users and projects to the local system.

web

enabled: Whether interfaces for applications should be enabled (`true`) or not (`false`).
prefix: The address prefix for web interfaces (if enabled is true).
suffix: The address suffix for web interfaces (if enabled is true).

machines

See Machines.

Host information

Host information defines the address, port and scheme to a location. For example:

address: postgres
port: 8080
scheme: http

This states that the container named postgres is accessible over http on port 8080.

address: The name/address of the host.
port optional: The port number to use. If not defined, the Integration Module will attempt to use a reasonable default value.
scheme: The scheme to use. For example http, https, etc.

File systems

The fileSystems section define the storage products for your HPC system, along with additional parameters that tell the Integration Module how to find your drives, and how users are billed. The fileSystem can have multiple products if you require different payment models or offer different kind of storage solutions. Each product is named using the key of the block.

my-storage:
  management:
    type: GPFS

  payment:
    type: Resource
    unit: GB

  driveLocators:
    home:
      entity: User
      pattern: "/gpfs/home/#{localUsername}"
      title: "Home"
      freeQuota: 10

    projects:
      entity: Project
      pattern: "/gpfs/work/#{localGroupName}-#{gid}"
      title: "Work"

Example of storage product named my-storage using pattern drive locators, billing users per GB.

Each storage product can be configured with the following options.

management

type

Possible values are GPFS, Scripted and None. If set to GPFS further information will be read from secrets.yml.

onQuotaUpdated optional

Path to script that will be executed every time a users’ or projects’ quota is updated, i.e. every time a resource allocation is approved or changed.

Only used if type is Scripted.

onUsageReporting optional

Path to script that will be executed every time the Integration Module evaluates the usage of all users and projects on the HPC system.

Only used if type is Scripted.

payment

Defines how payment should work for this product. See Payment for more details.

driveLocators

Drive locators define the method the Integration Module can use to find (virtual) drives on your system. That is, they are used to define the mapping between UCloud’s definition of a Drive and a path on your file system. Each drive locator is defined by a name and following options, i.e.

my-locator:
  # Options here

The drive locator will map UCloud drives to local file system paths by using either a pattern or a script, thus exactly one of them has to be defined for each drive locator.

Each drive locator can have the following options.

entity: Defines which entity this is a drive locator for. Possible values are User, Project and MemberFiles.
pattern (required if script is not defined): Use a text pattern to locate drives on the local file system.
script (required if pattern is not defined): Use a script to locate drives on the local file system.
title: Title for this drive locator.
freeQuota (required and only specifiable for locators with entity set to User): Defines how much free quota each user get.

Machines

u1-standard:
  partition: normal
  qos: standard

  nameSuffix: Cpu

  cpu: [ 1, 2, 4 ]
  memory: [ 1, 2, 4 ]

  cpuModel: Model
  memoryModel: Model

  payment:
    type: Resource
    unit: Cpu
    interval: Minutely

Example of a compute product with name u1-standard.

Every compute product (machine) can have the following options.

partition

Defines the Slurm partition to use for jobs submitted to this machine category.

constraint

groups optional

qos optional

Given to Slurm for jobs submitted to this machine category. Read the Slurm Documentation for more details.

nameSuffix

cpu, memory, gpu

A list of supported CPU, memory and GPU sizes respectively. I.e.

cpu: [1,2,4]

will create 4 compute products, with 1 CPU core, 2 CPU cores and 4 CPU cores respectively.

cpuModel optional, memoryModel optional, gpuModel optional

Textual description of the CPU, memory and GPU models/hardware respectively.

payment

Defines how this product is charged. See Payment for more details.

Payment

type: Possible values are Resource or Money.
price (required if type is Money)
currency (required if type is Money)
interval optional: Possible values are Minutely, Hourly and Daily.
unit: Possible values are GB, TB, PB, EB, GiB, TiB, PiB and EiB for storage products, and Cpu, Memory and Gpu for compute products.