Kyma CLI

Overview

Kyma CLI is a command-line tool that supports Kyma developers. It provides a set of commands and flags you can use to:

  • Provision a cluster locally or on cloud providers, such as GCP or Azure, or use Gardener to set up and easily manage your clusters.
  • Install, manage, and test Kyma.

The Kyma CLI is always released in parallel with Kyma to support the latest features, which also means that older Kyma versions can no longer be supported by the Kyma CLI. This Kyma CLI version is compatible with the corresponding Kyma release and the previous release, but it is incompatible with versions before the previous ones.

Details

Use Kyma CLI

Kyma CLI comes with a set of commands, each of which has its own specific set of flags. Use them to provision the cluster locally or using a chosen cloud provider, install, and test Kyma.

For the commands and flags to work, they need to follow this syntax:

Click to copy
kyma {COMMAND} {FLAGS}
  • {COMMAND} specifies the operation you want to perform, such as provisioning the cluster or installing Kyma.
  • {FLAGS} specifies optional flags you can use to enrich your command.

See the example:

Click to copy
kyma install -s master

See the full list of commands and flags.

CommandChild commandsDescriptionExample
completionNoneGenerates and displays the bash or zsh completion script.kyma completion
consoleNoneLaunches Kyma Console in a browser window.kyma console
createsystemCreates resources on the Kyma cluster. NOTE: The kyma create and kyma create system commands are still in alpha version.kyma create
installNoneInstalls Kyma on a cluster based on the current or specified release.kyma install
provisionminikube gardener gke aksProvisions a new cluster on a platform of your choice. Currently, this command supports cluster provisioning on GCP, Azure, Gardener, and Minikube.kyma provision minikube
testdefinitions delete list run status logs Runs and manages tests on a provisioned Kyma cluster. Using child commands, you can run tests, view test definitions, list and delete test suites, display test status, and fetch the logs of the tests.kyma test run
versionNoneShows the cluster version and the Kyma CLI version.kyma version

Kyma CLI command usage examples

The following examples show how to provision a cluster, install Kyma, and run the tests.

Provision a cluster locally or using cloud providers

To provision a cluster on a specific cloud provider (in this example GCP), run:

Click to copy
kyma provision gke --credentials {SERVICE_ACCOUNT_KEY_FILE_PATH} --name {CLUSTER_NAME} --project {GCP_PROJECT}

To provision a Minikube cluster, run:

Click to copy
kyma provision minikube

Install Kyma

To install Kyma using your own domain, run:

Click to copy
kyma install --domain {DOMAIN} --tls-cert {TLS_CERT} --tls-key {TLS_KEY}
  • {TLS_CERT} and {TLS_KEY} are the TLS certificate and TLS key for the domain used. Note that both of them must be encoded in base64. You can use OpenSSL (which is installed by default with macOS) to convert your TLS certificate and TLS key to base64-encoded values.
  • To simplify the process:
    • You can first encode the TLS certificate and TLS key and export them as environment variables:
    • Click to copy
      export TLS_CERT="$(openssl base64 -in {TLS_CERT_FILE_PATH})"
      export TLS_KEY="$(openssl base64 -in {TLS_KEY_FILE_PATH})"
    • {TLS_CERT_FILE_PATH} is the path to the file containing the TLS certificate and {TLS_KEY_FILE_PATH} is the path to the file containing the TLS key.
    • Now, you can use these environment variables to install Kyma with your own domain {DOMAIN} as shown below:
    • Click to copy
      kyma install --domain {DOMAIN} --tls-cert $TLS_CERT --tls-key $TLS_KEY

To install Kyma from the master branch, run:

Click to copy
kyma install --source master

To install Kyma using your own Kyma installer image, run:

Click to copy
kyma install --source {IMAGE}

To build an image from your local sources and install Kyma on a remote cluster based on this image, run:

