Skip to content

Latest commit

 

History

History
136 lines (92 loc) · 5.84 KB

031-gs-local-installation.md

File metadata and controls

136 lines (92 loc) · 5.84 KB
Raw
title type
Local Kyma installation
Getting Started

Overview

This Getting Started guide shows developers how to to quickly deploy Kyma locally on a Mac, Linux, or Windows. Kyma installs locally using a proprietary installer based on a Kubernetes operator. The document provides prerequisites, instructions on how to install Kyma locally and verify the deployment, as well as the troubleshooting tips.

Prerequisites

To run Kyma locally, clone this Git repository to your local machine and download these tools:

Read the prerequisite reasoning document to learn why Kyma uses these tools.

Setup certificates

Kyma comes with a local wildcard self-signed certificate. Trust it on the OS level for convenience. Alternatively, accept exceptions for each subdomain in your browser as you use Kyma.

Follow these steps to "always trust" the Kyma certificate on macOS:

  1. Open the Keychain Access application. Select System from the Keychains menu.
  2. Go to File, select Import items..., and import the Kyma certificate.
  3. Go to the Certificates view and find the *.kyma.local certificate you imported.
  4. Right-click the certificate and select Get Info.
  5. Expand the Trust list and set When using this certificate to Always trust.
  6. Close the certificate information window and enter your system password to confirm the changes.

NOTE:

  • The process is complete when you close the certificate information window and enter your password. You don't get the expected results if you try to use the certificate before completing this step.
  • "Always trusting" the certificate does not work with Mozilla Firefox.

Install Kyma on Minikube

NOTE: Running the installation script deletes any previously existing cluster from your Minikube.

  1. Change the working directory to installation:
cd installation
  1. Depending on your operating system, run run.sh for Mac and Linux or run.ps1 for Windows
cmd/run.sh

The run.sh script does not show the progress of the Kyma installation, which allows you to perform other tasks in the terminal window. However, to see the status of the Kyma installation, run this script after you set up the cluster and the installer:

scripts/is-installed.sh

Read the Reinstall Kyma document to learn how to reinstall Kyma without deleting the cluster from Minikube. To learn how to test Kyma, see the Testing Kyma document.

Custom Resource file

The Custom Resource file contains controls the Kyma installer, which is a proprietary solution based on the Kubernetes operator. The file contains the basic information that defines Kyma installation. Find the custom resource template here.

Control the installation process

To trigger the installation process, set the action label to install in the metadata of the Custom Resource with the installer configuration. To trigger the deinstallation process, set the action label to uninstall in the metadata of the Custom Resource with the installer configuration.

Generate a new Custom Resource file

Use the create-cr.sh script to generate the Custom Resource file. The script accepts these arguments:

  • --output - mandatory. The location of the Custom Resource output file
  • --url - the URL of the Kyma package to install
  • --version - the Kyma version
  • --ipaddr - the load balancer IP
  • --domain - the instance domain

For example:

$ ./installation/scripts/create-cr.sh --output kyma-cr.yaml --url {Kyma_TAR.GZ_URL} --version 0.0.1 --domain kyma.local

Verify the deployment

Follow the guidelines in the subsections to confirm that your Kubernetes API Server is up and running as expected.

Access Kyma with CLI

Verify the cluster deployment with the kubectl command line interface (CLI).

Run this command to fetch all Pods in all Namespaces:

kubectl get pods --all-namespaces

The command retrieves all Pods from all Namespaces, the status of the Pods, and their instance numbers. Check if the STATUS column shows Running for all Pods. If any of the Pods that you require do not start successfully, perform the installation again.

Access the Kyma console

Access your local Kyma instance through this link.

  • Click Login with Email and sign in with the admin@kyma.cx email address and the generic password from the Dex ConfigMap file.

  • Click the Environments section and select an Environment from the drop-down menu to explore Kyma further.

Access the Kubernetes Dashboard

Additionally, confirm that you can access your Kubernetes Dashboard. Run the following command to check the IP address on which Minikube is running:

minikube ip

The address of your Kubernetes Dashboard looks similar to this:

http://{ip-address}:30000

See the example of the website address:

http://192.168.64.44:30000

Troubleshooting

If the installer does not respond as expected, check the installation status using the is-installed.sh script with the --verbose flag added. Run:

scripts/is-installed.sh --verbose