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.

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:

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

To provision a Minikube cluster, run:

kyma provision minikube

Install Kyma

To install Kyma using your own domain, run:

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:

kyma install --source master

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

kyma install --source {IMAGE}

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

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:

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:

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:

kyma test definitions

To run all the tests, run:

kyma test run

To check the test results, run:

kyma test status

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:

• Docker
• Kyma CLI
• Kyma installed locally or on a cluster

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}

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

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

   Click to copy

   kubectl describe function {FUNCTION_NAME}

4. 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!"

5. Fetch the content of the resource to synchronize your local workspace sources with the cluster changes:

   Click to copy

   kyma sync function {FUNCTION_NAME}

6. 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!"