Over a million developers have joined DZone.
Refcard #233

Getting Started with Kubernetes

An open-source orchestration system for managing containerized applications across multiple hosts.

Written by

Arun Gupta VP, Developer Relations, Couchbase

Containers weighing you down? Kubernetes can scale them. In order to run and maintain successful containerized applications, organization is key. Kubernetes is a powerful system that provides a method for managing Docker and Rocket containers across multiple hosts. This Refcard includes all you need to know about Kubernetes including how to begin using it, how to successfully build your first pod and scale intelligently, and more.

Free PDF
Section 1

What is Kubernetes?

Kubernetes (kubernetes.io) is an open-source orchestration system for managing containerized applications across multiple hosts, providing basic mechanisms for the deployment, maintenance, and scaling of applications.

Kubernetes, or “k8s” or “kube” for short, allows the user to declaratively specify the desired state of a cluster using high-level primitives. For example, the user may specify that they want three instances of the Couchbase server container running. Kubernetes’ self-healing mechanisms, such as auto-restarting, re-scheduling, and replicating containers then converge the actual state towards the desired state.

Kubernetes supports Docker and Rocket containers. An abstraction around the containerization layer will allow for other container image formats and runtimes to be supported in the future.

Section 2

Key Concepts of Kubernetes


A Pod is the smallest deployable unit that can be created, scheduled, and managed. It’s a logical collection of containers that belong to an application.

Each resource in Kubernetes is de ned using a configuration file. For example, a Couchbase pod can be defined with the following .yaml file:

 apiVersion: v1
kind: Pod
# labels attached to this Pod
name: couchbase-pod
- name: couchbase
# Docker image that will run in this Pod
    image: couchbase
- containerPort: 8091


A label is a key/value pair that is attached to objects, such as pods. In the previous example, metadata.labels define the labels attached to the pod.

Labels define identifying for the object and is only meaningful and relevant to the user. Multiple labels can be attached to a resource. Labels can be used to organize and to select subsets of objects.

Replication Controller

A replication controller ensures that a specified number of pod replicas are running on worker nodes at all times. It allows both up- and down-scaling the number of replicas. It also ensures recreation of a pod when the worker node reboots or otherwise fails.

A Replication Controller creating two instances of a Couchbase pod can be defined as:

apiVersion: v1
kind: ReplicationController
name: couchbase-controller
# Two replicas of the Pod to be created
replicas: 2
# Identifies the label key and value on the Pod that
    # this Replication Controller is responsible for
app: couchbase-rc-pod
# ‘cookie cutter’ used for creating new pods when
# label key and value on the pod.
# These must match the selector above.
           app: couchbase-rc-pod
- name: couchbase
              image: couchbase
  - containerPort: 8091


Each Pod is assigned a unique IP address. If the Pod is inside a Replication Controller, then the pod is recreated but may be given a different IP address. This makes it dif cult for an application server, such as WildFly, to access a database, such as Couchbase, using its IP address.

A Service defines a logical set of Pods and a policy by which to access them. The IP address assigned to a Service does not change over time, and thus can be relied upon by other Pods. Typically, the Pods belonging to a Service are de ned by a label selector.

For example, a Couchbase service might be defined as:

apiVersion: v1
kind: Service
name: couchbase-service
app: couchbase-service-pod
- port: 8091
# label keys and values of the Pod started elsewhere
app: couchbase-rc-pod

Note that the labels used in selector must match the metadata used for creating the Pod by the Replication Controller.


A Volume is a directory on disk or in another container. A volume outlives any containers that run within the Pod, and the data is preserved across container restarts. The directory, the medium that backs it, and the contents within it are determined by the particular volume type used.

Multiple types of volumes are supported. Some of the commonly used volume types are shown below:

Volume Type Mounts Into Your Pod
hostPath A file or directory from the host node's filesystem
nfs Existing Network File System share
awsElasticBlockStore An Amazon Web Service EBS Volume
gcePersistentDisk A Google Compute Engine Persistent Disk

A Volume is specified in the Pod configuration file as shown:

