You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
Teams responsible for building and maintaining platforms often struggle to meet the growing expectations of application teams and organisations. Delivering the right services quickly, safely, and consistently is already challenging—adding Day 2 operations like upgrades and continuous improvements can lead to burnout.
37
+
38
+
With Kratix and Promises, Platform Engineers can offer anything-as-a-service, consistently enforce business rules, and streamline maintenance by managing all resources collectively, like a fleet.
39
+
:::tip
40
+
Learn more about platform team cognitive load from [Paula Kennedy at PlatformCon](https://www.youtube.com/watch?v=zfKwxL9KZ9I)
Many organisations have teams that specialise in specific domains, such as security, compliance, databases, or networking. These teams are responsible for ensuring that application teams follow the relevant business rules and policies.
45
+
46
+
With Promises, domain specialists can guarantee that every service request adheres to compliance requirements automatically. When policies change, they only need to update a Promise once—Kratix ensures all instances of their services are updated accordingly.
47
+
48
+
### Application Developers
49
+
Many application teams face delays waiting for essential platform services, leading to poor developer experience (DevEx), workarounds, shadow IT, and missed deadlines. The additional concerns—such as infrastructure, networking, security policies, and billing limits—can overwhelm teams, diverting focus from delivering value.
50
+
51
+
Effective platforms minimise cognitive load by offering everything-as-a-service with built-in business rules and policies. Kratix and Promises enable this while allowing Platform teams to provide services at the right level of abstraction—hiding complexity from those who don’t need to manage it.
52
+
33
53
## Kratix in action
34
54
Watch how Kratix supports teams using Backstage to provide anything-as-a-service.
35
55
<divalign="center"><iframewidth="560"height="315"src="https://www.youtube.com/embed/LlHHovxfJDg?si=326slhM8-yPPSFem"title="YouTube video player"frameborder="0"allow="accelerometer; autoplay; clipboard-write; encrypted-media; gyroscope; picture-in-picture; web-share"referrerpolicy="strict-origin-when-cross-origin"allowfullscreen></iframe></div>
Copy file name to clipboardexpand all lines: docs/main/03-reference/11-promises/01-intro.md
+78-62
Original file line number
Diff line number
Diff line change
@@ -6,10 +6,19 @@ description: Documentation for the Kratix Promise Custom Resource
6
6
7
7
# Promises
8
8
9
-
Conceptually, Kratix Promises are the building blocks that enable teams to design
10
-
platforms that specifically meet their customer needs.
9
+
At the core of Kratix are Promises. Promises are a set of instructions written in YAML that will produce a [resource](../resources/intro) whenever the Promise is invoked. This means that you can run software-as-a-service from your platform. A Promise consists of the dependencies it must setup before the Promise can be requested, an API description of how a user can request that Promise, the workflows that define how the provisioning takes place, and destination rules that allow the Promise Author to determine where resources should go.
11
10
12
-
Technically, a Promise is a YAML document that defines a contract between the Platform and its users.
11
+
This introduction is intended for platform engineers and people creating promises for use by the rest of their organisation.
12
+
13
+
```mdx-code-block
14
+
import PromiseHighLevel from "/img/docs/promise-high-level.png"
15
+
```
16
+
17
+
<figureclassName="diagram">
18
+
<imgclassName="small"src={PromiseHighLevel}alt="High level diagram of the parts of a Promise - API, Dependencies, Workflows and Destinations Rules" />
19
+
20
+
<figcaption>High level diagram of the parts of a Promise - API, Dependencies, Workflows and Destinations Rules</figcaption>
21
+
</figure>
13
22
14
23
## Use Case
15
24
@@ -25,24 +34,9 @@ those low-level tasks. It can be designed as a single Promise that does it all,
25
34
or it can be a collection of Promises that, combined, deliver the desired
26
35
functionality.
27
36
28
-
## Benefits
29
-
30
-
Promises:
31
-
32
-
- enable you to build your platform incrementally and in response to the needs
33
-
of your users.
34
-
- codify the contract between platform teams and application teams for the
35
-
delivery of a specific service, e.g. a database, an identity service, a
36
-
supply chain, or a complete development pipeline of patterns and tools.
37
-
- are easy to build, deploy, and update.
38
-
- are shareable and reusable between platforms, teams, business units, and other
39
-
organisations.
40
-
- add up to a frictionless experience when platform users want to create
41
-
services that they need to deliver value.
42
-
43
37
To see Promises in-action, check out the guides: [Installing a Promise](../../guides/installing-a-promise) and [Writing a Promise](../../guides/writing-a-promise).
44
38
45
-
## Promise API
39
+
## The Promise API
46
40
47
41
```yaml
48
42
apiVersion: platform.kratix.io/v1alpha1
@@ -54,18 +48,11 @@ metadata:
54
48
# optional: the version of this promise
55
49
kratix.io/promise-version: v1.0.0
56
50
spec:
57
-
# Check the scheduling docs for details
58
-
destinationSelectors:
59
-
- matchLabels:
60
-
# Arbitrary key/value pairs that will be used for scheduling
61
-
key: value
62
-
63
-
# A list of Promises that are required by the Promise
64
-
# All required Promises must be present and available for this promise to be made available
65
-
requiredPromises:
66
-
- name: required-promise-name
67
-
version: required-promise-version
68
-
51
+
# API that a Platform User will use to request an Resource from this Promise
52
+
api:
53
+
apiVersion: apiextensions.k8s.io/v1
54
+
kind: CustomResourceDefinition
55
+
# ...
69
56
# Array of Kubernetes resources to be scheduled to matching Workers
70
57
dependencies:
71
58
- apiVersion: apps/v1
@@ -74,63 +61,92 @@ spec:
74
61
name: service-operator
75
62
- #...
76
63
- #...
77
-
78
-
# API that a Platform User will use to request an Resource from this Promise
79
-
api:
80
-
apiVersion: apiextensions.k8s.io/v1
81
-
kind: CustomResourceDefinition
82
-
# ...
83
-
84
64
# Ordered set of tasks to run during a Promise and Resource lifecycle
85
65
workflows:
86
-
# Tasks to be run only during the Resource lifecycle
87
-
resource:
88
-
# Tasks to be run only on creation, maintenance, or update of a Resource
66
+
# Tasks to be run only during the Promise lifecycle
67
+
promise:
68
+
# Tasks to be run only on creation, maintenance, or update of the Promise
89
69
configure:
90
70
# A Kratix provided Pipeline that runs an ordered set of OCI compliant images
91
71
- apiVersion: platform.kratix.io/v1alpha1
92
72
kind: Pipeline
93
73
metadata:
94
-
name: configure-resource
74
+
name: configure-promise
95
75
spec:
96
76
containers:
97
77
- name: pipeline-stage-0
98
78
image: myorg/pipeline-image-1 # Kubernetes defaults to docker.io
99
79
- name: pipeline-stage-1
100
80
image: ghcr.io/myorg/pipeline-image-2
101
81
- #...
102
-
# Tasks to be run only during the Promise lifecycle
103
-
promise:
104
-
# Tasks to be run only on creation, maintenance, or update of the Promise
82
+
# Tasks to be run when a Promise is deleted
83
+
delete:
84
+
- apiVersion: platform.kratix.io/v1alpha1
85
+
kind: Pipeline
86
+
metadata:
87
+
name: delete-promise
88
+
spec:
89
+
containers:
90
+
- #...
91
+
# Tasks to be run only during the Resource lifecycle
92
+
resource:
93
+
# Tasks to be run only on creation, maintenance, or update of a Resource
105
94
configure:
106
95
# A Kratix provided Pipeline that runs an ordered set of OCI compliant images
107
96
- apiVersion: platform.kratix.io/v1alpha1
108
97
kind: Pipeline
109
98
metadata:
110
-
name: configure-promise
99
+
name: configure-resource
111
100
spec:
112
101
containers:
113
102
- name: pipeline-stage-0
114
103
image: myorg/pipeline-image-1 # Kubernetes defaults to docker.io
115
104
- name: pipeline-stage-1
116
105
image: ghcr.io/myorg/pipeline-image-2
117
106
- #...
118
-
# Healthcheck to be performed for requests of the Promise
119
-
healthChecks:
120
-
resource:
121
-
# The time or interval the check should run against
122
-
# This can follow Cron syntax or macros such as @hourly
123
-
schedule: "* * * * *"
124
-
# A Pipeline that runs an ordered set of OCI compliant images to perform health checks
125
-
workflow:
126
-
apiVersion: platform.kratix.io/v1alpha1
127
-
kind: Pipeline
128
-
metadata:
129
-
name: health
130
-
spec:
131
-
containers:
132
-
- image: ghcr.io/myorg/health-check
133
-
name: health
107
+
# Tasks to be run when a Resource is deleted
108
+
delete:
109
+
- apiVersion: platform.kratix.io/v1alpha1
110
+
kind: Pipeline
111
+
metadata:
112
+
name: delete-resource
113
+
spec:
114
+
containers:
115
+
- #...
116
+
# Check the scheduling docs for details
117
+
destinationSelectors:
118
+
- matchLabels:
119
+
# Arbitrary key/value pairs that will be used for scheduling
120
+
key: value
121
+
# A list of Promises that are required by the Promise
122
+
# All required Promises must be present and available for this promise to be made available
123
+
requiredPromises:
124
+
- name: required-promise-name
125
+
version: required-promise-version
134
126
```
127
+
:::info
128
+
Learn more about the requiredPromises fields in the [Compound Promise Workshop](../../../workshop/part-ii/compound-promise#defining-promises-as-required-promises).
129
+
:::
130
+
135
131
136
132
It's also possible to install Promises via a Promise Release. Check the [Promise Release](../promises/releases) docs for details.
133
+
134
+
### API
135
+
When a platform engineer installs a Promise, Kratix creates a new API that application developers use to create and customise their resources using the available API options.
136
+
When the API request is submitted to Kratix, the Promise uses the API options to create the resources as described in the Promise.
137
+
For example, if the Promise describes a database, a Jenkins installation, and an update script, calling the Promise from the API will generate a new instance of all of those resources for the user.
138
+
139
+
### Dependencies
140
+
Dependencies are everything that the Promise relies on to function. A Kratix Promise can even be built on other Kratix Promises. A dependency is the pre-requisite software to create the resource and make it operational. A dependency might be a low-level resource such as a database, a pre-defined environment, a connection, a queue, or a bundle of related items that work together.
141
+
142
+
### Workflows
143
+
Workflows are the actions that must run in order to fulfil a Promise. They are a chain of containers that execute in sequence to fulfill the promise specifications, including responses to API specifications, notifications, business rules, and custom specifications.
144
+
145
+
The Promise workflows are run as part of the Promise lifecycle, and the Resource workflows are run as part of the Resource lifecycle. Under both Promise and Resource workflows, Kratix supports two workflow types:
146
+
- The `configure` workflows runs when either the Promise or Resource is created, updated or reconciled.
147
+
- The `delete` workflow runs when either the Promise or Resource is deleted.
148
+
149
+
You can learn more about [Promise Workflows](workflows) and [Resource Workflows](../resources/workflows) in their respective docs.
150
+
151
+
### Destination Rules
152
+
Destination rules are defined in the `destinationSelectors` section of the Promise spec. These are the rules that all the Promise will follow when determining where resources should go. Learn more about how to use destinationSelectors as part of [multi-destination scheduling](../destinations/multidestination-management#promises).
When getting started with Kratix, many people install a Marketplace Promise to experiment with. As you use it, it may become clear that you need a more customised solution.
9
+
10
+
You clone the Promise and tweak the Promise description to apply to your own environment. You then install it so the Promise is available for request.
11
+
12
+
This iterative writing is useful because it allows you to use the structure of existing Promises to customise what you want for your own platform. Once you’re comfortable with modifying existing Promises, creating your own from scratch is more natural.
13
+
14
+
We suggest these examples as good starting places:
You create a Promise by assembling a YAML file which defines all the dependencies and workflows that the Promise will include. It also defines the API that is used to request a resource. Once the Promise is written, it needs to be installed so that the dependencies it refers to will be available when a user requests them.
20
+
21
+
Below is an example of a Promise contains all the essential elements. For Promises that have more complexity, you can see the Promise Marketplace.
22
+
23
+
First, there is the metadata that describes the Promise name, version, and labels.
24
+
25
+
```apiVersion: platform.kratix.io/v1alpha1
26
+
kind: Promise
27
+
metadata:
28
+
name: app-example
29
+
labels:
30
+
kratix.io/promise-version: v0.1.0
31
+
```
32
+
Then the specification describes how the resources will be created.
33
+
34
+
```
35
+
Spec:
36
+
```
37
+
38
+
Dependencies are all the things required for the platform to run the Promise. For example, a Promise might create a namespace.
39
+
40
+
```
41
+
dependencies:
42
+
- apiVersion: v1
43
+
kind: Namespace
44
+
metadata:
45
+
name: promise-example
46
+
```
47
+
48
+
The API is how the user creates and customises their resources. Using the API, application teams can create, update, or delete promise instances. Users can also use the API to customise the Promise request in ways made available by the Promise. For example, the container image of a resource or its size.
49
+
50
+
```
51
+
api:
52
+
apiVersion: apiextensions.k8s.io/v1
53
+
kind: CustomResourceDefinition
54
+
metadata:
55
+
name: apps.marketplace.kratix.io
56
+
spec:
57
+
group: marketplace.kratix.io
58
+
names:
59
+
kind: app
60
+
plural: apps
61
+
singular: app
62
+
scope: Namespaced
63
+
versions:
64
+
- name: v1alpha1
65
+
schema:
66
+
openAPIV3Schema:
67
+
properties:
68
+
spec:
69
+
properties:
70
+
image:
71
+
description: container image for application that will be deployed
72
+
example: gcr.io/syntasso/great-app
73
+
type: string
74
+
type: object
75
+
type: object
76
+
served: true
77
+
storage: true
78
+
```
79
+
80
+
Workflows are a series of containers executed in sequence. Putting the actions in containers allows them to be consistent and reusable. Containerising the actions allows for maximum flexibility in language and modularity while maximising testability.
81
+
82
+
```
83
+
workflows:
84
+
resource:
85
+
configure:
86
+
- apiVersion: platform.kratix.io/v1alpha1
87
+
kind: Pipeline
88
+
metadata:
89
+
name: configure-resource
90
+
spec:
91
+
containers:
92
+
- name: pipeline-stage-0
93
+
image: myorg/pipeline-image-1 # Kubernetes defaults to docker.io
Installing a Promise is a simple application of the Promise YAML file to the platform cluster. The API is then available for users to call, promise-workflows execute, and the dependencies are installed and made available so that the Promise can be fulfilled when it is requested. A promise exists on the platform cluster and can be called to create an consistent promise instance at any time.
Copy file name to clipboardexpand all lines: docs/main/03-reference/11-promises/03-updates.md
+3-3
Original file line number
Diff line number
Diff line change
@@ -4,19 +4,19 @@ sidebar_label: Updates
4
4
description: Documentation on how updates behave for Promises
5
5
---
6
6
7
-
Kratix supports updating Promises with new specifications.
8
-
9
7
An update to a Promise will cause Kratix to reconcile on the new Promise definition,
10
8
and any changes will be rolled out during this reconciliation.
11
9
12
-
This may include:
10
+
All elements of a promise are updatable. Any change to the Promise specification on the platform triggers all of the workflows to re-run. Changes may include:
13
11
- Updating the Promise API, which rolls out an update to the underlying CRD for the
14
12
Resources managed by the Promise.
15
13
- Updating the Promise or Resource workflows.
16
14
- Updating the Promise scheduling.
17
15
- Updating the Promise's static dependencies (the `dependencies` field in the Promise
18
16
spec).
19
17
18
+
This central distribution of updates is a powerful way to keep your Promise-built resources current, secure, and visible over time.
19
+
20
20
## Workflows
21
21
22
22
Any update to the Promise `spec` will result in Kratix re-running the Promise Configure
Copy file name to clipboardexpand all lines: docs/main/03-reference/11-promises/04-delete.md
+1-6
Original file line number
Diff line number
Diff line change
@@ -3,12 +3,7 @@ description: Documentation for deleting a Kratix Promise
3
3
title: Deleting a Promise
4
4
sidebar_label: Deleting
5
5
---
6
-
7
-
:::caution
8
-
9
-
Deleting a Promise will cascade delete all the associated requested Resources and Dependencies.
10
-
11
-
:::
6
+
Deleting a Promise deletes both the Promise and all the resources and dependencies associated with it. Deleting a Promise runs the specific delete workflow that is declared in the Promise. Once the delete workflow runs, the resources uniquely associated with that Promise are removed from the platform and finally the Promise itself is removed from the platform.
12
7
13
8
To delete a Promise, run the command below, making sure to replace the
14
9
`<promise name>` with the Promise you want to remove:
0 commit comments