This the multi-page printable view of this section. Click here to print.

Return to the regular view of this page.

Stateless Applications

1: Exposing an External IP Address to Access an Application in a Cluster
2: Example: Deploying PHP Guestbook application with MongoDB

1 - Exposing an External IP Address to Access an Application in a Cluster

This page shows how to create a Kubernetes Service object that exposes an external IP address.

Before you begin

Install kubectl.
Use a cloud provider like Google Kubernetes Engine or Amazon Web Services to create a Kubernetes cluster. This tutorial creates an external load balancer, which requires a cloud provider.
Configure kubectl to communicate with your Kubernetes API server. For instructions, see the documentation for your cloud provider.

Objectives

Run five instances of a Hello World application.
Create a Service object that exposes an external IP address.
Use the Service object to access the running application.

Creating a service for an application running in five pods

Run a Hello World application in your cluster:

service/load-balancer-example.yaml

apiVersion: apps/v1
kind: Deployment
metadata:
  labels:
    app.kubernetes.io/name: load-balancer-example
  name: hello-world
spec:
  replicas: 5
  selector:
    matchLabels:
      app.kubernetes.io/name: load-balancer-example
  template:
    metadata:
      labels:
        app.kubernetes.io/name: load-balancer-example
    spec:
      containers:
      - image: gcr.io/google-samples/node-hello:1.0
        name: hello-world
        ports:
        - containerPort: 8080

kubectl apply -f https://k8s.io/examples/service/load-balancer-example.yaml

The preceding command creates a Deployment and an associated ReplicaSet. The ReplicaSet has five Pods each of which runs the Hello World application.

Display information about the Deployment:

kubectl get deployments hello-world
kubectl describe deployments hello-world

Display information about your ReplicaSet objects:

kubectl get replicasets
kubectl describe replicasets

Create a Service object that exposes the deployment:

kubectl expose deployment hello-world --type=LoadBalancer --name=my-service

Display information about the Service:
```
kubectl get services my-service
```
The output is similar to:
```
NAME         TYPE           CLUSTER-IP     EXTERNAL-IP      PORT(S)    AGE
my-service   LoadBalancer   10.3.245.137   104.198.205.71   8080/TCP   54s
```
Note: The type=LoadBalancer service is backed by external cloud providers, which is not covered in this example, please refer to this page for the details.
Note: If the external IP address is shown as <pending>, wait for a minute and enter the same command again.

Display detailed information about the Service:

kubectl describe services my-service

The output is similar to:

Name:           my-service
Namespace:      default
Labels:         app.kubernetes.io/name=load-balancer-example
Annotations:    <none>
Selector:       app.kubernetes.io/name=load-balancer-example
Type:           LoadBalancer
IP:             10.3.245.137
LoadBalancer Ingress:   104.198.205.71
Port:           <unset> 8080/TCP
NodePort:       <unset> 32377/TCP
Endpoints:      10.0.0.6:8080,10.0.1.6:8080,10.0.1.7:8080 + 2 more...
Session Affinity:   None
Events:         <none>

Make a note of the external IP address (LoadBalancer Ingress) exposed by your service. In this example, the external IP address is 104.198.205.71. Also note the value of Port and NodePort. In this example, the Port is 8080 and the NodePort is 32377.

In the preceding output, you can see that the service has several endpoints: 10.0.0.6:8080,10.0.1.6:8080,10.0.1.7:8080 + 2 more. These are internal addresses of the pods that are running the Hello World application. To verify these are pod addresses, enter this command:

kubectl get pods --output=wide

The output is similar to:

NAME                         ...  IP         NODE
hello-world-2895499144-1jaz9 ...  10.0.1.6   gke-cluster-1-default-pool-e0b8d269-1afc
hello-world-2895499144-2e5uh ...  10.0.1.8   gke-cluster-1-default-pool-e0b8d269-1afc
hello-world-2895499144-9m4h1 ...  10.0.0.6   gke-cluster-1-default-pool-e0b8d269-5v7a
hello-world-2895499144-o4z13 ...  10.0.1.7   gke-cluster-1-default-pool-e0b8d269-1afc
hello-world-2895499144-segjf ...  10.0.2.5   gke-cluster-1-default-pool-e0b8d269-cpuc

