Cloud Native Toolkit - Command Line Interface¶

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 console                  Launch the IKS or OpenShift admin console
  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
  igc dashboard                Open the Developer Dashboard in the default
                               browser
  igc enable                   Enable the current repository with pipeline logic
  igc endpoints                List the current ingress hosts for deployed apps
                               in a namespace
                                         [aliases: ingress, endpoint, ingresses]
  igc git-secret [name]        Create a kubernetes secret that contains the url,
                               username, and personal access token for a git
                               repo
  igc git [remote]             Launches a browser to the git repo url specified
                               by the remote. If not provided remote defaults to
                               origin
  igc gitops                   Registers the git repository in the kubernetes
                               cluster as the gitops repository for the given
                               namespace
  igc sync [namespace]         Create a namespace (if it does not exist) and
                               prepare it with the necessary configuration
                                                   [aliases: project, namespace]
  igc pull-secret [namespace]  Copy pull secrets into the provided project from
                               the template namespace
  igc pipeline [gitUrl]        Register a pipeline for the current code
                               repository
  igc tool-config [name]       Create the config map and secret for a tool
                               configured in the environment
  igc vlan                     Print out the vlan values
  igc yq <command>             lightweight yaml command-line processor that
                               addresses deficiencies with the existing `yq`
                               command

Options:
  --version  Show version number                                       [boolean]
  --help     Show help                                                 [boolean]

igc pipeline
kubectl pipeline
oc pipeline

Prerequisite tools¶

Some of the commands provided by the Toolkit CLI orchestrate interactions between other CLIs. To get started please install the prerequisite tools, in particular:

• The Kubernetes CLI
• The Red Hat OpenShift CLI
• The IBM Cloud CLI - used to interact with IBM Cloud vlans (not needed if tools will not run on IBM Cloud)

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¶

igc dashboard

HOST=$(oc get routes/dashboard -n tools -o jsonpath='{.spec.host}')
open "https://$HOST"

The following commands would have the same result on Kubernetes:

HOST=$(kubectl get ingress/developer-dashboard -n tools -o jsonpath='{.spec.rules[0].host}')
open "https://$HOST"

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

console¶

Opens the IKS or OpenShift admin console in the default browser. If a default browser has not been configured, then the URL to the console will be printed out.

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

Usage¶

igc console

open $(oc whoami --show-console)

REGION="..."
CLUSTER_NAME="..."
CLUSTER_ID=$(ibmcloud ks cluster get --cluster ${CLUSTER_NAME} | grep -E "^ID" | sed -E "s/ID: +([^ ]+)/\\1/g")
open "https://${REGION}.containers.cloud.ibm.com/kubeproxy/clusters/${CLUSTER_ID}/service/#/overview?namespace=default"

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

git¶

Opens the Git repo in the default browser for the current working directory. If a default browser has not been configured, then the URL to the repo will be printed out.

Usage¶

igc git

igc git origin-fork

alias gh="open https://github.$(git config remote.origin.url | cut -f2 -d. | tr ':' /)"

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¶

igc credentials

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'
  },
  . . .
}

# config maps
kubectl get configmap -n tools -l grouping=garage-cloud-native-toolkit -o json | \
  jq '[.items[] | select(.metadata.name != "ibmcloud-config").data]'

# secrets
kubectl get secret -n tools -l grouping=garage-cloud-native-toolkit -o json | \
  jq '[.items[] | select(.metadata.name != "ibmcloud-apikey").data | with_entries(.value |= @base64d)]'

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¶

igc endpoints

# routes
kubectl get route -n tools

# ingress
kubectl get ingress -n tools

kubectl get ingress -n tools

sync¶

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 environment.

The command synchronize the ConfigMaps and Secrets from a template namespace (ie tools) 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)

This command copies the 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.

The command will setup the "development" namespace where DevOps pipelines can be run (e.g. myapp-dev)

The "development" namespace will have the ConfigMaps and Secrets copied over.

The command can also add additional privileges to the tekton pipeline service account. These privileges are needed to run the buildah task in OpenShift 4.7

Positionals:
  namespace  The namespace that will be created and/or prepared

Options:
      --version            Show version number                         [boolean]
      --help               Show help                                   [boolean]
  -t, --templateNamespace  the template namespace that will be the source of the
                           config                    [string] [default: "tools"]
  -z, --serviceAccount     the service account that will be used within the
                           namespace               [string] [default: "default"]
  -p, --tekton             flag indicating the tekton pipeline service account
                           should be given privileged scc
      --verbose            flag to produce more verbose logging        [boolean]

Usage¶

