Skip to main contentIBM Garage for Cloud

Cloud Native Toolkit CLI

The Cloud-Native Toolkit Command Line Interface (CLI)

The IBM Cloud-Native Toolkit includes the IBM Garage for Cloud (IGC) Command Line Interface (CLI). The IGC CLI provides a set of helpful utilities that can be invoked from the command line. It was created to automate and simplify complicated and repetitive tasks, allowing developers to be more productive.

Use of the CLI is in no way required to work with the Cloud-Native Toolkit and everything done by the CLI can be done manually instead. For each of the commands, the equivalent manual steps are also given for the sake of full transparency and to take away any notion of “magic” that the CLI might be performing.

Some of the utilities provided by the CLI include:

  • Register your application’s git repo into a CI pipeline (Jenkins, Tekton, etc.)
  • List the ingress URLs and route URLs defined within the cluster
  • List the connection information (endpoints, user names, and passwords) for the tools configured in the environment
  • Help copy config maps and secrets into new projects/namespace
  • Enable existing Code Patterns with the necessary artifacts to be integrated easily into the Developer Environment

You can either install the CLI onto your computer or install the Cloud Shell Commands environment.

    • Install the CLI:

      npm i -g @ibmgaragecloud/cloud-native-toolkit-cli
    • Verify the version:

      igc --version
  • Follow the instructions in the cloud-shell-commands readme to install the Cloud Shell Commands.

Invoking the CLI

When the CLI is installed, it adds an executable named igc to the PATH. Running igc --help will list the available commands. The output text will be similar to the following:

