7. Manifest Attribute Breakdown

7.1. Supported attributes

The YAML file below details all the possible attributes that could be used when creating a manifest file.

Note

These are all the possible attribute names that could be used. There is still flexbility in their values.

When specifying values for the environment variable attributes a type can be explicitly set. However there are still some restrictions on this, as only singular base class types are supported. For example environment variables of type:boolean can have value:true, but for variables of type:list expects only string values as the list type can be comprised of different types of elements.

name: Bundle Name
version: "1.0"
description: Bundle description
website: http://www.mycompany.com
icon: mybundle.png
serialize: true
profile: profile1
snapshot: enabled
snapshot_schedule:
    cron: "30 5 * * 3"
    retain: 2
clone: enabled
clonemode: unfenced
ha_restarts: 3
ha_relocate: true
roles: [role1, role2]
upgrade_order: [role2, role1]
tags: ["sql", "db", "web"]

role1:
    name: role1
    multinode: true
    multinode_label: partition
    multinode_fixed: true
    multinode_value: 3
    multinode_min: 1
    multinode_max: 4
    labels:
        labelkey1: labelvalue1
        labelkey2: labelvalue2
    annotations:
        annokey1: annovalue1
        annokey2: annovalue2
    ports:
      - containerPort: 80
        hostPort: 8086
        protocol: TCP
    restart_on_scalein: true
    restart_on_scaleout: true
    candisable: true
    description: Role1 description
    multi_ips: true
    elastic_ip: true
    commandline: /bin/do something
    entrypoint: custom-entrypoint.sh
    scaleout: enabled
    scalein: enabled
    addvolume: enabled
    scaleup_mem: enabled
    scaledown_mem: disabled
    scaleup_cpu: enabled
    scaledown_cpu: enabled
    rolling_upgrade: true
    norootfs: false
    restart_on_clone: false
    block_cloud_metadata: true
    shareProcessNamespace: true
    skip_headless_service: true
    virtualize_sysinfo: true
    image:
        name: role1-image
        version: "1.2-dev"
        engine: docker
        registry_name: My Docker Hub
        upgrade_from: [v1, v2]
        init_mode: false
    compute:
        memory: 1G
        hugepages_1gi: 1G
        hugepages_2mi: 1G
        cpu:
            reserve: false
            cores: 4
        gpu:
            count: 2
            type: "nvidia-a100"
    storage:
        - type: data
          media: ssd
          path: /data
          size: 10G
          fstype: raw
          shared: true
          blocksize: 512
          nparts: 1
          replication: 2
          faultdomain: "host"
          layout: "pack"
          workload: 2
          compression: "1"
          encryption: "CHACHA20"
          snap_reserved: 40
          count: 3
          mincount: 1
          maxcount: 10
          affinity: rack
          tags:
              size: x-large
          mount_in_sidecars: true
          mount_in_initcontainers: true
        - type: something
          media: ssd
          path: /something
    service_ports: [60, 443]
    serviceAccountName: "role1-sa"
    podSecurityContext:
      runAsUser: 0
    securityContext:
      allowPrivilegeEscalation: true
    grace_period_seconds: 5
    tolerations:
        - effect: NoSchedule
          key: node-type/secure
    services:
    - type: NodePort
    labels:
        l1: v1
        l2: v2
    annotations:
        a1: av1
        a2: av2
    scope: pod
    ports:
    - port: 80
        protocol: TCP
        name: web
    - type: ClusterIP
    ports:
    - port: 80
        protocol: TCP
        name: web
    - type: LoadBalancer
    ports:
    - port: 80
        protocol: TCP
        name: web
    hostAliases:
    - ip: "1.2.3.4"
      hostnames:
      - "foo.remote"
      - "bar.remote"
    initContainers:
    - name: "init"
      image: k8s.gcr.io/busybox
      imagePullPolicy: IfNotPresent
      resources:
        limits:
          cpu: "25m"
          memory: 128Mi
      command:
        - sleep
        - "30"
      securityContext:
        privileged: true
      volumeMounts:
      - name: vol-cm1
        mountPath: /cm1
    livenessProbe:
      httpGet:
        path: /
        port: 80
        httpHeaders:
        - name: Custom-Header
          value: Awesome
      initialDelaySeconds: 3
      periodSeconds: 3
    readinessProbe:
      exec:
        command:
        - sleep
        - "5"
      initialDelaySeconds: 5
    sidecars:
    - name: busyside1
      image: k8s.gcr.io/busybox
      command:
        - sleep
        - "3000"
      resources:
        limits:
          memory: 200Mi
        requests:
          cpu: 100m
          memory: 100Mi
      volumeMounts:
      - name: vol-cm1
        mountPath: /cm1
      - name: vol-cm2
        mountPath: /cm2
      - name: vol-cm3
        mountPath: /cm3
      securityContext:
        allowPrivilegeEscalation: true
    env:
        BROADCAST_ADDRESS: '{{IP_ADDRESS}}'
        MAX_HEAP_SIZE: 512M
        ENV_TEXT_EXAMPLE:
            type: text
            value: "example value"
            label: "Text Field"
            mandatory: true
            editatclone: true
            editatscale: true
            addatclone: true
            max_chars: 8
        ENV_PASSWORD_EXAMPLE:
            type: password
            value: "password123"
            label: "Password Field"
            removeatclone: true
        ENV_NUMBER_EXAMPLE:
            type: number
            value: 15
            min: 10
            max: 20
            label: "Number Field"
        ENV_BOOLEAN_EXAMPLE:
            type: boolean
            value: true
            label: "Boolean Field"
        ENV_FILE_EXAMPLE:
            type: filecontent
            label: "Contents from a file"
        ENV_LIST_EXAMPLE:
            type: list
            items:
                - option1
                - option2
                - option3
            value: option2
            label: "List Field"
        ENV_TIME_EXAMPLE:
            type: date-time
            value: 2016-09-21T15:30
            label: "Time Field"
    vnodehooks:
        poststart: "bash do_something.sh ip_address={{IP_ADDRESS}}"
    affinityrules: ["same host", "model a or b and not small"]