apiVersion: v1
kind: ReplicationController
name: couchbase-controller
replicas: 1
# In-line template of the Pod
app: couchbase-rc-pod
- name: couchbase-rc-pod
                  image: arungupta/couchbase
  - containerPort: 8091
  # name must match the volume name below
                  - name: nfs
mountPath: /usr/share/couchbase
- name: nfs
  claimName: nfs

This configuration file also shows that a Pod template can be specified within a ReplicationController specification.

Section 3

Kubernetes Architecture

Kubernetes architecture with key components is shown:

Image title

A Kubernetes cluster is a set of physical or virtual machines and other infrastructure resources that are used to run your applications. The machines that manage the cluster are called Master Nodes and the machines that run the containers are called Worker Nodes.


A Node is a physical or virtual machine. It has the necessary services to run application containers.

A Master Node is the central control point that provides a unified view of the cluster. Multiple masters can be setup to create a highly- available cluster.

A Worker Node runs tasks as delegated by the master. Each Worker Node can run multiple pods.


Kubelet is a service running on each Node that manages containers and is managed by the master. This service reads container manifests as YAML or JSON files that describe each Pod. A typical way to provide this manifest is using the configuration file as shown in the previous sections. Kubelet ensures that the containers defined in the Pods are started and continue running.

Kubelet is a Kubernetes-internal concept and generally does not require direct manipulation.

Section 4

Getting Started With Kubernetes

Start the Kubernetes Cluster

A Kubernetes cluster can be started in multiple ways. The most common ones use Vagrant, Amazon Web Service (AWS), Google Compute Engine (GCE), and Azure. This link provides complete details about different options.

The latest Kubernetes release can be downloaded here. This includes the binary to start the cluster and the kubectl script to manage this cluster.

Alternatively, the cluster can also be started as curl -sS https:// get.k8s.io | bash.

The KUBERNETES_PROVIDER environment variable defines which variant to use. A cluster can be started as:


Additional worker nodes can be created by setting the environment variable NUM_MINIONS, for example:

export NUM_MINIONS=6

A cluster can be shut down with:


Variant-specific configurations for Vagrant, Amazon, GCE, and Azure are shown next.

Start the Cluster Using Vagrant

Running Kubernetes with Vagrant is an easy way to run, develop, and test on your local machine.

A Kubernetes cluster using Vagrant can be started with:


By default, the Vagrant will create two Fedora VMs—one for the master node and one for the worker node. The status of the created VMs can be seen using the vagrant status command, for example:

vagrant status
Current machine states:

master running (virtualbox)
minion-1 running (virtualbox)

By default, each VM is assigned 1GB memory. A different number can be assigned by setting the KUBERNETES_MEMORY environment variable, for example:


Complete instructions to run and manage a Kubernetes cluster using Vagrant are available at: kubernetes.io/v1.1/docs/getting-started-guides/ vagrant.html.

Start the Cluster Using AWS

Running Kubernetes with AWS requires:

  • An AWS account
  • Installation and configuration of AWS CLI
  • An AWS instance and profile with EC2 full access Set KUBERNETES_PROVIDER to aws with:

Start and configure the cluster as explained earlier.

By default, the script will provide a new VPC and a 4 node Kubernetes cluster in us-west-2a (Oregon) with t2.micro instances running on Ubuntu. These, and other values, such as memory allotment for Master and Worker node, can be configured in cluster/aws/config-default.sh.

Start the Cluster Using GCE

Running Kubernetes with GCE requires:

Either unset KUBERNETES_PROVIDER or set it to gce as:


Start and configure the cluster as explained earlier.

By default, the script will provision a single Master node and 4 Worker nodes in us-central1-b zone with n1-standard-1 instances running on Debian. These, and other values, such as memory allotment for Master and Worker node, can be configured in cluster/gce/config-default.sh.

Start the Cluster Using Azure

Running Kubernetes with Azure requires:

  • Azure account
  • Installation and configuration of the Azure CLI




Values for these can be obtained using the command azure account show.

Start and configure the cluster as explained earlier.

By default, the script will provision a single Master node and 3 Worker nodes in westus zone with Standard_A1 instances. These, and other values can be configured in cluster/azure/config-default.sh.