$ igc --help
IBM Garage Cloud Native Toolkit CLI (https://cloudnativetoolkit.dev)
Usage: igc <command> [args]
Commands:
igc create-webhook Create a git webhook for a given Jenkins pipeline
igc credentials Lists the urls and credentials for the tools deployed
to the cluster

As of v0.5.1, the IGC CLI will now install the commands as plugins to the kubectl and oc CLIs. For example, all of the following are equivalent:

igc pipeline
kubectl pipeline
oc pipeline

Prerequisite tools

Log into your cluster

Most all of the commands provided by the IGC CLI interact with a cluster. It probably comes as no surprise then that you should be logged into the prior to running the commands.

  • oc login --server=<url> --token=<apikey>
  • ibmcloud ks cluster config --cluster <CLUSTER>

Log into your IBM Cloud account

The vlan command provided by the IGC CLI interacts with your IBM Cloud account to get the VLAN information needed to create a cluster. The command assumes you have already logged into your account prior to running the command.

  • Log into your IBM Cloud account with the correct region and resource group:

    ibmcloud login -a cloud.ibm.com -r <region> -g <resource group>

Available commands

dashboard

Opens the Developer Dashboard in the default browser. If a default browser has not been configured, then the URL to the Dashboard will be printed out.

The dashboard displays the Cloud-Native Toolkit tools configured within the cluster along with links to activation content and links to Starter Kits to start a project quickly.

This command requires that the login context for the cluster has already been established.

Command flags

  • -n: the namespace where the dashboard has been deployed; the default is tools

Usage

The command is used in the following way:

igc dashboard

Related commands

  • credentials: shows information about the same tools shown in the dashboard from the command-line
  • tool-config: allows configuration for additional tools to be added to the cluster, making them available to the dashboard and credentials command

credentials

Lists the endpoints, user names, and passwords for the tools configured in the environment. This is the easiest way to get the login credentials for each of the installed tools. Ideally all of the tools would be accessible via SSO at which point this command will be obsolete.

The command works by reading information available in the cluster. When each tool is installed by the toolkit, a config map and secret are created to store the url and credential for the tool. That information is used in a number of different ways within the environment:

  • Provide configuration information to the pipelines
  • Populate the tiles on the Developer Dashboard
  • Populate the results of the credentials command

This command requires that the login context for the cluster has already been established.

Command flags

  • -n: the namespace where the tools have been deployed; the default is tools

Usage

The command is used in the following way:

igc credentials

The credential output is JSON format like this

Credentials: {
argocd: {
user: 'admin',
password: '12345678',
url: 'https://argocd-tools.mycluster.us-east.containers.appdomain.cloud'
},
. . .
dashboard: {
url: 'https://dashboard-tools.mycluster.us-east.containers.appdomain.cloud'

Related commands

  • dashboard: displays the url of the Developer Dashboard and launches the default browser
  • tool-config: allows configuration for additional tools to be added to the cluster, making them available to the dashboard and credentials command

endpoints

Lists the ingress and/or route URLs for the applications in a given namespace. An attempt will be made to get the namespace from the current context if one is not provided as an argument. Results of the command are provided in an interactive menu. If one of the endpoints is selected, it will display the URL and launch it in the default browser. Selecting Exit will print the full list of endpoints and exit.

This command requires that the login context for the cluster has already been established.

Command flags

  • -n: the namespace from which the endpoints will be read; the value will be read from the current context if not provided

Usage

The command is used in the following way:

igc endpoints

sync (formerly namespace)

Creates a Kubernetes namespace or OpenShift project (if it doesn’t already exist) and sets it up so that the namespace can be used as a target for application deployments and/or to host the Developer Environment. The command performs two major functions - 1) set up a service account in the namespace with the pull secret(s) for the IBM Container Registry and 2) synchronize the ConfigMaps and Secrets from a template namespace to create a “development” namespace. After the command has run successfully it will set the provided namespace in the current context (e.g. equivalent to oc project X)

The pull secret(s) are required in order for pods to pull images that are stored in the IBM Container Registry. When the cluster is created in IBM Cloud, a pull secret is provided in the default namespace. In order for a pod in another namespace to use it, the secret must first be copied into the namespace. After that, the pod either needs to reference the pull secret directly or the service account used by the resource needs to have a reference to the secret. The CLI copies the pull secret over and adds it to the service account so the pod can take either approach.

The other function this command performs is to copy relevant ConfigMaps and Secrets into the namespace that are needed for development activities. Managing resources across namespaces (particularly ConfigMaps and Secrets) is a common challenge in Kubernetes environments. We have provided the command at this time to simplify the steps required to get everything ready. Ultimately, this problem seems like an ideal one for an Operator to solve and when one is available (either from the Toolkit or elsewhere) this command will be retired or transitioned.

There are two different types of namespaces that the command will set up:

  • “release” namespace where applications can be deployed (e.g. test, staging)

-OR-

  • “development” namespace where DevOps pipelines can be run and where application components can be deployed (e.g. dev)

Both “release” and “development” namespaces will have the pull secret(s) created. However, only the “development” namespace will also have the ConfigMaps and Secrets copied over.

Command flags

  • -t: the template namespace that will be the source of the config maps and secrets; the default is tools
  • -z: the name of the service account; the default is default
  • --dev: flag indicating the namespace should be set for development
  • --verbose: flag indicating that the console output should persist on the screen

Usage

Create a test namespace

igc sync test

Create a dev namespace for development

igc sync dev --dev

pipeline

Connects a branch in a Git repo to a either a Jenkins or Tekton CI pipeline in the Developer Environment and triggers an initial build. A webhook is also created so that when a new commit is added to the branch, the pipeline is triggered to start the process to rebuild and redeploy the app using the new code. The Git repo needs to be hosted using a site that supports triggers such as GitHub or GitLab.

This command requires that the terminal is already logged in to the cluster. It also requires that the terminal’s current directory is the repository directory for your local copy of the Git repo. The command uses the local Git repo’s configuration to find the server copy.

If Jenkins or Tekton are not specified when the command is invoked then you will be prompted for which CI tool to use. The command will also prompt for the username and personal access token to access the Git repository, unless those are provided as command-line parameters. It will also prompt you for the branch to use to trigger builds; the default is the current branch.

Command flags

  • -n: the deployment namespace; if not provided the namespace from the current context will be used
  • -u: the username for accessing the Git repo
  • -p: the personal access token for accessing the Git repo
  • --jenkins: deploy using a Jenkins pipeline
  • --tekton: deploy using a Tekton pipeline

Usage

Create a Jenkins pipeline in the `dev` namespace and prompt for the Git credentials
igc pipeline --jenkins

Create a Tekton pipeline in the my-dev namespace, using the Git credentials gituser and gitpat

igc pipeline -n my-dev -u gituser -p gitpat --tekton

enable

Adds DevOps artifacts to a Git repo that the Developer Environment uses to deploy the app. The command displays a list of available pipelines and applies the one you select to your code repo. The DevOps files added to your repo include (but are not limited to):

  • Helm chart
  • Jenkinsfile

This command DOES NOT require that the terminal is already logged in to an IBM Cloud account nor the cluster. It DOES require that the terminal’s current directory is the repository directory for your local copy of the Git repo.

The command will add files to the local repo. You should commit these new files and push them to the server repo. Then run igc pipeline to connect your repo to a pipeline in the environment.

Command flags

  • --repo: the set of pipelines to choose from; the default is https://github.com/ibm-garage-cloud/garage-pipelines
  • -p: the name of the pipeline that should be installed; if not provided then you will be prompted
  • -b: the branch from which the pipeline should be installed; the default is stable
  • r: the version number of the pipeline that should be installed; the default is latest

Usage

  1. Before running the command, make sure you have a clean repository with no unstaged changes. Either commit any changes or stash them temporarily with git stash. It is particularly important that any changes to the pipeline be dealt with.

  2. Apply the pipeline updates using the CLI command

igc enable
  1. Review the changes using git diff and revert any application-specific changes that should remain (e.g. customization to the Jenkins pipeline in the Jenkinsfile, specific values added to values.yaml, customizations to the templates in the helm chart)

  2. Commit the changes when you are happy with them

tool-config

Configures a new tool in the environment. After deploying the tool, use this command to add the tool to the list of credentials so that it will be displayed in the dashboard.

Command flags

  • The name for the tool
  • -n: the tools namespace; the default is tools
  • --url: the endpoint for accessing the tool, usually its dashboard
  • --username: (optional) the user name for logging into to tool
  • --password: (optional) the password for logging into to tool

Usage

The following gives an example of using the tool-config command to set up a tool named my-tool with its dashboard’s endpoint and credentials

igc tool-config my-tool \
--url https://mytool-dashboard.mycluster.us-east.containers.appdomain.cloud \
--username admin \
--password password

vlan

Lists the VLANs for a particular IBM Cloud region. This information is useful for preparing Terraform cluster creation steps. The command reads all the data centers in the region and allows you to select the appropriate data center for the vlan.

This command requires that the terminal is already logged in to the cloud region. It does NOT need to be logged in to a cluster.

Usage

List a pair of public/private VLANs for a new environment to use

igc vlan