Port Tuple

Release 3.0 onwards, we have introduced port tuples when launching VM services. With this
support, user can create ports and then bind those ports to a service instance.

In R2.x, the service-monitor daemon would create a VM object for each VM based service
instance and create/attach ports to the VM. The VM object was being usedto bind the
VM based service instances to the ports.

In this model, heat engine knew only about the service instance object. The objects created 
by the service-monitor daemon (such as VM, ports, ...) were not visible to heat. 
We saw issues with this approach and decided on the new design of port-tuples.

With the new design, user can create ports and bind them to the created VM based service 
instance. All the objects created are directly visible to the heat-engine and thus managed
by heat directly.

A new object called PortTuple was added to the schema whcih contains all the ports of a VM.
The workflow is as follows:

- User creates a port-tuple
- User creates ports and marks them left/right/mgmt etc and adds them to a port-tuple.
- User links the port-tuple to a service instance
- User launches the virtual-machine using the ports in a port-tuple


Here is step by step creation of a heat template which uses the port-tuple feature.

1. Create a Service Template. We have a version field in the ServiceTemplate.
   We use version 2 for the Port Tuple feature.

  template_ServiceTemplate:
    type: OS::Contrail::ServiceTemplate
    properties:
      name: { get_param: name }
      service_template_properties:
        {
          service_template_properties_version: { get_param: service_template_properties_version },
          service_template_properties_service_mode: { get_param: service_template_properties_service_mode },
          service_template_properties_service_type: { get_param: service_template_properties_service_type },
          service_template_properties_image_name: { get_param: service_template_properties_image_name },
          service_template_properties_service_scaling: { get_param: service_template_properties_service_scaling },
          service_template_properties_interface_type:
            [
              {
              service_template_properties_interface_type_service_interface_type: { get_param: service_template_properties_interface_type_service_interface_type_1 },
              service_template_properties_interface_type_shared_ip: { get_param: service_template_properties_interface_type_shared_ip_1 },
              service_template_properties_interface_type_static_route_enable: { get_param: service_template_properties_interface_type_static_route_enable_1 },
              },
              {
              service_template_properties_interface_type_service_interface_type: { get_param: service_template_properties_interface_type_service_interface_type_2 },
              service_template_properties_interface_type_shared_ip: { get_param: service_template_properties_interface_type_shared_ip_2 },
              service_template_properties_interface_type_static_route_enable: { get_param: service_template_properties_interface_type_static_route_enable_2 },
              },
              {
              service_template_properties_interface_type_service_interface_type: { get_param: service_template_properties_interface_type_service_interface_type_3 },
              service_template_properties_interface_type_shared_ip: { get_param: service_template_properties_interface_type_shared_ip_3 },
              service_template_properties_interface_type_static_route_enable: { get_param: service_template_properties_interface_type_static_route_enable_3 },
              }
            ],
          service_template_properties_flavor: { get_param: service_template_properties_flavor },
          service_template_properties_ordered_interfaces: { get_param: service_template_properties_ordered_interfaces },
          service_template_properties_service_virtualization_type: { get_param: service_template_properties_service_virtualization_type },
          service_template_properties_availability_zone_enable: { get_param: service_template_properties_availability_zone_enable },
        }
      domain: { get_param: domain }


2. Create three virtual-networks (management, left, right)

  template_NetworkIpam_1:
    type: OS::Contrail::NetworkIpam
    properties:
      name: { get_param: service_instance_properties_interface_list_virtual_network_1 }

  template_NetworkIpam_2:
    type: OS::Contrail::NetworkIpam
    properties:
      name: { get_param: service_instance_properties_interface_list_virtual_network_2 }

  template_NetworkIpam_3:
    type: OS::Contrail::NetworkIpam
    properties:
      name: { get_param: service_instance_properties_interface_list_virtual_network_3 }
      
    template_VirtualNetwork_1:
    type: OS::Contrail::VirtualNetwork
    depends_on: [ template_NetworkIpam_1 ]
    properties:
      name: { get_param: service_instance_properties_interface_list_virtual_network_1 }
      network_ipam_refs: { get_resource: template_NetworkIpam_1 }
      network_ipam_refs_data:
        {
          network_ipam_refs_data_ipam_subnets:
            [{
              network_ipam_refs_data_ipam_subnets_subnet:
                {
                  network_ipam_refs_data_ipam_subnets_subnet_ip_prefix: { get_param: network_ipam_refs_data_ipam_subnets_subnet_ip_prefix_1 },
                  network_ipam_refs_data_ipam_subnets_subnet_ip_prefix_len: { get_param: network_ipam_refs_data_ipam_subnets_subnet_ip_prefix_len_1 },
                },
            }]
         }

  template_VirtualNetwork_2:
    type: OS::Contrail::VirtualNetwork
    depends_on: [ template_NetworkIpam_2 ]
    properties:
      name: { get_param: service_instance_properties_interface_list_virtual_network_2 }
      network_ipam_refs: { get_resource: template_NetworkIpam_2 }
      network_ipam_refs_data:
        {
          network_ipam_refs_data_ipam_subnets:
            [{
              network_ipam_refs_data_ipam_subnets_subnet:
                {
                  network_ipam_refs_data_ipam_subnets_subnet_ip_prefix: { get_param: network_ipam_refs_data_ipam_subnets_subnet_ip_prefix_2 },
                  network_ipam_refs_data_ipam_subnets_subnet_ip_prefix_len: { get_param: network_ipam_refs_data_ipam_subnets_subnet_ip_prefix_len_2 },
                },
            }]
         }
  template_VirtualNetwork_3:
    type: OS::Contrail::VirtualNetwork
    depends_on: [ template_NetworkIpam_3 ]
    properties:
      name: { get_param: service_instance_properties_interface_list_virtual_network_3 }
      network_ipam_refs: { get_resource: template_NetworkIpam_3 }
      network_ipam_refs_data:
        {
          network_ipam_refs_data_ipam_subnets:
            [{
              network_ipam_refs_data_ipam_subnets_subnet:
                {
                  network_ipam_refs_data_ipam_subnets_subnet_ip_prefix: { get_param: network_ipam_refs_data_ipam_subnets_subnet_ip_prefix_3 },
                  network_ipam_refs_data_ipam_subnets_subnet_ip_prefix_len: { get_param: network_ipam_refs_data_ipam_subnets_subnet_ip_prefix_len_3 },
                },
            }]
         }