Use the external IP address (LoadBalancer Ingress) to access the Hello World application:
```
curl http://<external-ip>:<port>
```
where <external-ip> is the external IP address (LoadBalancer Ingress) of your Service, and <port> is the value of Port in your Service description. If you are using minikube, typing minikube service my-service will automatically open the Hello World application in a browser.
The response to a successful request is a hello message:
```
Hello Kubernetes!
```

Cleaning up

To delete the Service, enter this command:

kubectl delete services my-service

To delete the Deployment, the ReplicaSet, and the Pods that are running the Hello World application, enter this command:

kubectl delete deployment hello-world

What's next

Learn more about connecting applications with services.

2 - Example: Deploying PHP Guestbook application with MongoDB

This tutorial shows you how to build and deploy a simple (not production ready), multi-tier web application using Kubernetes and Docker. This example consists of the following components:

A single-instance MongoDB to store guestbook entries
Multiple web frontend instances

Objectives

Start up a Mongo database.
Start up the guestbook frontend.
Expose and view the Frontend Service.
Clean up.

Before you begin

You need to have a Kubernetes cluster, and the kubectl command-line tool must be configured to communicate with your cluster. If you do not already have a cluster, you can create one by using minikube or you can use one of these Kubernetes playgrounds:

Your Kubernetes server must be at or later than version v1.14. To check the version, enter kubectl version.

Start up the Mongo Database

The guestbook application uses MongoDB to store its data.

Creating the Mongo Deployment

The manifest file, included below, specifies a Deployment controller that runs a single replica MongoDB Pod.

application/guestbook/mongo-deployment.yaml

apiVersion: apps/v1
kind: Deployment
metadata:
  name: mongo
  labels:
    app.kubernetes.io/name: mongo
    app.kubernetes.io/component: backend
spec:
  selector:
    matchLabels:
      app.kubernetes.io/name: mongo
      app.kubernetes.io/component: backend
  replicas: 1
  template:
    metadata:
      labels:
        app.kubernetes.io/name: mongo
        app.kubernetes.io/component: backend
    spec:
      containers:
      - name: mongo
        image: mongo:4.2
        args:
          - --bind_ip
          - 0.0.0.0
        resources:
          requests:
            cpu: 100m
            memory: 100Mi
        ports:
        - containerPort: 27017

Launch a terminal window in the directory you downloaded the manifest files.

Apply the MongoDB Deployment from the mongo-deployment.yaml file:

kubectl apply -f https://k8s.io/examples/application/guestbook/mongo-deployment.yaml

Query the list of Pods to verify that the MongoDB Pod is running:

kubectl get pods

The response should be similar to this:

NAME                            READY     STATUS    RESTARTS   AGE
mongo-5cfd459dd4-lrcjb          1/1       Running   0          28s

Run the following command to view the logs from the MongoDB Deployment:
```
kubectl logs -f deployment/mongo
```

Creating the MongoDB Service

The guestbook application needs to communicate to the MongoDB to write its data. You need to apply a Service to proxy the traffic to the MongoDB Pod. A Service defines a policy to access the Pods.

application/guestbook/mongo-service.yaml

apiVersion: v1
kind: Service
metadata:
  name: mongo
  labels:
    app.kubernetes.io/name: mongo
    app.kubernetes.io/component: backend
spec:
  ports:
  - port: 27017
    targetPort: 27017
  selector:
    app.kubernetes.io/name: mongo
    app.kubernetes.io/component: backend

Apply the MongoDB Service from the following mongo-service.yaml file:

kubectl apply -f https://k8s.io/examples/application/guestbook/mongo-service.yaml

