// Module included in the following assemblies:
//
// * networking/k8s_nmstate/k8s-nmstate-updating-node-network-config.adoc

:_mod-docs-content-type: REFERENCE
[id="virt-example-nmstate-IP-management_{context}"]
= Examples: IP management

[role="_abstract"]
The following example configuration snippets show different methods of IP management.

These examples use the `ethernet` interface type to simplify the example while showing the related context in the policy configuration. These IP management examples can be used with the other interface types.

[id="virt-example-nmstate-IP-management-static_{context}"]
== Static

The following snippet statically configures an IP address on the Ethernet interface:

[source,yaml]
----
# ...
    interfaces:
    - name: eth1
      description: static IP on eth1
      type: ethernet
      state: up
      ipv4:
        dhcp: false
        address:
        - ip: 192.168.122.250 <1>
          prefix-length: 24
        enabled: true
# ...
----
<1> Replace this value with the static IP address for the interface.

[id="virt-example-nmstate-IP-management-no-ip_{context}"]
== No IP address

The following snippet ensures that the interface has no IP address:

[source,yaml]
----
# ...
    interfaces:
    - name: eth1
      description: No IP on eth1
      type: ethernet
      state: up
      ipv4:
        enabled: false
# ...
----

[IMPORTANT]
====
Always set the `state` parameter to `up` when you set both the `ipv4.enabled` and the `ipv6.enabled` parameter to `false` to disable an interface. If you set `state: down` with this configuration, the interface receives a DHCP IP address because of automatic DHCP assignment. 
====

[id="virt-example-nmstate-IP-management-dhcp_{context}"]
== Dynamic host configuration

The following snippet configures an Ethernet interface that uses a dynamic IP address, gateway address, and DNS:

[source,yaml]
----
# ...
    interfaces:
    - name: eth1
      description: DHCP on eth1
      type: ethernet
      state: up
      ipv4:
        dhcp: true
        enabled: true
# ...
----

The following snippet configures an Ethernet interface that uses a dynamic IP address but does not use a dynamic gateway address or DNS:

[source,yaml]
----
# ...
    interfaces:
    - name: eth1
      description: DHCP without gateway or DNS on eth1
      type: ethernet
      state: up
      ipv4:
        dhcp: true
        auto-gateway: false
        auto-dns: false
        enabled: true
# ...
----

[id="virt-example-nmstate-IP-management-mac_{context}"]
== Media Access Control (MAC) address

You can use a MAC address to identify a network interface instead of using the name of the network interface. A network interface name can change for various reasons, such as an operating system configuration change. However, every network interface has a unique MAC address that does not change. This means that using a MAC address is a more permanent way to identify a specific network interface.

Supported values for the `identifier` parameter include the default `name` value and the value `mac-address`. The `name` value applies a configuration to an interface that holds a specified interface name. 

Using a `mac-address` value for the `identifier` parameter indicates that a MAC address is the identifier for the network interface. If you set the `identifier` value to `mac-address`, you must enter a specific MAC address in the following `mac-address` parameter field. 

[NOTE]
====
You can still specify a value for the `name` parameter, but setting the `identifier: mac-address` value means that a MAC address is used as the primary identifier for a network interface. If you specify an incorrect MAC address, `nmstate` reports an invalid argument error. 
====

The following snippet specifies a MAC address as the primary identifier for an Ethernet device, named `eth1`, with a MAC address of `8A:8C:92:1A:F6:98`:

[source,yaml]
----
# ...
interfaces:
- name: eth1
  profile-name: wan0
  type: ethernet
  state: up
  identifier: mac-address
  mac-address: 8A:8C:92:1A:F6:98
# ...
----

[id="virt-example-nmstate-IP-management-dns_{context}"]
== DNS

By default, the `nmstate` API stores DNS values globally as against storing them in a network interface. For certain situations, you must configure a network interface to store DNS values.

[TIP]
====
Setting a DNS configuration is comparable to modifying the `/etc/resolv.conf` file.
====

To define a DNS configuration for a network interface, you must initially specify the `dns-resolver` section in the network interface's YAML configuration file. To apply an NNCP configuration to your network interface, you need to run the `oc apply -f <nncp_file_name>` command.

The following example shows a default situation that stores DNS values globally:

* Configure a static DNS without a network interface. Note that when updating the `/etc/resolv.conf` file on a host node, you do not need to specify an interface, IPv4 or IPv6, in the `NodeNetworkConfigurationPolicy` (NNCP) manifest.
+
[IMPORTANT]
====
During pod creation, Kubernetes uses the `/etc/resolv.conf` file that exists on a node. If you modify the `/etc/resolv.conf` file on a host node, the changes do not propagate to the `/etc/resolv.conf` file that exists in a container. You must re-create the container for changes to take effect.
====
+
Example of a DNS configuration for a network interface that globally stores DNS values:
+
[source,yaml]
----
apiVersion: nmstate.io/v1
kind: NodeNetworkConfigurationPolicy
metadata:
 name: worker-0-dns-testing
spec:
  nodeSelector:
    kubernetes.io/hostname: <target_node>
  desiredState:
    dns-resolver:
      config:
        server:
        - 2001:db8:f::1
        - 192.0.2.251
        search:
        - example.com
        - example.org
# ...
----
+
[IMPORTANT]
====
You can specify DNS options under the `dns-resolver.config` section of your NNCP file as demonstrated in the following example:

[source,terminal]
----
# ...
desiredState:
    dns-resolver:
      config:
        options:
         - timeout:2
         - attempts:3
# ...
----

If you want to remove the DNS options from your network interface, apply the following configuration to your NNCP and then run the `oc apply -f <nncp_file_name>` command: 

[source,terminal]
----
# ...
    dns-resolver:
      config: {}
    interfaces: []
# ...
----
====

The following examples show situations that require configuring a network interface to store DNS values:

* If you want to rank a static DNS name server over a dynamic DNS name server, define the interface that runs either the Dynamic Host Configuration Protocol (DHCP) or the IPv6 Autoconfiguration (`autoconf`) mechanism in the network interface YAML configuration file.
+
Example configuration that adds `192.0.2.1` to DNS name servers retrieved from the DHCPv4 network protocol:
+
[source,yaml]
----
# ...
dns-resolver:
  config:
    server:
    - 192.0.2.1
interfaces:
  - name: eth1
    type: ethernet
    state: up
    ipv4:
      enabled: true
      dhcp: true
      auto-dns: true
# ...
----

* If you need to configure a network interface to store DNS values instead of adopting the default method, which uses the `nmstate` API to store DNS values globally, you can set static DNS values and static IP addresses in the network interface YAML file.
+
[IMPORTANT]
====
Storing DNS values at the network interface level might cause name resolution issues after you attach the interface to network components, such as an Open vSwitch (OVS) bridge, a Linux bridge, or a bond. 
====
+
Example configuration that stores DNS values at the interface level:
+
[source,yaml]
----
# ...
dns-resolver:
  config:
    server:
    - 2001:db8:1::d1
    - 2001:db8:1::d2
    - 192.0.2.1
    search:
    - example.com
    - example.org
interfaces:
  - name: eth1
    type: ethernet
    state: up
    ipv4:
      address:
      - ip: 192.0.2.251
        prefix-length: 24
      dhcp: false
      enabled: true
    ipv6:
      address:
      - ip: 2001:db8:1::1
        prefix-length: 64
      dhcp: false
      enabled: true
      autoconf: false
# ...
----

* If you want to set static DNS search domains and static DNS name servers for your network interface, define the static interface that runs either the Dynamic Host Configuration Protocol (DHCP) or the IPv6 Autoconfiguration (`autoconf`) mechanism in the network interface YAML configuration file.
+
[IMPORTANT]
====
Specifying the following `dns-resolver` configurations in the network interface YAML file might cause a race condition at reboot that prevents the `NodeNetworkConfigurationPolicy` (NNCP) from applying to pods that run in your cluster:

* Setting static DNS search domains and dynamic DNS name servers for your network interface.
* Specifying domain suffixes for the `search` parameter and not setting IP addresses for the `server` parameter.
====
+
Example configuration that sets `example.com` and `example.org` static DNS search domains along with static DNS name server settings:
+
[source,yaml]
----
# ...
dns-resolver:
  config:
    server:
    - 2001:db8:f::1
    - 192.0.2.251
    search:
    - example.com
    - example.org
interfaces:
  - name: eth1
    type: ethernet
    state: up
    ipv4:
      enabled: true
      dhcp: true
      auto-dns: true
    ipv6:
      enabled: true
      dhcp: true
      autoconf: true
      auto-dns: true
# ...
----