Click to copy
kyma install --source local --custom-image {IMAGE}
  • For example, if your {IMAGE} is user/my-kyma-installer:v1.4.0, then this command will build an image from your local sources and push it your repository user/my-kyma-installer with the tag v1.4.0. Then, this image user/my-kyma-installer:v1.4.0 will be used in the Deployment for kyma-installer.

To install kyma with only specific components, run:

Click to copy
kyma install --components {COMPONENTS_FILE_PATH}
  • {COMPONENTS_FILE_PATH} is the path to a YAML file containing the desired component list to be installed such as the one below:
  • Click to copy
    components:
    - name: "cluster-essentials"
    namespace: "kyma-system"
    - name: "testing"
    namespace: "kyma-system"
    - name: "istio"
    namespace: "istio-system"
    - name: "xip-patch"
    namespace: "kyma-installer"
    - name: "istio-kyma-patch"
    namespace: "istio-system"
    - name: "dex"
    namespace: "kyma-system"
  • In this example, only these 6 components will be installed on the cluster.

To override the standard Kyma installation, run:

Click to copy
kyma install --override {OVERRIDE_FILE_PATH}
  • {OVERRIDE_FILE_PATH} is the path to a YAML file containing the parameters to override such as the one below:
  • Click to copy
    apiVersion: v1
    kind: ConfigMap
    metadata:
    name: ory-overrides
    namespace: kyma-installer
    labels:
    installer: overrides
    component: ory
    kyma-project.io/installation: ""
    data:
    hydra.deployment.resources.limits.cpu: "153m"
    hydra.deployment.resources.requests.cpu: "53m"
    ---
    apiVersion: v1
    kind: ConfigMap
    metadata:
    name: monitoring-overrides
    namespace: kyma-installer
    labels:
    installer: overrides
    component: monitoring
    kyma-project.io/installation: ""
    data:
    alertmanager.alertmanagerSpec.resources.limits.memory: "304Mi"
    alertmanager.alertmanagerSpec.resources.requests.memory: "204Mi"
  • In this example, overrides are provided for 2 different components: ory and monitoring. For ory, the values of hydra.deployment.resources.limits.cpu and hydra.deployment.resources.requests.cpu will be overriden to 153m and 53m respectively. For monitoring, the values of alertmanager.alertmanagerSpec.resources.limits.memory and alertmanager.alertmanagerSpec.resources.requests.memory will be overriden to 304Mi and 204Mi respectively.

  • It is also possible to provide multiple override files at the same time

    Click to copy
    kyma install --override {OVERRIDEL_FILE_1_PATH} --override {OVERRIDE_FILE_2_PATH}

Upgrade Kyma

To upgrade the Kyma version on the cluster, you can run the upgrade command which has the same structure and same flags as the install command.

Test Kyma

To check which test definitions are deployed on the cluster, run:

Click to copy
kyma test definitions

To run all the tests, run:

Click to copy
kyma test run

To check the test results, run:

Click to copy
kyma test status

Kyma CLI alpha command usage examples

The following examples show how to use the alpha commands to provision a cluster, install and upgrade Kyma, and handle errors.

Provision a cluster

To provision a k3s cluster, run:

Click to copy
kyma alpha provision k3s

If you want to define the name of your k3s cluster and pass arguments to the Kubernetes API server (for example, to log to stderr), run:

Click to copy
kyma alpha provision k3s --name='custom_name' --server-args='--alsologtostderr'

Install Kyma

