Check out what's in the latest release of Kabanero Learn More

Managing stacks with the command-line interface (CLI)

The stack management CLI is a command-line interface used by the enterprise, solution, or application architect who defines and manages the application stacks. Developers use these stacks to create governed applications for their business.

Installing the stack management CLI

  1. Download the archive corresponding to the platform you are running on.

    • Latest CLI release

    • Latest CLI release - If you are using Homebrew, you can use the brew install kabanero-io/kabanero/kabanero command to do a brew install of the latest version

    • All CLI releases

  2. Extract the archive. The archive holds the ./kabanero command, which is ready to be used.

    • Test the installation by running the ./kabanero help command and viewing the help output.

  3. Configure the CLI service. To do this, follow the steps outlined in the following documentation:

  4. Optional - Add the path to the kabanero command to your PATH environment variable so that you can use the kabanero command without specifying the path each time.

Monitoring and administration commands

Login

Use the stack management CLI URL to log in. There are two ways you can get this URL:

  1. View the CLI URL in the landing page instance details.

  2. Log in to your cluster and run: oc get routes -n kabanero. The URL is for the kabanero-cli route.

Run the kabanero login command to authenticate.

Example login commands:

kabanero login <SM_CLI_URL> -u <GITHUB_USER_ID>
kabanero login <SM_CLI_URL> -u <GITHUB_USER_ID> --insecure-skip-tls-verify=true
kabanero login <SM_CLI_URL> -u <GITHUB_USER_ID> --p <GITHUB_PAT> --certificate-authority "<LOCAL_CERT_LOCATION>"
  • <SM_CLI_URL> is your stack management CLI URL from above

  • <GITHUB_USER_ID> is your GitHub user name

  • <GITHUB_PAT> is your GitHub Personal Access Token or your GitHub password

    • Your PAT must have the read:org - Read org and team membership, read org projects OAuth Scope allowed. You can select this when creating your PAT in GitHub

    • When you log in to an instance by using GitHub credentials, a temporary access token is stored in a your-home-directory/.kabanero/config.yaml file for subsequent command-line calls.

  • <LOCAL_CERT_LOCATION> is the path to a file containing a TLS certificate

    • To get the certification, run: openssl s_client -connect <SM_CLI_URL>:443 -servername <SM_CLI_URL>

    • Copy the content from -----BEGIN CERTIFICATE----- to -----END CERTIFICATE ----- (including these two lines) and paste it into a new file with a filename of your choice. Pass this filename and location to the login command using the --certificate-authority option.

Note: if you do not use either the --certificate-authority or --insecure-skip-tls-verify=true options, you are prompted to confirm that want to proceed with an insecure connection:

kabanero login <SM_CLI_URL> -u <username>
Password:
Are you sure you want to continue with an insecure connection to <SM_CLI_URL> (y/n):

Complete list of flags:

--certificate-authority string    Path to a certificate file for the certificate authority
-h, --help                        Help for login
--insecure-skip-tls-verify        If set to true, the server's certificate will not be checked for validity; the HTTPS connection is insecure
-p, --password string             GitHub password or PAT; if not provided, a prompt appears
-u, --username string             GitHub username

Onboard a developer (Removed)

The kabanero onboard command was removed and is not available in this release.

List application stacks

Run the kabanero list command to list all the application stacks in a kabanero instance, along with their status.

kabanero list

Example result:

Kabanero Instance Stacks  Version Status    Valid Digest
------------------------  ------- ------    ------------
java-openliberty          0.2.19  active    matched
java-openliberty          0.2.21  active    matched
java-spring-boot2         0.3.18  active    matched
java-spring-boot2         0.3.21  active    matched
nodejs                    0.2.6   inactive  NA
nodejs                    0.3.1   active    matched
nodejs-express            0.2.8   active    matched
nodejs-loopback           0.1.6   active    matched
nodejs-loopback           0.1.8   active    matched

GitHub Curated Stacks (repo name - url):
  central - <stack_hub_index_1_url>
  central2 - <stack_hub_index_2_url>

GitHub Curated Stacks     Version Repo
---------------------     ------- ----
java-openliberty          0.2.19  central
java-spring-boot2         0.3.18  central
java-spring-boot2         0.3.21  central2
nodejs                    0.3.1   central
nodejs                    0.2.6   central2
nodejs-express            0.2.8   central
nodejs-express            0.2.9   central2
nodejs-loopback           0.1.6   central
nodejs-loopback           0.1.8   central2

If a stack is removed from the curated stack hub on GitHub, its status shows as obsolete. If a stack is obsolete, a SYNC command deletes it.

Example result showing stack with an obsolete status:

Kabanero Instance Stacks  Version Status            Valid Digest
------------------------  ------- ------            ------------
java-openliberty          0.2.19  active            matched
java-openliberty          0.2.21  active (obsolete) matched
java-spring-boot2         0.3.18  active            matched
java-spring-boot2         0.3.21  active            matched
nodejs                    0.2.6   inactive          NA
nodejs                    0.3.1   active            matched
nodejs-express            0.2.8   active            matched
nodejs-loopback           0.1.6   active            matched
nodejs-loopback           0.1.8   active            matched


GitHub Curated Stacks (repo name - url):
  central - <stack_hub_index_1_url>
  central2 - <stack_hub_index_2_url>

GitHub Curated Stacks     Version Repo
---------------------     ------- ----
java-openliberty          0.2.19  central
java-spring-boot2         0.3.18  central
java-spring-boot2         0.3.21  central2
nodejs                    0.2.6   central
nodejs                    0.3.1   central2
nodejs-express            0.2.8   central
nodejs-express (new)      0.2.9   central2
nodejs-loopback           0.1.6   central
nodejs-loopback           0.1.8   central2

