References

Attribute Reference Tables

Technologies can have a variety of attributes. Some are common to jobs, apps, while others are type-specific.

The parser is sensitive to float ambiguity when the attribute expects a value of type string. To remove this ambiguity, you must write id: "3.10" instead of id: 3.10. This concerns all attributes of type string.

Common Attributes Table

The following attributes are common to jobs, apps.

Attribute Description Default value

version
Mandatory
String

The version of the file format.

The supported versions are v1 and v2, which are only allowed in the v2 file format.

none

id
Mandatory
String

The unique identifier of the technology in the repository.

none

label
Mandatory
String

The name of the technology as it will appear in the user interface.

none

description
Optional
String (multiline)

The description of the technology as it will appear in the user interface.

none

available
Optional
Boolean

Makes the technology unusable when the answer is false. This means that it is no longer possible to create new jobs and apps, or to update existing ones with this technology. However, jobs and apps that already use it continue to work.

false

type
Mandatory
String

Indicates whether it is a job or an app.

The supported types are JOB and APP.

none

icon
Optional
String

The name of the icon as it appears in the Saagie Design System.

You can use either the icon or iconPath attribute, but you cannot use both at the same time.

none

iconPath
Optional
String

The path of the technology icon file included in the associated technology subdirectory.

  • Only JPG and PNG formats are accepted. The icon size limit is 64 Ko and it must be square in shape.

  • You can use either the icon or iconPath attribute, but you cannot use both at the same time.

none

contexts
Mandatory
Array

Defines the different versions or features of the technology.

none

contexts[]
.id
Mandatory
String

The context’s unique identifier of your technology.

none

contexts[]
.label
Mandatory
String

The name of the context as it will appear in the user interface.

none

contexts[]
.description
Optional
String (multiline)

The description of the context as it will appear in the user interface.

Example 1. Multiline file description
description: >
  Several lines of text,
  with some "quotes" of various 'types',
  plus another line at the end.

none

contexts[]
.available
Optional
Boolean

Makes the context unusable when the answer is false. This means it is no longer possible to create new jobs and apps, or to update existing ones with this context. However, jobs and apps that already use it continue to work.

You should be aware that when applying state-related attributes, some states take priority over others. For more information, see the State-Related Attribute Rules.

false

contexts[]
.recommended
Optional
Boolean

Labels the context as Recommended when the response is true.

You should be aware that when applying state-related attributes, some states take priority over others. For more information, see the State-Related Attribute Rules.

false

contexts[]
.trustLevel
Mandatory
String

Informs that the context is not stable when the response is experimental.

  • The supported values are stable or experimental.

  • You should be aware that when applying state-related attributes, some states take priority over others. For more information, see the State-Related Attribute Rules.

none

contexts[]
.deprecationDate
Optional
Timestamp

Informs that the context is deprecated when a depreciation date is specified. The value must be a past date with the format yyyy-mm-ddThh:mm:ssZ.

Leave the attribute value empty if the technology is not deprecated.

You should be aware that when applying state-related attributes, some states take priority over others. For more information, see the State-Related Attribute Rules.

none
If you encounter problems with one of these fields, contact Saagie Support.

When defining a value on the available, recommended, trustlevel, and deprecationDate attributes, the rules for the technology’s status that appears in the user interface (UI) are as follows:

  • If you set available: false, then the technology will appear as Disabled in the UI, regardless of the value of the trustlevel and deprecationDate attributes.

  • If you set only available: true, then no specific label will be displayed next to the technology in the UI.

  • If you set available: true in addition of:

    • deprecationDate: "2021-06-19T10:30:50Z", then the technology will appear as Deprecated in the UI, regardless of the value of the trustLevel attribute.

    • trustLevel: experimental, then the technology will appear as Experimental in the UI.

    • trustLevel: stable, then the technology will appear as Stable in the UI.

  • If you set recommended: true in addition to the above rules, then the technology will also appear as Recommended in the UI.

Type-Specific Attribute Tables

  • Job attributes table

  • App attributes table

The following attributes apply to jobs only.

Attribute Description Default value

defaultResources
.cpu
.limit
Optional
Double

The recommended CPU limit and request.

It can be overridden if you have defined a value at the context level with the contexts[].defaultResources.cpu.limit attribute.

1.0

defaultResources
.memory
.limit
Optional
Data size (integer with unit)

The recommended memory limit and request in $Integer $Unit format. For example, 1024 MB or 2 GiB.

It can be overridden if you have defined a value at the context level with the contexts[].defaultResources.memory.limit attribute.

500 MB

contexts[]
.job
.features
Optional
-

The list of the features available in the job creation form.

none

contexts[]
.dockerInfo
Mandatory
-

Information about the Docker image of a technology.

none

contexts[]
.dockerInfo
.image
Mandatory
String

The Docker image name of the technology.

none

contexts[]
.dockerInfo
.version
Mandatory
String

The Docker image version (or tag).

latest

contexts[]
.defaultResources
.cpu
.limit
Optional
Double

The recommended CPU limit and request.

It overrides the value defined at technology level with the defaultResources.cpu.limit attribute.

1.0

contexts[]
.defaultResources
.memory
.limit
Optional
Data size (integer with unit)

The recommended memory limit and request in $Integer $Unit format. For example, 1024 MB or 2 GiB.

It overrides the value defined at technology level with the defaultResources.memory.limit attribute.

500 MB
List of Features of the Job Creation Form

Jobs have at least one context that contains its own list of features. In each context, there can be several features, but only one of each type.