There are several ways to install Kyma:

  • You can simply use the deploy command without any flags, and Kyma provides a default domain. For example, if you install Kyma on a local cluster, the default URL is https://console.local.kyma.dev.

    Click to copy
    kyma alpha deploy
  • To install Kyma using your own domain name, you must provide the certificate and key as files. If you don't have a certificate yet, you can create a self-signed certificate and key:

    Click to copy
    openssl req -x509 -newkey rsa:4096 -keyout key.pem -out crt.pem -days 365

    When prompted, provide your credentials, such as your name and your domain (as wildcard: *.$DOMAIN).

    Then, pass the certificate files to the deploy command:

    Click to copy
    kyma alpha deploy --domain {DOMAIN} --tls-cert crt.pem --tls-key key.pem
  • Optionally, you can specify from which source you want to deploy Kyma, such as the master branch, a specific PR, or a release version. For more details, see the documentation for the alpha deploy command. For example, to install Kyma from a specific version, such as 1.19.1, run:

    Click to copy
    kyma alpha deploy --source=1.19.1
  • Alternatively, to build Kyma from your local sources and deploy it on a remote cluster, run:

    Click to copy
    kyma alpha deploy --source=local

    NOTE: By default, Kyma expects to find local sources in the $GOPATH/src/github.com/kyma-project/kyma folder. To adjust the path, set the -w ${PATH_TO_KYMA_SOURCES} parameter.

  • To deploy Kyma with only specific components, run:

    Click to copy
    kyma alpha deploy --components {COMPONENTS_FILE_PATH}

    {COMPONENTS_FILE_PATH} is the path to a YAML file containing the desired component list to be installed. In the following example, only six components are deployed on the cluster:

    Click to copy
    prerequisites:
    - name: "cluster-essentials"
    - name: "istio"
    namespace: "istio-system"
    components:
    - name: "testing"
    - name: "xip-patch"
    - name: "istio-kyma-patch"
    - name: "dex"
  • You can also install Kyma with different configuration values than the default settings. For details, see Change Kyma settings.

Upgrade Kyma

The alpha deploy command not only installs Kyma, you also use it to upgrade the Kyma version on the cluster. You have the same options as described under Install Kyma.

NOTE: If you upgrade from one Kyma release to a newer one, an automatic compatibility check compares your current version and the new release. The compatibility check only works with release versions. If you installed Kyma from a PR, branch, revision, or local version, the compatibility cannot be checked.

Change Kyma settings

To change your Kyma configuration, use the alpha deploy command and deploy the same Kyma version that you're currently using, just with different settings.

You can use the --values-file and the --value flag.

  • To override the standard Kyma configuration, run:

    Click to copy
    kyma alpha deploy --values-file {VALUES_FILE_PATH}

    In the following example, {VALUES_FILE_PATH} is the path to a YAML file containing the desired configuration:

    • For ory, the values of hydra.deployment.resources.limits.cpu and hydra.deployment.resources.requests.cpu will be overriden to 153m and 53m respectively.

    • For monitoring, the values of alertmanager.alertmanagerSpec.resources.limits.memory and alertmanager.alertmanagerSpec.resources.requests.memory will be overriden to 304Mi and 204Mi respectively.

    Click to copy
    ory:
    hydra:
    deployment:
    resources:
    limits:
    cpu: 153m
    requests:
    cpu: 53m
    monitoring:
    alertmanager:
    alertmanagerSpec:
    resources:
    limits:
    memory: 304Mi
    requests:
    memory: 204Mi
  • You can also provide multiple values files at the same time:

    Click to copy
    kyma deploy --values-file {VALUES_FILE_1_PATH} --values-file {VALUES_FILE_2_PATH}

    NOTE: If a value is defined in several files, the value of the last file in the list is used.

  • Alternatively, you can specify single values instead of a file:

    Click to copy
    kyma deploy --value ory.hydra.deployment.resources.limits.cpu=153m \
    --value ory.hydra.deployment.resources.requests.cpu=53m \
    --value monitoring.alertmanager.alertmanagerSpec.resources.limits.memory=304Mi \
    --value monitoring.alertmanager.alertmanagerSpec.resources.requests.memory=204Mi

    NOTE: If a value is defined several times, the last value definition in the list is used. The --value flag also overrides any conflicting value that is defined with a --value-file flag.

Debugging

