IBM Cloud Docs
Getting started with solution tutorials

Getting started with solution tutorials

Solution tutorials provide step-by-step instructions on how to use IBM Cloud to implement common patterns based on best practices and proven technologies.

Before going through the tutorials collection, this guide will help you set up your development environment to successfully follow the instructions of the guides found in this collection.

Objectives

Install must-have tools to be productive with IBM Cloud:

  • IBM Cloud CLI - the command line interface to interact with IBM Cloud API.
  • Docker - to deliver and run software in packages called containers.
  • kubectl - a command line interface for running commands against Kubernetes clusters.
  • oc - manages OpenShift applications, and provides tools to interact with each component of your system.
  • Helm 3 - helps you manage Kubernetes applications — Helm Charts help you define, install, and upgrade even the most complex Kubernetes application.
  • Terraform - automates your resource provisioning.
  • jq - a lightweight and flexible command-line JSON processor.
  • Git - a free and open source distributed version control system.

To avoid the installation of these tools, you can also use the Cloud Shell from the IBM Cloud console.

Microsoft Windows

The following sections assume you are running Microsoft Windows 10 64-bit under a user with Administrator privileges. Once you're done with the specific sections, proceed to the configuration common to all operating systems.

IBM Cloud CLI

  1. Download and install the IBM Cloud CLI from https://github.com/IBM-Cloud/ibm-cloud-cli-release/releases/latest.

  2. Verify the installation with:

    ibmcloud version

    You may need to restart your machine after the installation.

Docker

  1. Docker Desktop on Windows is one option to run container images on Windows. Make sure to review the terms of the license agreement before proceeding with the installation.

  2. If you don't have one, sign up for a free account at https://hub.docker.com/signup.

  3. Download and install Docker Desktop on Windows from https://docs.docker.com/docker-for-windows/install/.

  4. Verify the installation with:

    docker --version
docker run hello-world

    You may need to log out and wait for the Docker daemon to be started.

kubectl

  1. Download kubectl from https://kubernetes.io/docs/tasks/tools/#install-kubectl-on-windows.
  2. Move kubectl.exe binary to your PATH.
  3. Verify the installation with:
    kubectl version --client=true

oc

  1. Download the latest 4.x OpenShift CLI (oc) from https://mirror.openshift.com/pub/openshift-v4/clients/ocp/stable/.
  2. Move oc.exe binary to your PATH.
  3. Verify the installation with:
    oc version

Helm 3

  1. Download helm from https://github.com/helm/helm/releases/latest.
  2. Uncompress the downloaded archive.
  3. Move helm.exe binary to your PATH.
  4. Verify the installation with:
    helm version

Terraform

  1. Download terraform from https://developer.hashicorp.com/terraform/downloads.
  2. Uncompress the downloaded archive.
  3. Move the terraform.exe binary to your PATH.
  4. Verify the installation with:
    terraform version

To manage IBM Cloud resources with Terraform, you also need to install the IBM Cloud Provider. Starting with Terraform 0.13, the provider can be automatically downloaded from Terraform plugin registry. Follow the instructions in the provider documentation to configure the required_providers property in your Terraform templates.

jq

  1. Download jq from https://jqlang.github.io/jq/.
  2. Rename jq-win64.exe to jq.exe.
  3. Move jq.exe binary to your PATH.
  4. Verify the installation with:
    jq --version

Git

  1. Download and install git from https://github.com/git-for-windows/git/releases/latest.
  2. Verify the installation with:
    git --version

Proceed to the configuration common to all operating systems.

Apple macOS

The following sections assume you are running macOS High Sierra or later under a user with Administrator privileges. Once you're done with the specific sections, proceed to the configuration common to all operating systems.

IBM Cloud CLI

  1. Download and install the IBM Cloud CLI from https://github.com/IBM-Cloud/ibm-cloud-cli-release/releases/latest.
  2. Verify the installation with:
    ibmcloud version

