Skip to main content

Surfacing information via Status

This is Part 4 of a series illustrating how to write Kratix Promises.

πŸ‘ˆπŸΎ Previous: Accessing secrets and storing state
πŸ‘‰πŸΎ Next: Writing Compound Promises

In the previous tutorial, you learned how to access secrets and states from a Pipeline. In this section, you will learn how to surface information to users via the status of a Resource.

You will:

Conveying information back to the application developers​

What we've focused on so far is how to define a Kratix Promise in a compelling way so that platform users choose to use the platform. A Kratix-powered platform enables users to ask for the services they need, on-demand, without having to know unnecessary business and service lifecycle requirements.

What platform users need, though, is the end-to-end experience of making a simple request, understanding what's happening with the request, then ultimately making use of the service created by the request. So how do you communicate information about a request back to platform users, and how do users use the services that the platform creates?

There are actually a number of ways you can communicate the status of a service to the platform, and the choice comes down to the Promise and Promise Workflow author.

One approach is to generate notifications for internal systems like Slack or Teams from the Promise Workflow's Pipeline container.

Another approach, which is what we'll choose today, is to follow convention and leverage the status field on Kubernetes resources. The Kratix Workflow's Pipeline has the ability to write information back to the status of the Resource.

In the context of your Promise, an example of what you might want to convey back is the configuration of the Resource (e.g. default configuration), and how to access the running Resources (e.g. a URL or connection string).


As we saw in Promise Workflows, within the Pipeline container file system, Kratix mounts a /kratix/metadata directory to manage important configuration that is independent of the Resources definitions for your State Store.

In this section, you will focus on one of the files in the metadata directory: status.yaml.

The status.yaml file can contain arbitrary key-value pairs. Anything you write in this file will be persistent in the resource, and visible when the user inspects it.

The message key is a special key that is displayed as part of the kubectl get resource command.

With that in-mind, you can update your existing workflows/resource-configure script to surface some information about the Resource in the status.yaml file. One of the things you may want to surface is, for example, the URL of the running application. You also want to expose the date the resource was created, as a human-friendly string.


Kubernetes automatically adds a metadata.creationTimestamp field to all resources. The date you will add to the status is only to illustrate how to add dynamic information to the status.

Add the following lines to the end of your workflow/resource-configure script:


# Set the resource status
cat <<EOF > /kratix/metadata/status.yaml
createdAt: ${createdAt}
message: "${name}"

Next, run the tests:

./scripts/test-pipeline resource-configure

You should see the following in your local directory:

πŸ“ app-promise
└── test
Β Β  β”œβ”€β”€ input
Β Β  β”‚Β Β  └── object.yaml
Β Β  β”œβ”€β”€ metadata
Β Β  β”‚Β Β  └── status.yaml
Β Β  └── output
Β Β  β”œβ”€β”€ deployment.yaml
Β Β  β”œβ”€β”€ ingress.yaml
Β Β  └── service.yaml

If you inspect the test/metadata/status.yaml file, you should see something like the following:

createdAt: "Wed Jan 1 15:00:00 UTC 2023"
message: ""

Excellent. With that file in place, Kratix will automatically persist that information to the status of the Resource. The next time the pipeline runs, the input/object.yaml file will contain the status field with the information persisted from the status.yaml.

However our pipeline is not, once again, idempotent. If you run the pipeline again, you will see that the createdAt field is updated to the current date. You can fix this by checking the status on the resource, and only updating the status if it is not already set.

Update your workflow/resource-configure script to the following:

createdAt=$(yq '.status.createdAt // ""' /kratix/input/object.yaml)
if [ -z "$createdAt" ]; then

# Set the resource status
cat <<EOF > /kratix/metadata/status.yaml
createdAt: "$(createdAt)"
message: "${name}"

Now test your changes:

./scripts/test-pipeline resource-configure

Inspect the test/metadata/status.yaml file. Since your input does not contain the status field, you should see today's date in the createdAt field. Now, to test that the status is not updated if it already exists, change your test input to look like the following:

kind: App
name: my-app
namespace: default
image: example/image:v1.0.0
port: 9000
createdAt: "Thu Jan 28 15:00:00 UTC 2021"
message: ""

Re-run the tests:

./scripts/test-pipeline resource-configure

If you inspect the test/metadata/status.yaml file now, you should see the following:

createdAt: "Thu Jan 28 15:00:00 UTC 2021"
message: ""

Great! Now you have a way to persist information about your Resource, and you have a way to ensure that the information is not overwritten if it already exists.

ApplicationEngineereasy appConfigure Workflowobject.yaml/inputs//outputs/metadata/status.yamlresource-configureConfigure Workflowobject.yaml/inputs//outputs/metadata/status.yamlresource-configurecreatedAt: Thurs...message: my-app...status: createdAt: Thurs... message: my-app... easy appstatus: createdAt: Thurs... message: my-app... createdAt: Thurs...message: my-app...
Flow of the Status update for the app Promise

This time, you haven't changed the Promise at all, but rather updated the underlying pipeline image. The existing resources will automatically get the new status information on the next reconciliation.

Just like last time, you can force a reconciliation by adding the = true label:

kubectl --context $PLATFORM label todo

Once the pipeline completes, you should see the new status information on the Resource:

kubectl --context $PLATFORM describe todo

The above command outputs something similar to the following:

Name:         todo
Namespace: default
Labels: <none>
Annotations: <none>
API Version:
Kind: App
Creation Timestamp: 2024-01-31T15:27:43Z
Generation: 1
Resource Version: 814088
UID: 19266d15-6362-4a54-85fb-b4965af65c24
Image: syntasso/sample-todo:v0.1.0
Port: 8080
Last Transition Time: 2024-01-31T16:15:38Z
Message: Pipeline completed
Reason: PipelineExecutedSuccessfully
Status: True
Type: PipelineCompleted
Created At: Wed Jan 1 15:01:01 UTC 2023
Events: <none>

Note how the status field is now populated with the information you added to the status.yaml file.


You may also notice that there's a condition called PipelineCompleted. This is a special condition that is automatically added to the status of the Resource, and set to True when the pipeline completes successfully.

Furthermore, the value for the message key should also be displayed as part of the get command:

kubectl --context $PLATFORM get

The above command should output the following:


Try retriggering the reconcilation by adding the label again. You should notice that the CreatedAt field is not updated, just like you observed in the test.

πŸŽ‰ Β  Congratulations!​

You successfully surfaced information back to the user by writing to the resource status! You Promise is getting more and more useful.

To recap what you achieved:

  1. βœ…Β Β Learned how to use metadata to set a custom Resource status
  2. βœ…Β Β Learned how to make writing to status idempotent

πŸ‘‰πŸΎΒ Β  Next, let's add support for stateful applications.