Modify network configuration on an existing machine

TechPreview

Caution

Modification of L2 templates in use is only allowed with a mandatory validation step from the infrastructure operator to prevent accidental cluster failures due to unsafe changes. The list of risks posed by modifying L2 templates includes:

  • Services running on hosts cannot reconfigure automatically to switch to the new IP addresses and/or interfaces.

  • Connections between services are interrupted unexpectedly, which can cause data loss.

  • Incorrect configurations on hosts can lead to irrevocable loss of connectivity between services and unexpected cluster partition or disassembly.

Warning

Netplan does not handle arbitrary configuration changes. For details, see Netplan documentation.

To modify network configuration of an existing machine, you need to create a new L2 template and change the assignment of the template for that particular machine.

Warning

When a new network configuration is being applied on nodes, sequential draining of corresponding nodes and re-running of LCM on them occurs the same way as it is done during cluster update.

Therefore, before proceeding with modifying the network configuration, verify that the management cluster is up-to-date as described in Verify the management cluster status before MOSK update.

To modify network configuration on an existing machine:

  1. Select from the following options:

    • Create a new L2 template using the Create L2 templates procedure.

    • Duplicate the existing L2Template object associated with the machine to be configured, ensuring that the duplicated L2Template:

      • Contains a unique name in the metadata.name field

      • Does not contain the ipam/DefaultForCluster label

      • Since MOSK 23.3, refers to the cluster using the cluster.sigs.k8s.io/cluster-name label

      • Before MOSK 23.3, refers to the cluster using Spec.clusterRef: <cluster-name>

  2. Create the new L2Template object:

    kubectl create -f <new-l2template-object-name>.yaml

  3. Assign the new L2Template object to an existing machine:

    In the related Machine object, add the following fields to the spec section:

    kubectl edit machine <machine-name>

    spec:
  providerSpec:
    value:
      l2TemplateSelector:
        name: <new-l2-template-name>

    In the IpamHost object associated with the required machine, add the following fields to the spec section:

    Note

    The IpamHost object is automatically created with the same name as the related Machine object and is located in the same namespace.

    kubectl edit ipamhost <ipamhost-name>

    spec:
  l2TemplateSelector:
    name: <new-l2-template-name>

    Caution

    The name field must match the name of the created L2Template object. To verify the list of available L2Template objects:

    kubectl get l2Template -n <MOSK namespace>

  4. Verify the statuses of the IpamHost objects that use the objects updated in the previous step:

    kubectl get IpamHost <ipamHostName> -o=jsonpath-as-json='{.status.netconfigCandidate}{"\n"}{.status.netconfigCandidateState}{"\n"}{.status.netconfigFilesStates}{"\n"}{.status.messages}'

    Caution

    The following fields of the ipamHost status are renamed since MOSK 23.1 in the scope of the L2Template and IpamHost objects refactoring:

    • netconfigV2 to netconfigCandidate

    • netconfigV2state to netconfigCandidateState

    • netconfigFilesState to netconfigFilesStates (per file)

    No user actions are required after renaming.

    The format of netconfigFilesState changed after renaming. The netconfigFilesStates field contains a dictionary of statuses of network configuration files stored in netconfigFiles. The dictionary contains the keys that are file paths and values that have the same meaning for each file that netconfigFilesState had:

    • For a successfully rendered configuration file: OK: <timestamp> <sha256-hash-of-rendered-file>, where a timestamp is in the RFC 3339 format.

    • For a failed rendering: ERR: <error-message>.

    • If the configuration is valid:

      • The netconfigCandidate field contains the Netplan configuration file candidate rendered using the modified objects

      • The netconfigCandidateState and netconfigFilesStates fields have the OK status

      • The netconfigFilesStates field contains the old date and checksum meaning that the effective Netplan configuration is still based on the previous versions of the modified objects

      • The messages field may contain some warnings but no errors

    • If the L2 template rendering fails, the candidate for Netplan configuration is empty and its netconfigCandidateState status contains an error message. A broken candidate for Netplan configuration cannot be approved and become the effective Netplan configuration.

    Warning

    Do not proceed to the next step until you make sure that the netconfigCandidate field contains the valid configuration and this configuration meets your expectations.

  5. Approve the new network configuration for the related IpamHost objects:

    kubectl patch IpamHost <ipamHostName> --type='merge' -p "{\"spec\":{\"netconfigUpdateAllow\":true}}"

    Once applied, the new configuration is copied to the netconfigFiles field of the effective Netplan configuration, then copied to the corresponding LCMMachine objects.

  6. Verify the statuses of the updated IpamHost objects:

    kubectl get IpamHost <ipamHostName> -o=jsonpath-as-json='{.status.netconfigCandidate}{"\n"}{.status.netconfigCandidateState}{"\n"}{.status.netconfigFilesStates}{"\n"}{.status.messages}'

    Caution

    The following fields of the ipamHost status are renamed since MOSK 23.1 in the scope of the L2Template and IpamHost objects refactoring:

    • netconfigV2 to netconfigCandidate

    • netconfigV2state to netconfigCandidateState

    • netconfigFilesState to netconfigFilesStates (per file)

    No user actions are required after renaming.

    The format of netconfigFilesState changed after renaming. The netconfigFilesStates field contains a dictionary of statuses of network configuration files stored in netconfigFiles. The dictionary contains the keys that are file paths and values that have the same meaning for each file that netconfigFilesState had:

    • For a successfully rendered configuration file: OK: <timestamp> <sha256-hash-of-rendered-file>, where a timestamp is in the RFC 3339 format.

    • For a failed rendering: ERR: <error-message>.

    The new configuration is copied to the effective Netplan configuration and both configurations are valid when:

    • The netconfigCandidateState and netconfigFilesStates fields have the OK status and the same checksum

    • The messages list does not contain any errors

  7. Verify the updated LCMMachine objects:

    kubectl get LCMMachine <LCMMachineName> -o=jsonpath-as-json='{.spec.stateItemsOverwrites}'

    In the output of the above command, hash sums contained in the bm_ipam_netconfig_files values must match those in the IpamHost.status.netconfigFilesStates output. If so, the new configuration is copied to LCMMachine objects.

  8. Monitor the update operations that start on nodes. For details, see Verify machine status.