The alpha commands support error handling in several ways, for example:

  • To get a detailed view of the installation process, use the --verbose flag.
  • To tweak the values on a component level, use alpha deploy --components: Pass a components list that includes only the components you want to test and try out the settings that work for your installation.
  • To understand which component failed during deployment, deactivate the default atomic deployment: --atomic=false. With atomic deployment active, any component that hasn't been installed successfully is rolled back, which may make it hard to find out what went wrong. By disabling the flag, the failed components are not rolled back.

Installation

Install Kyma CLI

You can easily install Kyma CLI on macOS, Linux, or Windows. To do so, perform the instructions described in the following sections.

macOS

To install Kyma CLI on macOS, run:

Click to copy
curl -Lo kyma.tar.gz "https://github.com/kyma-project/cli/releases/download/$(curl -s https://api.github.com/repos/kyma-project/cli/releases/latest | grep tag_name | cut -d '"' -f 4)/kyma_Darwin_x86_64.tar.gz" \
&& mkdir kyma-release && tar -C kyma-release -zxvf kyma.tar.gz && chmod +x kyma-release/kyma && sudo mv kyma-release/kyma /usr/local/bin \
&& rm -rf kyma-release kyma.tar.gz

Homebrew

To install Kyma CLI using Homebrew, run:

Click to copy
brew install kyma-cli

If the Homebrew team does not update the Homebrew formula of the CLI within three days of the release, follow this guide to update it manually to the most recent version. For a sample Homebrew Kyma CLI formula version bump, see this PR.

Linux

To install Kyma CLI on Linux, run:

Click to copy
curl -Lo kyma.tar.gz "https://github.com/kyma-project/cli/releases/download/$(curl -s https://api.github.com/repos/kyma-project/cli/releases/latest | grep tag_name | cut -d '"' -f 4)/kyma_Linux_x86_64.tar.gz" \
&& mkdir kyma-release && tar -C kyma-release -zxvf kyma.tar.gz && chmod +x kyma-release/kyma && sudo mv kyma-release/kyma /usr/local/bin \
&& rm -rf kyma-release kyma.tar.gz

Windows

To install Kyma CLI on Windows, download and unzip the release artifact. Remember to adjust your PATH environment variable.

Click to copy
{KYMA_VERSION}=1.2.0
Invoke-WebRequest -OutFile kyma.zip https://github.com/kyma-project/cli/releases/download/${KYMA_VERSION}/kyma_Windows_x86_64.zip
Expand-Archive -Path kyma.zip -DestinationPath .\kyma-cli
cd kyma-cli

Chocolatey (Windows)

To install Kyma CLI on Windows using Chocolatey, run:

Click to copy
choco install kyma-cli

You don't have to bump Kyma CLI Chocolatey package manually with each new release, as it includes a script that automatically checks for new releases and updates the package to the latest one.

Still, the package requires some maintenance to keep its dedicated site atchocolatey.org up to date. This means you should regularly update the description, details, screenshots, etc. To keep the site up to date, submit a pull request to Chocolatey's GitHub repository.

Other

To install a different release version, change the path to point to the desired version and architecture:

Click to copy
curl -Lo kyma.tar.gz https://github.com/kyma-project/cli/releases/download/${KYMA_VERSION}/kyma_${ARCH}.tar.gz

Tutorials

Use Kyma CLI as kubectl plugin

This short tutorial shows how to extend kubectl to support Kyma CLI and its commands.

To use Kyma CLI as the kubectl plugin, perform the following steps:

NOTE: To use Kyma CLI as a kubectl plugin, use Kubernetes version 1.12.0 or higher.

  1. Rename the kyma binary to kubectl-kyma and place it anywhere in your {PATH}:

    Click to copy
    sudo mv ./kyma /usr/local/bin/kubectl-kyma
  2. Run kubectl plugin list command to see your plugin on the list of all available plugins.

  3. Invoke your plugin as a kubectl command:

    Click to copy
    kubectl kyma version
    Kyma CLI version: v0.6.1
    Kyma cluster version: 1.0.0

