Service Operations

Services map a port on each cluster node to ports on one or more pods.

The mapping uses a selector key:value pair in the service, and the labels property of pods. Any pods whose labels match the service selector are made accessible through the service's port.

For more information, see the Services Overview.

Before you begin

Follow the directions to:

Set your default Compute Engine zone.
Set your default cluster.
Use gcloud alpha container get-credentials to make your cluster's credentials available to kubectl.

Create a service

Services are created by passing a configuration file to the kubectl create command:

$ kubectl create -f FILE

Where:

-f FILE or --filename FILE is a relative path to a service configuration file in either JSON or YAML format.

A successful service create request returns the service name. You can use a sample file below to try a create request.

Service configuration file

When creating a service, you must point to a service configuration file as the value of the -f flag. The configuration file can be formatted as YAML or as JSON, and supports the following fields:

{
  "id": string,
  "kind": "Service",
  "apiVersion": "v1beta1",
  "selector": {
    string: string
  },
  "containerPort": int,
  "protocol": string,
  "port": int,
  "createExternalLoadBalancer": bool
}

Required fields are:

id: The name of this service.
kind: Always Service.
apiVersion: Currently v1beta1.
selector: The label key:value pair that defines the pods to target.
containerPort The port to target on the pod.
port: The port on the node instances to map to the containerPort.

Optional fields are:

protocol: The Internet protocol to use when connecting to the container port. Must be TCP.
createExternalLoadBalancer: If true, sets up Google Compute Engine network load balancing for your service. This provides an externally-accessible IP address that sends traffic to the correct port on your cluster nodes. To do this, a target pool is created that contains all nodes in the cluster. A forwarding rule defines a static IP address and maps it to the service's port on the target pool. Traffic is sent to clusters in the pool in round-robin order.

You can find the IP address created for your service with the following gcloud command:
```
$ gcloud compute forwarding-rules list
```

Sample files

The following service configuration files assume that you have a set of pods that expose port 9376 and carry the label app=example.

Both files create a new service named myapp which resolves to TCP port 9376 on any pod with the app=example label.

The difference in the files is in how the service is accessed. The first file does not create an external load balancer; the service can be accessed through port 8765 on any of the nodes' IP addresses.

{
  "id": "myapp",
  "kind": "Service",
  "apiVersion": "v1beta1",
  "selector": {
    "app": "example"
  },
  "containerPort": 9376,
  "protocol": "TCP",
  "port": 8765
}

The second file uses Google Compute Engine network load balancing to create a single IP address that spreads traffic to all of the nodes in your cluster. This option is specified with the "createExternalLoadBalancer": true property.

{
  "id": "myapp",
  "kind": "Service",
  "apiVersion": "v1beta1",
  "selector": {
    "app": "example"
  },
  "containerPort": 9376,
  "protocol": "TCP",
  "port": 8765,
  "createExternalLoadBalancer": true
}

To access the service, a client connects to the external IP address, which forwards to port 8765 on a node in the cluster, which in turn accesses port 9376 on the pod. See the Service configuration file section of this doc for directions on finding the external IP address.

View a service

To list all services on a cluster, use the kubectl get command:

$ kubectl get services

A successful get request returns all services that exist on the specified cluster:

NAME    LABELS   SELECTOR    IP              PORT
myapp   <none>   app=MyApp   10.123.255.83   8765

To return information about a specific service, use the kubectl describe command:

$ kubectl describe service NAME

Details about the specific service are returned:

Name:     myapp
Labels:   <none>
Selector: app=MyApp
Port:     8765
No events.

To return information about a service when event information is not required, substitute get for describe.

Delete a service

To delete a service, use the kubectl delete command:

$ kubectl delete service NAME

A successful delete request returns the deleted service's name.

Except as otherwise noted, the content of this page is licensed under the Creative Commons Attribution 3.0 License, and code samples are licensed under the Apache 2.0 License. For details, see our Site Policies.

Last updated May 26, 2015.