role2:
    name: role2
    depends: [role1]
    ....

apphooks:
    poststart: "bash do_something_else.sh"

roleaffinity:
    - name: "separate rack"
      affinityrules: ["different rack"]
      roles: [role1, role2]
affinityrules:
   - name: "same host"
      constraints:
         - type: infrastructure
           target: host
   - name: "model a or b and not small"
      constraints:
         - type: tag
           target: host
           tags:
               model: [a, b],
               size: ["-small"]
    - name: "different rack"
      constraints:
          - type: infrastructure
            target: "-rack"

7.2. Mandatory attributes

7.2.1. Application Level

7.2.1.1. name

name: Bundle Name

Currently not used. The bundle name is set when the bundle is first added.

7.2.1.2. version

version: "1.0"

Currently not used. The bundle version is set when the bundle is first added.

7.2.1.3. icon

icon: myBundle.png

Path to the image file to display as an icon for the bundle. The image must exist at the specified path.

7.2.1.4. roles

roles: [role1, role2]

An array of names for the roles the application will consist of.

7.2.2. Role Level

Applications are comprised of roles. Each application must have at least one role. The attributes detailed below are mandatory for each role.

7.2.2.1. name

role1:
    name: role1

Name of the role.

7.2.2.2. scaleout

role1:
    scaleout: enabled

Enable scale out for this role and as a result allow for more containers of this role to be deployed. Possible values: ‘enabled’ or ‘disabled’. If not specified the default is ‘disabled’.

7.2.2.3. addvolume

role1:
    addvolume: enabled

Enable adding additional volumes to containers of this role. Possible values: ‘enabled’ or ‘disabled’. If not specified the default is ‘disabled’.

7.2.2.4. scaleup_mem

role1:
    scaleup_mem: enabled

Enable increasing memory for containers of this role. Possible values: ‘enabled’ or ‘disabled’. If not specified the default is ‘enabled’.

7.2.2.5. scaledown_mem

role1:
    scaledown_mem: disabled

Enable decreasing memory for containers of this role. Possible values: ‘enabled’ or ‘disabled’. If not specified the default is ‘disabled’.

7.2.2.6. scaleup_cpu

role1:
    scaleup_cpu: enabled

Enable increasing CPUs for containers of this role. Possible values: ‘enabled’ or ‘disabled’. If not specified the default is ‘enabled’.

7.2.2.7. scaledown_cpu

role1:
    scaledown_cpu: enabled

Enable decreasing CPUs for containers of this role. Possible values: ‘enabled’ or ‘disabled’. If not specified the default is ‘enabled’.

7.2.3. Image Level

For a container to spawned for a role an image must be specified. Each role contains at least one image. The attributes detailed below are mandatory for each image.

7.2.3.1. name

role1:
    image:
        name: role1-image

Name of the image to be used when creating an instance of this role.

Note

For LXC - The name must match the image name that was given when the image file was uploaded to the server.

For Docker - The name must match the image name from dockerhub or private registry (e.g. name:version => cassandra:3.0).

7.2.3.2. version

role1:
    image:
        version: "1.2-dev"

Version of the image to be used when creating an instance of this role.

Note

For LXC - The version must match the image version that was given when the image file was uploaded to the server.

For Docker - The version must match the image version tag from dockerhub or private registry (e.g. name:version => cassandra:3.0).

7.2.3.3. engine

role1:
    image:
        engine: docker

Engine to be used for instances of this role. Possible engines: ‘docker’, ‘lxc’ or ‘kvm’.

7.2.4. Storage Resource Level

Each role has storage resource requirements for the containers it spawns. The attributes detailed below are mandatory when defining the storage resource limits for a role.

7.2.4.1. type

role1:
    storage:
        - type: data

The value specified for this attribute indicates the volume type (e.g. data / commitlog / root_fs / etc.). There can be multiple volume types per role depending on the number of volumes however they all need to be unique within the role.

7.3. Optional attributes

7.3.1. Application Level

7.3.1.1. description

description: Bundle description

Currently not being used.

7.3.1.2. website

website: http://www.mycompany.com

Currently not being used. Support for this is planned.

7.3.1.3. serialize

serialize: true

When true, container provisioning will be sequential and based off the role order in the manifest. The default value is ‘false’.

7.3.1.4. profile

profile: profile1

Specified name will be used in the UI to display application specific fields in order to support application specific behavior. For example, Oracle uses special inputs such as SCN and timestamp when performing a restore.

7.3.1.5. snapshot

snapshot: enabled

Enable snapshots for an application. Possible values: ‘enabled’, ‘disabled’, and ‘no’. There is a distinction between ‘disabled’ and ‘no’ as the former indicates that snapshots have been disabled for the current build whilst the latter indicates that the application doesn’t support snapshots. The default value is ‘no’.

7.3.1.6. snapshot_schedule

snapshot_schedule:
    cron: "30 5 * * 3"
    retain: 2

When the snapshot_schedule attribute is specified, a snapshot schedule is automatically configured for the newly created application. This schedule will only be set if the snapshot attribute is enabled. Details on how to configure the schedule via a Cron string can be found here.

Note

This attribute is only supported on Robin version 5.3.0 and above.

7.3.1.7. clone

clone: enabled

Enable cloning for an application. Possible values: ‘enabled’, ‘disabled’, and ‘no’. There is a distinction between ‘disabled’ and ‘no’ as the former indicates that cloning has been disabled for the current build whilst the latter indicates that the application doesn’t support cloning. The default value is ‘no’.

7.3.1.8. clonemode

clone: unfenced

An application can be cloned in two modes: fenced or unfenced. The fenced clone mode results in the network properties of the application like the IP Address, hostname etc are identical to the parent. Robin acheives this by creating a fence around the cloned application. Robin recommends the unfenced clone mode (where the application attains its own network configuration), in combination with a post clone hook in order to modify the clone as necessary. Possible values: ‘fenced’, ‘unfenced’. The default value is ‘fenced’.

