Contents


Get started with Docker and Kubernetes

Learn how to use Docker containers and Kubernetes clusters, the building blocks of the next generation of DevOps

Comments

Docker and Kubernetes are two of the hottest technologies in the world of IT. This tutorial will get you up and running with both technologies in the IBM Cloud. Best of all, you can do everything here in your free IBM Cloud Lite account (see sidebar).

This tutorial will show you how to:

  1. Get the sample code and install the tools you'll need
  2. Build a Docker image and run it on your local machine
  3. Create a Kubernetes cluster in the IBM Cloud
  4. Create a Docker image in the IBM Cloud
  5. Deploy the Docker image to your Kubernetes cluster

Getting the sample code

To get started, clone the Github repo that contains the sample code. The app you'll deploy is nothing more than a "Hello World" page combined with a Dockerfile that builds the app into a Docker image. The sample code is at github.com/IBM/dWTVSimpleContainerApp.

The home page for the dWTVSimpleContainerApp repo

The home page for the dWTVSimpleContainerApp repo

At the command line, type git clone https://github.com/IBM/dWTVSimpleContainerApp.git to clone the repo, then change to the directory of the cloned repo (cd dWTVSimpleContainerApp):

Cloning the github repo

Cloning the github repo

Now that you have the sample code installed on your machine, you're ready to install the tools you'll need as you take over the world of containers and clusters.

Before we continue...

By law, any article that discusses containers must include a picture of a container ship loaded down with ... well, containers. So here you go:

A container ship in the middle of the                 ocean, being eaten by a giant                 squid

A container ship in the middle of the ocean, being eaten by a giant squid

We hope you enjoyed this compulsory diversion.

Installing the required tools

Before you can run docker build or do anything else with Docker and Kubernetes, you'll need to install the tools for IBM Cloud, Docker, and Kubernetes.

Installing the IBM Cloud tools

Go to console.bluemix.net/docs/cli/index.html#downloads and click the Download link to get the latest version of the IBM Cloud tools. Download the tools for your platform and run the installer.

The IBM Cloud                 tools download page

The IBM Cloud tools download page

Note: For historical reasons, the command to work with IBM Cloud resources is bluemix. You may be concerned that typing seven whole characters for every command will be exhausting. Worry not, friends: We've abbreviated the command to bx. You'll find this shortcut will save you hours of typing each day, freeing you to spend more time with family and friends, re-devote yourself to long-neglected hobbies, or perhaps take a second job to make ends meet.

You're welcome.

Installing Docker

The next step is to install Docker and its associated command-line tools. Go to docker.com and click the Get Docker link:

Downloading the Docker tools from                 docker.com

Downloading the Docker tools from docker.com

Download and install Docker Community Edition. Depending on your platform, you may get a message that you need to reboot your system before continuing. Wait until you've installed the Kubernetes tools before doing that.

Installing the Kubernetes tools

Although you won't use Kubernetes until later in this article, you might as well install the kubectl tool now. Go to kubernetes.io/docs/tasks/tools/install-kubectl/ and install kubectl according to the instructions for your platform.

Installing kubectl

Installing kubectl

When you create a cluster in the IBM Cloud, you'll configure kubectl to work with your cluster ... but there are a few steps you'll need to go through first. For now, just install the command.

Logging in to the IBM Cloud

At this point, you should have all of the IBM Cloud, Docker, and Kubernetes tools installed, and you've rebooted your machine if necessary. The next step is to log in to your IBM Cloud account. At the command line, type bx login to log in:

Logging in to the IBM Cloud

Logging in to the IBM Cloud

Once you've logged in to the IBM Cloud, you need to install the plugins for the IBM Container Service and the IBM Container Registry. Type the following commands:

  • bx plugin install container-service -r Bluemix
  • bx plugin install container-registry -r Bluemix
  • bx cr login

The first two commands install the plugins for the container service and the container registry from the Bluemix repository. The last command logs you in to the container registry service. This lets you access Docker images in the public registry of the IBM Cloud.