Query the list of Services to verify that the MongoDB Service is running:

kubectl get service

The response should be similar to this:

NAME           TYPE        CLUSTER-IP   EXTERNAL-IP   PORT(S)    AGE
kubernetes     ClusterIP   10.0.0.1     <none>        443/TCP    1m
mongo          ClusterIP   10.0.0.151   <none>        27017/TCP   8s

Note: This manifest file creates a Service named mongo with a set of labels that match the labels previously defined, so the Service routes network traffic to the MongoDB Pod.

Set up and Expose the Guestbook Frontend

The guestbook application has a web frontend serving the HTTP requests written in PHP. It is configured to connect to the mongo Service to store Guestbook entries.

Creating the Guestbook Frontend Deployment

application/guestbook/frontend-deployment.yaml

apiVersion: apps/v1
kind: Deployment
metadata:
  name: frontend
  labels:
    app.kubernetes.io/name: guestbook
    app.kubernetes.io/component: frontend
spec:
  selector:
    matchLabels:
      app.kubernetes.io/name: guestbook
      app.kubernetes.io/component: frontend
  replicas: 3
  template:
    metadata:
      labels:
        app.kubernetes.io/name: guestbook
        app.kubernetes.io/component: frontend
    spec:
      containers:
      - name: guestbook
        image: paulczar/gb-frontend:v5
        # image: gcr.io/google-samples/gb-frontend:v4
        resources:
          requests:
            cpu: 100m
            memory: 100Mi
        env:
        - name: GET_HOSTS_FROM
          value: dns
        ports:
        - containerPort: 80

Apply the frontend Deployment from the frontend-deployment.yaml file:

kubectl apply -f https://k8s.io/examples/application/guestbook/frontend-deployment.yaml

Query the list of Pods to verify that the three frontend replicas are running:

kubectl get pods -l app.kubernetes.io/name=guestbook -l app.kubernetes.io/component=frontend

The response should be similar to this:

NAME                        READY     STATUS    RESTARTS   AGE
frontend-3823415956-dsvc5   1/1       Running   0          54s
frontend-3823415956-k22zn   1/1       Running   0          54s
frontend-3823415956-w9gbt   1/1       Running   0          54s

Creating the Frontend Service

The mongo Services you applied is only accessible within the Kubernetes cluster because the default type for a Service is ClusterIP. ClusterIP provides a single IP address for the set of Pods the Service is pointing to. This IP address is accessible only within the cluster.

If you want guests to be able to access your guestbook, you must configure the frontend Service to be externally visible, so a client can request the Service from outside the Kubernetes cluster. However a Kubernetes user you can use kubectl port-forward to access the service even though it uses a ClusterIP.

Note: Some cloud providers, like Google Compute Engine or Google Kubernetes Engine, support external load balancers. If your cloud provider supports load balancers and you want to use it, uncomment type: LoadBalancer.

application/guestbook/frontend-service.yaml

apiVersion: v1
kind: Service
metadata:
  name: frontend
  labels:
    app.kubernetes.io/name: guestbook
    app.kubernetes.io/component: frontend
spec:
  # if your cluster supports it, uncomment the following to automatically create
  # an external load-balanced IP for the frontend service.
  # type: LoadBalancer
  ports:
  - port: 80
  selector:
    app.kubernetes.io/name: guestbook
    app.kubernetes.io/component: frontend

Apply the frontend Service from the frontend-service.yaml file:

kubectl apply -f https://k8s.io/examples/application/guestbook/frontend-service.yaml

Query the list of Services to verify that the frontend Service is running:

kubectl get services

The response should be similar to this:

NAME           TYPE        CLUSTER-IP   EXTERNAL-IP   PORT(S)        AGE
frontend       ClusterIP   10.0.0.112   <none>        80/TCP         6s
kubernetes     ClusterIP   10.0.0.1     <none>        443/TCP        4m
mongo          ClusterIP   10.0.0.151   <none>        6379/TCP       2m