7.3.1.9. tags

tags: ["sql", "db", "web"]

List of tags to be used for bundle filtering.

7.3.1.10. ha_restarts

ha_restarts: 3

The value specified here indicates the number of times a restart operation should be attempted for a container before relocating it. The default value is 3.

7.3.1.11. ha_relocate

ha_relocate: true

Boolean value indicating whether or not the container should be relocated after it was restarted <ha_restarts> number of times. The default value is true.

7.3.1.12. upgrade_order

upgrade_order: [role1, role2]

An array of role names indicating the order in which they should be upgraded. This attribute is only valid for Docker based applications.

7.3.1.13. affinityrules

affinityrules:
   - name: "same host"
      constraints:
         - type: infrastructure
           target: host
   - name: "model a or b and not small"
      constraints:
         - type: tag
           target: host
           tags:
               model: [a, b],
               size: ["-small"]
    - name: "different rack"
      constraints:
          - type: infrastructure
            target: "-rack"

If this attribute is set, its values define rules which ultimately determine the placement polices for roles/containers if they are referenced. More details on defining affinity rules are available here.

7.3.1.14. roleaffinity

roleaffinity:
    - name: "separate rack"
      affinityrules: ["different rack"]
      roles: [role1, role2]

If this attribute is set, its values will determine the affinity rules that containers of different roles must adhere to. More details on constructing inter-role affinity rules between roles are available here.

7.3.1.15. apphooks

apphooks:
    poststart: "bash app_start.sh"

The apphooks attribute can be used to specify any application level scripts that need to be run in tandem with lifecycle operations on the application. More details on application hook scripts can be found here.

7.3.2. Role Level

Applications are comprised of roles. Each application must have at least one role. The attributes detailed below are optional for each role.

7.3.2.1. multinode

role1:
    multinode: true

Enable multiple instances of this role to be created. The default value is false.

7.3.2.2. multinode_label

role1:
    multinode_label: partition

This attributes defines the application specific name to be displayed in the UI, next to the number of instances input field. For exmaple mongoDB uses the term ‘shard’ whilst cassandra uses ‘partition’. The default value is ‘partition’.

7.3.2.3. multinode_value

role1:
    multinode_value: 3

When the multinode attribute is set to true, the value specified for this attribute defines the initial value for the number of instance to create for a particular role. The default value is 1.

7.3.2.4. multinode_min

role1:
    multinode_value: 2

When the multinode attribute is set to true, the value specified for this attribute defines the minimum value for the number of instance to create for a particular role.

7.3.2.5. multinode_max

role1:
    multinode_value: 4

When the multinode attribute is set to true, the value specified for this attribute defines the maximum value for the number of instance to create for a particular role.

7.3.2.6. multinode_fixed

role1:
    multinode_fixed: true

When the multinode attribute is set to true, the value specified for this attribute determines whether the number of instances to create for a particular role is fixed. The default value is false.

7.3.2.7. labels

role1:
    labels:
        labelkey1: labelvalue1
        labelkey2: labelvalue2

The labels attribute can be used to specify any Kubernetes labels that need to be attached on all pods that are created for this role in order to highlight identifying attributes of the objects that are meaningful and relevant to users. These labels can be specified as key-value pairs.

7.3.2.8. annotations

role1:
    annotations:
        annokey1: annovalue1
        annokey2: annovalue2

The annotations attribute can be used to specify any Kubernetes annotations that need to be attached to all pods created for this role. Annotations can be viewed as arbitrary non-identifying metadata for the spawned objects. These annotations can be specified as key-value pairs.

7.3.2.9. tolerations

role1:
    tolerations:
        - effect: NoSchedule
          key: node-type/secure
        - effect: NoExecute
          key: node-type/public
        - effect: PreferNoSchedule
          key: node-type/private

The tolerations attribute can be used to signal to the Robin scheduler to place pods created as part of this role on nodes with matching taints. Thus, the combination of node taints and pod tolerations can be used to control the placement of pods and ensure they are not spawned on inappropriate nodes. For the sake of convenience, the tolerations can be defined within the manifest in the exact same manner as one would in native Kubernetes. As a result, for additional details on configuring tolerations and/or taints review the documentation here.

7.3.2.10. ports

role1:
    ports:
        - containerPort: 80
          hostPort: 8086
          protocol: TCP

The ports attribute can be used to provide a mapping of the custom values for the application pod main container port to the host port necessary for accessing the application. In the example above; container port 80 for the application should be exposed on host port 8086 using TCP protocol.

7.3.2.11. grace_period_seconds

role1:
    grace_period_seconds: 5

The grace_period_seconds attribute can be used to specify the number of seconds Kubernetes should wait for a graceful shutdown before forcefully terminating the pod(s) created as part of this role.

Note

The value specified will override the default Kubernetes value of 30 seconds.

7.3.2.12. restart_on_scalein

role1:
    restart_on_scalein: true

This attribute determines if all the pods spawned for a respective role will be restarted when a scale-in operation is performed. The default value is false.

7.3.2.13. restart_on_scaleout

role1:
    restart_on_scaleout: true

This attribute determines if all the pods spawned for a respective role will be restarted when a scale-out operation is performed. The default value is false.

7.3.2.14. scalein

role1:
    scalein: enabled

Enable scale in for this role and as a result allow for containers of this role that were deployed to be destroyed. Possible values: ‘enabled’ or ‘disabled’. If not specified the default is ‘enabled’.

7.3.2.15. hpa

role1:
    hpa:
    metrics:
    - type: Pods
      pods:
      metric:
        name: cpu_usage
      target:
        type: AverageValue
        averageValue: 800m

If this attribute is set, the metrics defined within determine the conditions on which the Kubernetes Horizontal Pod Autoscaler will automatically scale the pods deployed for this role. More details on enabling HPA and how to specify the limits can be here.

7.3.2.16. candisable

role1:
    candisable: true/false

When set to true the specified role can be disabled with regard to the final application. The default value is false, even when it isn’t defined in the manifest file. This should only be set to true if the hook scripts for the bundle can handle a missing role in the template file.