Using Docker images and containers on your machine

Starting Docker

Now it's time to start building things. First, you need to start Docker on your machine. How you do that, of course, depends on your platform.

Windows

Double-click the desktop icon:

Docker                 desktop icon on Windows

When Docker is up and running, you'll see a message in the lower right-hand corner of your desktop:

Docker                 'up and running' message on Windows

Docker 'up and running' message on Windows

Mac

Click the desktop icon:

Docker desktop             icon on the Mac

Docker desktop icon on the Mac

When Docker is up and running, clicking the Docker icon in the menu bar shows this comforting status message:

Docker 'up                 and running' status on the Mac

Docker 'up and running' status on the Mac

Linux

Starting Docker on Linux can vary from one distribution to another, but you'll typically run one of these two commands:

  • sudo systemctl start docker
  • sudo service docker start

If you're having trouble starting Docker on Linux, see the Docker documentation for more information.

Building a Docker image

With Docker up and running, it's time to build the image that contains your app. The repo you cloned earlier contains a Dockerfile that tells Docker how to build the image. The file looks like this:

FROM ibmcom/ibmnode:latest

RUN mkdir -p /usr/src/app
WORKDIR /usr/src/app

COPY package.json /usr/src/app
RUN npm install

EXPOSE 6006

COPY . /usr/src/app

CMD ["node", "app.js"]

Here is a brief explanation of the commands in the file:

  • Line 1: This tells Docker that the image will be based on the latest IBM node.js image. (You can access this image because you ran the bx cr login command earlier.)
  • Lines 3 and 4: This creates the directory /usr/src/app and tells Docker to use that as the working directory.
  • Lines 6 and 7: Copies the package.json file to the working directory and runs the npm install command to install all of your app's dependencies.
  • Line 9: Tells Docker to open port 6006 to incoming traffic. The app listens for connections on this port.
  • Line 11: Copies all of the files in the current directory to the working directory.
  • Line 13: Tells Docker what command to run when the image starts. The first parameter is the command, the second is the list of arguments for that command. When this image starts, Docker runs node app.js.

Go to the command line and run the command docker build -t basicapp:v1 . (The period there is part of the command; it tells Docker to do its work in the current directory.) You'll see something like this:

Results of the                 docker build command

Results of the docker build command

Your results will vary. In this screen capture, the node.js image already exists on the system, so there are lots of things that Docker doesn't have to download. The first time you run docker build on your machine, none of the dependencies your image needs will be on your machine, so Docker will have to download them. Subsequent calls to docker build will probably work much faster. Also notice that the npm install command hasn't finished running in this example.

Running a Docker image on your machine

You're no doubt tingling with excitement already, what with having built your first Docker image and all that, but let's move on and actually run that image. At the command line, type docker create basicapp:v1 to create a container from your image:

Creating a Docker             container from a Docker image

Creating a Docker container from a Docker image

Um, not terribly exciting, is it? You ran a command and got a long hex string that probably means something, although it's not clear what that might be. Fortunately, the Docker community has some great tools that make it easy to work with Docker containers. If you're running on Windows or the Mac, use the awesome Kitematic tool. Start it from the system tray on Windows or the menu bar on the Mac:

Starting Kitematic                 on Windows or the Mac

Starting Kitematic on Windows or the Mac

Note: As of this writing, Kitematic requires a separate install on Windows. Check the Docker documentation for instructions.

When Kitematic starts, you'll see a display similar to this one:

The main Kitematic             screen

The main Kitematic screen

There are tiles for various Docker images in the dockerhub catalog. If you'd like to set up Jenkins or PostgreSQL or Minecraft or other software, you can easily do that with these images. The interesting thing here is in the upper left-hand corner: It's a list of all the containers running on your machine. Each one has a randomly assigned name. In this screen capture, the container is named unruffled_swirles—much more memorable than the long string of hex characters you saw at the command line a minute ago.