Docker

  1. Docker Desktop on Mac is one option to run container images on macOS. Make sure to review the terms of the license agreement before proceeding with the installation. Other options include Podman.
  2. If you don't have one, sign up for a free account at https://hub.docker.com/signup.
  3. Download and install Docker Desktop on Mac from https://docs.docker.com/docker-for-mac/install/.
  4. Verify the installation with:
    docker --version
docker run hello-world

kubectl

  1. Download kubectl from https://kubernetes.io/docs/tasks/tools/#install-kubectl-on-macos.
  2. Make the kubectl binary executable.
    chmod +x ./kubectl
  3. Move the binary to your PATH.
    sudo mv ./kubectl /usr/local/bin/kubectl
  4. Verify the installation with:
    kubectl version --client=true

oc

  1. Download the latest 4.x OpenShift CLI (oc) from https://mirror.openshift.com/pub/openshift-v4/clients/ocp/stable/.
  2. Extract openshift-client-mac.tar.gz (Intel) or openshift-install-mac-arm64.tar.gz (Apple Silicon):
    tar zxvf openshift-client-mac*.tar.gz oc
  3. Move the oc binary to your PATH.
    sudo mv ./oc /usr/local/bin/oc
  4. Verify the installation with:
    oc version
    macOS Catalina and later may prompt you with a message saying the developer cannot be verified. To allow oc to be executed anyway, run sudo xattr -r -d com.apple.quarantine /usr/local/bin/oc.

Helm 3

  1. Download helm from https://github.com/helm/helm/releases/latest.
  2. Uncompress the downloaded archive.
  3. Move the helm binary to your PATH.
    sudo mv ./darwin-amd64/helm /usr/local/bin/helm
  4. Verify the installation with:
    helm version
    macOS Catalina and later may prompt you with a message saying the developer cannot be verified. To allow helm to be executed anyway, run sudo xattr -r -d com.apple.quarantine /usr/local/bin/helm.

Terraform

  1. Download terraform from https://developer.hashicorp.com/terraform/downloads.
  2. Uncompress the downloaded archive.
  3. Move the terraform binary to your PATH.
    sudo mv ./terraform /usr/local/bin/terraform
  4. Verify the installation with:
    terraform version

To manage IBM Cloud resources with Terraform, you also need to install the IBM Cloud Provider. Starting with Terraform 0.13, the provider can be automatically downloaded from Terraform plugin registry. Follow the instructions in the provider documentation to configure the required_providers property in your Terraform templates.

jq

  1. Download jq from https://jqlang.github.io/jq/.
  2. Rename the downloaded file to jq.
  3. Make the jq binary executable.
    chmod +x ./jq
  4. Move the jq binary to your PATH.
    sudo mv ./jq /usr/local/bin/jq
  5. Verify the installation with:
    jq --version
    macOS Catalina and later may prompt you with a message saying the developer cannot be verified. To allow jq to be executed anyway, run sudo xattr -r -d com.apple.quarantine /usr/local/bin/jq.

Git

  1. Check that git is installed:
    git --version
    macOS may prompt you to install the developer tools. These tools include the git command line.

Proceed to the configuration common to all operating systems.

Ubuntu Linux

The following sections assume you are running Ubuntu Linux as non-root user with access to root privileges. Once you're done with the specific sections, proceed to the configuration common to all operating systems. If you are using the Linux-based Cloud Shell, proceed to the section on Cloud Shell.

IBM Cloud CLI

  1. Download and install the IBM Cloud CLI from https://github.com/IBM-Cloud/ibm-cloud-cli-release/releases/latest.
  2. Verify the installation with:
    ibmcloud version

Docker

  1. If you don't have one, sign up for a free account at https://hub.docker.com/signup.
  2. Install Docker Engine on Ubuntu following the instructions from https://docs.docker.com/engine/install/ubuntu/.
  3. Verify the installation with:
    docker --version
sudo docker run hello-world
    To run Docker under your own user instead of root, perfom the post install steps.