7.3.2.17. description

role1:
    description: Role1 description

Currently not being used.

7.3.2.18. multi_ips

role1:
    multi_ips: true

If this attribute is set to true then another IP pool can be used for this particular role, in addition to the application level IP pool. All containers for this role would have one IP Address assigned from each pool. However these two IP pools must be on different subnets.

7.3.2.19. elastic_ip

role1:
    elastic_ip: true

Enables the allocation of an Elastic IP Address for all containers within a particular role which in turn allows direct access to the container, without the need for portmapping.

7.3.2.20. norootfs

role1:
    norootfs: false

If this attribute is set to false, the root_fs volume type will not be added to storage section for a particular role. The default value is false. Note this attribute is only valid for Docker based applications.

7.3.2.21. restart_on_clone

role1:
    restart_on_clone: false

If this attribute is set to true, all the vnodes of a particular role will be restarted after a clone operation. The default value is false.

7.3.2.22. shareProcessNamespace

role1:
    shareProcessNamespace: true

If this attribute is set to true, all processes within a container are visible to every other containers in the same pod. The default value is false.

7.3.2.23. skip_headless_service

role1:
    skip_headless_service: true

If this attribute is set to true, the creation of the Kubernetes headless service for the given role will be skipped when the application is deployed. The default value is false.

7.3.2.24. block_cloud_metadata

role1:
    block_cloud_metadata: true

If this attribute is set to true, PODs will be blocked from accessing cloud instance metadata. The default value is false. Note this option is applicable only for cloud deployments.

Note

This is currently used in the Cloudera bundle to prevent the Cloudera SCM agents which are running within the PODs from detecting the public IP Address of the physical host as the POD’s public address.

7.3.2.25. virtualize_sysinfo

role1:
    virtualize_sysinfo: true

If this attribute is set to true, Robin virtualizes the proc filesystem inside the POD such that /proc/meminfo displays the correct memory settings inside the container. The default value is false.

Note

Applications like Cloudera utilize the sysinfo library function which in turn incorrectly fetches the host memory settings for the POD. As a result Cloudera fetches the incorrect memory details for the POD.

7.3.2.26. entrypoint

role1:
    entrypoint: custom-entrypoint.sh

Specifies the entrypoint that should be run instead of the default Docker entrypoint. The custom entrypoint script should be present in the scripts folder of the bundle. Note this option is only valid for Docker based applications.

Note

If a container image has /bin/bash or /bin/sh as an entrypoint, as there is no tty console associated in default Kubernetes, the containers go into the Completed state and eventually into CrashLoopBackOff.

Add the following env parameter in the bundle under each role section which has /bin/bash or /bin/sh as the entrypoint.

DOCKER_OPTS: --tty

7.3.2.27. commandline

role1:
    commandline: arg1 arg2

If this attribute is set, its values will be passed to the Docker entrypoint script. Note this attribute is valid only for Docker based applications.

7.3.2.28. rolling_upgrade

role1:
    rolling_upgrade: true

Enables rolling upgrades for a particular role. Possible values: true, false. Default valus is false. Note this attribute is only valid for Docker based applications.

7.3.2.29. depends

role3:
    depends: [role1, role2]

Array of rolenames that indicate the roles (and their respective containers) that have to be created before a particular role.

7.3.2.30. service_ports

role1:
    service_ports: [80, 443]

A comma separated list of ports that need to be port mapped per role. The orchestrator maps these ports to unique port on the physical host within the range 20000-30000 if port mapping is enabled during application creation.

7.3.2.31. env

role1:
    env:
        BROADCAST_ADDRESS: '{{IP_ADDRESS}}'
        MAX_HEAP_SIZE: 512M
        ENV_TEXT_EXAMPLE:
            type: text
            value: "example value"
            label: "Text Field"
            mandatory: true
            editatclone: true
            editatscale: true
            addatclone: true
            max_chars: 8
        ENV_PASSWORD_EXAMPLE:
            type: password
            value: "password123"
            label: "Password Field"
            removeatclone: true
        ENV_NUMBER_EXAMPLE:
            type: number
            value: 15
            min: 10
            max: 20
            label: "Number Field"
        ENV_BOOLEAN_EXAMPLE:
            type: boolean
            value: true
            label: "Boolean Field"
        ENV_FILE_EXAMPLE:
            type: filecontent
            label: "Contents from a file"
        ENV_LIST_EXAMPLE:
            type: list
            items:
                - option1
                - option2
                - option3
            value: option2
            label: "List Field"
        ENV_TIME_EXAMPLE:
            type: date-time
            value: 2016-09-21T15:30
            label: "Time Field"

A set of environment variables to be exposed to each container created for a particular role. They can either be defined as a key-value pair (for example MAX_HEAP_SIZE in the example above) or with a definition. The below attributes can be used when constructing an environment variable using a definition:

  • The type attribute, which is mandatory, specifies the type of input for the variable.

  • The label attribute can be used to override the environment variable name when it is displayed in the Robin UI.

  • The mandatory attribute can be set to true if the environment variable needs to be defined as part of the application deployment.

  • The max_chars attribute can be used to limit the size of the input for an environment variable.

  • The addatclone attribute if set to true, will result in the respective environment variable only being available when the application is cloned. This variable is not used when creating the original application.

  • The removeatclone attribute if set to true, will result in the respective environment variable not being available when the application is cloned. This variable will be used when creating the original application.

Note

When the order of the environment variables is important, they should be defined as an array, by adding a hyphen before each variable.

7.3.2.32. vnodehooks

role1:
    vnodehooks:
        poststart: "bash vnode_start.sh ip_address={{IP_ADDRESS}}"

The vnodehooks attribute can be used to specify any Vnode level scripts that need to be run in tandem with lifecycle operations on the Vnode. More details on Vnode hook scripts can be found here.

7.3.2.33. livenessProbe

role1:
    livenessProbe:
      httpGet:
        path: /
        port: 80
        httpHeaders:
        - name: Custom-Header
          value: Awesome
      initialDelaySeconds: 3
      periodSeconds: 3