Viewing the Frontend Service via `kubectl port-forward`

Run the following command to forward port 8080 on your local machine to port 80 on the service.
```
kubectl port-forward svc/frontend 8080:80
```
The response should be similar to this:
```
Forwarding from 127.0.0.1:8080 -> 80
Forwarding from [::1]:8080 -> 80
```
load the page http://localhost:8080 in your browser to view your guestbook.

Viewing the Frontend Service via `LoadBalancer`

If you deployed the frontend-service.yaml manifest with type: LoadBalancer you need to find the IP address to view your Guestbook.

Run the following command to get the IP address for the frontend Service.

kubectl get service frontend

The response should be similar to this:

NAME       TYPE           CLUSTER-IP      EXTERNAL-IP        PORT(S)        AGE
frontend   LoadBalancer   10.51.242.136   109.197.92.229     80:32372/TCP   1m

Copy the external IP address, and load the page in your browser to view your guestbook.

Scale the Web Frontend

You can scale up or down as needed because your servers are defined as a Service that uses a Deployment controller.

Run the following command to scale up the number of frontend Pods:
```
kubectl scale deployment frontend --replicas=5
```

Query the list of Pods to verify the number of frontend Pods running:

kubectl get pods

The response should look similar to this:

NAME                            READY     STATUS    RESTARTS   AGE
frontend-3823415956-70qj5       1/1       Running   0          5s
frontend-3823415956-dsvc5       1/1       Running   0          54m
frontend-3823415956-k22zn       1/1       Running   0          54m
frontend-3823415956-w9gbt       1/1       Running   0          54m
frontend-3823415956-x2pld       1/1       Running   0          5s
mongo-1068406935-3lswp          1/1       Running   0          56m

Run the following command to scale down the number of frontend Pods:
```
kubectl scale deployment frontend --replicas=2
```

Query the list of Pods to verify the number of frontend Pods running:

kubectl get pods

The response should look similar to this:

NAME                            READY     STATUS    RESTARTS   AGE
frontend-3823415956-k22zn       1/1       Running   0          1h
frontend-3823415956-w9gbt       1/1       Running   0          1h
mongo-1068406935-3lswp          1/1       Running   0          1h

Cleaning up

Deleting the Deployments and Services also deletes any running Pods. Use labels to delete multiple resources with one command.

Run the following commands to delete all Pods, Deployments, and Services.

kubectl delete deployment -l app.kubernetes.io/name=mongo
kubectl delete service -l app.kubernetes.io/name=mongo
kubectl delete deployment -l app.kubernetes.io/name=guestbook
kubectl delete service -l app.kubernetes.io/name=guestbook

The responses should be:

deployment.apps "mongo" deleted
service "mongo" deleted
deployment.apps "frontend" deleted
service "frontend" deleted

Query the list of Pods to verify that no Pods are running:
```
kubectl get pods
```
The response should be this:
```
No resources found.
```

What's next

Complete the Kubernetes Basics Interactive Tutorials
Use Kubernetes to create a blog using Persistent Volumes for MySQL and Wordpress
Read more about connecting applications
Read more about Managing Resources

Stateless Applications

1 - Exposing an External IP Address to Access an Application in a Cluster

Before you begin

Objectives

Creating a service for an application running in five pods

Cleaning up

What's next

2 - Example: Deploying PHP Guestbook application with MongoDB

Objectives

Before you begin

Start up the Mongo Database

Creating the Mongo Deployment

Creating the MongoDB Service

Set up and Expose the Guestbook Frontend

Creating the Guestbook Frontend Deployment

Creating the Frontend Service

Viewing the Frontend Service via kubectl port-forward

Viewing the Frontend Service via LoadBalancer

Scale the Web Frontend

Cleaning up

What's next

Viewing the Frontend Service via `kubectl port-forward`

Viewing the Frontend Service via `LoadBalancer`