kubectl

  1. Download kubectl from https://kubernetes.io/docs/tasks/tools/#install-kubectl-on-linux.
  2. Make the kubectl binary executable.
    chmod +x ./kubectl
  3. Move the binary to your PATH.
    sudo mv ./kubectl /usr/local/bin/kubectl
  4. Verify the installation with:
    kubectl version --client=true

oc

  1. Download the latest 4.x OpenShift CLI (oc) from https://mirror.openshift.com/pub/openshift-v4/clients/ocp/stable/.
  2. Extract openshift-client-linux.tar.gz:
    tar zxvf openshift-client-linux.tar.gz oc
  3. Move the oc binary to your PATH.
    sudo mv ./oc /usr/local/bin/oc
  4. Verify the installation with:
    oc version

Helm 3

  1. Download helm from https://github.com/helm/helm/releases/latest.
  2. Uncompress the downloaded archive.
  3. Move the helm binary to your PATH.
    sudo mv ./linux-amd64/helm /usr/local/bin/helm
  4. Verify the installation with:
    helm version

Terraform

  1. Download terraform from https://developer.hashicorp.com/terraform/downloads.
  2. Uncompress the downloaded archive.
  3. Move the terraform binary to your PATH.
    sudo mv ./terraform /usr/local/bin/terraform
  4. Verify the installation with:
    terraform version

To manage IBM Cloud resources with Terraform, you also need to install the IBM Cloud Provider. Starting with Terraform 0.13, the provider can be automatically downloaded from Terraform plugin registry. Follow the instructions in the provider documentation to configure the required_providers property in your Terraform templates.

jq

  1. Install jq with:
    sudo apt install jq
  2. Verify the installation with:
    jq --version

Git

  1. Install git with:
    sudo apt install git
  2. Verify the installation with:
    git --version

Proceed to the configuration common to all operating systems.

Common to all operating systems

The next sections are common to all operating systems.

IBM Cloud CLI plugins

Plugins extend the capabilities of the IBM Cloud CLI with commands specific to a service.

  1. Install the following plugins:
    ibmcloud plugin install container-registry
ibmcloud plugin install cloud-object-storage
ibmcloud plugin install kubernetes-service
ibmcloud plugin install vpc-infrastructure
ibmcloud plugin install code-engine
    To see all the available plugins, run ibmcloud plugin repo-plugins and to install a plugin ibmcloud plugin install <PLUGIN_NAME>

GitHub account

  1. Sign up for a free account at https://github.com/.
  2. Create a new public repository at https://github.com/new to get familiar with GitHub.

IBM Cloud GitLab

IBM Cloud provides you with hosted Git repositories built on GitLab Community Edition and accessible with the same credentials used to log in IBM Cloud. It is recommended to configure your SSH public key to simplify the command line interactions with the Git repositories.

  1. Use these instructions to generate a new SSH key pair if you don't have one.
  2. Add your SSH public key to your Git settings in the region where you plan to host your Git repositories, such as Dallas (us-south.git.cloud.ibm.com), London (eu-gb.git.cloud.ibm.com) or Frankfurt (eu-de.git.cloud.ibm.com).

To verify the configuration:

  1. Create a new private project in GitLab, select the option to initialize the repository with a README.
  2. Checkout the project from the command line by cloning with the SSH link.
  3. Update the README file.
  4. Commit and push the changes.

Cloud Shell

oc

Follow these steps if you need to use another version of the OpenShift CLI than the one pre-installed:

  1. Download the latest stable 4.x OpenShift CLI (oc)
    curl https://mirror.openshift.com/pub/openshift-v4/clients/ocp/stable/openshift-client-linux.tar.gz --output oc.tar.gz
  2. Extract oc.tar.gz:
    tar zxvf oc.tar.gz oc
  3. Add your current directory to PATH
    export PATH=$PWD:$PATH
  4. Verify the installation with:
    oc version