Mandatory parameters of L2 templates

Think of an L2 template as a template for networking configuration for your hosts. You may adjust the parameters according to the actual requirements and hardware setup of your hosts.

L2 template mandatory parameters

Parameter

Description

cluster.sigs.k8s.io/cluster-name label

Mandatory since MOSK 23.3. References the Cluster object that this template is applied to.

L2 template requirements

  • An L2 template must have the same project (Kubernetes 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 later be assigned to a particular machine using l2TemplateSelector.

  • The following rules apply to the default L2 template of a namespace:

    • Since MOSK 23.3, creation of the default L2 template for a namespace is disabled. On existing clusters, the Spec.clusterRef: default parameter of such an L2 template is automatically removed during the migration process. Subsequently, this parameter is not substituted with the cluster.sigs.k8s.io/cluster-name label, ensuring the application of the L2 template across the entire Kubernetes namespace. Therefore, you can continue using existing default L2 templates for namespaces.

    • Before MOSK 23.3, the default L2Template object for a namespace must have the Spec.clusterRef: default parameter that is deprecated in MOSK 23.3.

clusterRef

Deprecated since MOSK 23.3. 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.

Note

Before MOSK 23.3, an L2 template requires clusterRef: <clusterName> in the spec section. Since MOSK 23.3, this parameter is deprecated and automatically migrated to the cluster.sigs.k8s.io/cluster-name: <clusterName> label.

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 field contains a list of subnet definitions with parameters used by template macros.

  • subnetName

    Defines the alias name of the subnet that can be used to reference this subnet from the template macros and that will be used in the npTemplate section. This name may differ from the name of the actual Subnet resource if the labelSelector field is present and uniquely identifies the resource.

    This parameter is mandatory for every entry in the l3Layout list.

  • subnetPool

    Deprecated since MOSK 24.2. Optional. Default: none. Defines a 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.

    Warning

    The SubnetPool object may not work as expected due to its deprecation. If you still require this feature, contact Mirantis support for further information.

    Existing configurations that use the SubnetPool object in L2Template will be automatically migrated during cluster update to MOSK 24.2. As a result of migration, existing Subnet objects will be referenced in L2Template objects instead of SubnetPool.

  • 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 within one management cluster, for example, the PXE subnet.

    • namespace - the Subnet object is accessible within the same project and management cluster where the L2 template is defined.

    • cluster - CR uses the namespace where the referenced cluster is located. A subnet is only accessible to the cluster that L2Template.metadata.labels:cluster.sigs.k8s.io/cluster-name (mandatory since MOSK 23.3) or L2Template.spec.clusterRef (deprecated in MOSK 23.3) refers to. The Subnet objects with the cluster scope will be created for every new cluster.

  • labelSelector

    Contains a dictionary of labels and their respective values that will be used to find the matching Subnet object for the subnet. If the labelSelector field is omitted, the Subnet object will be selected by name, specified by the subnetName parameter.

Caution

The l3Layout section is mandatory for each L2Template custom resource.

Caution

Using the l3Layout section, define all subnets that are used in the npTemplate section. Defining only part of subnets is not allowed.

If labelSelector is used in l3Layout, use any custom label name that differs from system names. This allows for easier cluster scaling in case of adding new subnets as described in Expand IP addresses capacity in an existing cluster.

Mirantis recommends using a unique label prefix such as user-defined/.

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.

Caution

Mirantis strongly recommends following the below conventions on network interface naming:

  • A physical NIC name set by an L2 template must not exceed 15 symbols. Otherwise, an L2 template creation fails. This limit is set by the Linux kernel.

  • Names of virtual network interfaces such as VLANs, bridges, bonds, veth, and so on must not exceed 15 symbols.

    Mirantis recommends setting interfaces names that do not exceed 13 symbols for both physical and virtual interfaces to avoid corner cases and issues in netplan rendering.