GuidesChangelogDiscussions
Log In
Log In

Getting Started

Suggest Edits

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.4.0  bash

Ketch CLI auto-completion

Ketch CLI supports auto-completion for most major shells. Run ketch completion -h in your terminal and follow direction to setup auto-completion for your shell.

ketch completion -h   
To load completions:

Bash:

  $ source <(ketch completion bash)

  # To load completions for each session, execute once:
  # Linux:
  $ ketch completion bash > /etc/bash_completion.d/ketch
  # macOS:
  $ ketch completion bash > /usr/local/etc/bash_completion.d/ketch

Zsh:

  # If shell completion is not already enabled in your environment,
  # you will need to enable it.  You can execute the following once:

  $ echo "autoload -U compinit; compinit" >> ~/.zshrc

  # To load completions for each session, execute once:
  $ ketch completion zsh > "${fpath[1]}/_ketch"

  # You will need to start a new shell for this setup to take effect.

fish:

  $ ketch completion fish | source

  # To load completions for each session, execute once:
  $ ketch completion fish > ~/.config/fish/completions/ketch.fish

PowerShell:

  PS> ketch completion powershell | Out-String | Invoke-Expression

  # To load completions for every new session, run:
  PS> ketch completion powershell > ketch.ps1
  # and source this file from your PowerShell profile.

Usage:
  ketch completion [bash|zsh|fish|powershell]

Flags:
  -h, --help   help for completion

Ingress Controller, Cluster Issuer and Cert Manager

📘

Existing cluster resources

The ingress controller, cluster issuer, or cert-manager should only be installed if one is not currently installed in the cluster where Ketch will be installed.

In case there is already an ingress controller (Traefik or Istio), cluster issuer or cert-manager installed in the cluster, the steps below specific to each are not necessary.

* Installing Cert-Manager

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

kubectl apply --validate=false -f https://github.com/jetstack/cert-manager/releases/download/v1.0.3/cert-manager.yaml

* Installing Traefik

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

helm repo add traefik https://helm.traefik.io/traefik
helm repo update
helm install traefik traefik/traefik

* Installing Istio

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

ISTIO_VERSION=1.9.0 && curl -L https://istio.io/downloadIstio |ISTIO_VERSION=1.9.0 sh - && cd istio-$ISTIO_VERSION && export PATH=$PWD/bin:$PATH

istioctl install --set profile=demo

* Cluster Issuer

If not already present in your cluster, you can install a cluster issuer by creating the cluster-issuer-istio.yaml file with the following content:

apiVersion: cert-manager.io/v1
kind: ClusterIssuer
metadata:
  name: le 
spec:
  acme:
    server: https://acme-v02.api.letsencrypt.org/directory
    privateKeySecretRef:
      name: my-account-key
    solvers:
    - http01:
       ingress:
         class: istio

Once the file is created, you can install it using the following command:

kubectl apply -f cluster-issuer-istio.yaml

Ketch Controller

Run the command below to install the Ketch controller:

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

Deploying an Application

Creating a Framework

Deploying applications is easy once you've installed Ketch, where the first step is to create a framework.

When creating a framework, you should assign which ingress controller you want to associate with the framework.

  • When using Traefik: 
ketch framework add dev  --ingress-service-endpoint 104.155.134.17 --ingress-type traefik

📘

Traefik Ingress IP

You can find Traefik's ingress service IP by running the command below:

kubectl get services

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

  • When using Istio: 
ketch framework add dev  --ingress-service-endpoint 104.155.134.17 --ingress-type istio

📘

Istio Ingress IP

You can find Istio's ingress service IP by running the command below:

kubectl get services -n istio-system

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

📘

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. This can be achieved 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 from source.

Deploying Applications 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 app by providing the secret name using

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

Deploying Applications From Source

Ketch uses Cloud Native Buildpacks to deploy an application from source code. You can specify specific builder (default heroku/buildpacks:20) with deploy --builder flag. You can also provide one or more build packs using --build-packs flag.

# Deploy app using default heroku/buildpacks:20 builder
$ ketch app deploy python-sample .  -i docker.io/$DOCKER_REPO/python-sample:1.0 -k istio-framework

During application deployment, Ketch creates a docker image using default builder heroku/buildpacks:20 and pushes it to a docker registry. To build and push docker images, ketch uses the docker CLI on your machine 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

Ketch uses Cloud Native Buildpacks to make it easier to deploy applications from source. See Cloud Native Buildpacks documentation for details.

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

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

ketch app list

After you deploy 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.

Updated 6 days ago