Application specification (API reference)

Overview of the applications specification yaml structure (application API reference)

Example

Example of how your application deployment might look like:

name: redis-example-private
description: Multi-container redis example
scheduling:
  type: Conditional
  selectors:
    location: roof
spec:
  containers:
  - name: hello
    image: quay.io/synpse/hello-synpse-redis-go-private:latest
    # set user
    user: root
    # Registry authentication
    auth:
      username:  my_registry
      fromSecret: registry_secret
    # Enable GPUs
    gpus: all
    # Expose a port
    ports:
    - 8090:8090
    # Or set:
    # networkMode: host
    # Optionally mount tty devices into the container
    devices:
      - hostPath: /dev/ttyACM0
        containerPath: /dev/ttyACM0
    # Run container as privileged
    privileged: true
    # Add/drop capabilities
    capAdd:
      - SYS_ADMIN
    capDrop:
      - NET_RAW
    # Configure namespaced kernel parameters (sysctls)
    sysctl:
      "net.ipv4.conf.all.src_valid_mark": "1"
      "net.ipv4.ip_forward": "1"
    files:
      - filepath: /etc/my-app/config.conf
        contents: >
          config file contents here
  - name: redis
    image: docker.io/redis:latest
    # Mount a file type secret directly into 
    # the container
    secrets:
    - name: redis-config
      filepath: /path/to/config.yaml
    env:
    - name: REDIS_PASSWORD
      fromSecret: redis-password
    - name: RANDOM_KEY
      value: random-value
    # Mount a volume from the host machine
    volumes:
    - /tmp/redis:/data
    logging:
      driver: "syslog"
      # type: "your-type"
      # config:
      #  env: os,custom

Spec API

Field	Description	Type
name	Application name	string
description	Application description	string
type	Application type Options: container - container runtime	string
scheduling	Scheduling configuration	See Scheduling
spec	Application deployment specification	See Specification

Scheduling

Field	Description	Type
type	Scheduling type Options: NoDevices - defaults when no type and no selectors are specified AllDevices - schedule on all available devices Conditional - defaults when no type but selectors are specified	string
selectors	Label based device selector use with Conditional type, where if label matches with device labels - application is scheduled.	key value pair

Specification

Field	Description	Type
containers	List of containers specification	[]Container See Container
execs	List of exec specifications	[]Exec See Exec
selectors	Label based device selector use with Conditional type, where if label matches with device labels - application is scheduled.	key value pair

Container

Field	Description	Type
name	Container name	string
image	Image of the application Exampe: quay.io/synpse/hello-synpse:latest	string
args	Arguments to star the application	[]string
gpus	Expose GPUs to your application. Currently the only valid value is "all"	string
auth	Container registry authentication	See Auth
capAdd	Add Linux capabilities, for example: capAdd: - NET_ADMIN	[]string
capDrop	Remove Linux capabilities, for example: capAdd: - MKNOD	[]string
command	Command to execute inside the container	string
hostname	Container hostname inside the application. If multiple container provided, this acts as a local dns Default: If not specified is set to Name value	string
networkMode	Network mode for the application Options: host - host network isolated - isolated network bridge bridge - shared bridge for the application	string
ports	Port mapping for the application. Format: <host_port>:<container_port> Example: 8080:8080 - map port 8080 to container port 8080 8080 - same as above 8080:80 - host 8080 port to container port 80	[]string
forcePull	Boolean if image should be force pulled. Options: false - don't force pull (ignored if image tag is latest) true - always pull image
privileged	Run as privileged container	bool
imagePullTimeout	Image pull timeout Example: "8h"	duration
user	Sets the username or UID used and optionally the groupname or GID for the specified command. Example: user user:group uid uid:gid user:gid uid:group	string
volumes	Volumes to mount from device for persistence. Format: <hostpath>:<container_path> Example: /tmp/redis:/tmp	[]string
environment	List of environment variables to expose into container	[]Environment See Environment
secrets	Secrets to mount as files into the container	[]SecretRef See SecretRef

Exec

Field	Description	Type
name	Exec application name	string
command	Command to be executed Example: /usr/bin/firefox	string
args	Command arguments Example: - https://synpse.net - --kiosk	[]string
user	Unix uset to be used. User must exist. Default: root Example: demo .	string
ports	Port mapping for the application. Format: <host_port>:<exec_port> Example: 8080:8080 - map port 8080 to container port 8080 8080 - same as above 8080:80 - host 8080 port to container port 80	[]string
environment	List of environment variables to expose into container	[]Environment See Environment
secrets	Secrets to mount as files into the container	[]SecretRef See SecretRef

Auth

Field	Description	Type
username	Username for docker registry	string
password	Password for docker registry	string
fromSecret	Use secret value instead of specifying password in plain-text (recommended)	string
email	(Optional) Email used in authentication. Needed for some registries	string
serverAddress	(Optional) Server address for the registry. Needed for some registries	string

Devices

Synpse allows adding host device to the container, similarly how Docker API works. It is often necessary to directly expose devices to a container. The devices config enables that. For example, a specific block storage device or loop device or audio device can be added to an otherwise unprivileged container and have the application directly access it.

Field	Description	Type
hostPath	Path to the device on the host machine (for example /dev/ttyACM0)	string
containerPath	Path to the device on the container. Usually this would match the path on the host machine for easier configuration of your application.	string

Environment

Field	Description	Type
name	Name of the variable	string
value	Value of the variable	string
fromSecret	(optional) Secret name to used as value of the variable	string

Secret (file)

Secrets has its own API. This documentation is here for convenience as it is very closely tied to Application API

Field	Description	Type
name	Secret name	string
filepath	Full path to the file which will have the secret contents written into it	string