Kubectl CLI


is a command-line utility that controls the Kubernetes cluster. This utility can be used in the following format:

kubectl [command] [type] [name] [flags]
  • [command] specifies the operation that needs to be performed on the resource. For example, create, describe, delete, or scale.
  • [type] specifies the Kubernetes resource type. For example, pod, service, replicationcontroller, or node. Resource types are case-sensitive, and you can specify the singular, plural, or abbreviated forms.
  • [name] Specifies the name of the resource. Names are case- sensitive. If the name is omitted, details for all resources will be displayed (for example, kubectl get pods). Some examples of kubectl commands and their purpose:
  • Command Purpose
    kubectl create -f couchbase-pod.yml Create a Couchbase pod
    kubectl create -f couchbase-rc.yml Create a Couchbase Replication Controller
    kubectl get pods List all the pods
    kubectl describe pod couchbase-pod Describe the Couchbase pod
    kubectl --help 

    shows the complete list of available commands.

    Section 5

    Run Your First Container

    A Container can be started on a Kubernetes cluster using the kubectl script. The easiest way to do this is to specify the Docker image name to the run command:

    kubectl.sh run couchbase --image=arungupta/couchbase

    This command will start a pre-configured Couchbase container in a Pod wrapped inside a Replication Controller. The status of this RC can be seen:

    kubectl.sh get rc
      run=couchbase 1 16s

    The status of the Pod can be seen:

     kubectl.sh get po
    couchbase-0s8lx 1/1 Running 0 1m

    Alternatively, the Container can also be started using the configuration file:

    kubectl.sh create -f couchbase-pod.yaml

    The file couchbase-pod.yaml contains the Pod definition as explained earlier.

    Section 6

    Scale Applications

    Pods in a replication controller can be scaled up and down:

    kubectl.sh scale --replicas=3 rc couchbase
    replicationcontroller “couchbase” scaled

    Then the updated number of replicas can be seen:

    kubectl.sh get rc

    Note, the updated number of replicas is 3 here. The image, arungupta/ couchbase in this case, will need to ensure that the cluster can be formed using three individual instances.

    Section 7

    Application Using Multiple Containers

    Typical applications consist of a “frontend” and a “backend.” The “frontend” would typically be an application server, such as WildFly. The “backend” would typically be a database, such as Couchbase.

    Image title

    The steps involved are:

    Start the “backend” Replication Controller: The Couchbase Replication Controller should contain the spec for a Couchbase Pod. The template should include metadata that will be used by the Service.

  • Start the “backend” Service: The Couchbase Service uses the selector to select the previously started Pods.
  • Start the “frontend” Replication Controller: The WildFly Replication Controller should contain the spec for the WildFly pod. The Pod should include the application predeployed. This is typically done by extending WildFly’s Docker image, copying the WAR file in the /opt/jboss/wildfly/standalone/ deployments directory, and creating a new Docker image. The application can connect to the database by discovering “backend” services using Environment Variables or DNS.
  • Section 8

    Namespace, Resource Quotas, and Limits

    By default, all user resources in the Kubernetes cluster are created in a namespace called default. Objects created by Kubernetes are in the kube-system namespace.

    By default, a pod runs with unbounded CPU and memory requests/limits.

    A resource can be created in a different namespace and assigned different memory requests/limits to meet the application’s needs.

    Resources created by the user can be partitioned into multiple namespaces. Resources created in one namespace are hidden from a different namespace. This allows for a logical grouping of resources.

    Each namespace provides:

    • a unique scope for resources to avoid name collisions

    • policies to ensure appropriate authority to trusted users

    • ability to specify constraints for resource consumption

    A new namespace can be created using the following configuration file:

    apiVersion: v1
    kind: Namespace
    name: development
    name: development

    A replication controller in the default namespace can be created:

     kubectl.sh create -f couchbase-rc.yml
     replicationcontroller “couchbase” created

    And a replication controller in the new namespace can be created:

    kubectl.sh --namespace=development create -f couchbase-
    replicationcontroller “couchbase” created

    A list of replication controllers in all namespaces can be obtained:

    kubectl.sh get rc --all-namespaces
    default couchbase couchbase 
    development couchbase couchbase

    Specifying a quota allows you to restrict how much of a cluster’s resources can be consumed across all pods in a namespace.

    Resource quotas can be specified using a configuration file:

    apiVersion: v1
    kind: ResourceQuota
    name: quota
    cpu: “20”
    memory: 1Gi
    pods: “10”
            replicationcontrollers: “20”
            resourcequotas: “1”
            services: “5”

    Now a pod can be created by the specifying limits:

    apiVersion: v1 
    kind: Pod
    name: couchbase-pod
    - name: couchbase
    image: couchbase
    - containerPort: 8091
     cpu: “1”
                 memory: 512Mi

    Namespace, resource quota, and limits allow a Kubernetes cluster to share the resources of multiple groups and provide different levels of QoS for each group.

    Section 9


    Kubernetes docs:


    Kubernetes Issue Tracker:



    • Featured
    • Latest
    • Popular
    Design Patterns
    Learn design patterns quickly with Jason McDonald's outstanding tutorial on the original 23 Gang of Four design patterns, including class diagrams, explanations, usage info, and real world examples.
    211.4k 620.6k
    Core Java
    Gives you an overview of key aspects of the Java language and references on the core library, commonly used tools, and new Java 8 features.
    131.6k 368.4k
    Getting Started with Git
    This updated Refcard explains why so many developers are migrating to this exciting platform. Learn about creating a new Git repository, cloning existing projects, the remote workflow, and more to pave the way for limitless content version control.
    130.4k 296.8k
    Getting Started with Ajax
    Introduces Ajax, a group interrelated techniques used in client-side web development for creating asynchronous web applications.
    102.6k 215.6k
    Foundations of RESTful Architecture
    The Representational State Transfer (REST) architectural style is a worldview that elevates information into a first-class element of architectures. REST allows us to achieve the architectural properties of performance, scalability, generality, simplicity, modifiability, and extensibility. This newly updated Refcard explains main HTTP verbs, describes response codes, and lists libraries and frameworks. It also gives additional resources to further explore each topic.
    103.9k 180.7k
    Spring Configuration
    Catalogs the XML elements available as of Spring 2.5 and highlights those most commonly used: a handy resource for Spring context configuration.
    104.8k 268.4k
    Scrum is a framework that allows people to productively and creatively deliver products of the highest possible value. With over 70% of Agile teams using Scrum or Scrum hybrid, learn more about its benefits in managing complex product development. This newly updated Refcard explores the details of Scrum, including theory, values, roles, and events. It also includes a sample of a popular approach to deliver Integrated Increments in a scaled environment.
    96.6k 258.8k
    Core CSS: Part I
    Covers Core principles of CSS that will expand and strengthen your professional ability to work with CSS. Part one of three.
    91.5k 201.3k
    jQuery Selectors
    Introduces jQuery Selectors, which allow you to select and manipulate HTML elements as a group or as a single element in jQuery.
    94.2k 360.1k
    Core Java Concurrency
    Helps Java developers working with multi-threaded programs understand the core concurrency concepts and how to apply them.
    92k 199.5k
    Getting Started with Eclipse
    Eclipse IDE is a cross-platform, multi-purpose, open-source Integrated Development Environment. It is widely used to develop projects in Java, JavaScript, PHP, C++, Scala, and many others. This newly updated Refcard breaks down installing, setting up, and getting started with Eclipse. It also covers productivity tips, creating new projects and files, accessing Source Control Managers, and debugging configurations.
    80.2k 226.2k
    Core CSS: Part II
    Covers Core principles of CSS that will expand and strengthen your professional ability to work with CSS. Part two of three.
    74.6k 143.3k
    {{ card.title }}
    {{card.downloads | formatCount }} {{card.views | formatCount }}

    Dev Resources & Solutions Straight to Your Inbox

    Thanks for subscribing!

    Awesome! Check your inbox to verify your email so you can start receiving the latest in tech news and resources.


    {{ parent.title || parent.header.title}}

    {{ parent.tldr }}

    {{ parent.urlSource.name }}