Valid digest

As part of digest governance, for each application stack, the value of the digest in the Kabanero custom resource (CR) is checked against the value of the digest in the container registry. For more information, see Governing stacks with semantic versioning tags. The Valid Digest column can have four different values:

  1. matched: the values for the application stack’s digest in the Kabanero custom resource (CR) and the container registry are the same

  2. mismatched: the values for the application stack’s digest in the Kabanero CR and the container registry do not match

  3. NA: indicates that the stack is deactivated, therefore no digest exists to compare

  4. unknown: a value was not received from the container registry; possible reasons include a network timeout to the container registry server

Note: An unknown digest value when using a private container registry might indicate that a kubernetes secret is needed to authenticate to the the registry. For more information, see Step 2 of Configuring governance policy for stacks.

Synchronize stacks

Running the kabanero sync will ensure that the desired states of stacks are consistent with the current configuration. Sync activates, deletes, and updates versions of the Kabanero stacks to reflect the state of the curated application stack hub. See also [kabanero deactivate]. Modifications to the curated application stack hub index might be slow to replicate in GitHub and therefore might not be reflected immediately in KABANERO LIST or SYNC display output.

kabanero sync

Example results:

kabanero instance stacks are already synchronized with the github curated stacks

Curated stacks and active stacks are now fully synchronized.

Inactive stacks are activated during the sync operation, as shown in the following example:

Kabanero Instance Stacks  Version Status
------------------------  ------- ------
nodejs                    0.2.6   inactive ==> active

This example result shows a stack added from a stack entry in curated stack hub:

Kabanero Instance Stacks  Version Status
------------------------  ------- ------
java-openliberty          0.2.21  added to Kabanero

Running the kabanero sync command when one of the stacks is obsolete deletes the stack.

This example result shows a stack deleted because it is no longer in curated stack hub:

Kabanero Instance Stacks  Version Status
------------------------  ------- ------
java-openliberty          0.2.21  deleted

Show the active repository application stack for an instance

Make sure the instance is installed in the Kabanero namespace. There are two ways to view the active application stacks repository for an instance.

  1. From the OpenShift console, view Administration > Custom Resource Definitions > Kabanero > Instances > Kabanero > YAML

  2. Displaying the configured Kabanero CR with the OC CLI command

    oc get kabanero -n kabanero -o yaml

Show the version number

Run the kabanero version command to display the version of Kabanero that is running.

kabanero version

Example result:

kabanero cli version: 0.9.0
kabanero command line service image: kabanero/kabanero-command-line-services:0.9.0

Describe

Run the kabanero describe command to list the details of an application stack.

kabanero describe stack-name version-number

Running the kabanero describe command produces a list of details that allows for identifying mismatches in the specified application stack. This information is useful when a mismatch is indicated for the digest values.

Example:

kabanero describe java-spring-boot2 0.3.28

Example result:

kabanero describe java-spring-boot2 0.3.28
stack name:  java-spring-boot2
version:  0.3.28
project:  kabanero
source:  https://raw.githubusercontent.com/kabanero-io/kabanero-command-line-services/master/index.yaml
image:  docker.io/kabanerobeta/java-spring-boot2
status:  active
digest check:  matched
kabanero digest:  5343a17b5a2d1923755d5853f4f0507f4ef1cc429238768d9b17c34dee3b829a
image digest:  5343a17b5a2d1923755d5853f4f0507f4ef1cc429238768d9b17c34dee3b829a

Notice that the kabanero describe command allows you to see that the kabanero digest matches the image digest.

Deactivate

Run the kabanero deactivate command to prevent a specific version of an application stack from being used in pipeline builds.

kabanero deactivate stack-name version-number

Running the deactivate command removes the specified application stack from the list of available application types, without deleting it from the instance.

To restore a deactivated application stack, run the kabanero sync command. See [Synchronize application stacks].

Example:

kabanero deactivate nodejs 0.3.1

Example result:

Stack name: nodejs version: 0.3.1 deactivated

Running the kabanero list command now shows the deactivated application stack as inactive.

Kabanero Instance Stacks  Version Status    Valid Digest
------------------------  ------- ------    ------------
java-openliberty          0.2.19  active    matched
java-spring-boot2         0.3.18  active    matched
java-spring-boot2         0.3.21  active    matched
nodejs                    0.2.6   inactive  NA
nodejs                    0.3.1   inactive  NA
nodejs-express            0.2.8   active    matched
nodejs-loopback           0.1.6   active    matched
nodejs-loopback           0.1.8   active    matched

GitHub Curated Stacks (repo name - url):
  central - <stack_hub_index_1_url>
  central2 - <stack_hub_index_2_url>

GitHub Curated Stacks     Version Repo
---------------------     ------- ----
java-openliberty          0.2.19  central
java-spring-boot2         0.3.18  central
java-spring-boot2         0.3.21  central2
nodejs                    0.3.1   central
nodejs                    0.2.6   central2
nodejs-express            0.2.8   central
nodejs-express            0.2.9   central2
nodejs-loopback           0.1.6   central
nodejs-loopback           0.1.8   central2

Log out

Run the kabanero logout command to disconnect from the instance.

kabanero logout

Example result:

Logged out of Kabanero instance: <SM_CLI_URL>

Global Options

These options can be enabled on any command.

  • Help for a command. For example, kabanero refresh -h

    • -h

    • --help

  • Turn on debug output and logging to a file in $HOME/.kabanero/logs

    • -v

    • --verbose

Edit This Page