*************************************************************************************************
Template generation
*************************************************************************************************

In order to create an application from a Robin bundle one needs to provide an appropriate application template JSON. 
Robin allows one to natively generate a template for a specified bundle to ease this process. Often run-time configurations/parameters 
need to be specified during application deployment such that they override the defaults that present in the bundle manifest file. As a result,
one can pass in an optional input YAML wherein these modifications are specified so as to create template with these customized values in place. 

Topics covered in this section include:

=============================== =================================================================================
``robin template generate``      Generate a application template from a bundle
=============================== =================================================================================

User Input YAML
---------------

A definitive input YAML is shown below with all the possible values that can be specified. Comments detailing the purpose of each variable are 
provided in-line.

.. code-block:: yaml

   # This is a sample YAML file which can be used as an input to generate
   # a ROBIN template from a bundle to create ROBIN applications.
   # Use only the keys that are required for your application.

   # Name of the app
   name: "appname"

   # Resource pool
   rpool: "default"
   # VNC required ?
   vnc: false

   # Set restart count for Robin AP to try re-deploying VNodes
   # for failed applications
   restart_num: 5

   # Array of IPPools
   ippools: ["robin-default"]

   # Appvars
   appvars:
     json:
       key1: "value1"
       key2: "value"

   # Resource groups
   resgrps:
   - name: scan1
     count: 1
     attributes: {}
   - name: scan2
     count: 1
     attributes: {}

   # Set snapshot schedule for app
   snapshot_schedule:
     cron: 10 * * * *
     retain: 2

   # App is numa aware
   numa_aware: null

   # Docker Registry Name (Can be overriden at the role level)
   registry: "Internal"

   # Default replication factor (Can be overriden at the role level)
   replication: 1

   # Default faultdomain (Can be overriden at the role level)
   faultdomain: null

   # NO rootfs for the entire app (Can be overriden at the role level)
   norootfs: false

   # Rootfs size for the entire app (Can be overriden at the role level)
   rootfs_size: null

   # Media for the entire app (Can be overriden at the role level)
   media: HDD

   # App snapshot space percent for the entire app (Can be overriden at the role level)
   snap_reserved: 20

   # Add global option to skip creation of K8S headless service as a part of Robin App creation
   skip_headless_service: True

   # Set the network policy scope for an application. Valid values include: "allow-all", "namespace", "tenant", "user", "app", "deny-all"
   # If not specified the default value is "allow-all" 
   network_policy_scope: "namespace"

   # ROLES section. An array of roles.
   # Please make sure the role names match exactly the role names
   # present in the application bundle being used
   roles:
   - name: role1  # Replace this with an actual role in the bundle
     # Number of vnodes in the Role
     multinode_value: 2

     # Number of Vnode restart attempts to be done by Robin AP
     # This role level setting overrides the global restart_num setting listed above
     restart_num: 2

     # No root fs for this role
     norootfs: true

     # root fs size for this role
     rootfs_size: "10G"

     # If role has candisable in bundle and user wants to disable role1
     disabled: true

     # Add role level option to skip creation of K8S headless service as a part of Robin App creation
     # This option will overide the global level skip_headless_service option
     skip_headless_service: True

     # dual_stack option can be used for OVS dual stack clusters to have a 1:1 mapping between
     # pod hostnames and IP addresses
     dual_stack: True

     # shareProcessNamespace option can be used to enable process namespace sharing where processes in a container 
     # are visible to all other containers in that pod.
     shareProcessNamespace: True

     # skip_global_ippool option allows users to skip adding global IP pool to role vnodes network section
     # during application creation. By default, Robin will add the global ippool to all role's vnode network section
     skip_global_ippool: True

     # Set the network policy scope for vnodes created as part of this role. 
     # Valid values include: "allow-all", "namespace", "tenant", "user", "app", "deny-all"
     # This role level option will override the value for the global setting for this option
     network_policy_scope: namespace

     # Role specific ippools with customizable parameters 
     # These are seperate from the global IP pool which is defined as the first ippool at the app level 
     # name (optional) parameter per ip pool will be used to map Robin IP pool names
     # to NET names defined in the bundle manifest YAML files
     # primary (optional) parameter per ip pool will be used to support Robin feature to configure
     # multiple IPs on a single pod interface. This feature is only supported with OVS and SR-IOV IP pools
     # trust (optional) parameter per SR-IOV ip pool will be used to have trust enabled for SR-IOV VFs Default: off
     # spoofchk (optional) parameter per SR-IOV ip pool will be used to have sppofchk enabled/disabled for SR-IOV VFs. Default: on
     # bond_mode (optional) parameter per SR-IOV ip pool will be used to set bonding mode. Used with bond CNI. Default: active-backup
     # mtu (optional) parameter will be used to set custom MTU configuration per IP pool
     # staic_macs (optional) per ip pool will be used to set static MAC addresses for each Pod/Vnode
     # static_ips (optional) per ip pool will be used to set static IP addresses for each Pod/Vnode
     # tags (optional) per SR-IOV ip pool will be used to select NICs based on key/value pair passed
     ippools:
     - ippool: private
       static_ips: ["192.168.1.101", "192.168.1.102"]
       static_macs: ["02:0b:0c:11:22:33", "02:0b:0c:11:32:44"]
       name: fronthaul
       trust: on
       bond_mode: active-backup
       spoofchk: off
       mtu: 1500
     - ippool: pool-2
       name: midhaul
       trust: on
       bond_mode: active-backup
       spoofchk: off
       mtu: 1500
       tags: 
         name: sriov0
     - ippool: pool-3
       name: fcaps
     - ippool: pool-4
       static_ips: ["10.168.1.101"]
     - ippool: pool-5
       static_ips: ["20.168.1.101", "20.168.1.102"]
    - ippool: test-primary-pool
    - ippool: test-secondary-pool
      primary: test-primary-pool

     # Tolerations to be added to VNodes within a role for an application
     # to tolerate node taints.
     # This can be used to add new tolerations to a bundle manifest role
     # apart from any tolerations already specified in the bundle.
     tolerations:
     - effect: NoSchedule
       key: node-role.kubernetes.io/master
     - effect: NoSchedule
       key: node-role.kubernetes.io/agent

     # Labels to be added to VNodes within a role for an application.
     # This can be used to add new labels to a bundle manifest role
     # apart from labels already specified in the bundle
     labels:
       labelkey1: labelvalue1
       labelkey2: labelvalue2

     # Compute inputs for the role.
     # Value for terminationGracePeriodSeconds to be used in K8S pod spec
     grace_period_seconds: 60

     containers:
     # This is the main container without name
     - image: "imgname:imgversion"
       imagePullPolicy: "IfNotPresent"
       cpu:
         isol: true # Used for isol-shared/isol-dedicated workloads
         nonisol: true # Used for non-isol workloads
         reserve: true # Used for isol-dedicated
         min: 2.5 # Used for minimum number of CPU cores
         max: 2.5 # Used for maximum number of CPU cores
       memory: "8G"
       hugepages-1Gi: "0"
       hugepages-2Mi: "0"
       gpu:
         count: 2
         type: "nvidia-a100"
       # Env customization for the main container.
       env:
         key5: value5
         key6: value6
       # Specify container <-> host ports mapping (only for main app container pod spec)
       ports:
       - containerPort: 80
         hostPort: 8099
         protocol: TCP
     - name: side1
       image: "imgname:imgversion"
       imagePullPolicy: "IfNotPresent"
       cpu: "8"
       memory: "8G"
       hugepages-1Gi: "0"
       hugepages-2Mi: "0"
       # Env customization for the sidecar container.
       # Users should be able to update existing ENV variables 
       # as well as add new ENV variables for sidecar containers
       env:
         key1: value1
         key2: value2
     - name: init1
       image: "imgname:imgversion"
       imagePullPolicy: "IfNotPresent"
       cpu: "8"
       memory: "8G"
       hugepages-1Gi: "0"
       hugepages-2Mi: "0"
       # Env customization for the init container.
       # Users should be able to update existing ENV variables 
       # as well as add new ENV variables for init containers
       env:
         key3: value3
         key4: value4

     # Hostnames for the vnodes in this role inputs for the role.
     hostnames: ["h1", "h2"]

     # Registry to use for this role.
     registry: null

     # Role and Vnode level service definitions
     # Only existing service definitions in Robin bundles will be updated
     # as part of services section here. No new services will be added to the bundle
     services:
     - type: NodePort
       labels:
         l1: v1
         l2: v2
       annotations:
         a1: av1
         a2: av2
       scope: pod
       ports:
       - port: 80
         protocol: TCP
         name: web
         node_port: 30000
     - type: ClusterIP
       labels:
         l1: v1
         l2: v2
       annotations:
         a1: av1
         a2: av2
       ports:
       - port: 80
         protocol: TCP
         name: web

     # Storage customization per volume type. One entry per voltype
     storage:
       data:
         count: 3
         blocksize: 4096
         compression: "disabled"
         fstype: "ext4"
         size: "10G"
         snap_reserved: 20
         encryption: "chacha20"
         replication: 3
         faultdomain: "host"
         fstype: "ext4"
         media: "HDD"
         qos_enabled: False,
         qos_priority: 1,
         qos_rd_max_iops: 2000000,
         qos_rd_min_iops: 0,
         qos_rd_min_window: 500,
         qos_rd_weight: 1,
         qos_wr_max_iops: 2000000,
         qos_wr_min_iops: 0,
         qos_wr_min_window: 500,
         qos_wr_weight: 1
       log:
         count: 3
         size: 2G

     # Placement constraints for this role. One of the following 4 can be given
     placeon_different_nodes_on_same_rack: false
     placeon_different_nodes_on_different_rack: false
     round_robin_across_different_racks: false
     round_robin_across_different_datacenters: false

     # Antiaffinity for this role. One of the following 3 can be enabled
     anti_affinity_on_host: false
     anti_affinity_on_rack: false
     anti_affinity_on_datacenter: false

     # Compute and storage affinity for this role. One of the 3 can be enabled
     compute_storage_on_same_node: false
     compute_storage_on_same_rack: false
     compute_storage_on_same_datacenter: false

     # Place the vnodes of this role matching host tags
     placeon_host_match_tags:
       worker: "worker2"
       floor: "first"

     # Colocate this role with other roles in the application. One of the 3 can be enabled
     colocate_with_roles_on_host: ["role2", "role3"]
     colocate_with_roles_on_rack: ["role4", "role5"]
     colocate_with_roles_on_datacenter: ["role6"]

     # Do colocate this role with other roles in the application. One of the 3 can be enabled
     donot_colocate_with_roles_on_host: ["role4", "role5"]
     donot_colocate_with_roles_on_rack: ["role6"]
     donot_colocate_with_roles_on_datacenter: []

   # Role 2
   - name: role2  # Replace this with an actual role in the bundle
     multinode_value: 2

   # Role 3
   - name: role3  # Replace this with an actual role in the bundle
     multinode_value: 2

   # Role 4
   - name: role4  # Replace this with an actual role in the bundle
     multinode_value: 2