igc sync -p myapp-dev

oc sync -p myapp-dev

kubectl sync myapp-dev

  export TEMPLATE_NAMESPACE="tools"
  export NAMESPACE="NAMESPACE"

  kubectl get configmap -l group=catalyst-tools -n ${TEMPLATE_NAMESPACE} -o jsonpath='{ range .items[*] }{ .metadata.name }{ "\n" }{ end }' | \
    while read cm; do
      kubectl get configmap ${cm} --namespace ${TEMPLATE_NAMESPACE} --export -o yaml | \
        kubectl apply --namespace $NAMESPACE -f -
    done

  kubectl get secret -l group=catalyst-tools -n ${TEMPLATE_NAMESPACE} -o jsonpath='{ range .items[*] }{ .metadata.name }{ "\n" }{ end }' | \
    while read cm; do
      kubectl get secret ${cm} --namespace ${TEMPLATE_NAMESPACE} --export -o yaml | \
        kubectl apply --namespace $NAMESPACE -f -
    done

  oc adm policy add-scc-to-user privileged -z pipeline

pull-secret¶

Copy pull secrets into the provided project from the template namespace for the IBM Container Registry.

Set up a service account in the namespace with the pull secret(s) for the IBM Container Registry that are copied.

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.

This command should be use to set up "release" namespaces where applications can be deployed (e.g. test, staging)

Positionals:
  namespace  The namespace into which the pull-secret(s) will be created

Options:
      --version            Show version number                         [boolean]
      --help               Show help                                   [boolean]
  -t, --templateNamespace  the template namespace that will be the source of the
                           config                    [string] [default: "tools"]
  -z, --serviceAccount     the service account that will be used within the
                           namespace               [string] [default: "default"]
      --dev                flag to indicate this is a development namespace and
                           that development artifacts should be created[boolean]
      --verbose            flag to produce more verbose logging        [boolean]

Usage¶

igc pull-secret myapp-test -t default -z default

export NAMESPACE="myapp-test"
export SERVICE_ACCOUNT="default"

if [[ $(kubectl get secrets -n "${NAMESPACE}" -o jsonpath='{ range .items[*] }{ .metadata.name }{ "\n" }{ end }' | grep icr | wc -l | xargs) -eq 0 ]]; then
    echo "*** Copying pull secrets from default namespace to ${NAMESPACE} namespace"

    kubectl get secrets -n default | grep icr | sed "s/\([A-Za-z-]*\) *.*/\1/g" | while read default_secret; do
        kubectl get secret ${default_secret} -n default -o yaml --export | sed "s/name: default-/name: /g" | kubectl -n ${NAMESPACE} create -f -
    done
else
    echo "*** Pull secrets already exist on ${NAMESPACE} namespace"
fi


EXISTING_SECRETS=$(kubectl get serviceaccount/${SERVICE_ACCOUNT} -n "${NAMESPACE}" -o json  | tr '\n' ' ' | sed -E "s/.*imagePullSecrets.: \[([^]]*)\].*/\1/g" | grep icr | wc -l | xargs)
if [[ ${EXISTING_SECRETS} -eq 0 ]]; then
    echo "*** Adding secrets to serviceaccount/${SERVICE_ACCOUNT} in ${NAMESPACE} namespace"

    PULL_SECRETS=$(kubectl get secrets -n "${NAMESPACE}" -o jsonpath='{ range .items[*] }{ "{\"name\": \""}{ .metadata.name }{ "\"}\n" }{ end }' | grep icr | grep -v "${NAMESPACE}" | paste -sd "," -)
    kubectl patch -n "${NAMESPACE}" serviceaccount/${SERVICE_ACCOUNT} -p "{\"imagePullSecrets\": [${PULL_SECRETS}]}"
else
    echo "*** Pull secrets already applied to serviceaccount/${SERVICE_ACCOUNT} in ${NAMESPACE} namespace"
fi

pipeline¶

Connects a branch in a Git repo to a either a Jenkins or Tekton CI pipeline in the 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. Currently, webhook creation is supported for repositories hosted on Gitlab, Github, Github Enterprise, Bitbucket, and Gogs.

This command can either be used to register a git repository that has previously been cloned to the local filesystem OR using the remote repo url.

Repository location¶

The pipeline command supports registering a CI pipeline for a repository that has been cloned locally or using the remote repository url.

Local repository¶

If you are registering a local repository then you must run the command from within the directory of your local clone of the Git repo. When registering a local repository, the pipeline will use the branch that is currently checked out.

Remote repository¶

To register a remote repository, pass the repo url as an argument to the pipeline command. For example:

oc pipeline "https://github.com/my-org/my-repo"

You can optionally provide the branch name with the url using a hash (#):

oc pipeline "https://github.com/my-org/my-repo#my-branch"

Pipeline type¶

The pipeline command supports registering pipelines with either Tekton or Jenkins. The pipeline can be specified from the command-line with either the --tekton or --jenkins flags. If a flag is not provided then you will be prompted to select the pipeline.

Git credentials¶

The command will prompt for the username and password/personal access token to access the Git repository, unless those are already stored in a secret in the cluster namespace or provided as command-line parameters. The username and password can be provided with the -u and -p flags. If you want to change the credentials that have already been stored in the cluster namespace, the -g argument an be provided and you will be prompted for the credentials.

Tekton template pipeline¶

If a Tekton pipeline will be used, a template pipeline must be selected for the new repository pipeline. The command reads the template pipelines available in the template namespace. The template namespace can be provided with the -t argument and will default to tools if not provided. The command will also filter the list of pipelines based on the runtime determined from the given repository.

If there is more than one template pipeline available then you will be prompted to pick one. The template pipeline can also be provided on the command-line using the --pipeline argument. If the name doesn't match an available pipeline then you will be prompted to select one.

Pipeline parameters¶

Once the pipeline template is selected, you will be prompted to provide values for the defined pipeline parameters. The values can also be provided from the command-line using the -p argument. The name of the parameter is listed at the beginning of the prompt message. Multiple parameters can be provided by repeating the -p argument. For example:

oc pipeline --tekton "https://github.com/my-org/my-repo" -p scan-image=false -p edge=false

Optional arguments¶

• -u: the username for accessing the Git repo
• -P: the password or personal access token for accessing the Git repo
• -g: ignore existing git-credentials secret and prompt to update the values
• -p: provide parameters for the pipeline
• --jenkins: deploy using a Jenkins pipeline
• --tekton: deploy using a Tekton pipeline
• --pipeline: the name of the Tekton pipeline
• -n: the deployment namespace; if not provided the namespace from the current context will be used
• -t: the template namespace; if not provided the value will default to tools

oc pipeline --jenkins

oc pipeline -n my-dev -u gituser -P gitpat --tekton

oc project {NAMESPACE}
oc adm policy add-scc-to-user privileged -z jenkins

enable¶

Adds DevOps artifacts to a Git repo that the 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¶

git-secret¶

Creates a kubernetes secret that contains the username and personal access token for a git repo and a config map that contains the url, host, org, repo, and branch for the git repository. The secret is always named git-credentials and the config map is named {git org}.{git repo}. The config map and secret will be created in the currently selected namespace/project, unless a value is passed with the -n flag. If the git-credentials secret already exists then it won't be replaced/updated it won't be updated unless the --replace argument is passed.

Command flags¶

• [positional]: overwrites the name of the config map
• -n: the namespace where the secret and config map should be created. Defaults to the currently selected project/namespace
• -d: the directory where the cloned repository is located. Defaults to the current working directory
• -u: the username for the git secret, If not provided the value will be collected from a prompt
• -p: the personal access token, If not provided the value will be collected from a prompt
• --values: an optional yaml file that contains additional attributes to add to the secret
• --replace: flag indicating that the secret should be replaced/updated if it already exists

Usage¶

==="CLI" The following gives an example of using the git-secret command to set up the config map and secret in the dev namespace

```shell
igc git-secret -n dev
```

gitops¶

Creates a kubernetes secret that contains the username and personal access token for a git repo and a config map that contains the url, host, org, repo, and branch for the git repository. The secret is always named git-credentials and the config map is named gitops-repo. The config map and secret will be created in the currently selected namespace/project, unless a value is passed with the -n flag. If the git-credentials secret already exists then it won't be replaced/updated unless the --replace argument is passed.

Command flags¶

• -n: the namespace where the secret and config map should be created. Defaults to the currently selected project/namespace
• -d: the directory where the cloned repository is located. Defaults to the current working directory
• -u: the username for the git secret, If not provided the value will be collected from a prompt
• -p: the personal access token, If not provided the value will be collected from a prompt
• --values: an optional yaml file that contains additional attributes to add to the secret
• --replace: flag indicating that the secret should be replaced/updated if it already exists

Usage¶

igc gitops -n dev

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¶

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

helm install my-tool tool-config \
  --repo https://ibm-garage-cloud.github.io/toolkit-charts/ \
  --set url=https://mytool-dashboard.mycluster.us-east.containers.appdomain.cloud \
  --set username=admin \
  --set 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¶

igc vlan