The livenessProbe attribute can be used to specify a recurring probe that allows one to detect if a pod has transitioned into a broken state. For the sake of convenience, the probe can be defined within the manifest in the exact same manner as one would in native Kubernetes. As a result, for additional details on configuring the probe review the documentation here.

7.3.2.34. readinessProbe

role1:
    readinessProbe:
      exec:
        command:
        - sleep
        - "5"
      initialDelaySeconds: 5

The readinessProbe attribute can be used to specify a recurring probe that allows one to detect if a pod is ready to serve and receive traffic. For the sake of convenience, the probe can be defined within the manifest in the exact same manner as one would in native Kubernetes. As a result, for additional details on configuring the probe review the documentation here.

7.3.2.35. initContainers

role1:
    initContainers:
    - name: "init"
      image: k8s.gcr.io/busybox
      imagePullPolicy: IfNotPresent
      resources:
        limits:
          cpu: "25m"
          memory: 128Mi
      command:
        - sleep
        - "30"
      securityContext:
        privileged: true
      volumeMounts:
      - name: vol-cm1
        mountPath: /cm1
      - name: vol-cm2
        mountPath: /cm2
      - name: vol-cm3
        mountPath: /cm3

The initContainers attribute can be used to specify the configuration for specialized containers that are spawned before the main application container to perform setup oriented tasks. For the sake of convenience, these containers can be defined within the manifest in the exact same manner as one would in native Kubernetes. As a result, for additional details on configuring init containers review the documentation here.

7.3.2.36. serviceAccountName

role1:
    serviceAccountName: "role1-sa"

The serviceAccountName attribute can be used to specify the service account that pods, which are spawned for the role, should use in order to authenticate with the Kubernetes API server.

7.3.2.37. sidecars

role1:
   sidecars:
   - name: busyside1
     image: k8s.gcr.io/busybox
     command:
       - sleep
       - "3000"
     resources:
       limits:
         memory: 200Mi
       requests:
         cpu: 100m
         memory: 100Mi
     volumeMounts:
     - name: vol-cm1
       mountPath: /cm1
     - name: vol-cm2
       mountPath: /cm2
     - name: vol-cm3
       mountPath: /cm3
     securityContext:
       allowPrivilegeEscalation: true

The sidecars attribute can be used to specify the configuration for specialized containers that are spawned alongside the main container within the same Pod in order to enhance application operations and perform auxillary tasks. More details on configuring sidecar containers can be found here.

7.3.2.38. services

role1:
    services:
    - type: NodePort
    labels:
        l1: v1
        l2: v2
    annotations:
        a1: av1
        a2: av2
    scope: pod
    ports:
    - port: 80
        protocol: TCP
        name: web
    - type: ClusterIP
    ports:
    - port: 80
        protocol: TCP
        name: web
    - type: LoadBalancer
    ports:
    - port: 80
        protocol: TCP
        name: web

The services attribute can be used to specify any Kubernetes services that need to be created as part of application deployment. More details on configuring services to be created can be found here.

7.3.2.39. hostAliases

role1:
    hostAliases:
    - ip: "1.2.3.4"
      hostnames:
      - "foo.remote"
      - "bar.remote"

The hostAliases attribute can be used to add entries to a Pod’s /etc/hosts file so as to provide a Pod-level override of hostname resolution when DNS and other options are not applicable. For the sake of convenience, these custom entries can be defined within the manifest in the exact same manner as one would in native Kubernetes. As a result, for additional details on configuring host aliases review the documentation here.

7.3.2.40. podSecurityContext

role1:
    podSecurityContext:
      runAsUser: 0

The podSecurityContext attribute can be used to specify the security context of the Pod. The values specified defines the privilege and access control settings for a Pod. For the sake of convenience, the values that can be specified under this attribute are the exact same as those available in native Kubernetes. As a result, for additional details on the valid options for the Pod security context review the documentation here.

7.3.2.41. securityContext

role1:
    securityContext:
      allowPrivilegeEscalation: true

The securityContext attribute can be used to specify the security context of the main container for the pods spawned for this role. The security settings specified here will override those set at the Pod level when there is an overlap. For the sake of convenience, the values that can be specified under this attribute are the exact same as those available in native Kubernetes. As a result, for additional details on the valid options for the container security context review the documentation here.

7.3.2.42. affinityrules

role1:
    affinityrules: ["same host", "model a or b and not small"]

The value of this attribute must be a comma seperated list of affinity rule names through which container placement will be contrained. These rule names must refer to constraints specified in affinityrules attribute that is specified at the application level.

7.3.3. Image Level

For a container to spawned for a role an image must be specified. Each role contains at least one image. The attributes detailed below are optional for each image.

7.3.3.1. upgrade_from

role1:
    image:
        upgrade_from: [2.*, 3.1]

Array of versions which can be upgraded to this version of the image. This attribute is only valid for Docker based applications.

7.3.3.2. registry_name

role1:
    image:
        registry_name: My Docker Hub

If this attribute is set, the value specified will define a default registry to use. Note this attribute is valid only for Docker based applications.

7.3.3.3. init_mode

role1:
    image:
        init_mode: false

If this attribute is set to false, Robin will not spawn the container with the --init option. This is useful as by default Robin deploys containers with the --init option which will run an init inside the container that forwards signals and reaps processes. If the docker image itself has init as an entrypoint, a conflict will arise since there are now two processes competing for PID 1.

7.3.4. Compute Resource Level

Each role has compute resource requirements for the containers it spawns. The attributes detailed below are optional when defining the computee resource limits for a role.

7.3.4.1. memory

role1:
    compute:
        memory: 1G

If this attribute is set, the value specified is the default memory size (in M or G) for a container of a particular role.

7.3.4.2. hugepages_1gi

role1:
    compute:
        hugepages_1gi: 1G

If this attribute is set, the value specified is the default amount of 1Gi Hugepages (in M or G) for a container of a particular role.

7.3.4.3. hugepages_2mi