.. Note:: It is not necessary to include all roles in the bundle as a part of the input file; one can customize values for particular roles and use default bundle values for the others.


Generating a Template
----------------------

.. tabs::

      .. tab:: CLI

          In order to generate an application template for a specific bundle with run time configurations, issue the following command:

          .. code-block:: text

                  # robin template generate <bundleid>
                                            --input <input_yaml>
                                            --details
                                            --table

          ======================== =========================================================
          ``bundleid``              Id of Application Bundle to generate a template for
          ``--input <input_yaml>``  Input file containing custom run time values
          ``--details``             Display the resulting template as it would be shown in the Robin UI
          ``--table``               Display the resulting template in a tabular format
          ======================== =========================================================

          **Example 1 (Custom values for multiple roles):**

          .. code-block:: text

                # cat user-input-demo.yaml
                appname: "elk1"
                roles:
                - name: data_node
                  multinode_value: 5
                  containers:
                  - cpu: 8
                    memory: 8G

                # robin template generate 3 --input user-input-demo.yaml --table
                Role                  | Engine | Image                                               | Vnodes | Cpu    | Mem      | Network       | Storage(Vols/Size)
                ----------------------+--------+-----------------------------------------------------+--------+--------+----------+---------------+--------------------
                data_node             | docker | docker.elastic.co/elasticsearch/elasticsearch:6.6.2 | 5      | 8 (40) | 8G (40G) | robin-default | 1/200G (5/1000G)
                dedicated_master_node | docker | docker.elastic.co/elasticsearch/elasticsearch:6.6.2 | 1      | 1 (1)  | 1G (1G)  | robin-default | 1/200G (1/200G)
                kibana                | docker | docker.elastic.co/kibana/kibana:6.6.2               | 1      | 1 (1)  | 1G (1G)  | robin-default | -
                logstash              | docker | docker.elastic.co/logstash/logstash:6.6.2           | 1      | 1 (1)  | 1G (1G)  | robin-default | 1/10G (1/10G)
                master_eligible_node  | docker | docker.elastic.co/elasticsearch/elasticsearch:6.6.2 | 1      | 1 (1)  | 1G (1G)  | robin-default | 1/200G (1/200G)
                                      |        |                                                     |        |        |          |               |
                Total                 |        |                                                     | 9      | 44     | 44G      |               | 8/1T


          **Example 2 (Custom values for networking attributes):**

          .. code-block:: text

              # cat input-static-ips-pools.yaml 
              appname: "ovs-staticips-app"
              media: HDD
              ippools: ["ovs-1"]
              roles:
                - name: server
                  multinode_value: 2
                  ippools:
                  - ippool: ovs-1
                  - ippool: ovs-2
                    static_ips: ["10.168.10.122", "10.168.10.123"]
                  - ippool: ovs-3
                    static_ips: ["20.168.20.122", "20.168.20.123"]
                    static_macs: ["02:0b:0c:11:22:33", "02:0b:0c:11:32:44"]

              # robin template generate 1 --input-static-ips-pools.yaml --table
              Role   | Engine | Image             | Vnodes | Cpu   | Mem         | Network           | Storage(Vols/Size)
              -------+--------+-------------------+--------+-------+-------------+-------------------+--------------------
              server | docker | robinsys/centos:7 | 2      | 1 (2) | 200M (400M) | ovs-1,ovs-2,ovs-3 | 2/2G (4/4G)
                     |        |                   |        |       |             |                   |
              Total  |        |                   | 2      | 2     | 400M        |                   | 4/4G


          .. note:: Users can also create applications by directly specifying the input YAML file in place of the template JSON in the ``robin app create from-bundle`` command.