Service
Written by
Updated at September 24, 2025
Service represents a Kubernetes service that acts as a backend for Gwin resources. Services are used as backend targets in HTTPRoute, GRPCRoute, TLSRoute, and Ingress resources to distribute incoming traffic within a Kubernetes cluster.
Service is a standard Kubernetes resource. Below, we describe its fields and annotations used by Gwin. For configuration details, see the upstream documentation.
For an alternative approach using CRD instead of annotations, see ServicePolicy.
Cheatsheet
NOTE: Specification provided below is not valid configuration.
It's just demonstration of all Service fields.
apiVersion: v1
kind: Service
metadata:
name: example-service
namespace: example-ns
annotations: # see annotations example below
gwin.yandex.cloud/targets.type: "Node"
gwin.yandex.cloud/targets.ipFamily: "IPv4"
gwin.yandex.cloud/targets.cidrs: "10.0.0.0/8,172.16.0.0/12"
gwin.yandex.cloud/targets.albZoneMatch: "true"
gwin.yandex.cloud/targets.node.onlyWithPods: "true"
gwin.yandex.cloud/targets.node.addressType: "InternalIP"
spec:
type: NodePort # service type for Gwin backends
selector:
app: example-app # pod selector
ports:
- name: http # port name
protocol: TCP # protocol
port: 80 # service port
targetPort: 8080 # container port
nodePort: 30080 # node port
- name: https
protocol: TCP
port: 443
targetPort: 8443
nodePort: 30443
| Field | Description |
|---|---|
| metadata | ServiceMeta Name, namespace and annotations. |
| spec | ServiceSpec Service specification. |
ServiceMeta
Appears in: Service
| Field | Description |
|---|---|
| name | string Name of the Service. |
| namespace | string Namespace of the Service. |
| annotations | map[string]string Annotations of the Service. |
Annotations cheatsheet
NOTE: Specification provided below is not valid configuration.
apiVersion: v1
kind: Service
metadata:
annotations:
# Target configuration
gwin.yandex.cloud/targets.type: "Node" # Node or Pod targets
gwin.yandex.cloud/targets.ipFamily: "IPv4" # IP family for targets
gwin.yandex.cloud/targets.cidrs: "10.0.0.0/8,172.16.0.0/12" # Address filtering
gwin.yandex.cloud/targets.albZoneMatch: "true" # Zone matching
# Node-specific configuration (when targets.type is "Node")
gwin.yandex.cloud/targets.node.onlyWithPods: "true" # Only nodes with pods
gwin.yandex.cloud/targets.node.addressType: "InternalIP" # Address type
Annotations reference
Target Configuration
| Annotation and description |
|---|
gwin.yandex.cloud/targets.type (string) Specifies whether to use Node or Pod endpoints as ALB targets. Node uses cluster nodes as targets (default), Pod uses individual pods as targets. Example: Node |
gwin.yandex.cloud/targets.ipFamily (string) Specifies which IP family to use for target addresses. Currently only IPv4 is supported. Example: IPv4 |
gwin.yandex.cloud/targets.cidrs (string list) Helps select appropriate target addresses when targets have multiple IP addresses. Only addresses within these CIDR blocks will be used for ALB targets. Example: 10.0.0.0/8,172.16.0.0/12 |
gwin.yandex.cloud/targets.albZoneMatch (boolean) Controls whether to verify that targets are located in the same zones as the ALB. When true (default), only targets in ALB zones are included. Example: true |
Node Target Configuration
| Annotation and description |
|---|
gwin.yandex.cloud/targets.node.onlyWithPods (boolean) Controls whether to include only nodes that have pods for this service. When true (default), only nodes running pods that match the service selector are used as targets. Example: true |
gwin.yandex.cloud/targets.node.addressType (string) Specifies which node address type to use for ALB targets. InternalIP uses node's internal IP address (default), ExternalIP uses node's external IP address. Example: InternalIP |
ServiceSpec
Appears in: Service
| Field | Description |
|---|---|
| type | string Type of service. For Gwin backends, must be NodePort. |
| selector | map[string]string Label selector for pods that this service routes to. |
| ports | []ServicePort List of ports exposed by this service. |
ServicePort
Appears in: ServiceSpec
| Field | Description |
|---|---|
| name | string Name of the port. Must be unique within the service. |
| protocol | string Protocol for this port. Must be TCP, UDP, or SCTP. Defaults to TCP. |
| port | int32 Port number exposed by the service. |
| targetPort | int32 or string Port number or name on the pod that traffic should be directed to. |
| nodePort | int32 Port on each node on which this service is exposed when type is NodePort. If not specified, a port will be allocated automatically. |