At this point, you have a Docker container running on your machine. It has the basic Hello World app running inside it, but how do you access that app? To do that, you'll have to define a port for the app. Docker will map incoming requests for the port number you define to port 6006 in your container. (Recall the EXPOSE 6006 command in the Dockerfile.) Click the Settings menu in the upper right, then click Ports:

The Ports menu                 beneath the Settings menu

The Ports menu beneath the Settings menu

You'll see a display that lets you map the port 6006 in your Docker container to a port on your machine. Here's how to use port 32008:

Mapping a Docker                 port to a port on localhost

Mapping a Docker port to a port on localhost

Click Save to save the mapping, then go to http://localhost:32008 in your browser. You'll see the Hello World app up and running:

The Hello World app             running in a Docker container

The Hello World app running in a Docker container

Congratulations! You've successfully built a Docker image, deployed it to your machine, and configured the Docker runtime so that you can access the app running in the Docker container from a browser.

For Linux, as of this writing Kitematic for Linux does not exist. For similar functionality, try Portainer:

The Portainer                 console

The Portainer console

Portainer is packaged as a Docker image, so the installation process is nothing more than asking Docker to download and run that image. See portainer.io for all the details.

Creating a Kubernetes cluster in the IBM Cloud

The ultimate goal here is to deploy an app running in a Docker container to a Kubernetes cluster. It takes a few minutes for a cluster to get up and running, so go ahead and create the cluster now. You'll do the Docker deployment later. From the IBM Cloud console, go to the menu in the upper left-hand corner and click Containers:

The Containers menu                 item

The Containers menu item

Next, click the Create cluster button in the middle of the page:

The 'Create cluster'                 button

The 'Create cluster' button

Finally, give your cluster a name (in the example below, the cluster is named "Mailbag") and make sure you've checked the Lite plan (aka the free plan), then click the Create Cluster button on the right-hand side of the panel:

The cluster creation             panel

The cluster creation panel

It may take several minutes for the cluster to be provisioned and started. While that's happening, go ahead and build the Docker image that you'll deploy to the cluster.

Creating a Docker image in the IBM Cloud

You've created a Docker image on your local machine, which is great, but you need to get that image into the IBM Cloud before you can deploy it to a Kubernetes cluster. (Make sure you've logged in to the IBM Cloud image repository with the bx cr login command before you go forward.) First, define a namespace for your images. As an example, to create the mailbag namespace, enter this command:

bx cr namespace-add mailbag

Namespaces allow you to create groups of Docker images in your IBM Cloud account. You can't create or upload a Docker image until you have a namespace. Your results should look like this:

Defining a namespace                 for Docker images

Defining a namespace for Docker images

Now you need to get your Docker images into your container repository in the IBM Cloud. You can do that in one of two ways: build the image directly in the cloud or push an existing image into the cloud. Here are the instructions for each approach:

Building a Docker image in the IBM Cloud

You can use the bluemix command to create an image in the cloud. Type bx cr build -t registry.ng.bluemix.net/mailbag/basicapp:v1 . (Be sure to include the period at the end of the command.)

The command to                 build a Docker image in the IBM Cloud

The command to build a Docker image in the IBM Cloud

The output of this command is similar to the docker build command:

Output from the                 Bluemix Docker build command

Output from the Bluemix Docker build command

The bx cr build command automatically pushes the new image into your image repository. You can type bx cr images to ensure that your image was created and is in the IBM Cloud:

The Docker image is                 built and stored under the mailbag namespace

The Docker image is built and stored under the mailbag namespace

Pushing an existing Docker image into the IBM Cloud

If you want to take a Docker image that you've already built and push it into the cloud, use these two Docker commands:

  1. docker tag basicapp:v1 registry.ng.bluemix.net/mailbag/basicapp:v2
  2. docker push registry.ng.bluemix.net/mailbag/basicapp:v2

Your results should look like this:

