feat: add ingress and ingressClass (#102)

## What type of PR is this?

/kind feature:   add ingress and ingressClass for network module

## Which issue(s) this PR fixes:

Fixes KusionStack/kusion#1306

modules/network/example/dev/example_workspace.yaml

@@ -1,7 +1,7 @@
 modules: 
   network: 
     path: oci://ghcr.io/kusionstack/network
-    version: 0.2.0
+    version: 0.3.0
     configs: 
       default: 
         port: 

modules/network/example/dev/kcl.mod

@@ -3,8 +3,8 @@ name = "example"
 
 [dependencies]
 kam = { git = "https://github.com/KusionStack/kam.git", tag = "0.2.0" }
-service = {oci = "oci://ghcr.io/kusionstack/service", tag = "0.1.0" }
-network = { oci = "oci://ghcr.io/kusionstack/network", tag = "0.2.0" }
+service = { oci = "oci://ghcr.io/kusionstack/service", tag = "0.2.0" }
+network = { oci = "oci://ghcr.io/kusionstack/network", tag = "0.3.0" }
 
 [profile]
 entries = ["main.k"]

modules/network/example/dev/main.k

@@ -3,6 +3,7 @@ import kam.v1.app_configuration as ac
 import service
 import service.container as c
 import network as n
+import network.ingress as ni
 
 nginx: ac.AppConfiguration {
     workload: service.Service {
@@ -16,10 +17,39 @@ nginx: ac.AppConfiguration {
         "network": n.Network {
             ports: [
                 n.Port {
-                    port: 80
-                    public: True
+                    port: 8080
+                    targetPort: 80
+                    public: False
                 }
             ]
+           ingress: {
+               defaultBackend: {
+                    service: {
+                        port: {
+                            number: 8080
+                        }
+                    }
+               }
+               rules: [
+                    {
+                        http: {
+                            paths: [
+                                {
+                                    path: "/"
+                                    pathType: "Prefix"
+                                    backend: {
+                                        service: {
+                                            port: {
+                                                number: 8080
+                                            }
+                                        }
+                                    }
+                                }
+                            ]
+                        }
+                    }
+               ]
+           }
         }
     }
 }

modules/network/ingress/ingress.k

@@ -0,0 +1,47 @@
+schema Ingress:
+    """ Ingress is a collection of rules that allow inbound connections to reach the endpoints defined by a backend.
+    An Ingress can be configured to give services externally-reachable urls, load balance traffic, terminate SSL,
+    offer name based virtual hosting etc.
+
+    Attributes
+    ----------
+    defaultBackend: IngressBackend, default is Undefined, optional.
+        DefaultBackend is the backend that should handle requests that don't match any rule. If Rules are not specified,
+        DefaultBackend must be specified. If DefaultBackend is not set, the handling of requests that do not match any
+        of the rules will be up to the Ingress controller.
+    ingressClassName: str, default is Undefined, optional.
+        IngressClassName is the name of an IngressClass cluster resource. Ingress controller implementations use this
+        field to know whether they should be serving this Ingress resource, by a transitive connection
+        (controller -> IngressClass -> Ingress resource). Although the `kubernetes.io/ingress.class` annotation
+        (simple constant name) was never formally defined, it was widely supported by Ingress controllers to create a
+        direct binding between Ingress controller and Ingress resources. Newly created Ingress resources should prefer
+        using the field. However, even though the annotation is officially deprecated, for backwards compatibility
+        reasons, ingress controllers should still honor that annotation if present.
+    rules: [IngressRule], default is Undefined, optional.
+        Rules is a list of host rules used to configure the Ingress. If unspecified, or no rule matches, all traffic is
+        sent to the default backend.
+    tls: [IngressTLS], default is Undefined, optional.
+        TLS represents the TLS configuration. Currently the Ingress only supports a single TLS port, 443. If multiple
+        members of this list specify different hosts, they will be multiplexed on the same port according to the hostname
+        specified through the SNI TLS extension, if the ingress controller fulfilling the ingress supports SNI.
+    labels: {str:str}, default is Undefined, optional.
+        Labels are key/value pairs that are attached to the workload.
+    annotations: {str:str}, default is Undefined, optional.
+        Annotations are key/value pairs that attach arbitrary non-identifying metadata to the workload.
+    """
+
+    # DefaultBackend is the backend that should handle requests that don't match any rule.
+    defaultBackend?:                 IngressBackend
+
+    # IngressClassName is the name of an IngressClass cluster resource.
+    ingressClassName?:               str
+
+    # Rules is a list of host rules used to configure the Ingress.
+    rules?:                          [IngressRule]
+
+    # TLS represents the TLS configuration.
+    tls?:                            [IngressTLS]
+
+    # Labels and annotations can be used to attach arbitrary metadata as key-value pairs to resources.
+    labels?:                         {str:str}
+    annotations?:                    {str:str}

modules/network/ingress/ingress_backend.k

@@ -0,0 +1,63 @@
+schema IngressBackend:
+    """ IngressBackend describes all endpoints for a given service and port.
+
+    Attributes
+    ----------
+    resource: TypedLocalObjectReference, default is Undefined, optional.
+        Resource is an ObjectRef to another Kubernetes resource in the namespace of the Ingress object. If resource is
+        specified, a service.Name and service.Port must not be specified. This is a mutually exclusive setting with
+        "Service".
+    service: IngressServiceBackend, default is Undefined, optional.
+        Service references a service as a backend. This is a mutually exclusive setting with "Resource".
+    """
+
+    # Resource is an ObjectRef to another Kubernetes resource in the namespace of the Ingress object.
+    resource?:                 TypedLocalObjectReference
+
+    # Service references a service as a backend.
+    service?:                  IngressServiceBackend
+
+    check:
+        not resource or not service, "resource and number are mutually exclusive"
+
+
+schema IngressServiceBackend:
+    """ IngressServiceBackend references a Kubernetes Service as a Backend.
+
+    Attributes
+    ----------
+    name: str, default is Undefined, optional.
+         Name is the referenced service. The service must exist in the same namespace as the Ingress object.
+         If the name is not set, the generated public service name will be used.
+    port: ServiceBackendPort, default is Undefined, optional.
+         Port of the referenced service. A port name or port number is required for a IngressServiceBackend.
+    """
+
+    # Name is the referenced service. The service must exist in the same namespace as the Ingress object.
+    # If the name is not set, the generated public service name will be used.
+    name?:                 str
+
+    # Port of the referenced service. A port name or port number is required for a IngressServiceBackend.
+    port?:                ServiceBackendPort
+
+
+schema ServiceBackendPort:
+    """ ServiceBackendPort is the service port being referenced. A port name or port number is required
+    for a IngressServiceBackend.
+
+    Attributes
+    ----------
+    name: str, default is Undefined, optional.
+        Name is the name of the port on the Service. This is a mutually exclusive setting with "Number".
+    number: int, default is Undefined, optional.
+        Number is the numerical port number (e.g. 80) on the Service. This is a mutually exclusive setting with "Name".
+    """
+
+    # Name is the name of the port on the Service. This is a mutually exclusive setting with "Number".
+    name?:                 str
+
+    # Number is the numerical port number (e.g. 80) on the Service. This is a mutually exclusive setting with "Name".
+    number?:               int
+
+    check:
+        not name or not number, "name and number are mutually exclusive"

modules/network/ingress/ingress_class.k

@@ -0,0 +1,70 @@
+schema IngressClass:
+    """ IngressClass represents the class of the Ingress, referenced by the Ingress Spec. The
+    `ingressclass.kubernetes.io/is-default-class` annotation can be used to indicate that an IngressClass should be
+    considered default. When a single IngressClass resource has this annotation set to true, new Ingress resources
+    without a class specified will be assigned this default class.
+
+    Attributes
+    ----------
+    controller: str, default is Undefined, optional.
+        Controller refers to the name of the controller that should handle this class. This allows for different "flavors"
+        that are controlled by the same controller. For example, you may have different parameters for the same implementing
+        controller. This should be specified as a domain-prefixed path no more than 250 characters in length,
+        e.g. "acme.io/ingress-controller". This field is immutable.
+    parameters: IngressClassParametersReference, default is Undefined, optional.
+        Parameters is a link to a custom resource containing additional configuration for the controller. This is optional
+        if the controller does not require extra parameters.
+    labels: {str:str}, default is Undefined, optional.
+        Labels are key/value pairs that are attached to the workload.
+    annotations: {str:str}, default is Undefined, optional.
+        Annotations are key/value pairs that attach arbitrary non-identifying metadata to the workload.
+    """
+
+    # Controller refers to the name of the controller that should handle this class.
+    controller?:                 str
+
+    # Parameters is a link to a custom resource containing additional configuration for the controller.
+    parameters?:                 IngressClassParametersReference
+
+    # Labels and annotations can be used to attach arbitrary metadata as key-value pairs to resources.
+    labels?:                     {str:str}
+    annotations?:                {str:str}
+
+schema IngressClassParametersReference:
+    """ IngressClassParametersReference identifies an API object. This can be used to specify a cluster or
+    namespace-scoped resource.
+
+    Attributes
+    ----------
+    kind: str, default is Undefined, required.
+        Kind is the type of resource being referenced.
+    name: str, default is Undefined, required.
+        Name is the name of resource being referenced.
+    apiGroup: str, default is Undefined, optional.
+        ApiGroup is the group for the resource being referenced. If APIGroup is not specified, the specified Kind must be
+        in the core API group. For any other third-party types, APIGroup is required.
+    namespace: str, default is Undefined, optional.
+        Namespace is the namespace of the resource being referenced. This field is required when scope is set to "Namespace"
+        and must be unset when scope is set to "Cluster".
+    scope: str, default is Undefined, optional.
+        Scope represents if this refers to a cluster or namespace scoped resource. This may be set to "Cluster" (default)
+        or "Namespace".
+    """
+
+    # Kind is the type of resource being referenced.
+    kind:                 str
+
+    # Name is the name of resource being referenced.
+    name:                 str
+
+    # ApiGroup is the group for the resource being referenced.
+    apiGroup?:            str
+
+    # Namespace is the namespace of the resource being referenced.
+    namespace?:           str
+
+    # Scope represents if this refers to a cluster or namespace scoped resource.
+    scope?:               str
+
+    check:
+        scope in ["Namespace", "Cluster"] if scope, "scope value is invalid"

modules/network/ingress/ingress_rule.k

@@ -0,0 +1,82 @@
+schema IngressRule:
+    """ IngressRule represents the rules mapping the paths under a specified host to the related backend services.
+    Incoming requests are first evaluated for a host match, then routed to the backend associated with the matching IngressRuleValue.
+
+    Attributes
+    ----------
+    host: str, default is Undefined, optional.
+        Host is the fully qualified domain name of a network host, as defined by RFC 3986. Note the following deviations
+        from the "host" part of the URI as defined in RFC 3986: 1. IPs are not allowed. Currently an IngressRuleValue can
+        only apply to the IP in the Spec of the parent Ingress. 2. The : delimiter is not respected because ports are not
+        allowed. Currently the port of an Ingress is implicitly :80 for http and :443 for https. Both these may change in
+        the future. Incoming requests are matched against the host before the IngressRuleValue. If the host is unspecified,
+        the Ingress routes all traffic based on the specified IngressRuleValue.
+        Host can be "precise" which is a domain name without the terminating dot of a network host (e.g. "foo.bar.com")
+        or "wildcard", which is a domain name prefixed with a single wildcard label (e.g. ".foo.com"). The wildcard
+        character '' must appear by itself as the first DNS label and matches only a single label. You cannot have a
+        wildcard label by itself (e.g. Host == "*"). Requests will be matched against the Host field in the following
+        way: 1. If host is precise, the request matches this rule if the http host header is equal to Host. 2. If host is
+        a wildcard, then the request matches this rule if the http host header is to equal to the suffix (removing the
+        first label) of the wildcard rule.
+    http: HTTPIngressRuleValue, default is Undefined, optional.
+        HTTPIngressRuleValue is a list of http selectors pointing to backends. In the example: http:///? -> backend where
+        parts of the url correspond to RFC 3986, this resource will be used to match against everything after the last '/'
+        and before the first '?' or '#'.
+    """
+
+    # Host is the fully qualified domain name of a network host, as defined by RFC 3986.
+    host?:                 str
+
+    # HTTPIngressRuleValue is a list of http selectors pointing to backends.
+    http?:                 HTTPIngressRuleValue
+
+
+schema HTTPIngressRuleValue:
+    """ HTTPIngressRuleValue is a list of http selectors pointing to backends. In the example:
+    http://<host>/<path>?<searchpart> -> backend where where parts of the url correspond to RFC 3986, this resource will
+    be used to match against everything after the last '/' and before the first '?' or '#'.
+
+    Attributes
+    ----------
+    paths: [HTTPIngressPath], default is Undefined, required.
+        Paths is a collection of paths that map requests to backends.
+    """
+
+    # Paths is a collection of paths that map requests to backends.
+    paths:                 [HTTPIngressPath]
+
+
+schema HTTPIngressPath:
+    """ HTTPIngressPath associates a path with a backend. Incoming urls matching the path are forwarded to the backend.
+
+    Attributes
+    ----------
+    backend: IngressBackend, default is Undefined, required.
+        Backend defines the referenced service endpoint to which the traffic will be forwarded to.
+    pathType: str, default is Undefined, required.
+        PathType determines the interpretation of the path matching. PathType can be one of the following values:
+        * Exact: Matches the URL path exactly. * Prefix: Matches based on a URL path prefix split by '/'. Matching is
+        done on a path element by element basis. A path element refers is the list of labels in the path split by the '/'
+        separator. A request is a match for path p if every p is an element-wise prefix of p of the request path. Note
+        that if the last element of the path is a substring of the last element in request path, it is not a match
+        (e.g. /foo/bar matches /foo/bar/baz, but does not match /foo/barbaz).
+        ImplementationSpecific: Interpretation of the Path matching is up to the IngressClass. Implementations can treat
+        this as a separate PathType or treat it identically to Prefix or Exact path types. Implementations are required
+        to support all path types.
+    path: str, default is Undefined, optional.
+        Path is matched against the path of an incoming request. Currently it can contain characters disallowed from the
+        conventional "path" part of a URL as defined by RFC 3986. Paths must begin with a '/' and must be present when
+        using PathType with value "Exact" or "Prefix".
+    """
+
+    # Backend defines the referenced service endpoint to which the traffic will be forwarded to.
+    backend:                 IngressBackend
+
+    # PathType determines the interpretation of the path matching.
+    pathType:                str
+
+    # Path is matched against the path of an incoming request.
+    path?: str
+
+    check:
+        pathType in ["Exact", "Prefix", "ImplementationSpecific"] if pathType, "pathType value is invalid"

modules/network/ingress/ingress_tls.k

@@ -0,0 +1,20 @@
+schema IngressTLS:
+    """ IngressTLS describes the transport layer security associated with an ingress.
+
+    Attributes
+    ----------
+    hosts: [str], default is Undefined, optional.
+        Hosts is a list of hosts included in the TLS certificate. The values in this list must match the name/s used in
+        the tlsSecret. Defaults to the wildcard host setting for the loadbalancer controller fulfilling this Ingress, if
+        left unspecified.
+    secretName: str, default is Undefined, optional.
+        SecretName is the name of the secret used to terminate TLS traffic on port 443. Field is left optional to allow
+        TLS routing based on SNI hostname alone. If the SNI host in a listener conflicts with the "Host" header field used
+        by an IngressRule, the SNI host is used for termination and value of the "Host" header is used for routing.
+    """
+
+    # Hosts is a list of hosts included in the TLS certificate.
+    hosts?:                 [str]
+
+    # SecretName is the name of the secret used to terminate TLS traffic on port 443.
+    secretName?:            str

modules/network/ingress/typed_local_object_reference.k

@@ -0,0 +1,24 @@
+schema TypedLocalObjectReference:
+    """ TypedLocalObjectReference contains enough information to let you locate the typed referenced object inside the
+    same namespace.
+
+    Attributes
+    ----------
+    kind: str, default is Undefined, required.
+        Kind is the type of resource being referenced.
+    name: str, default is Undefined, required.
+        Name is the name of resource being referenced.
+    apiGroup: str, optional.
+        APIGroup is the group for the resource being referenced. If APIGroup is not specified, the specified Kind must
+        be in the core API group. For any other third-party types, APIGroup is required.
+    """
+
+    # Kind is the type of resource being referenced.
+    kind:                      str
+
+    # Name is the name of resource being referenced.
+    name:                      str
+
+    # APIGroup is the group for the resource being referenced. If APIGroup is not specified, the specified Kind must
+    # be in the core API group. For any other third-party types, APIGroup is required.
+    apiGroup?:                 str

modules/network/kcl.mod

@@ -1,3 +1,3 @@
 [package]
 name = "network"
-version = "0.2.1-rc.1"
+version = "0.3.0"