Use Kyma CLI to manage Functions

This tutorial shows how to use the available CLI commands to manage Functions in Kyma. You will see how to:

  1. Create local files that contain the basic configuration for a sample "Hello World" Python Function (kyma init function).
  2. Generate a Function custom resource (CR) from these files and apply it on your cluster (kyma apply function).
  3. Fetch the current state of your Function's cluster configuration after it was modified (kyma sync function).

This tutorial is based on a sample Python Function run on a lightweight k3d cluster.

Prerequisites

Before you start, make sure you have the following tools installed:

Steps

Follow these steps:

  1. Run the init Kyma CLI command to create local files with the default configuration for a Python Function. Go to the folder in which you want to initiate the workspace content and run this command:

    Click to copy
    kyma init function --runtime python38 --name {FUNCTION_NAME}

    Alternatively, use the --dir {FULL_FOLDER_PATH} flag to point to the directory where you want to create the Function's source files.

    NOTE: Python 3.8 is only one of the available runtimes. Read about all supported runtimes and sample Functions to run on them.

    The init command creates the following files in your workspace folder:

  • config.yaml with the Function's configuration
  • handler.py with the Function's code and the simple "Hello World" logic
  • requirements.txt with an empty file for your Function's custom dependencies

    This command also sets sourcePath in the config.yaml file to the full path of the workspace folder:

    Click to copy
    name: my-function
    namespace: default
    runtime: python38
    source:
    sourceType: inline
    sourcePath: {FULL_PATH_TO_WORKSPACE_FOLDER}
  1. Run the apply Kyma CLI command to create a Function CR in the YAML format on your cluster:

    Click to copy
    kyma apply function

    TIP: To apply a Function from a different location, use the --filename flag followed by the full path to the config.yaml file.

    Alternatively, use the --dry-run flag to list the file that will be created before you apply it. You can also preview the file's content in the format of your choice by adding the --output {FILE_FORMAT} flag, such as --output yaml.

  2. Once applied, view the Function's details on the cluster:

    Click to copy
    kubectl describe function {FUNCTION_NAME}
  3. Change the Function's source code on the cluster to return "Hello Serverless!":

    a) Edit the Function:

    Click to copy
    kubectl edit function {FUNCTION_NAME}

    b) Modify source as follows:

    Click to copy
    ...
    spec:
    runtime: python38
    source: |-
    def main(event, context):
    return "Hello Serverless!"
  4. Fetch the content of the resource to synchronize your local workspace sources with the cluster changes:

    Click to copy
    kyma sync function {FUNCTION_NAME}
  5. Check the local handler.py file with the Function's code to make sure that the cluster changes were fetched:

    Click to copy
    cat handler.py

    This command returns the result confirming that the local sources were synchronized with cluster changes:

    Click to copy
    def main(event, context):
    return "Hello Serverless!"

Debug a Function

This tutorial shows how to use an external IDE to debug a Function in Kyma CLI.

Steps

Follows these steps:

  • Visual Studio Code
  • GoLand

Troubleshooting

Sudden container failure

The container can suddenly fail when you use the kyma run function command with these flags: - runtime=Nodejs12 or runtime=Nodejs10 - debug=true - hot-deploy=true

In such a case, you can see the [nodemon] app crashed message in the container's logs.

If you use Kyma in Kubernetes, Kubernetes itself should run the Function in the container. If you use Kyma without Kubernetes, you have to rerun the container yourself.

Debugger stops at dependency files

If you debug your Function in runtime=Nodejs12 or runtime=Nodejs10 and you set a breakpoint in the first line of the main Function, the debugger can stop at dependencies.

The reason is that you shouldn't debug the first line. Add a comment in the first line instead, and start debugging from the second line.