Introduction

A Service is an umbrella over a group of pods and policies that define how to access them.

API group	Resource	Kube Skeleton
core/v1	Service	skel

Here's an example Kubernetes Service spec:

kind: Service
apiVersion: v1
metadata:
  name: my-service
spec:
  selector:
    app: MyApp
  ports:
  - protocol: TCP
    port: 80
    targetPort: 9376

The following sections contain detailed information about each field in Short syntax, including how the field translates to and from Kubernetes syntax.

API Overview

Field	Type	K8s counterpart(s)	Description
version	`string`	`apiVersion`	The version of the resource object
cluster	`string`	`metadata.` `clusterName`	The name of the cluster on which this Service is running
name	`string`	`metadata.name`	The name of the Service
namespace	`string`	`metadata.` `namespace`	The K8s namespace this Service will be a member of
labels	`string`	`metadata.labels`	Metadata about the Service, including identifying information
annotations	`string`	`metadata.` `annotations`	Non-identifying information about the Service
cname	`string`	`externalName`	This service will return a CNAME that is set by this field. No proxying will be performed
type	`string`	`type`	The type of the service. Can be omitted (for `cname` services) or set to "cluster-ip", "node-port" or "load-balancer"
selector	`map[string]` `string`	`selector`	A set of key-value pairs that match the labels of pods that should be proxied to
external_ips	`[]string`	`externalIPs`	A set of ip addresses for which nodes in the cluster will accept traffic
port	`string`	`ports`	Unnamed port mapping of format `$PROTOCOL://$SVC_PORT:$CONTAINER_PORT`. More details below
node_port	`int32`	`ports`	Request specific node port for a node-port service
ports	`[]NamedPort`	`ports`	A list of named ports to expose. See Named Port Overview
cluster_ip	`string`	`clusterIP`	Request specific cluster ip for the service
unready_ endpoints	`bool`	`publishNot` `ReadyAddresses`	Publish addresses before backends are ready
route_policy	`string`	`externalTraffic` `Policy`	Policy for routing external traffic. Can be "node-local" or "cluster-wide"
stickiness	`int` or `bool`	`sessionAffinity` and `sessionAffinity` `Config`	Stickiness Policy for the service. More information below
lb_ip	`string`	`loadBalancerIP`	Request specific IP address for the created LB service
lb_client_ips	`[]string`	`loadBalancer` `SourceRanges`	(for LB service) IP addresses to allow traffic from. Can specify CIDR here
healthcheck_ port	`int32`	`healthCheck` `NodePort`	Port for health check

The following fields are status fields, and cannot be set

Field	Type	K8s counterpart(s)	Description
endpoints	`[]string`	`status.loadBalancer.ingress`	A list of hostnames or IP addresses that reflect the ip address/hostname of the created LB

The port and node_port keys are used to specify the unnamed port for the Service. Kubernetes only allows one unnamed port. Therefore, there is only one field for unnamed port. The unnamed port should be of the format

$PROTOCOL://$SERVICE_PORT:$CONTAINER_PORT

The $PROTOCOL is defaulted to tcp if not specified.

If only one port value is specified, then $SERVICE_PORT and $CONTAINER_PORT are considered to be the same value.

The following are valid values for port

port: tcp://8080:80 # Protocol: TCP ServicePort: 8080 ContainerPort: 80
port: 8080:80 # Protocol: TCP ServicePort: 8080 ContainerPort: 80
port: udp://8080 # Protocol: UDP ServicePort: 8080 ContainerPort: 8080

The stickiness values can be set to true or a valid integer value. If set to true, it configures the session affinity of the service based on client ip addresses.

If set to a number value, then, along with configuring the session affinity, it also configures the number of seconds the session affinity sticks to a client ip address, before it expires.

Named Port Overview

Named ports contain a struct that contains two keys

node_port - an int32 type field that denotes a named node_port of the service
$name - a string type field of the format $PROTOCOL://$SERVICE_PORT:$CONTAINER_PORT

The $name key is prefixed with a $ to denote that it can be any valid Kubernetes name, and that will be set as the name of the port. The semantics of the value follow the same behavior as the port field in Service (explained above).

Here are valid named port examples

ports:
- web: 8080:80  # port named "web" with service-port: 8080 and container-port: 80
- db: 8080      # port named "db" with node-port set to 5432
  node_port: 5432  
- dns: udp://53:53
  node_port: 53

Examples

A ClusterIP service with stickiness

service:
  name: web-service
  ports:
  - http: 80:8080 # service-port:container-port
  selector:
    app: web
  stickiness: true
  type: cluster-ip # default value is cluster-ip
  version: v1

A load balancer service with specific endpoints and ingress IPs

service:
  endpoints:
  - aws.elb.jngfdgdgpkdfgk484989485.amazonaws.com
  - 45.54.67.79
  name: lb-service
  ports:
  - http: 80:8080
  route_policy: node-local
  selector:
    app: web
  type: load-balancer
  version: v1

A node port service with a node port chosen

service:
  name: web
  ports:
  - http: 80  # service-port, container-port is same as service-port
    node_port: 32123
  selector:
    app: web
  type: node-port
  version: v1

Skeleton

Short Type	Skeleton
Service	skel

Here's a starter skeleton of a Short Service.

service:
  name: app-service
  port: 80:8080  # service-port:container-port
  selector:
    app: web
  type: cluster-ip
  version: v1