3. Create a Service Instance

  template_ServiceInstance:
    type: OS::Contrail::ServiceInstance
    depends_on: [ template_ServiceTemplate, template_VirtualNetwork_1, template_VirtualNetwork_2, template_VirtualNetwork_3 ]
    properties:
      name: { get_param: name }
      service_instance_properties:
        {
          service_instance_properties_interface_list:
            [
              {
                service_instance_properties_interface_list_virtual_network:
                 {
                   list_join: [':', { get_attr: [ template_VirtualNetwork_1, fq_name ] } ]
                 },
              },
              {
              service_instance_properties_interface_list_virtual_network:
                {
                  list_join: [':', { get_attr: [ template_VirtualNetwork_2, fq_name ] } ]
                },
              },
              {
                service_instance_properties_interface_list_virtual_network:
                  {
                    list_join: [':', { get_attr: [ template_VirtualNetwork_3, fq_name ] } ]
                  },
              }
            ]
          }
  
4. Create the Port Tuple

  template_PortTuple:
    type: OS::Contrail::PortTuple
    depends_on: [ template_ServiceInstance ]
    properties:
      name: port_tuple
      service_instance: { get_resource: template_ServiceInstance }
  
5. Create the Ports and add them to the Port Tuple

  template_VirtualMachineInterface_1:
    type: OS::Contrail::VirtualMachineInterface
    depends_on: [ template_PortTuple, template_VirtualNetwork_1 ]
    properties:
      name: { get_param: service_instance_properties_interface_list_virtual_network_1 }
      virtual_machine_interface_properties:
        {
          virtual_machine_interface_properties_service_interface_type: { get_param: service_template_properties_interface_type_service_interface_type_1 },
        }
      port_tuple_refs: { get_resource: template_PortTuple }
      virtual_network_refs: { get_resource: template_VirtualNetwork_1 }

  template_VirtualMachineInterface_2:
    type: OS::Contrail::VirtualMachineInterface
    depends_on: [ template_PortTuple, template_VirtualNetwork_2 ]
    properties:
      name: { get_param: service_instance_properties_interface_list_virtual_network_2 }
      virtual_machine_interface_properties:
        {
          virtual_machine_interface_properties_service_interface_type: { get_param: service_template_properties_interface_type_service_interface_type_2 },
        }
      port_tuple_refs: { get_resource: template_PortTuple }
      virtual_network_refs: { get_resource: template_VirtualNetwork_2 }

  template_VirtualMachineInterface_3:
    type: OS::Contrail::VirtualMachineInterface
    depends_on: [ template_PortTuple, template_VirtualNetwork_3 ]
    properties:
      name: { get_param: service_instance_properties_interface_list_virtual_network_3 }
      virtual_machine_interface_properties:
        {
          virtual_machine_interface_properties_service_interface_type: { get_param: service_template_properties_interface_type_service_interface_type_3 },
        }
      port_tuple_refs: { get_resource: template_PortTuple }
      virtual_network_refs: { get_resource: template_VirtualNetwork_3 }
  
5. Create the Instance IPs

  template_InstanceIp_1:
    type: OS::Contrail::InstanceIp
    depends_on: [ template_VirtualMachineInterface_1, template_VirtualNetwork_1 ]
    properties:
      name: { get_param: service_instance_properties_interface_list_virtual_network_1 }
      virtual_machine_interface_refs: { get_resource: template_VirtualMachineInterface_1 }
      virtual_network_refs: { get_resource: template_VirtualNetwork_1 }

  template_InstanceIp_2:
    type: OS::Contrail::InstanceIp
    depends_on: [ template_VirtualMachineInterface_2, template_VirtualNetwork_2 ]
    properties:
      name: { get_param: service_instance_properties_interface_list_virtual_network_2 }
      virtual_machine_interface_refs: { get_resource: template_VirtualMachineInterface_2 }
      virtual_network_refs: { get_resource: template_VirtualNetwork_2 }

  template_InstanceIp_3:
    type: OS::Contrail::InstanceIp
    depends_on: [ template_VirtualMachineInterface_3, template_VirtualNetwork_3 ]
    properties:
      name: { get_param: service_instance_properties_interface_list_virtual_network_3 }
      virtual_machine_interface_refs: { get_resource: template_VirtualMachineInterface_3 }
      virtual_network_refs: { get_resource: template_VirtualNetwork_3 }

6. Create the VM binding the three ports to it

  instance:
    type: OS::Nova::Server
    depends_on: [ template_InstanceIp_1, template_InstanceIp_2, template_InstanceIp_3 ]
    properties:
      name:
      image: { get_param: service_template_properties_image_name }
      flavor: { get_param: service_template_properties_flavor }
      networks:
        - port: { get_resource: template_VirtualMachineInterface_1 }
        - port: { get_resource: template_VirtualMachineInterface_2 }
        - port: { get_resource: template_VirtualMachineInterface_3 }