Tagging a                 Docker image and pushing it into the IBM Cloud

Tagging a Docker image and pushing it into the IBM Cloud

Note: This example uses the tag v2 on the assumption that you already have a v1 image in your repository, created by the command in the previous section. Creating two tags (v1 and v2) gives you two versions of the same image. As before, typing bx cr images lists the Docker images in your repository.

Configuring the kubectl command

You'll use a combination of bx and kubectl commands to deploy the image as a container running in the cluster and to expose the container to the world. Before you can run these commands, you need to configure the kubectl command to work with your cluster running in the IBM Cloud. Here are the commands you'll run, along with an explanation of each:

  1. bx cs cluster-config Mailbag
    This uses the Bluemix container service plugin to get the configuration details of the Mailbag cluster you created earlier. It returns a command that you can copy and paste to set the KUBECONFIG environment variable.
  2. [Set the KUBECONFIG variable]
    This command is in the output from the previous command. It is an export statement on Linux and the Mac, and a set command in the Windows command line; it returns the information you need for an $env:KUBECONFIG definition in Windows PowerShell.

These two commands look like this on Linux or the Mac:

Defining the                 KUBECONFIG environment variable

Defining the KUBECONFIG environment variable

(Notice that the export command is merely a cut and paste of the output of the bx cs cluster-config command.)

Once KUBECONFIG is set, any kubectl commands you run automatically affect your cluster running in the IBM Cloud.

Deploying a Docker image to your Kubernetes cluster

At this point, the Docker image you want to deploy is in the IBM Cloud, your Kubernetes cluster is up and running, and the kubectl command is configured to work with your cluster.

It's showtime!

You're only four commands away from victory. Here they are:

  1. kubectl run apptest --image=registry.ng.bluemix.net/mailbag/basicapp:v1
    This starts the Docker image basicapp:v1 from your IBM Cloud container repository in the cluster. It creates a Kubernetes deployment named apptest.
  2. kubectl expose deployment/apptest --type=NodePort --name=apptest-service --port=6006
    This longwinded command exposes the apptest deployment as a NodePort named apptest-service running on port 6006. (We'll talk about NodePorts some other time; suffice to say it's your only option with a free cluster.) At this point, the deployment is created and the service is exposed: Creating a deployment and exposing a service
    Creating a deployment and exposing a service
  3. kubectl describe service apptest-service
    This displays a variety of useful information about the service you just exposed. Amongst other things, it displays the randomly assigned port number that Kubernetes gave to this service: The                         randomly assigned port number for your service
    The randomly assigned port number for your service
  4. bx cs workers Mailbag
    Finally, you need to get the IP address of the Kubernetes cluster itself. This command returns that information: The IP address of                 the Kubernetes cluster
    The IP address of the Kubernetes cluster

Drum roll please: Now that you know the IP address of the cluster and the port number of the service, you can combine the two in your browser and see Hello World in all its glory:

The Hello World                 application running in a Docker container running in a Kubernetes                 cluster

The Hello World application running in a Docker container running in a Kubernetes cluster

You've deployed your Docker image to a Kubernetes cluster running on the web. The Hello World application is worldwide; anyone anywhere can access it. Try to remain humble as you bask in the glory of your accomplishments here.

Summary

At this point you're completely ready to take over the world of containers and clusters. You know how to build a Docker image, how to push it to the IBM Cloud, and how to deploy it in a Kubernetes cluster. The app running in the Docker container in your cluster is live on the web, so anyone in the world can behold your handiwork. There are plenty more things to master (handling credentials inside a cluster, for example), but you're off to a solid start.


Downloadable resources


Related topics


Comments

Sign in or register to add and subscribe to comments.

static.content.url=http://www.ibm.com/developerworks/js/artrating/
SITE_ID=1
Zone=Cloud computing, DevOps
ArticleID=1056644
ArticleTitle=Get started with Docker and Kubernetes
publish-date=01162018