Create L2 templates

Caution

Since Container Cloud 2.9.0, L2 templates have a new format. In the new L2 templates format, l2template:status:npTemplate is used directly during provisioning. Therefore, a hardware node obtains and applies a complete network configuration during the first system boot.

Update any L2 template created before Container Cloud 2.9.0 as described in Release Notes: Switch L2 templates to the new format.

After you create subnets for one or more managed clusters or projects as described in Create subnets or Automate multiple subnet creation using SubnetPool, follow the procedure below to create L2 templates for a managed cluster. This procedure contains exemplary L2 templates for the following use cases:

• L2 template example with bonds and bridges
  • Dedicated network for the Kubernetes pods traffic
  • Dedicated network for the Kubernetes services traffic (MetalLB)
  • Dedicated network for the Ceph distributed storage traffic
  • Example of an L2 template with interfaces bonding
• L2 template example for automatic multiple subnet creation

To create an L2 template for a new managed cluster:

1. Log in to a local machine where your management cluster kubeconfig is located and where kubectl is installed.

   Note

   The management cluster kubeconfig is created during the last stage of the management cluster bootstrap.

2. Inspect the existing L2 templates to select the one that fits your deployment:

   kubectl --kubeconfig <pathToManagementClusterKubeconfig> \
   get l2template -n <ProjectNameForNewManagedCluster>
   

3. Create an L2 YAML template specific to your deployment using one of the exemplary templates:

   • L2 template example with bonds and bridges

   • L2 template example for automatic multiple subnet creation

   Note

   You can create several L2 templates with different configurations to be applied to different nodes of the same cluster. See Assign L2 templates to machines for details.

4. Add or edit the mandatory parameters in the new L2 template. The following tables provide the description of the mandatory and the l3Layout section parameters in the example templates mentioned in the previous step.

   L2 template mandatory parameters

   Parameter	Description
   clusterRef	References the Cluster object that this template is applied to. The default value is used to apply the given template to all clusters within a particular project, unless an L2 template that references a specific cluster name exists. Caution An L2 template must have the same namespace as the referenced cluster. A cluster can be associated with many L2 templates. Only one of them can have the ipam/DefaultForCluster label. Every L2 template that does not have the ipam/DefaultForCluster label can be later assigned to a particular machine using l2TemplateSelector. A project (Kubernetes namespace) can have only one default L2 template (L2Template with Spec.clusterRef: default).
   ifMapping or autoIfMappingPrio	ifMapping is a list of interface names for the template. The interface mapping is defined globally for all bare metal hosts in the cluster but can be overridden at the host level, if required, by editing the IpamHost object for a particular host. The ifMapping parameter is mutually exclusive with autoIfMappingPrio. autoIfMappingPrio is a list of prefixes, such as eno, ens, and so on, to match the interfaces to automatically create a list for the template. If you are not aware of any specific ordering of interfaces on the nodes, use the default ordering from Predictable Network Interfaces Names specification for systemd. You can also override the default NIC list per host using the IfMappingOverride parameter of the corresponding IpamHost. The provision value corresponds to the network interface that was used to provision a node. Usually, it is the first NIC found on a particular node. It is defined explicitly to ensure that this interface will not be reconfigured accidentally. The autoIfMappingPrio parameter is mutually exclusive with ifMapping.
   l3Layout	Subnets to be used in the npTemplate section. The l3Layout section is mandatory for each L2Template custom resource (CR). For more details about L2Template, see L2Template API.
   npTemplate	A netplan-compatible configuration with special lookup functions that defines the networking settings for the cluster hosts, where physical NIC names and details are parameterized. This configuration will be processed using Go templates. Instead of specifying IP and MAC addresses, interface names, and other network details specific to a particular host, the template supports use of special lookup functions. These lookup functions, such as nic, mac, ip, and so on, return host-specific network information when the template is rendered for a particular host. For details about netplan, see the official netplan documentation. Caution All rules and restrictions of the netplan configuration also apply to L2 templates. For details, see the official netplan documentation.

   For more details about the L2Template custom resource (CR), see the L2Template API section.

   l3Layout section parameters

   Parameter	Description
   subnetName	Name of the Subnet object that will be used in the npTemplate section to allocate IP addresses from. All Subnet names must be unique across a single L2 template.
   subnetPool	Optional. Default: none. Name of the parent SubnetPool object that will be used to create a Subnet object with a given subnetName and scope. If a corresponding Subnet object already exists, nothing will be created and the existing object will be used. If no SubnetPool is provided, no new Subnet object will be created.
   scope	Logical scope of the Subnet object with a corresponding subnetName. Possible values: global - the Subnet object is accessible globally, for any Container Cloud project and cluster in the region, for example, the PXE subnet. namespace - the Subnet object is accessible within the same project and region where the L2 template is defined. cluster - the Subnet object is only accessible to the cluster that L2Template.spec.clusterRef refers to. The Subnet objects with the cluster scope will be created for every new cluster.

   The following table describes the main lookup functions for an L2 template.

   Lookup function	Description
   {{nic N}}	Name of a NIC number N. NIC numbers correspond to the interface mapping list.
   {{mac N}}	MAC address of a NIC number N registered during a host hardware inspection.
   {{ip “N:subnet-a”}}	IP address and mask for a NIC number N. The address will be auto-allocated from the given subnet if the address does not exist yet.
   {{ip “br0:subnet-x”}}	IP address and mask for a virtual interface, “br0” in this example. The address will be auto-allocated from the given subnet if the address does not exist yet.
   {{gateway_from_subnet “subnet-a”}}	IPv4 default gateway address from the given subnet.
   {{nameservers_from_subnet “subnet-a”}}	List of the IP addresses of name servers from the given subnet.

   Note

   Every subnet referenced in an L2 template can have either a global or namespaced scope. In the latter case, the subnet must exist in the same project where the corresponding cluster and L2 template are located.

5. Add the L2 template to your management cluster:

   kubectl --kubeconfig <pathToManagementClusterKubeconfig> apply -f <pathToL2TemplateYamlFile>
   

6. Optional. Further modify the template:

   kubectl --kubeconfig <pathToManagementClusterKubeconfig> \
   -n <ProjectNameForNewManagedCluster> edit l2template <L2templateName>
   

7. Proceed with Add a machine. The resulting L2 template will be used to render the netplan configuration for the managed cluster machines.

The workflow of the netplan configuration using an L2 template is as follows:

1. The kaas-ipam service uses the data from BareMetalHost, the L2 template, and subnets to generate the netplan configuration for every cluster machine.

2. The generated netplan configuration is saved in the status.netconfigV2 section of the IpamHost resource. If the status.l2RenderResult field of the IpamHost resource is OK, the configuration was rendered in the IpamHost resource successfully. Otherwise, the status contains an error message.

3. The baremetal-provider service copies data from the status.netconfigV2 of IpamHost to the Spec.StateItemsOverwrites[‘deploy’][‘bm_ipam_netconfigv2’] parameter of LCMMachine.

4. The lcm-agent service on every host synchronizes the LCMMachine data to its host. The lcm-agent service runs a playbook to update the netplan configuration on the host during the pre-download and deploy phases.

See also

• Assign L2 templates to machines

• Create a custom bare metal host profile