diff --git a/README.md b/README.md index cb0083a7..57191e68 100644 --- a/README.md +++ b/README.md @@ -265,7 +265,7 @@ If you want you can even add all available APIs at the same time to see which me We advise new users, or users operating a single tenant Kubernetes cluster to start out with a streamlined, lightweight network management experience. In this "mode" DANM only recognizes one network management API, called **DanmNet**. Both administrators, and tenant users manage their networks through the same API. Everyone has the same level of access, and can configure all the parameters supported by DANM at their leisure. -At the same time it is impossible to create networks, which can be used across tenants (disclaimer: we use the word "tenant" as a synonym to "Kubernetes namespace"). +At the same time it is impossible to create networks, which can be used across tenants (disclaimer: we use the word "tenant" as a synonym to "Kubernetes namespace" throughout the document). ##### Production-grade network management experience In a real, production-grade cluster the lightweight management paradigm does not suffice, because usually there are different users, with different roles interacting with each other. There are possibly multiple users using their own segment of the cloud -or should we say tenant?- at the same time; while there can be administrator(s) overseeing that everything is configured, and works as it should be. @@ -283,7 +283,7 @@ Wonder how? Refer to chapter [Connecting TenantNetworks to TenantConfigs](#conne Interested user can find reference manifests showcasing the features of the new APIs under [DANM V4 example manifests](https://github.com/nokia/danm/tree/master/example/4_0_examples). ##### Network management in the practical sense -Regardless which paradigm thrives in your cluster, network objects are managed the exact same way - you just might not be allowed to execute a specific provisioning operation in case you are trying to overstep your boundaries! Don't worry, as DANM will always explicitly and instantly tells you if this is the case. +Regardless which paradigm thrives in your cluster, network objects are managed the exact same way - you just might not be allowed to execute a specific provisioning operation in case you are trying to overstep your boundaries! Don't worry, as DANM will always explicitly and instantly tell you if this is the case. Unless explicitly stated in the description of a specific feature, all API features are generally supported, and supported the same way regardless through which network management API type you use them. Network management always starts with the creation of Kubernetes API objects, logically representing the characteristics of a network Pods can connect to. @@ -336,7 +336,7 @@ Sorry, but they made us do it :) **Note**: some CNI plugins try to be smart about this limitation on their own, and decided not to adhere to the CNI standard! An example of this behaviour can be found in Flannel. It is the user's responsibility to put the network connection of such boneheaded backends to the first place in the Pod's annotation! -However, DANM also supports both explicit, and implicit interface naming schemes for all NetworkTypes to help you flexibly name the other -and CNI standard- interfaces! +Besides making sure the first interface is always named correctly, DANM also supports both explicit, and implicit interface naming schemes for all NetworkTypes to help you flexibly name the other -and CNI standard- interfaces! An interface connected to a network containing the container_prefix attribute is always named accordingly. You can use this API to explicitly set descriptive, unique names to NICs connecting to this network. In case container_prefix is not set in an interface's network descriptor, DANM automatically uses the "eth" as the prefix when naming the interface. Regardless which prefix is used, the interface name is also suffixed with an integer number corresponding to the sequence number of the network connection (e.g. the first interface defined in the annotation is called "eth0", second interface "eth1" etc.) @@ -368,8 +368,10 @@ This way users can dynamically configure various networking solutions via the sa A generic framework supporting this method is built into DANM's code, but still this level of integration requires case-by-case implementation. As a result, DANM currently supports two integration levels: - - **Dynamic integration level:** CNI-specific network attributes (such as IP ranges, parent host devices etc.) can be controlled on a per network level, taken directly from the CRD object - - **Static integration level:** CNI-specific network attributes (such as IP ranges, parent host devices etc.) can be only configured via static CNI configuration files (Note: this is the default CNI configuration method) + - **Dynamic integration level:** CNI-specific network attributes (such as IP ranges, parent host devices etc.) can be controlled on a per network level, exclusively taken directly from the CRD object + - **Static integration level:** CNI-specific network attributes are by default configured via static CNI configuration files (Note: this is the default CNI configuration method); but certain parameters are influenced by the DANM API configuration values. + +Always refer to the schema descriptors for more details on which parameters are universally supported! Our aim is to integrate all the popular CNIs into the DANM eco-system over time, but currently the following CNI's achieved dynamic integration level: @@ -383,12 +385,12 @@ Our aim is to integrate all the popular CNIs into the DANM eco-system over time, No separate configuration needs to be provided to DANM when it connects Pods to networks, if the network is backed by a CNI plugin with dynamic integration level. Everything happens automatically purely based on the network manifest! -When network management is delegated to CNI plugins with static integration level; DANM reads their configuration from the configured CNI config directory. +When network management is delegated to CNI plugins with static integration level; DANM first reads their configuration from the configured CNI config directory. The directory can be configured via setting the "CNI_CONF_DIR" environment variable in DANM CNI's context (be it in the host namespace, or inside a Kubelet container). Default value is "/etc/cni/net.d". In case there are multiple configuration files present for the same backend, users can control which one is used in a specific network provisioning operation via the NetworkID parameter. So, all in all: a Pod connecting to a network with "NetworkType" set to "bridge", and "NetworkID" set to "example_network" gets an interface provisioned by the /bridge binary based on the /example_network.conf file! -In addition to simply delegating the interface creation operation, generally supported DANM API-based features -such as static and dynamic IP route provisioning, flexible interface naming- are also configured by DANM. +In addition to simply delegating the interface creation operation, the universally supported features of the DANM management APIs -such as static and dynamic IP route provisioning, flexible interface naming, or centralized IPAM- are also configured either before, or after the delegation took place. ##### Connecting Pods to specific networks Pods can request network connections to networks by defining one or more network connections in the annotation of their (template) spec field, according to the schema described in the **schema/network_attach.yaml** file. @@ -396,8 +398,8 @@ For each connection defined in such a manner DANM provisions exactly one interfa In case you have added more than one network management APIs to your cluster, it is possible to connect the same Pod to different networks of different APIs. But please note, that physical network interfaces are 1:1 mapped to logical networks. In addition to simply invoking other CNI libraries to set-up network connections, Pod's can even influence the way their interfaces are created to a certain extent. -For example Pods can ask DANM to provision L3 IP addresses to their IPVLAN, MACVLAN or SR-IOV interfaces dynamically, statically, or not at all! -Or, as described earlier; creation of policy-based L3 IP routes into their network namespace is also a supported by the solution. +For example Pods can ask DANM to provision L3 IP addresses to their network interfaces dynamically, statically, or not at all! +Or, as described earlier; creation of policy-based L3 IP routes into their network namespace is also universally supported by the solution. ##### Defining default networks If the Pod annotation is empty (no explicit connections are defined), DANM tries to fall back to a configured default network. In the lightweight network management paradigm default networks can be only configured on a per namespace level, by creating one DanmNet object with ObjectMeta.Name field set to "default" in the Pod's namespace. @@ -414,9 +416,9 @@ DANM waits for the CNI result of all executors before converting, and merging th If any executor reported an error, or hasn't finished its job even after 10 seconds; the result of the whole operation will be an error. DANM reports all errors towards kubelet in case multiple CNI plugins failed to do their job. #### DANM IPAM -DANM includes a fully generic and very flexible IPAM module in-built into the solution. The usage of this module is seamlessly integrated together with the natively supported CNI plugins, that is, DANM's IPVLAN, Intel's SR-IOV, and the CNI project's reference MACVLAN plugins. +DANM includes a fully generic and very flexible IPAM module in-built into the solution. The usage of this module is seamlessly integrated together with all the natively supported CNI plugins (DANM's IPVLAN, Intel's SR-IOV, and the CNI project's reference MACVLAN plugins); as well as with any other CNI backend fully adhering to the v0.3.1 CNI standard! -That is because just like the above CNIs, configuration of DANM's IPAM is also integrated into the DANM's network management APIs through the attributes called "cidr", "allocation_pool", and "net6". Therefore users of the module can easily configure all aspects of network management by manipulating solely dynamic Kubernetes API objects! +The main feature of DANM's IPAM is that it's fully integrated into DANM's network management APIs through the attributes called "cidr", "allocation_pool", and "net6". Therefore users of the module can easily configure all aspects of network management by manipulating solely dynamic Kubernetes API objects! This native integration also enables a very tempting possibility. **As IP allocations belonging to a network are dynamically tracked *within the same API object***, it becomes possible to define: * discontinuous subnets 1:1 mapped to a logical network @@ -426,6 +428,13 @@ Network administrators can simply put the CIDR, and the allocation pool into the The flexible IPAM module also allows Pods to define the IP allocation scheme best suited for them. Pods can ask dynamically allocated IPs from the defined allocation pool, or can ask for one, specific, static address. The application can even ask DANM to forego the allocation of any IPs to their interface in case a L2 network interface is required. +##### Using IPAM with static backends +While using the DANM IPAM with dynamic backends is mandatory, netadmins can freely choose if they want their static CNI backends to be also integrated to DANM's IPAM; or they would prefer these interfaces to be statically configured by another IPAM module. +By default the "ipam" section of a static delegate is always configured from the CNI configuration file identified by the network's NetworkID parameter. +However, users can overwrite this inflexible -and most of the time host-local- option by defining "cidr", and/or "net6" in their network manifest just as they would with a dynamic backend. +When a Pod connects to a network with static NetworkType but containing allocation subnets, and explicitly asks for an "ip", and/or "ip6" address from DANM in its annotation; DANM overwrites the "ipam" section coming from the static config with its own, dynamically allocated address. +If a Pod does not ask DANM to allocate an IP, or the network does not define the necessary parameters; the delegation automatically falls back to the "ipam" defined in the static config file. +**Note**: DANM can only integrate static backends to its flexible IPAM if the CNI itself is fully compliant to the standard, i.e. uses the plugin defined in the "ipam" section of its configuration. It is the administrator's responsibility to configure the DANM management APIs according to the capabilities of every CNI! ##### IPv6 and dual-stack support DANM's IPAM module, and its integration to dynamic backends -IPVLAN, MACVLAN, and SR-IOV CNIs- support both IPv6, and dual-stack (one IPv4, and one IPv6 address provisioned to the same interface) addresses! To configure an IPv6 CIDR for a network, network administrators shall configure the "net6" attribute. Additionally, IP routes for IPv6 subnets can be configured via "routes6". @@ -438,6 +447,8 @@ That being said, network administrators using IPv6, or dual-stack features need * the smallest supported IPv6 subnet is /64 * allocation pools cannot be defined for IPv6 subnets +This feature is generally supported the same way even for static CNI backends! However guaranteeing that every specific backend is compabile and comfortable with both IPv6, and dual IPs allocated by an IPAM cannot be guaranteed by DANM. +Therefore, it is the administrator's responsibility to configure the DANM management APIs according to the capabilities of every CNI! #### DANM IPVLAN CNI DANM's IPVLAN CNI uses the Linux kernel's IPVLAN module to provision high-speed, low-latency network interfaces for applications which need better performance than a bridge (or any other overlay technology) can provide. diff --git a/schema/ClusterNetwork.yaml b/schema/ClusterNetwork.yaml index da399062..69e11d43 100644 --- a/schema/ClusterNetwork.yaml +++ b/schema/ClusterNetwork.yaml @@ -14,16 +14,16 @@ metadata: spec: # This parameter provides a second identifier for ClusterNetworks, and can be used to control a number of API features. # For static delegates, the parameter configures which CNI configuration file is to be used if NetworkType points to a static-level CNI backend. - # For dynamic delegates, VxLAN host interfaces are suffixed, while VLAN host interfaces are prefixed with the NetworkID. + # VxLAN host interfaces are suffixed, while VLAN host interfaces are prefixed with the NetworkID. # This allows deployment administrators to separate their own interfaces from others' in a multi-tenant environment, i.e. by setting NetworkID to "name_namespace" value. - # OPTIONAL - STRING, MAXIMUM 12 CHARACTERS + # OPTIONAL - STRING, MAXIMUM 11 CHARACTERS NetworkID: ## NETWORK_ID ## # This parameter, denotes which backend is used to provision the container interface connected to this network. # Currently supported values with dynamic integration level are IPVLAN (default), SRIOV, or MACVLAN. # - IPVLAN option results in an IPVLAN sub-interface provisioned in L2 mode, and connected to the designated host device # - SRIOV option pushes a pre-allocated Virtual Function of the configured host device to the container's netns # - MACVLAN option results in a MACVLAN sub-interface provisioned in bridge mode, and connected to the designated host device - # Setting this option to another value results in delegating the network provisioning operation to the named backend with static configuration (i.e. most Options are ignored). + # Setting this option to another value results in delegating the network provisioning operation to the named backend with static configuration (i.e. coming from a standard CNI config file). # The default IPVLAN backend is used when this parameter is not specified. # OPTIONAL - ONE OF {ipvlan,sriov,macvlan,} # DEFAULT VALUE: ipvlan @@ -37,9 +37,8 @@ spec: # - K8S_NAMESPACE1 # - K8S_NAMESPACE2 # Specific extra configuration options can be passed to the network provisioning backends. - # Most of the parameters are only supported for dynamic level backends, such as IPVLAN, MACVLAN, and SRIOV. - # Other network interfaces are always provisioned based on their associated static CNI configuration files. - # The exceptional attributes are "rt_tables", "container_prefix", and "routes/6". DANM universally supports the features related to these parameters for all CNI backends. + # Most of the parameters are generally supported for all network types. + # Options only supported for dynamic level backends, such as IPVLAN, MACVLAN, and SRIOV are explicitly noted. Options: # Name of the parent host device (i.e. physical host NIC). # Sub-interfaces are connected to this NIC in case NetworkType is set to IPVLAN, or MACVLAN. @@ -53,13 +52,11 @@ spec: # OPTIONAL - STRING device_pool: ## DEVICE_PLUGIN_RESOURCE_POOL_MAME ## # The IPv4 CIDR notation of the subnet associated with the network. - # Pods connecting to this network will get their IPv4 IP from this subnet, if defined. - # Only has an effect with dynamically integrated backends. Ignored for other NetworkTypes. + # Pods connecting to this network get an IPv4 address to their interface from this subnet. # OPTIONAL - IPv4 CIDR FORMAT (e.g. "10.0.0.0/24") cidr: ## SUBNET_CIDR ## # IPv4 allocation will be done according to the narrowed down allocation pool parameter, if defined. # Allocation pool must be provided together with "cidr", and shall be included in the subnet range. - # Only has an effect with dynamically integrated backends. Ignored for other NetworkTypes. # If CIDR is provided without defining an allocation pool, it is automatically calculated for the whole netmask (minus the first, and the last IP). # The gateway IPs of all the configured IP routes are also automatically reserved from the allocation pool when it is generated. # When the network administrator sets the allocation pool, DANM assumes the non-usable IPs (e.g. broadcast IP, gateway IPs etc.) were already discounted. @@ -67,10 +64,8 @@ spec: start: ## FIRST_ASSIGNABLE_IP ## end: ## LAST_ASSIGNABLE_IP ## # The IPv6 CIDR notation of the subnet associated with the network. - # Pods connecting to this network will get their IPv6 addresses from this subnet, if defined. - # Only has an effect with dynamically integrated backends. Ignored for other NetworkTypes. - # OPTIONAL - IPv6 CIDR FORMAT (e.g. "2001:db8::/45"). - # NOTE: Netmask of the subnet cannot be higher than /64 (i.e. /65 and upwards). + # Pods connecting to this network will get their IPv6s from this subnet, if defined. + # OPTIONAL - IPv6 CIDR FORMAT (e.g. "2001:db8::/45"). Netmask of the subnet cannot be higher than /64 (i.e. /65 and upwards). net6: ## SUBNET_CIDR ## # Interfaces connected to this network are renamed inside the Pod's network namespace to a string starting with "container_prefix". # If not provided, DANM uses "eth" as the prefix. diff --git a/schema/DanmNet.yaml b/schema/DanmNet.yaml index 73e60dff..7a0376c4 100644 --- a/schema/DanmNet.yaml +++ b/schema/DanmNet.yaml @@ -13,29 +13,28 @@ metadata: spec: # This parameter provides a second identifier for DanmNets, and can be used to control a number of API features. # For static delegates, the parameter configures which CNI configuration file is to be used if NetworkType points to a static-level CNI backend. - # For dynamic delegates, VxLAN host interfaces are suffixed, while VLAN host interfaces are prefixed with the NetworkID. + # VxLAN host interfaces are suffixed, while VLAN host interfaces are prefixed with the NetworkID. # This allows deployment administrators to separate their own interfaces from others' in a multi-tenant environment, i.e. by setting NetworkID to "name_namespace" value. - # OPTIONAL - STRING, MAXIMUM 12 CHARACTERS + # OPTIONAL - STRING, MAXIMUM 11 CHARACTERS NetworkID: ## NETWORK_ID ## # This parameter, denotes which backend is used to provision the container interface connected to this network. # Currently supported values with dynamic integration level are IPVLAN (default), SRIOV, or MACVLAN. # - IPVLAN option results in an IPVLAN sub-interface provisioned in L2 mode, and connected to the designated host device # - SRIOV option pushes a pre-allocated Virtual Function of the configured host device to the container's netns # - MACVLAN option results in a MACVLAN sub-interface provisioned in bridge mode, and connected to the designated host device - # Setting this option to another value results in delegating the network provisioning operation to the named backend with static configuration (i.e. most Options are ignored). + # Setting this option to another value results in delegating the network provisioning operation to the named backend with static configuration (i.e. coming from a standard CNI config file). # The default IPVLAN backend is used when this parameter is not specified. # OPTIONAL - ONE OF {ipvlan,sriov,macvlan,} # DEFAULT VALUE: ipvlan NetworkType: ## BACKEND_TYPE ## # Specific extra configuration options can be passed to the network provisioning backends. - # Most of the parameters are only supported for dynamic level backends, such as IPVLAN, MACVLAN, and SRIOV. - # Other network interfaces are always provisioned based on their associated static CNI configuration files. - # The exceptional attributes are "rt_tables", "container_prefix", and "routes/6". DANM universally supports the features related to these parameters for all CNI backends. + # Most of the parameters are generally supported for all network types. + # Options only supported for dynamic level backends, such as IPVLAN, MACVLAN, and SRIOV are explicitly noted. Options: # Name of the parent host device (i.e. physical host NIC). # Sub-interfaces are connected to this NIC in case NetworkType is set to IPVLAN, or MACVLAN. # Only has an effect with dynamically integrated backends. Ignored for other NetworkTypes. - # Also ignored for SR-IOV, as the pre-allocated Virtual Functions belonging to the configured Kubernetes Device pool are pushed into the connecting Pod's network namespace, regardless which Physical Funtion they belong to. + # Also ignored for SR-IOV, as the pre-allocated Virtual Functions belonging to a configured Kubernetes Device pool are pushed into the connecting Pod's network namespace, regardless which Physical Funtion they belong to. # OPTIONAL - STRING host_device: ## PARENT_DEVICE_NAME ## # Name of a network Device Plugin resource pool @@ -44,13 +43,11 @@ spec: # OPTIONAL - STRING device_pool: ## DEVICE_PLUGIN_RESOURCE_POOL_MAME ## # The IPv4 CIDR notation of the subnet associated with the network. - # Pods connecting to this network will get their IPv4 IP from this subnet, if defined. - # Only has an effect with dynamically integrated backends. Ignored for other NetworkTypes. + # Pods connecting to this network get an IPv4 address to their interface from this subnet. # OPTIONAL - IPv4 CIDR FORMAT (e.g. "10.0.0.0/24") cidr: ## SUBNET_CIDR ## # IPv4 allocation will be done according to the narrowed down allocation pool parameter, if defined. # Allocation pool must be provided together with "cidr", and shall be included in the subnet range. - # Only has an effect with dynamically integrated backends. Ignored for other NetworkTypes. # If CIDR is provided without defining an allocation pool, it is automatically calculated for the whole netmask (minus the first, and the last IP). # The gateway IPs of all the configured IP routes are also automatically reserved from the allocation pool when it is generated. # When the network administrator sets the allocation pool, DANM assumes the non-usable IPs (e.g. broadcast IP, gateway IPs etc.) were already discounted. @@ -59,7 +56,6 @@ spec: end: ## LAST_ASSIGNABLE_IP ## # The IPv6 CIDR notation of the subnet associated with the network. # Pods connecting to this network will get their IPv6s from this subnet, if defined. - # Only has an effect with dynamically integrated backends. Ignored for other NetworkTypes. # OPTIONAL - IPv6 CIDR FORMAT (e.g. "2001:db8::/45"). Netmask of the subnet cannot be higher than /64 (i.e. /65 and upwards). net6: ## SUBNET_CIDR ## # Interfaces connected to this network are renamed inside the Pod's network namespace to a string starting with "container_prefix". diff --git a/schema/TenantNetwork.yaml b/schema/TenantNetwork.yaml index 1168521b..98b2e064 100644 --- a/schema/TenantNetwork.yaml +++ b/schema/TenantNetwork.yaml @@ -5,7 +5,7 @@ apiVersion: danm.k8s.io/v1 # This results in the following characteristics: # - TenantNetworks are expected to be freely provisioned by the user the tenant belongs to # - Cluster specific networking attributes (VLAN ID, VxLAN ID, name of host NICs, backend associated CNI config files) are automatically associated to TenantNetworks based on the configuration provided by the cluster's network administrator -# - Cluster specific networking attributes (VLAN ID, VxLAN ID, name of host NICs, backend associated CNI config files) cannot be set, or changed by the tenant user +# - Cluster specific networking attributes (VLAN ID, VxLAN ID, name of host NICs, backend associated CNI config files) cannot be freely set, or changed by the tenant user # DANM can connect Pods to TenantNetworks of the same tenant (namespace). kind: TenantNetwork metadata: @@ -18,9 +18,9 @@ metadata: spec: # This parameter provides a second identifier for TenantNetworks, and can be used to control a number of API features. # For static delegates, the parameter configures which CNI configuration file is to be used if NetworkType points to a static-level CNI backend. - # For dynamic delegates, VxLAN host interfaces are suffixed, while VLAN host interfaces are prefixed with the NetworkID. + # VxLAN host interfaces are suffixed, while VLAN host interfaces are prefixed with the NetworkID. # This allows deployment administrators to separate their own interfaces from others' in a multi-tenant environment, i.e. by setting NetworkID to "name_namespace" value. - # OPTIONAL - STRING, MAXIMUM 12 CHARACTERS + # OPTIONAL - STRING, MAXIMUM 11 CHARACTERS # IN CASE THE CLUSTER ADMINISTRATOR DEFINED A NETWORKID IN THE USER'S TENANT FOR A SPECIFIC BACKEND, IT WILL OVERWRITE THE USER PROVIDED VALUE. NetworkID: ## NETWORK_ID ## # This parameter, denotes which backend is used to provision the container interface connected to this network. @@ -28,29 +28,35 @@ spec: # - IPVLAN option results in an IPVLAN sub-interface provisioned in L2 mode, and connected to the designated host device # - SRIOV option pushes a pre-allocated Virtual Function of the configured host device to the container's netns # - MACVLAN option results in a MACVLAN sub-interface provisioned in bridge mode, and connected to the designated host device - # Setting this option to another value results in delegating the network provisioning operation to the named backend with static configuration (i.e. most Options are ignored). + # Setting this option to another value results in delegating the network provisioning operation to the named backend with static configuration (i.e. coming from a standard CNI config file). # The default IPVLAN backend is used when this parameter is not specified. # OPTIONAL - ONE OF {ipvlan,sriov,macvlan,} # DEFAULT VALUE: ipvlan NetworkType: ## BACKEND_TYPE ## # Specific extra configuration options can be passed to the network provisioning backends. - # Most of the parameters are only supported for dynamic level backends, such as IPVLAN, MACVLAN, and SRIOV. - # Other network interfaces are always provisioned based on their associated static CNI configuration files. - # The exceptional attributes are "rt_tables", "container_prefix", and "routes/6". DANM universally supports the features related to these parameters for all CNI backends. + # Most of the parameters are generally supported for all network types. + # Options only supported for dynamic level backends, such as IPVLAN, MACVLAN, and SRIOV are explicitly noted. Options: + # Name of the parent host device (i.e. physical host NIC). + # Sub-interfaces are connected to this NIC in case NetworkType is set to IPVLAN, or MACVLAN. + # Only has an effect with dynamically integrated backends. Ignored for other NetworkTypes. + # Also ignored for SR-IOV, as the pre-allocated Virtual Functions belonging to a configured Kubernetes Device pool are pushed into the connecting Pod's network namespace, regardless which Physical Funtion they belong to. + # DANM automatically chooses one of the configured tenant interface profiles when this parameter is left empty. + # If defined, DANM chooses the interface profile with the matching name. If that is not allowed to be used by tenants DANM denies the creation of the network. + # OPTIONAL - STRING + host_device: ## PARENT_DEVICE_NAME ## # Name of a network Device Plugin resource pool # The device_pool parameter generally represents the base resource name of the Kubernetes Devices connected to this network. # This option is mandatory for TenantNetworks with "NetworkType: sriov", and it represents the K8s Virtual Function Device pool connecting Pods are getting their VFs from. + # If defined, DANM chooses the interface profile from the tenant's configuration with the matching name. If that is not allowed to be used by tenants DANM denies the creation of the network. # OPTIONAL - STRING device_pool: ## DEVICE_PLUGIN_RESOURCE_POOL_MAME ## # The IPv4 CIDR notation of the subnet associated with the network. - # Pods connecting to this network will get their IPv4 IP from this subnet, if defined. - # Only has an effect with dynamically integrated backends. Ignored for other NetworkTypes. + # Pods connecting to this network get an IPv4 address to their interface from this subnet. # OPTIONAL - IPv4 CIDR FORMAT (e.g. "10.0.0.0/24") cidr: ## SUBNET_CIDR ## # IPv4 allocation will be done according to the narrowed down allocation pool parameter, if defined. # Allocation pool must be provided together with "cidr", and shall be included in the subnet range. - # Only has an effect with dynamically integrated backends. Ignored for other NetworkTypes. # If CIDR is provided without defining an allocation pool, it is automatically calculated for the whole netmask (minus the first, and the last IP). # The gateway IPs of all the configured IP routes are also automatically reserved from the allocation pool when it is generated. # When the network administrator sets the allocation pool, DANM assumes the non-usable IPs (e.g. broadcast IP, gateway IPs etc.) were already discounted. @@ -58,10 +64,8 @@ spec: start: ## FIRST_ASSIGNABLE_IP ## end: ## LAST_ASSIGNABLE_IP ## # The IPv6 CIDR notation of the subnet associated with the network. - # Pods connecting to this network will get their IPv6 addresses from this subnet, if defined. - # Only has an effect with dynamically integrated backends. Ignored for other NetworkTypes. - # OPTIONAL - IPv6 CIDR FORMAT (e.g. "2001:db8::/45"). - # NOTE: Netmask of the subnet cannot be higher than /64 (i.e. /65 and upwards). + # Pods connecting to this network will get their IPv6s from this subnet, if defined. + # OPTIONAL - IPv6 CIDR FORMAT (e.g. "2001:db8::/45"). Netmask of the subnet cannot be higher than /64 (i.e. /65 and upwards). net6: ## SUBNET_CIDR ## # Interfaces connected to this network are renamed inside the Pod's network namespace to a string starting with "container_prefix". # If not provided, DANM uses "eth" as the prefix. diff --git a/schema/network_attach.yaml b/schema/network_attach.yaml index 2d198a2b..33b65aad 100644 --- a/schema/network_attach.yaml +++ b/schema/network_attach.yaml @@ -23,8 +23,6 @@ spec: # DANM shall be driven with networking related requirements stated in this JSON formatted field. # Each entry listed in danm.k8s.io/interfaces annotation results in a network interface provisioned into every Pod's network namespace created based on this template. # The interface is provisioned via the backend specified in the referenced network object (or with DANM's in-built IPVLAN CNI by default). - # Please note, that some provisioning options are only relevant for specific dynamic level backends. - # For CNIs with only static integration level, Pod-level overwrite options are ignored even if present. # MANDATORY - LIST OF REQUIRED NETWORK INTERFACES # One network connection can have the following attributes: # EXACTLY ONE OF THE FOLLOWING NETWORK IDENTIFIER OPTIONS: @@ -32,15 +30,17 @@ spec: # OPTION2: "tenantNetwork": Name of the TenantNetwork (i.e. ObjectMeta.Name) to which the interface should be connected to. # OPTION3: "clusterNetwork": Name of the ClusterNetwork (i.e. ObjectMeta.Name) to which the interface should be connected to. # "ip": desired IPv4 address assigment scheme. - # Ignored for non-dynamic NetworkTypes. - # OPTIONAL PARAMETER - but either "ip" or "ip6" needs to be present. Presence of either "ip" or "ip6" is MANDATORY + # Mandatory for connecting to networks with dynamic NetowrkTypes, such as IPVLAN, MACVLAN, or SR-IOV. + # Optional for static NetworkTypes. When "ip" is defined for a static network also having Spec.Options.Cidr set, the "ipam" section of its static CNI config file is overwritten by DANM. + # OPTIONAL PARAMETER # Possible values: # - "dynamic": the first free IPv4 address is dynamically allocated from the referenced network's allocation pool # - "## DESIRED_STATIC_IPV4_ADDR_FROM_ALLOCATION_POOL (e.g. "10.10.0.101/24") ##" # - "none": no IPv4 is allocated to the interface # "ip6": desired IPv6 address assigment scheme. - # Ignored for non-dynamic NetworkTypes. - # OPTIONAL PARAMETER - but either "ip" or "ip6" needs to be present. Presence of either "ip" or "ip6" is MANDATORY + # Mandatory for connecting to networks with dynamic NetowrkTypes, such as IPVLAN, MACVLAN, or SR-IOV. + # Optional for static NetworkTypes. When "ip6" is defined for a static network also having Spec.Options.Net6 set, the "ipam" section of its static CNI config file is overwritten by DANM. + # OPTIONAL PARAMETER # Possible values: # - "dynamic": a random, free IPv6 address is dynamically allocated from the referenced network's net6 CIDR # - "## DESIRED_STATIC_IPV6_ADDR_FROM_NET6 ##"