role1:
    compute:
        hugepages_2mi: 1G

If this attribute is set to true, the value specified is the default amount of 2Mi Hugepages (in M or G) for a container of a particular role.

7.3.4.4. cpu - nonisol

role1:
    compute:
        cpu:
            nonisol: true

If this attribute is set to true, the physical CPUs allocated for all vnodes within a role will come from the pool of non-isolated cores on the host.

Note

This attribute is deprecated as of Robin CNP v5.3.5. Existing bundles using this attribute will continue to function with the reserve attribute detailed below take precedence, however manifest files of new bundles will be rejected if it is included.

7.3.4.5. cpu - isol

role1:
    compute:
        cpu:
            nonisol: true

If this attribute is set to true, the physical CPUs allocated for all vnodes within a role will come from the pool of isolated cores on the host.

Note

This attribute is deprecated as of Robin CNP v5.3.5. Existing bundles using this attribute will continue to function with the reserve attribute detailed below take precedence, however manifest files of new bundles will be rejected if it is included.

7.3.4.6. cpu - reserve

role1:
    compute:
        cpu:
            reserve: true

This attribute is used to differentiate between isolated dedicated and isolated shared deployments. As a result, if it is set to true, the isolated physical CPUs allocated for vnodes within a role will be dedicated for the respective vnode and not shared by any other processes.

Note

This attribute only take affect when the isol attribute is set to true.

7.3.4.7. cpu - cores

role1:
    compute:
        cpu:
            cores: 4

If this attribute is set, the value specified is the default number of cores for a container of a particular role.

7.3.4.8. gpu - count

role1:
    compute:
        gpu:
            count: 2

If this attribute is set, the value specified is the default number of GPUs to allocate for a container of a particular role.

7.3.4.9. gpu - type

role1:
    compute:
        gpu:
            type: "nvidia-a100"

If this attribute is set, the value specified is the default type of GPU to allocate for a container of a particular role. If this attribute is not set, only non-partitioned GPU devices will be allocated.

7.3.5. Storage Resource Level

Each role has storage resource requirements for the containers it spawns. The attributes detailed below are optional when defining the storage resource limits for a role.

7.3.5.1. media

role1:
    storage:
      - type: data
        media: ssd

The media type of the disk from which the volume should be allocated from. Possible values: ssd, hdd. The default value is hdd.

7.3.5.2. path

role1:
    storage:
      - type: data
        path: /data

The default path to be used for the volume.

7.3.5.3. size

role1:
    storage:
      - type: data
        size: 10G

If this attribute is set, the value specified is the default volume size (in G or T) for all volumes of this type for the containers of a particular role. The default value is ‘1G’.

role1:
    storage:
      - type: data
        fstype: raw

If this attribute is set, the value specified is the file system type (ext4 / ext3 / xfs / btrfs / raw / zfs) for all volumes of this type for the containers of a particular role. The default value is ‘ext4’.

Note

If the value for the fstype attribute is ‘raw’ and the path attribute is not defined default paths such as /dev/rda .. rdz etc. will be generated.

7.3.5.4. shared

role1:
    storage:
      - type: data
        shared: true

When the value for this attribute is set to true then the volume template for that type will be shared between all containers in a particular role. The default value is false.

Note

This attribute can only be enabled when the value for the fstype attribute for the respective volume is ‘raw’.

7.3.5.5. blocksize

role1:
    storage:
      - type: data
        blocksize: 512

The block size of the disk from which the volume should be allocated from. Possible values: 512, 4096. The default value is 4096.

7.3.5.6. compression

role1:
    storage:
      - type: data
        compression: "1"

The compression algorithm to be applied to each volume created. Possible values: “0”, “1”. The former represents compression being disabled whilst the latter indicates LZ4 based compression. By default, compression is disabled.

7.3.5.7. encryption

role1:
    storage:
      - type: data
        encryption: "CHACHA20"

The encryption algorithm to be applied to each volume created. Possible values: “none”, “CHACHA20”, “AES128”, “AES256”. By default, encryption is disabled.

7.3.5.8. nparts

role1:
    storage:
      - type: data
        nparts: 1

If this attribute is set, the value specified is the number of partitions the block device will support. The default value is 0.

7.3.5.9. replication

role1:
    storage:
      - type: data
        replication: 2

If this attribute is set, the value specified is the number of replicas for the volume. Possible values: 1 (App provided protection), 2 (Two total copies), 3 (Three total copies). The default value is 1.

7.3.5.10. faultdomain

role1:
    storage:
      - type: data
        faultdomain: "host"

If this attribute is set, the value specified is the hardware component across which the replicas for each volume will be spread. Possible values: “disk”, “host” and “rack”. The default value is host.

7.3.5.11. layout

role1:
    storage:
      - type: data
        layout: "pack"

If this attribute is set, the value specified determines how volumes are placed on disk(s). Possible values: “pack”, “round-robin”. The latter specifies that volumes should be spread across disks whilst the latter indicates the opposite. Note, both of these options are enforced with a best-effort policy. The default value is round-robin.

7.3.5.12. workload

role1:
    storage:
      - type: data
        workload: 2

If this attribute is set, the value specified determines the type of volume spawned. This allows users to create volumes more suited to the workload to be run. Possible values: 0 (represents ordinary volumes), 1 (represents latency sensitive volumes), 2 (represents throughput intensive volumes), 3 (represents dedicated volumes which occupy a disk by themselves). The default value is 0 which spawns ordinary volumes.

7.3.5.13. snap_reserved

role1:
    storage:
      - type: data
        snap_reserved: 40

If this attribute is set, the value specified is the percentage of the volume size that is reserved for snapshots. Any integer value between 0 and 100 can be specified. The default value is 20%.

7.3.5.14. count

role1:
    storage:
      - type: data
        count: 3

If this attribute is set, the value specified is number of volumes of this type that will be created. In addition this value will be appended to the default path as a postfix i.e. if the values for path and count where /data and 3 respectively, three volumes would be created with the paths: /data1, /data2, /data3. The default value is 0.

