Skip to main content

Installing and using a Promise

Pre-requisites​

You need an installation of Kratix for this section. Click here for instructions

The simplest way to do so is by running the quick-start script from within the Kratix directory. The script will create two KinD clusters, install, and configure Kratix.

./scripts/quick-start.sh --recreate

You can run Kratix either with a multi-cluster or a single-cluster setup. The commands on the remainder of this document assume that two environment variables are set:

  1. PLATFORM representing the Platform cluster Kubernetes context
  2. WORKER representing the Worker cluster Kubernetes context

If you ran the quick-start script above, do:

export PLATFORM="kind-platform"
export WORKER="kind-worker"

For single cluster setups, the two variables should be set to the same value. You can find your cluster context by running:

kubectl config get-contexts

Refer back to Installing Kratix for more details.

In this guide, you will

  1. learn more about Kratix Promises
  2. install Jenkins as a Kratix Promise

What is a Kratix Promise?​

Conceptually, Promises are the building blocks of Kratix that allow you to develop your platform incrementally. Technically, a Promise is a YAML document that defines a contract between the Platform and its users. You can explore more about this contract and the internals of a Kratix Promise in the writing a Promise guide.

Kratix Promises​

  • enable you to build your platform incrementally and in response to the needs of your users.
  • codify the contract between platform teams and application teams for the delivery of a specific service, e.g. a database, an identity service, a supply chain, or a complete development pipeline of patterns and tools.
  • are easy to build, deploy, and update.
  • are sharable and reusable between platforms, teams, business units, and other organisations.
  • add up to a frictionless experience when platform users want to create services that they need to deliver value.

Now that you know more about Kratix Promises, follow the steps below to install a Promise.


Install the Kratix sample Jenkins Promise​

Now that your system is set up, you can install your first Kratix Promise! This guide will follow the steps below:

  1. Install the Jenkins Promise
  2. Request a new Jenkins instance
  3. Use the instance
  4. Cleanup environment

Overview

Install the Jenkins Promise​

tip

In this guide, we will be using Promises available on the Kratix Marketplace. The commands below will refer to a KRATIX_MARKETPLACE_REPO env variable. You can either:

  • clone the Kratix Marketplace and set it to the path of your local clone:
    export KRATIX_MARKETPLACE_REPO=/path/to/kratix-marketplace
  • set it to a remote URL:
    export KRATIX_MARKETPLACE_REPO="https://raw.githubusercontent.com/syntasso/kratix-marketplace/main"

Installing a Kratix Promise is as simple as applying the Promise YAML definition on your Platform cluster:

kubectl --context $PLATFORM apply \
  --filename "${KRATIX_MARKETPLACE_REPO}/jenkins/promise.yaml"

Verify that your platform cluster has registered Jenkins as a new available Kratix Promise.

kubectl --context $PLATFORM get crds jenkins.marketplace.kratix.io

The above command will give an output similar to

NAME                            CREATED AT
jenkins.marketplace.kratix.io   2021-05-10T12:00:00Z

The Jenkins Promise requires the Jenkins Operator to be deployed to the worker clusters. Kratix will deploy the operator when you apply the Promise. You can verify that the Jenkins Operator is now installed
(This may take a few minutes so --watch will watch the command. Press Ctrl+C to stop watching)

kubectl --context $WORKER get pods --watch

The above command will give an output similar to (it may take a couple of minutes):

NAME                                READY   STATUS    RESTARTS   AGE
jenkins-operator-7886c47f9c-zschr   1/1     Running   0          1m

🎉 Congratulations! You have installed your first Kratix Promise, which means your application teams can now get on-demand instances of Jenkins from your platform.

Request a Jenkins Instance​

Application developers using your platform will be issued a Jenkins instance after applying a Kratix Resource Request.



Verify-Instance

Test your platform by acting as an application developer and submitting a Resource Request.

kubectl --context $PLATFORM apply \
    --filename "${KRATIX_MARKETPLACE_REPO}/jenkins/resource-request.yaml"

Verify that the Resource Request was issued on the platform cluster.

kubectl --context $PLATFORM get jenkins.marketplace.kratix.io

The above command will give an output similar to

NAME      STATUS
example   Resource requested

Eventually (it can take a couple of minutes), a new Jenkins instance should spin up on your worker cluster. You can verify this by running the following command:

Verify the instance was created on the worker cluster
(This may take a few minutes so --watch will watch the command. Press Ctrl+C to stop watching)

kubectl --context $WORKER get pods --watch

The above command will give an output similar to

NAME                                READY   STATUS    RESTARTS   AGE
jenkins-dev-example                 1/1     Running   0          1m
jenkins-operator-7886c47f9c-zschr   1/1     Running   0          10m

🎉 Congratulations! You have successfully requested and created an on-demand instance of Jenkins from your platform.

Use your Jenkins instance​

Access the Jenkins UI in a browser to ensure the instance is working.

note

Before you can access Jenkins UI, you must port forward from within the Kubernetes cluster to a local port on your computer. Running the port-forward command is continuous—as long as the command is running, the connection stays open.

Open a new terminal to request the port forward.

export WORKER=kind-worker
kubectl --context $WORKER port-forward jenkins-dev-example 8080:8080

You can find Jenkins credentials by running:

username
kubectl --context $WORKER get secret jenkins-operator-credentials-dev-example \
    -o 'jsonpath={.data.user}' | base64 -d
password
kubectl --context $WORKER get secret jenkins-operator-credentials-dev-example \
    -o 'jsonpath={.data.password}' | base64 -d

Navigate to http://localhost:8080 and log in with the credentials. In production, you want the credentials to be stored in a secure location where it could be accessed by the application team. In this example, credentials are stored as unencrypted Kubernetes secrets.

Summary​

You installed your first Kratix Promise on your platform. Well done!

To recap the steps you took:

  1. ✅  Installed the sample Jenkins Promise
  2. ✅  Requested an instance of Jenkins
  3. ✅  Tested the instance by logging in to the Jenkins UI

This is only the beginning of working with Promises. Next you will deploy three different Promises to provide a complete solution for an application team.

Clean up environment​

To clean up your environment you need to delete the Jenkins Resource Requests and the Jenkins Promise.

To delete the Jenkins Resource Requests:

kubectl --context $PLATFORM delete \
    --filename "${KRATIX_MARKETPLACE_REPO}/jenkins/resource-request.yaml"

Verify the Jenkins Resource Request in the platform cluster is gone

kubectl --context $PLATFORM get jenkins

and the resources for the Jenkins instance in the worker cluster have been deleted

kubectl --context $WORKER get pods

The above command will give an output similar to (it may take a couple of minutes)

NAME                                READY   STATUS    RESTARTS   AGE
jenkins-operator-7886c47f9c-zschr   1/1     Running   0          1m

Now you can delete the Jenkins Promise

kubectl --context $PLATFORM delete \
  --filename "${KRATIX_MARKETPLACE_REPO}/jenkins/promise.yaml"

Verify the Jenkins Promise is gone

kubectl --context $PLATFORM get promises

and the Jenkins Operator is deleted from the worker cluster (this might take a couple minutes)

kubectl --context $WORKER get pods

Alternatively, you could delete the Promise directly. Kratix will delete all instances on Promise deletion by default. For more details, check the deletion reference docs

🎉   Congratulations!​

✅   You have installed a Kratix Promise and used it to create on-demand instances of a service.
👉🏾   Now you will deploy a web app that uses multiple Kratix Promises.