Getting started with Ketch only takes a few minutes. The sections below will guide you step-by-step from installing Ketch to deploying your first application.

More in-depth tutorials can also be found as part of this documentation.

Installing Ketch

The latest Ketch release can be found here. Use the following commands to install Ketch, changing the version in the commands to match the version of Ketch you want to install.

Ketch CLI

You can use the following command to download and install the Ketch CLI on your local machine:

curl -s https://raw.githubusercontent.com/shipa-corp/ketch/main/install.sh | bash

The command above will download and install the Ketch CLI based on your local operating system.

To install specific version of Ketch at a target location use command below:

curl -s https://raw.githubusercontent.com/shipa-corp/ketch/main/install.sh | INSTALL_DIR=. TAG=v0.6.2  bash

Installing Cert-Manager

If not already present in your cluster, you can install cert-manager by using the following commands:

kubectl apply -f https://github.com/jetstack/cert-manager/releases/download/v1.5.3/cert-manager.yaml

Installing Nginx

If not already present in your cluster, you can run following helm command to install Nginx ingress. For details see: https://kubernetes.github.io/ingress-nginx/deploy/.

helm upgrade --install ingress-nginx ingress-nginx \
  --repo https://kubernetes.github.io/ingress-nginx \
  --namespace ingress-nginx --create-namespace

Ketch Controller

Run the command below to install the Ketch controller:

kubectl apply -f https://github.com/shipa-corp/ketch/releases/download/v0.6.2/ketch-controller.yaml

📘

Cert Manager Pre-Req

In certain installation automation, Cert Manager could not be fully ready before deploying the Ketch Controller manifest. Can add a kubectl wait to your automation for Cert Manager's ready state.

kubectl wait --for=condition=available --timeout=300s deployment/cert-manager-webhook -n cert-manager

Deploying an Application

Creating a Framework

You can use frameworks to isolate the applications you deploy. A framework in Ketch maps to a namespace in your cluster.

Ketch automatically creates the namespace based on the framework name. Alongside the namespace, Ketch leverages the ingress controller you chose to create endpoints for your applications automatically.

Given the above, you should assign which ingress controller you want to associate with the framework.

When using nginx:

ketch framework add dev --ingress-service-endpoint 104.155.134.17 --ingress-type nginx

📘

Nginx Ingress IP

You can find Nginx ingress service IP by running the command below:

kubectl get services -n ingress-nginx

You should use the IP presented under the EXTERNAL-IP column.

👍

Existing Kubernetes Namespace

The commands above will create a dedicated namespace for the Ketch framework during the framework creation.

You can also have Ketch use an existing namespace for the framework instead by adding the --namespace flag in the command.

Deploy an Application

You can deploy your applications directly using an existing docker image from a public or private registry, or you can deploy directly from source.

Using a Docker Image

The command below will create and assign it to framework dev and then deploy provided docker image.

ketch app deploy bulletinboard -k dev -i docker.io/shipasoftware/bulletinboard:1.0

📘

Deploying image from private docker registry

If your image is in a private docker registry repo, you should set up docker-registry secret using kubectl.

Follow kubectl documentation on pulling images from private docker registry for details.

Once you set it up, you should create an app or update the app by providing the secret name using:

ketch app deploy $APPNAME -k $FRAMEWORK_NAME --registry-secret $DOCKER_REGISTRY_SECRET_NAME -i $IMAGE_URL

Deploying From Source

Ketch uses Cloud Native Buildpacks to deploy an application from source code. You can specify a specific builder (default heroku/buildpacks:20) with the deploy --builder flag.

You can also provide one or more build packs using the --build-packs flag.

ketch app deploy python-sample .  -i docker.io/$DOCKER_REPO/python-sample:1.0 -k istio-framework

Ketch creates a docker image during application deployment using default builder heroku/buildpacks:20 and pushes it to a docker registry.

Ketch uses the docker CLI on your machine to build and push docker images and expects you to be logged in using the docker login command.

If you are pushing the image to a private docker registry, follow the notes above on setting up a docker-registry secret and creating a ketch app with it using the --registry-secret option.

📘

Cloud Native Buildpacks for source deployment

You can see the list of supported builders by running the ketch builder list command.

Once deployed, you can check the application status by using the app list command:

ketch app list

After deploying your application, you can access it at the address associated with it using the ketch app list, in this example, http://bulletinboard.104.155.134.17.shipa.cloud.