A feature is defined by the following values:

Attribute Description Possible values

type

Defines the feature type.

  • COMMAND_LINE

  • ARTIFACT

  • SCHEDULER

  • GPU

  • DOCKER_INFO

label

Information displayed next to a field.

Character string

mandatory

Indicates whether if a field is required or not.

  • true

  • false

comment

Information that appears next to a field and provides examples of how to complete that field.

Character string

defaultValue

Example of a field’s default value.

Character string

The following attributes apply to apps only.

Attribute Description Default value

defaultResources
.cpu
.limit
Optional
Double

The recommended CPU limit and request.

It can be overridden if you have defined a value at the context level with the contexts[].defaultResources.cpu.limit attribute.

1.0

defaultResources
.memory
.limit
Optional
Data size (integer with unit)

The recommended memory limit and request in $Integer $Unit format. For example, 1024 MB or 2 GiB.

It can be overridden if you have defined a value at the context level with the contexts[].defaultResources.memory.limit attribute.

500 MB

baseline
Optional
String

The basic description of the application.

none

backgroundColor
Optional
String

The background color for the app card in the user interface.

none

contexts[]
.releaseNotes
Optional
String (multiline)

The context release notes.

none

contexts[]
.dockerInfo
Mandatory
-

Information about the Docker image of a technology.

none

contexts[]
.dockerInfo
.image
Mandatory
String

The Docker image name of the technology.

none

contexts[]
.dockerInfo
.version
Mandatory
String

The Docker image version (or tag).

latest

contexts[]
.ports
Mandatory
Array

The list of available open ports for a Docker container.

none

contexts[]
.ports[]
.port
Mandatory
Integer

The port number.

none

contexts[]
.ports[]
.name
Optional
String

The port label, with a description of its use.

none

contexts[]
.ports[]
.basePath
Optional
String

The name of the environment variable that will contain the URL generated by Saagie.

none

contexts[]
.volumes
Optional
Array

The list of Docker volume paths used by the application.

none

contexts[]
.volumes[]
-
String

The volume path.

The volume path attribute is required only if you use the volumes attribute above.

none

contexts[]
.defaultResources
.cpu
.limit
Optional
Double

The recommended CPU limit and request.

It overrides the value defined at technology level with the defaultResources.cpu.limit attribute.

1.0

contexts[]
.defaultResources
.memory
.limit
Optional
Data size (integer with unit)

The recommended memory limit and request in $Integer $Unit format. For example, 1024 MB or 2 GiB.

It overrides the value defined at technology level with the defaultResources.memory.limit attribute.

500 MB

readme
Optional
String

The path to the repository of the technology readme.md file from the saagie/technologies Git repository. For example, technologies/app/jupyer.

none
Job technology

Example for Java/Scala 8, 11, and 13.

metadata.yaml
version: "v1"
type: JOB
id: java-scala
label: Java/Scala
available: true
icon: java-scala
contexts:
  - id: 11
    label: 11
    available: true
    recommended: true
    dockerInfo:
      image: saagie/java-scala
      version: 11-1.10.0_merge_certified_experimental
    trustLevel: "stable"
    job:
      features:
        - type: COMMAND_LINE
          label: "Command line"
          mandatory: true
          comment: "Linux shell command to launch the job."
          defaultValue: java -jar {file} arg1 arg2
        - type: ARTIFACT
          label: "Package"
          mandatory: true
          comment: "Compatible upload file : .jar"
        - type: SCHEDULER
          label: "Scheduled"
          mandatory: true
  - id: 13
    label: 13
    available: true
    recommended: false
    dockerInfo:
      image: saagie/java-scala
      version: 13-1.10.0_merge_certified_experimental
    trustLevel: "experimental"
    job:
      features:
        - type: COMMAND_LINE
          label: "Command line"
          mandatory: true
          comment: "Linux shell command to launch the job."
          defaultValue: java -jar {file} arg1 arg2
        - type: ARTIFACT
          label: "Package"
          mandatory: true
          comment: "Compatible upload file : .jar"
        - type: SCHEDULER
          label: "Scheduled"
          mandatory: true
  - id: 8
    label: 8
    available: true
    recommended: false
    dockerInfo:
      image: saagie/java-scala
      version: 8-1.10.0_merge_certified_experimental
    trustLevel: "stable"
    job:
      features:
        - type: COMMAND_LINE
          label: "Command line"
          mandatory: true
          comment: "Linux shell command to launch the job."
          defaultValue: java -jar {file} arg1 arg2
        - type: ARTIFACT
          label: "Package"
          mandatory: true
          comment: "Compatible upload file : .jar"
        - type: SCHEDULER
          label: "Scheduled"
          mandatory: true
App technology

Example for Jupyter Notebook.

metadata.yaml
version: v1
type: APP
id: jupyter-doc
label: Jupyter Notebook
baseline: Data Science Notebook
backgroundColor: "#E87A35"
description: "The Jupyter Notebook is an open-source web application..."
available: true
icon: jupyter
customFlags: []
contexts:
  - id: "6.1.1"
    label: Jupyter Notebook
    releaseNotes: "Prevent inclusion of requests_unixsocket on Windows"
    available: true
    trustLevel: stable
    dockerInfo:
      image: saagie/jupyter-python-nbk
      version: v2
    ports:
      - port: 8888
        name: Notebook
        rewriteUrl: false
        basePath: SAAGIE_BASE_PATH
    volumes: ["/notebooks-dir"]