copyright

lastupdated

years
2014, 2018

2017-02-27

{:new_window: target="_blank"} {:shortdesc: .shortdesc} {:screen: .screen} {:pre: .pre} {:table: .aria-labeledby="caption"} {:codeblock: .codeblock} {:tip: .tip} {:download: .download}

Tutorial: Creating clusters

{: #cs_cluster_tutorial}

Deploy and manage a Kubernetes cluster in {{site.data.keyword.containerlong}}. You can automate the deployment, operation, scaling, and monitoring of containerized apps in a cluster. {:shortdesc}

In this tutorial series, you can see how a fictional public relations firm uses Kubernetes capabilities to deploy a containerized app in {{site.data.keyword.Bluemix_notm}}. Leveraging {{site.data.keyword.toneanalyzerfull}}, the PR firm analyzes their press releases and receives feedback.

Objectives

In this first tutorial, you act as the PR firm's networking administrator. You configure a custom Kubernetes cluster that is used to deploy and test a Hello World version of the app.

To set up the infrastructure:

Create a Kubernetes cluster with one worker node
Install the CLIs for running Kubernetes commands and managing Docker images
Create a private image repository in {{site.data.keyword.registrylong_notm}} to store your images
Add the {{site.data.keyword.toneanalyzershort}} service to the cluster so that any app in the cluster can use that service

Time required

40 minutes

Audience

This tutorial is intended for software developers and network administrators who have never created a Kubernetes cluster before.

Prerequisites

A Pay-As-You-Go or Subscription {{site.data.keyword.Bluemix_notm}} account

Lesson 1: Creating a cluster and setting up the CLI

{: #cs_cluster_tutorial_lesson1}

Create your cluster in the GUI and install the required CLIs. {: shortdesc}

To create your cluster:

It can take a few minutes to provision your cluster. To make the most of your time, create your cluster in the GUI before installing the CLIs. For this tutorial, create your cluster in the US East region.

The following CLIs and their prerequisites are used to manage clusters through the CLI:

{{site.data.keyword.Bluemix_notm}} CLI
{{site.data.keyword.containershort_notm}} plug-in
Kubernetes CLI
{{site.data.keyword.registryshort_notm}} plug-in
Docker CLI

To install the CLIs and their prerequisites:

As a prerequisite for the {{site.data.keyword.containershort_notm}} plug-in, install the {{site.data.keyword.Bluemix_notm}} CLI . To run {{site.data.keyword.Bluemix_notm}} CLI commands, use the prefix bx.
Follow the prompts to select an account and an {{site.data.keyword.Bluemix_notm}} organization. Clusters are specific to an account, but are independent from an {{site.data.keyword.Bluemix_notm}} organization or space.
Install the {{site.data.keyword.containershort_notm}} plug-in to create Kubernetes clusters and manage worker nodes. To run {{site.data.keyword.containershort_notm}} plug-in commands, use the prefix bx cs.
```
bx plugin install container-service -r Bluemix
```
{: pre}
To view a local version of the Kubernetes dashboard and deploy apps into your clusters, install the Kubernetes CLI . To run commands by using the Kubernetes CLI, use the prefix kubectl.
1. For complete functional compatibility, download the Kubernetes CLI version that matches the Kubernetes cluster version you plan to use. The current {{site.data.keyword.containershort_notm}} default Kubernetes version is 1.8.8.
  
  OS X: https://storage.googleapis.com/kubernetes-release/release/v1.8.8/bin/darwin/amd64/kubectl
  
  Linux: https://storage.googleapis.com/kubernetes-release/release/v1.8.8/bin/linux/amd64/kubectl
  
  Windows: https://storage.googleapis.com/kubernetes-release/release/v1.8.8/bin/windows/amd64/kubectl.exe
  
  Tip: If you are using Windows, install the Kubernetes CLI in the same directory as the {{site.data.keyword.Bluemix_notm}} CLI. This setup saves you some filepath changes when you run commands later.
2. If you're using OS X or Linux, complete the following steps.
  1. Move the executable file to the /usr/local/bin directory.
```
mv /<path_to_file>/kubectl /usr/local/bin/kubectl
```
    {: pre}
  2. Be sure that /usr/local/bin is listed in your PATH system variable. The PATH variable contains all directories where your operating system can find executable files. The directories that are listed in the PATH variable serve different purposes. /usr/local/bin is used to store executable files for software that is not part of the operating system and that was manually installed by the system administrator.
```
echo $PATH
```
    {: pre}
    
    Your CLI output looks similar to the following.
```
/usr/local/bin:/usr/bin:/bin:/usr/sbin:/sbin
```
    {: screen}
  3. Make the file executable.
```
chmod +x /usr/local/bin/kubectl
```
    {: pre}
To set up and manage a private image repository in {{site.data.keyword.registryshort_notm}}, install the {{site.data.keyword.registryshort_notm}} plug-in. To run registry commands, use the prefix bx cr.
```
bx plugin install container-registry -r Bluemix
```
{: pre}

To verify that the container-service and container-registry plug-ins are properly installed, run the following command:
```
bx plugin list
```
{: pre}
To build images locally and push them to your private image repository, install the Docker CE CLI . If you are using Windows 8 or earlier, you can install the Docker Toolbox instead.

Congratulations! You've successfully installed the CLIs for the following lessons and tutorials. Next, set up your cluster environment and add the {{site.data.keyword.toneanalyzershort}} service.

Lesson 2: Setting up your private registry

{: #cs_cluster_tutorial_lesson2}

Set up a private image repository in {{site.data.keyword.registryshort_notm}} and add secrets to your cluster so that the app can access the {{site.data.keyword.toneanalyzershort}} service. {: shortdesc}

Log in to the {{site.data.keyword.Bluemix_notm}} CLI by using your {{site.data.keyword.Bluemix_notm}} credentials, when prompted.
```
bx login [--sso]
```
{: pre}

Note: If you have a federated ID, use the --sso flag to log in. Enter your user name and use the provided URL in your CLI output to retrieve your one-time passcode.
Set up your own private image repository in {{site.data.keyword.registryshort_notm}} to securely store and share Docker images with all cluster users. A private image repository in {{site.data.keyword.Bluemix_notm}} is identified by a namespace. The namespace is used to create a unique URL to your image repository that developers can use to access private Docker images.

In this example, the PR firm wants to create only one image repository in {{site.data.keyword.registryshort_notm}}, so they choose pr_firm as their namespace to group all images in their account. Replace <your_namespace> with a namespace of your choice that is unrelated to the tutorial.
```
bx cr namespace-add <your_namespace>
```
{: pre}

Before you continue to the next step, verify that the deployment of your worker node is complete.

bx cs workers <cluster_name>

{: pre}

When your worker node is finished provisioning, the status changes to Ready and you can start binding {{site.data.keyword.Bluemix_notm}} services.

ID                                                 Public IP       Private IP       Machine Type   State    Status   Location   Version
kube-mil01-pafe24f557f070463caf9e31ecf2d96625-w1   169.48.131.37   10.177.161.132   free           normal   Ready    mil01      1.8.8

{: screen}

Lesson 3: Setting up your cluster environment

{: #cs_cluster_tutorial_lesson3}

Set the context for your cluster in your CLI. {: shortdesc}

Every time you log in to the container CLI to work with clusters, you must run these commands to set the path to the cluster's configuration file as a session variable. The Kubernetes CLI uses this variable to find a local configuration file and certificates that are necessary to connect with the cluster in {{site.data.keyword.Bluemix_notm}}.

Get the command to set the environment variable and download the Kubernetes configuration files.
```
bx cs cluster-config <cluster_name>
```
{: pre}

When the download of the configuration files is finished, a command is displayed that you can use to set the path to the local Kubernetes configuration file as an environment variable.

Example for OS X:
```
export KUBECONFIG=/Users/<user_name>/.bluemix/plugins/container-service/clusters/pr_firm_cluster/kube-config-prod-par02-pr_firm_cluster.yml
```
{: screen}
Copy and paste the command that is displayed in your terminal to set the KUBECONFIG environment variable.

Verify that the KUBECONFIG environment variable is set properly.

Example for OS X:

echo $KUBECONFIG

{: pre}

Output:

/Users/<user_name>/.bluemix/plugins/container-service/clusters/pr_firm_cluster/kube-config-prod-par02-pr_firm_cluster.yml

{: screen}

Verify that the kubectl commands run properly with your cluster by checking the Kubernetes CLI server version.
```
kubectl version  --short
```
{: pre}

Example output:
```
Client Version: v1.8.8
Server Version: v1.8.8
```
{: screen}

Lesson 4: Adding a service to your cluster

{: #cs_cluster_tutorial_lesson4}

With {{site.data.keyword.Bluemix_notm}} services, you can take advantage of already developed functionality in your apps. Any {{site.data.keyword.Bluemix_notm}} service that is bound to the cluster can be used by any app that is deployed in that cluster. Repeat the following steps for every {{site.data.keyword.Bluemix_notm}} service that you want to use with your apps.

Add the {{site.data.keyword.toneanalyzershort}} service to your {{site.data.keyword.Bluemix_notm}} account.

Note: When you add the {{site.data.keyword.toneanalyzershort}} service to your account, a message is displayed that the service is not free. If you limit your API call, this tutorial does not incur charges from the {{site.data.keyword.watson}} service. Review the pricing information for the {{site.data.keyword.watson}} {{site.data.keyword.toneanalyzershort}} service .
```
bx service create tone_analyzer standard <mytoneanalyzer>
```
{: pre}
Bind the {{site.data.keyword.toneanalyzershort}} instance to the default Kubernetes namespace for the cluster. Later, you can create your own namespaces to manage user access to Kubernetes resources, but for now, use the default namespace. Kubernetes namespaces are different from the registry namespace you created earlier.
```
bx cs cluster-service-bind <cluster_name> default <mytoneanalyzer>
```
{: pre}

Output:
```
bx cs cluster-service-bind <cluster_name> default <mytoneanalyzer>
Binding service instance to namespace...
OK
Namespace:	default
Secret name:	binding-mytoneanalyzer
```
{: screen}
Verify that the Kubernetes secret was created in your cluster namespace. Every {{site.data.keyword.Bluemix_notm}} service is defined by a JSON file that includes confidential information about the service, such as the user name, password and URL that the container uses to access the service. To securely store this information, Kubernetes secrets are used. In this example, the secret includes the credentials for accessing the instance of the {{site.data.keyword.watson}} {{site.data.keyword.toneanalyzershort}} that is provisioned in your account.
```
kubectl get secrets --namespace=default
```
{: pre}

Output:
```
NAME                       TYPE                                  DATA      AGE
binding-mytoneanalyzer     Opaque                                1         1m
bluemix-default-secret     kubernetes.io/dockercfg               1         1h
default-token-kf97z        kubernetes.io/service-account-token   3         1h
```
{: screen}

Great work! You've configured your cluster and your local environment is ready for you to start deploying apps into the cluster.

What's next?

{: #next}

Test your knowledge and take a quiz!
Try the Tutorial: Deploying apps into Kubernetes clusters in {{site.data.keyword.containershort_notm}} to deploy the PR firm's app into the cluster that you created.

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

cs_tutorials.md

cs_tutorials.md

Tutorial: Creating clusters

Objectives

Time required

Audience

Prerequisites

Lesson 1: Creating a cluster and setting up the CLI

Lesson 2: Setting up your private registry

Lesson 3: Setting up your cluster environment

Lesson 4: Adding a service to your cluster

What's next?

Files

cs_tutorials.md

Latest commit

History

cs_tutorials.md

File metadata and controls

Tutorial: Creating clusters

Objectives

Time required

Audience

Prerequisites

Lesson 1: Creating a cluster and setting up the CLI

Lesson 2: Setting up your private registry

Lesson 3: Setting up your cluster environment

Lesson 4: Adding a service to your cluster

What's next?