************************************************************************************************* Manifest Attribute Breakdown ************************************************************************************************* 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. .. code-block:: yaml 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 ephemeral_storage: - media: HDD size: 1073741824 faultdomain: host replication: 2 compute_storage_affinity: false path: "/mnt/scratch" disk_tags: size: x-large 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" Mandatory attributes -------------------- Application Level ^^^^^^^^^^^^^^^^^^ name ==== .. code-block:: yaml name: Bundle Name Currently not used. The bundle name is set when the bundle is first added. version ======== .. code-block:: yaml version: "1.0" Currently not used. The bundle version is set when the bundle is first added. icon ===== .. code-block:: yaml icon: myBundle.png Path to the image file to display as an icon for the bundle. The image must exist at the specified path. roles ====== .. code-block:: yaml roles: [role1, role2] An array of names for the roles the application will consist of. Role Level ^^^^^^^^^^^ Applications are comprised of roles. Each application must have at least one role. The attributes detailed below are mandatory for each role. name ===== .. code-block:: yaml role1: name: role1 Name of the role. scaleout ======== .. code-block:: yaml 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'. addvolume ========= .. code-block:: yaml role1: addvolume: enabled Enable adding additional volumes to containers of this role. Possible values: 'enabled' or 'disabled'. If not specified the default is 'enabled'. scaleup_mem ============ .. code-block:: yaml role1: scaleup_mem: enabled Enable increasing memory for containers of this role. Possible values: 'enabled' or 'disabled'. If not specified the default is 'enabled'. scaledown_mem =============== .. code-block:: yaml role1: scaledown_mem: disabled Enable decreasing memory for containers of this role. Possible values: 'enabled' or 'disabled'. If not specified the default is 'disabled'. scaleup_cpu ============ .. code-block:: yaml role1: scaleup_cpu: enabled Enable increasing CPUs for containers of this role. Possible values: 'enabled' or 'disabled'. If not specified the default is 'enabled'. scaledown_cpu =============== .. code-block:: yaml role1: scaledown_cpu: enabled Enable decreasing CPUs for containers of this role. Possible values: 'enabled' or 'disabled'. If not specified the default is 'enabled'. 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. name ==== .. code-block:: yaml 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). version ======== .. code-block:: yaml 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). engine ======= .. code-block:: yaml role1: image: engine: docker Engine to be used for instances of this role. Possible engines: 'docker', 'lxc' or 'kvm'. 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. type ==== .. code-block:: yaml 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. Optional attributes ------------------- Application Level ^^^^^^^^^^^^^^^^^^ description ============ .. code-block:: yaml description: Bundle description Currently not being used. website ========= .. code-block:: yaml website: http://www.mycompany.com Currently not being used. Support for this is planned. serialize ========== .. code-block:: yaml serialize: true When true, container provisioning will be sequential and based off the role order in the manifest. The default value is 'false'. profile ======== .. code-block:: yaml 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. snapshot ======== .. code-block:: yaml 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'. snapshot_schedule ================= .. code-block:: yaml 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. clone ===== .. code-block:: yaml 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'. clonemode ========= .. code-block:: yaml 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'. tags ==== .. code-block:: yaml tags: ["sql", "db", "web"] List of tags to be used for bundle filtering. ha_restarts =========== .. code-block:: yaml 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. ha_relocate ============ .. code-block:: yaml ha_relocate: true Boolean value indicating whether or not the container should be relocated after it was restarted number of times. The default value is true. upgrade_order ============== .. code-block:: yaml 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. affinityrules ============== .. code-block:: yaml 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 `_. roleaffinity ============ .. code-block:: yaml 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 `_. apphooks ========= .. code-block:: yaml 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 `_. Role Level ^^^^^^^^^^ Applications are comprised of roles. Each application must have at least one role. The attributes detailed below are optional for each role. multinode ========= .. code-block:: yaml role1: multinode: true Enable multiple instances of this role to be created. The default value is false. multinode_label ================ .. code-block:: yaml 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'. multinode_value ================ .. code-block:: yaml 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. multinode_min ============== .. code-block:: yaml 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. multinode_max ==================== .. code-block:: yaml 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. multinode_fixed ==================== .. code-block:: yaml 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. labels ======= .. code-block:: yaml 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. annotations ============ .. code-block:: yaml 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. tolerations ============ .. code-block:: yaml 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 `_. ports ===== .. code-block:: yaml 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. grace_period_seconds ==================== .. code-block:: yaml 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. restart_on_scalein =================== .. code-block:: yaml 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. restart_on_scaleout =================== .. code-block:: yaml 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. scalein ======== .. code-block:: yaml 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'. hpa ==== .. code-block:: yaml 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 `_. candisable =========== .. code-block:: yaml 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. description ============ .. code-block:: yaml role1: description: Role1 description Currently not being used. multi_ips ============ .. code-block:: yaml 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. elastic_ip ============ .. code-block:: yaml 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. norootfs ============ .. code-block:: yaml 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. restart_on_clone ================= .. code-block:: yaml 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. shareProcessNamespace ====================== .. code-block:: yaml 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. skip_headless_service ====================== .. code-block:: yaml 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. block_cloud_metadata ===================== .. code-block:: yaml 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. virtualize_sysinfo =================== .. code-block:: yaml 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. entrypoint ============ .. code-block:: yaml 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. .. code-block:: text DOCKER_OPTS: --tty commandline ============ .. code-block:: yaml 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. rolling_upgrade ================ .. code-block:: yaml 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. depends ======== .. code-block:: yaml role3: depends: [role1, role2] Array of rolenames that indicate the roles (and their respective containers) that have to be created before a particular role. service_ports ============= .. code-block:: yaml 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. env ==== .. code-block:: yaml 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. vnodehooks ============ .. code-block:: yaml 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 `_. livenessProbe =============== .. code-block:: yaml 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 `_. readinessProbe =============== .. code-block:: yaml 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 `_. initContainers =============== .. code-block:: yaml 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 `_. serviceAccountName =================== .. code-block:: yaml 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. sidecars ========= .. code-block:: yaml 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 `_. services ========= .. code-block:: yaml 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 `_. hostAliases ============ .. code-block:: yaml 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 `_. podSecurityContext =================== .. code-block:: yaml 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 `_. securityContext =================== .. code-block:: yaml 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 `_. affinityrules ============== .. code-block:: yaml 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. 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. upgrade_from ============= .. code-block:: yaml 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. registry_name ============== .. code-block:: yaml 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. init_mode ========== .. code-block:: yaml 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. 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. memory ========== .. code-block:: yaml 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. hugepages_1gi ============== .. code-block:: yaml 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. hugepages_2mi ============== .. code-block:: yaml 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. cpu - nonisol ============== .. code-block:: yaml 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. cpu - isol ============== .. code-block:: yaml 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. cpu - reserve ============== .. code-block:: yaml role1: compute: cpu: reserve: true This attribute is used to differentiate between *shared* and *guaranteed* CPU requests. As a result, if it is set to true, the physical CPUs allocated for vnodes within a role will be dedicated for the respective vnode and not shared by any other processes. If it is not specified the default value assumed is false. cpu - cores ============ .. code-block:: yaml role1: compute: cpu: cores: 4.03 If this attribute is set, the value specified is the default number of cores for a container of a particular role. 1 CPU unit is equivalent to 1 physical CPU core or 1 virtual core, depending on the type of a node (physical machine or virtual machine). You can specify a fractional value of a CPU unit when defining this attribute. gpu - count ============== .. code-block:: yaml 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. gpu - type ============== .. code-block:: yaml 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. 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. media ====== .. code-block:: yaml 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. path ==== .. code-block:: yaml role1: storage: - type: data path: /data The default path to be used for the volume. size ===== .. code-block:: yaml 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'. fstype ======= .. code-block:: yaml 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. shared ====== .. code-block:: yaml 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'. blocksize ========== .. code-block:: yaml 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. compression =========== .. code-block:: yaml 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. encryption =========== .. code-block:: yaml 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. nparts ====== .. code-block:: yaml 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. replication =========== .. code-block:: yaml 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. faultdomain =========== .. code-block:: yaml 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. layout ====== .. code-block:: yaml 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. workload ======== .. code-block:: yaml 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. snap_reserved ============= .. code-block:: yaml 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%. count ===== .. code-block:: yaml 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. mincount ========= .. code-block:: yaml 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. maxcount ========= .. code-block:: yaml 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. fixedcount =========== .. code-block:: yaml 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. affinity ======== .. code-block:: yaml 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. tags ==== .. code-block:: yaml 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. mount_in_sidecars ================== .. code-block:: yaml 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. mount_in_initcontainers ======================== .. code-block:: yaml 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. Miscellaneous -------------- 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:* .. code-block:: yaml 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:* .. code-block:: yaml 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:* .. code-block:: yaml 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:* .. code-block:: yaml 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:* .. code-block:: yaml 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:* .. code-block:: yaml 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:* .. code-block:: yaml 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:* .. code-block:: yaml CURRENT_APPLICATION_NAME: "{{APP_NAME}}" *Jinja2 equivalent:* .. code-block:: yaml CURRENT_APPLICATION_NAME: "{{app['name']}}" **SERVICE_NAMES** This variable contains the names of services created *Usage:* .. code-block:: yaml 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..VNODES[0].NODEPORT_SERVICE1}}" NAME_OF_FIRST_NODEPORT_OF_FIRST_ROLE: "{{ROLES[0].NODEPORT_SERVICE1}}" NAME_OF_FIRST_NODEPORT_OF_PARTICULAR_ROLE: "{{ROLES..NODEPORT_SERVICE1}}" NAME_OF_FIRST_CLUSTERIP_SERVICE_IN_FIRST_ROLE: "{{ROLES[0].CLUSTER_SERVICE1}}" NAME_OF_FIRST_CLUSTERIP_SERVICE_IN_PARTICULAR_ROLE: "{{ROLES..CLUSTER_SERVICE1}}" NAME_OF_FIRST_LOADBALANCER_IN_FIRST_ROLE: "{{ROLES[0].LOADBALANCER_SERVICE1}}" NAME_OF_FIRST_LOADBALANCER_IN_PARTICULAR_ROLE: "{{ROLES..LOADBALANCER_SERVICE1}}" **SERVICE_IP** This variable contains the IPs of services created *Usage:* .. code-block:: yaml IP_OF_FIRST_CLUSTERIP_SERVICE_IN_FIRST_ROLE: "{{ROLES[0].CLUSTER_IP1}}" IP_OF_FIRST_CLUSTERIP_SERVICE_IN_PARTICULAR_ROLE: "{{ROLES..CLUSTER_IP1}}" IP_OF_FIRST_LOADBALANCER_IN_FIRST_ROLE: "{{ROLES[0].LOADBALANCER_IP1}}" IP_OF_FIRST_LOADBALANCER_IN_PARTICULAR_ROLE: "{{ROLES..LOADBALANCER_IP1}}" **SERVICE_NAMES** This variable contains the mapped ports of services created *Usage:* .. code-block:: yaml MAPPED_PORT_FOR_NODEPORT_OF_THIS_CONTAINER: "{{NODEPORT.MAPPED_PORT.}}" MAPPED_PORT_FOR_NODEPORT_OF_FIRST_CONTINER_IN_THIS_ROLE: "{{VNODES[0].NODEPORT.MAPPED_PORT.}}" MAPPED_PORT_FOR_NODEPORT_OF_FIRST_CONTINER_IN_FIRST_ROLE: "{{ROLES[0].VNODES[0].NODEPORT.MAPPED_PORT.}}" MAPPED_PORT_FOR_NODEPORT_OF_FIRST_CONTINER_IN_PARTICULAR_ROLE: "{{ROLES..VNODES[0].NODEPORT.MAPPED_PORT.}}" MAPPED_PORT_FOR_NODEPORT_OF_FIRST_ROLE: "{{ROLES[0].NODEPORT.MAPPED_PORT.}}" MAPPED_PORT_FOR_NODEPORT_OF_PARTICULAR_ROLE: "{{ROLES..NODEPORT.MAPPED_PORT.}}" MAPPED_PORT_FOR_LOADBALANCER_IN_FIRST_ROLE: "{{ROLES[0].LOADBALANCER.MAPPED_PORT.}}" MAPPED_PORT_FOR_LOADBALANCER_IN_PARTICULAR_ROLE: "{{ROLES..LOADBALANCER.MAPPED_PORT.}}" **ENV** This variable can be used to refer to any user defined environment variables *Usage:* .. code-block:: yaml MYENV: "test" NEW_MYENV: "{{ENV.MYENV}}" ENV1: "{{ROLES.ROLE1.ENV.ENV1}}" *Jinja2 equivalent:* .. code-block:: yaml MYENV: "test" NEW_MYENV: "{{vnode['env']['MYENV']}}" 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: .. code-block:: python {% 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. .. code-block:: python {% 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: .. code-block:: bash robin app info --appjson 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: .. code-block:: yaml 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: .. code-block:: json { "service_url": "http://management-url" } For an multiple service URLs the foolowing structure is expected: .. code-block:: json { "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``.