7.3.5.15. mincount

role1:
    storage:
      - type: data
        count: 3
        mincount: 1

If this attribute is set, the value specified is the minimum number of volumes of the particular type that are to be created.

7.3.5.16. maxcount

role1:
    storage:
      - type: data
        maxcount: 12

If this attribute is set, the value specified is the maximum number of volumes of the particular type that are to be created.

7.3.5.17. fixedcount

role1:
    storage:
      - type: data
        count: 3
        fixedcount: true

If the value for this attribute is to true, only the count number of volumes of a particular type will be created. Note this attribute has to be used in conjunction with the count attribute to take affect.

7.3.5.18. affinity

role1:
    storage:
      - type: data
        affinity: rack

If this attribute is set, the value specified defines where the storage must be allocated from in relation to the instance. In this case, the storage must be allocated from the same rack that the instance is placed in. Possible values: host, rack.

7.3.5.19. tags

role1:
    storage:
      - type: data
         tags:
             size: x-large

If this attribute is set, the value specified defines which hosts the storage can be allocated from. This is because the host must match the tags specified. In this case, in order to provide storage for this volume the host must have a size tag with the value x-large.

Note

One can prepend the tag value with a hyphen to indicate the host serving the storage must not have that tag value.

7.3.5.20. mount_in_sidecars

role1:
    storage:
      - type: data
        mount_in_sidecars: true

When the value for this attribute is set to true, the volumes which are created will be bind mounted from the host and available within sidecar containers.

7.3.5.21. mount_in_initcontainers

role1:
    storage:
      - type: data
        mount_in_initcontainers: true

When the value for this attribute is set to true, the volumes which are created will be bind mounted from the host and available within init containers.

7.4. Miscellaneous

7.4.1. Built-in environment variables

Detailed below are several environment variables that Robin understands and thus are for reference within the manifest file:

IP_ADDRESS

This variable contains the IP Address of the current/referenced container.

Usage:

IP_OF_THIS_CONTAINER: "{{IP_ADDRESS}}"
IP_OF_FIRST_CONTINER_IN_THIS_ROLE: "{{VNODES[0].IP_ADDRESS}}"
IP_OF_FIRST_CONTINER_IN_FIRST_ROLE: "{{ROLES[0].VNODES[0].IP_ADDRESS}}"

Jinja2 equivalent:

IP_OF_THIS_CONTAINER: "{{vnode['network'][0]['allocated_ip']}}"
IP_OF_FIRST_CONTINER_IN_THIS_ROLE: "{{role['vnodes'][0]['network'][0]['allocated_ip']}}"
IP_OF_FIRST_CONTINER_IN_FIRST_ROLE: "{{app['roles'][0]['vnodes'][0]['network'][0]['allocated_ip']}}"

HOSTNAME

This variable contains the hostname assigned to the current/referenced container

Usage:

HOSTNAME_OF_THIS_CONTAINER: "{{HOSTNAME}}"
HOSTNAME_OF_FIRST_CONTINER_IN_THIS_ROLE: "{{VNODES[0].HOSTNAME}}"
HOSTNAME_OF_FIRST_CONTINER_IN_FIRST_ROLE: "{{ROLES[0].VNODES[0].HOSTNAME}}"

Jinja2 equivalent:

HOSTNAME_OF_THIS_CONTAINER: "vnode['hostname']"
HOSTNAME_OF_FIRST_CONTINER_IN_THIS_ROLE: "{{role['vnodes'][0]['hostname']}}"
HOSTNAME_OF_FIRST_CONTINER_IN_FIRST_ROLE: "{{app['roles'][0]['vnodes'][0]['hostname']}}"

DISKLIST

This variable contains a comma separated list of block devices attached to current container

Usage:

LIST_OF_BLOCKDEVS_ATTACHED_TO_THIS_CONTAINER: "{{DISKLIST}}"

IP_LIST

This variable contains a comma separated list of IP addresses of all the containers in a role

Usage:

LIST_OF_IPS_OF_ALL_CONTAINERS_IN_CURRENT_ROLE: "{{IP_LIST}}"
LIST_OF_IPS_OF_ALL_CONTAINERS_IN_FIRST_ROLE: "{{ROLES[0].IP_LIST}}"

Jinja2 equivalent:

LIST_OF_IPS_OF_ALL_CONTAINERS_IN_CURRENT_ROLE: "{% for v in role['vnodes'] %}{{v['network'][0]['allocated_ip']}}{% if not loop.last %},{% endif %}{% endfor %}"
LIST_OF_IPS_OF_ALL_CONTAINERS_IN_FIRST_ROLE: "{% for v in app['roles'][0]['vnodes'] %}{{v['network'][0]['allocated_ip']}}{% if not loop.last %},{% endif %}{% endfor %}"

APP_NAME

This variable contains the name of the application

Usage:

CURRENT_APPLICATION_NAME: "{{APP_NAME}}"

Jinja2 equivalent:

CURRENT_APPLICATION_NAME: "{{app['name']}}"

SERVICE_NAMES

This variable contains the names of services created

Usage:

NAME_OF_FIRST_NODEPORT_OF_THIS_CONTAINER: "{{NODEPORT_SERVICE1}}"
NAME_OF_FIRST_NODEPORT_OF_FIRST_CONTINER_IN_THIS_ROLE: "{{VNODES[0].NODEPORT_SERVICE1}}"
NAME_OF_FIRST_NODEPORT_OF_FIRST_CONTINER_IN_FIRST_ROLE: "{{ROLES[0].VNODES[0].NODEPORT_SERVICE1}}"
NAME_OF_FIRST_NODEPORT_OF_FIRST_CONTINER_IN_PARTICULAR_ROLE: "{{ROLES.<ROLE_NAME>.VNODES[0].NODEPORT_SERVICE1}}"
NAME_OF_FIRST_NODEPORT_OF_FIRST_ROLE: "{{ROLES[0].NODEPORT_SERVICE1}}"
NAME_OF_FIRST_NODEPORT_OF_PARTICULAR_ROLE: "{{ROLES.<ROLE_NAME>.NODEPORT_SERVICE1}}"

