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:
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:
kyma install -s master
See the full list of commands and flags.
Command | Child commands | Description | Example |
---|---|---|---|
completion | None | Generates and displays the bash or zsh completion script. | kyma completion |
console | None | Launches Kyma Console in a browser window. | kyma console |
create | system | Creates resources on the Kyma cluster. NOTE: The kyma create and kyma create system commands are still in alpha version. | kyma create |
install | None | Installs Kyma on a cluster based on the current or specified release. | kyma install |
provision | minikube gardener gke aks | Provisions a new cluster on a platform of your choice. Currently, this command supports cluster provisioning on GCP, Azure, Gardener, and Minikube. | kyma provision minikube |
test | definitions 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 |
version | None | Shows 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:
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 copyexport 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 copykyma 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}
isuser/my-kyma-installer:v1.4.0
, then this command will build an image from your local sources and push it your repositoryuser/my-kyma-installer
with the tagv1.4.0
. Then, this imageuser/my-kyma-installer:v1.4.0
will be used in theDeployment
forkyma-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 copycomponents:- 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 copyapiVersion: v1kind: ConfigMapmetadata:name: ory-overridesnamespace: kyma-installerlabels:installer: overridescomponent: orykyma-project.io/installation: ""data:hydra.deployment.resources.limits.cpu: "153m"hydra.deployment.resources.requests.cpu: "53m"---apiVersion: v1kind: ConfigMapmetadata:name: monitoring-overridesnamespace: kyma-installerlabels:installer: overridescomponent: monitoringkyma-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
andmonitoring
. Forory
, the values ofhydra.deployment.resources.limits.cpu
andhydra.deployment.resources.requests.cpu
will be overriden to153m
and53m
respectively. Formonitoring
, the values ofalertmanager.alertmanagerSpec.resources.limits.memory
andalertmanager.alertmanagerSpec.resources.requests.memory
will be overriden to304Mi
and204Mi
respectively.It is also possible to provide multiple override files at the same time
Click to copykyma 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
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:
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:
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:
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.
{KYMA_VERSION}=1.2.0Invoke-WebRequest -OutFile kyma.zip https://github.com/kyma-project/cli/releases/download/${KYMA_VERSION}/kyma_Windows_x86_64.zipExpand-Archive -Path kyma.zip -DestinationPath .\kyma-clicd kyma-cli
Chocolatey (Windows)
To install Kyma CLI on Windows using Chocolatey, run:
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:
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.
Rename the
kyma
binary tokubectl-kyma
and place it anywhere in your {PATH}:Click to copysudo mv ./kyma /usr/local/bin/kubectl-kymaRun
kubectl plugin list
command to see your plugin on the list of all available plugins.Invoke your plugin as a kubectl command:
Click to copykubectl kyma versionKyma CLI version: v0.6.1Kyma 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:
- Create local files that contain the basic configuration for a sample "Hello World" Python Function (
kyma init function
). - Generate a Function custom resource (CR) from these files and apply it on your cluster (
kyma apply function
). - 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:
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 copykyma 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 configurationhandler.py
with the Function's code and the simple "Hello World" logicrequirements.txt
with an empty file for your Function's custom dependenciesThis command also sets sourcePath in the
config.yaml
file to the full path of the workspace folder:Click to copyname: my-functionnamespace: defaultruntime: python38source:sourceType: inlinesourcePath: {FULL_PATH_TO_WORKSPACE_FOLDER}
Run the
apply
Kyma CLI command to create a Function CR in the YAML format on your cluster:Click to copykyma apply functionTIP: To apply a Function from a different location, use the
--filename
flag followed by the full path to theconfig.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
.Once applied, view the Function's details on the cluster:
Click to copykubectl describe function {FUNCTION_NAME}Change the Function's source code on the cluster to return "Hello Serverless!":
a) Edit the Function:
Click to copykubectl edit function {FUNCTION_NAME}b) Modify source as follows:
Click to copy...spec:runtime: python38source: |-def main(event, context):return "Hello Serverless!"Fetch the content of the resource to synchronize your local workspace sources with the cluster changes:
Click to copykyma sync function {FUNCTION_NAME}Check the local
handler.py
file with the Function's code to make sure that the cluster changes were fetched:Click to copycat handler.pyThis command returns the result confirming that the local sources were synchronized with cluster changes:
Click to copydef main(event, context):return "Hello Serverless!"