NAME_OF_FIRST_CLUSTERIP_SERVICE_IN_FIRST_ROLE: "{{ROLES[0].CLUSTER_SERVICE1}}"
NAME_OF_FIRST_CLUSTERIP_SERVICE_IN_PARTICULAR_ROLE: "{{ROLES.<ROLE_NAME>.CLUSTER_SERVICE1}}"

NAME_OF_FIRST_LOADBALANCER_IN_FIRST_ROLE: "{{ROLES[0].LOADBALANCER_SERVICE1}}"
NAME_OF_FIRST_LOADBALANCER_IN_PARTICULAR_ROLE: "{{ROLES.<ROLE_NAME>.LOADBALANCER_SERVICE1}}"

SERVICE_IP

This variable contains the IPs of services created

Usage:

IP_OF_FIRST_CLUSTERIP_SERVICE_IN_FIRST_ROLE: "{{ROLES[0].CLUSTER_IP1}}"
IP_OF_FIRST_CLUSTERIP_SERVICE_IN_PARTICULAR_ROLE: "{{ROLES.<ROLE_NAME>.CLUSTER_IP1}}"

IP_OF_FIRST_LOADBALANCER_IN_FIRST_ROLE: "{{ROLES[0].LOADBALANCER_IP1}}"
IP_OF_FIRST_LOADBALANCER_IN_PARTICULAR_ROLE: "{{ROLES.<ROLE_NAME>.LOADBALANCER_IP1}}"

SERVICE_NAMES

This variable contains the mapped ports of services created

Usage:

MAPPED_PORT_FOR_NODEPORT_OF_THIS_CONTAINER: "{{NODEPORT.MAPPED_PORT.<PORT_NUMBER>}}"
MAPPED_PORT_FOR_NODEPORT_OF_FIRST_CONTINER_IN_THIS_ROLE: "{{VNODES[0].NODEPORT.MAPPED_PORT.<PORT_NUMBER>}}"
MAPPED_PORT_FOR_NODEPORT_OF_FIRST_CONTINER_IN_FIRST_ROLE: "{{ROLES[0].VNODES[0].NODEPORT.MAPPED_PORT.<PORT_NUMBER>}}"
MAPPED_PORT_FOR_NODEPORT_OF_FIRST_CONTINER_IN_PARTICULAR_ROLE: "{{ROLES.<ROLE_NAME>.VNODES[0].NODEPORT.MAPPED_PORT.<PORT_NUMBER>}}"
MAPPED_PORT_FOR_NODEPORT_OF_FIRST_ROLE: "{{ROLES[0].NODEPORT.MAPPED_PORT.<PORT_NUMBER>}}"
MAPPED_PORT_FOR_NODEPORT_OF_PARTICULAR_ROLE: "{{ROLES.<ROLE_NAME>.NODEPORT.MAPPED_PORT.<PORT_NUMBER>}}"

MAPPED_PORT_FOR_LOADBALANCER_IN_FIRST_ROLE: "{{ROLES[0].LOADBALANCER.MAPPED_PORT.<PORT_NUMBER>}}"
MAPPED_PORT_FOR_LOADBALANCER_IN_PARTICULAR_ROLE: "{{ROLES.<ROLE_NAME>.LOADBALANCER.MAPPED_PORT.<PORT_NUMBER>}}"

ENV

This variable can be used to refer to any user defined environment variables

Usage:

MYENV: "test"
NEW_MYENV: "{{ENV.MYENV}}"
ENV1: "{{ROLES.ROLE1.ENV.ENV1}}"

Jinja2 equivalent:

MYENV: "test"
NEW_MYENV: "{{vnode['env']['MYENV']}}"

7.4.2. Jinja2 support

Robin natively supports Jinja2 templatization. As a result, Jinja syntax can be used within the manifest to parse the application configuration JSON and extract information needed for hook scripts. An example of its usage is shown below:

{% for v in vnode['storage'] if 'data' in v['type'] %}
    {{v['path']}}
    {% if not loop.last %},{% endif %}
{% endfor %}

This code is on separate lines for readability, but can combined into one line with no spaces between the blocks and still function appropriately. It will output a comma separated list of all the data directories of a vnode.

Note

In the above example the vnode variable is already defined. It will reference the JSON of the current Vnode that the hook script is operating on. In a similar vein variables such as role and app will already be defined however for application level hooks only app variable will be available.

Another example is shown below this time utilizing information stored at the applicaion level.

{% for r in app['roles'] if r['name'] in ['zookeeper', 'namenode'] %}
    {% for v in r['vnodes'] %}
        {{v['network'][0]['allocated_ip']}}
        {% if not loop.last %},{% endif %}
    {% endfor %}
    {% if not loop.last %},{% endif %}
{% endfor %}

It will output a comma seperated list of the IP Addresses for all the Vnodes if they were created for the roles “zookeeper” or “namenode”.

In order to view an exmaple of an application configuration JSON which can be parsed within a manifest file, run the below command on an existing application:

robin app info <app_name> --appjson

7.4.3. Service URL support

Robin exposes a service url feature through which the user can access an application’s native management UI via Robin’s own UI. This is convienent as it allows to check the status of their deployment and immediately be able to access their application without having to worry about the dynamically assigned attributes of the application such as the containers IP Address. In order to leverage this feature one can specify an info application hook script as displayed in the exmaple below:

apphooks:
    info: "python app_info.py"

One caveat is that the info script must print a JSON to standard output with either of the below structures for it to be interpreted by the Robin UI correctly.

For an individual service URL the foolowing structure is expected:

{
    "service_url": "http://management-url"
}

For an multiple service URLs the foolowing structure is expected:

{
    "service_urls": [
        {
            "name": "app1",
            "url": "http://management-url-1"
        },{
            "name": "app2",
            "url": "http://management-url-2"
        }
    ]
}

Note

This can be accessed via the REST API for retrieving applicaiton information with the additional parameter of info=true.