Skip to content

Commit 60ac625

Browse files
SaphMBSaphMB
authored
Healthchecks Reference documentation (#173)
* feat: introduce healthcheck reference documentation * Document healthDefinition and HealthRecord CRDS * Document how the creation of HealthRecords propogate to the resource.status * docs: add writing a healthcheck guide * chore: clarify healthcheck reference documentation * docs: update healthcheck ske guide * fix: move assets to the right place * docs: update reference page for health checks * feat: health agent installation instructions * fix: the alert admonition does not exist 😅 * docs: add health check example on non k8s - not a step by step guide, more of a general example * docs: capitalize Health Checks in guide * fix: add context to hc guide commands * fix: small tweaks to the hc guide --------- Co-authored-by: Sapphire Mason-Brown <[email protected]> Co-authored-by: Derik Evangelista <[email protected]>
1 parent 4cbcfbf commit 60ac625

18 files changed

+1007
-0
lines changed

‎docs/main/03-reference/11-promises/01-intro.md

+16
Original file line numberDiff line numberDiff line change
@@ -115,6 +115,22 @@ spec:
115115
- name: pipeline-stage-1
116116
image: ghcr.io/myorg/pipeline-image-2
117117
- #...
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
118134
```
119135
120136
It's also possible to install Promises via a Promise Release. Check the [Promise Release](../promises/releases) docs for details.

‎docs/main/03-reference/15-resources/04-status.md

+46
Original file line numberDiff line numberDiff line change
@@ -214,3 +214,49 @@ kubectl wait redis/example --for=condition=ConfigureWorkflowCompleted --timeout=
214214
```
215215

216216
Once the condition is `True` the command will exit.
217+
218+
# Health Checks
219+
220+
When configured for a Resource, [Health Checks](../16-health-checks/01-intro.md) provide
221+
an indication of Resource Health and communicate this to the user via the `status` of
222+
the Resource.
223+
224+
When a Health Record exists for a given Resource, detailing the result of a Health Check
225+
for that resource, Kratix updates the Resource to reflect this result. Let's use the example
226+
of a Health Check for Resource Requests of a Psql Promise. Following the completion of a
227+
Health Check, a `HealthRecord` detailing the result is created:
228+
229+
```yaml
230+
apiVersion: platform.kratix.io/v1alpha1
231+
kind: HealthRecord
232+
metadata:
233+
name: dev-psql-health
234+
data:
235+
promiseRef:
236+
name: psql
237+
resourceRef:
238+
name: dev-psql
239+
namespace: default
240+
state: ready
241+
lastRun: 1531958400
242+
details:
243+
acceptingConnection: true
244+
```
245+
246+
Eventually the `status` of the corresponding request is updated with the information in
247+
the Health Record.
248+
249+
```yaml
250+
apiVersion: example.promise.syntasso.io/v1
251+
kind: Psql
252+
metadata:
253+
name: dev-psql
254+
namespace: default
255+
# ...
256+
status:
257+
healthRecord:
258+
state: ready
259+
lastRun: 1531958400
260+
details:
261+
acceptingConnections: true
262+
```

‎docs/main/03-reference/16-health-checks/01-intro.md

+11
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,11 @@
1+
---
2+
description: Documentation for health checks
3+
title: Health Check
4+
sidebar_label: Introduction
5+
---
6+
7+
A [Kratix Promise](../promises/intro) can include health checks to ensure the provisioned resource meets the definition of healthy for the Promised Service.
8+
9+
Imagine you have written a Promise that provisions a service that can be accessed via a HTTP endpoint. For each provisioned service, you want to ensure that the endpoint is up and running. Health checks provide a mechanism for you to validate that your provisioned resource is healthy.
10+
11+
For further information, check out the [Health Definition](./healthdefinition) and [Health Record](./healthrecord) documentation.

‎docs/main/03-reference/16-health-checks/02-health-definition.md

+51
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,51 @@
1+
---
2+
description: Documentation for the Health Definition Custom Resources
3+
title: Health Definition
4+
sidebar_label: Health Definition
5+
id: healthdefinition
6+
---
7+
8+
# Health Definition
9+
10+
When a Promise defines a Healthcheck, Kratix will automatically create a Health Definition for that Healthcheck when a Resource Resource request is made. A Health Definition is the outline of the task that will be performed on a Destination to verify the health of a Resource Request.
11+
12+
```yaml
13+
apiVersion: platform.kratix.io/v1alpha1
14+
kind: HealthDefinition
15+
metadata:
16+
name: healthdefinition
17+
namespace: default
18+
spec:
19+
# A reference to the Resource Request the Health Check should be performed against
20+
resourceRef:
21+
name: request-name
22+
namespace: default
23+
# A reference the Promise the Health Check should be performed against
24+
promiseRef:
25+
name: promise-name
26+
# The time or interval the check should run against
27+
# This can follow Cron syntax or macros such as @hourly
28+
schedule: "* * * * *"
29+
# The definition of the Resource the check will be performed against
30+
input: |
31+
apiVersion: mypromise.org/v1
32+
kind: someservice
33+
metadata:
34+
name: someservice
35+
namespace: default
36+
spec:
37+
example: data
38+
status:
39+
url: test.com
40+
# The task to be performed on the destination
41+
workflow:
42+
# A Pipeline that runs an ordered set of OCI compliant images to perform health checks
43+
apiVersion: platform.kratix.io/v1alpha1
44+
kind: Pipeline
45+
metadata:
46+
name: health
47+
spec:
48+
containers:
49+
- image: ghcr.io/myorg/health-check
50+
name: health
51+
```

‎docs/main/03-reference/16-health-checks/03-health-record.md

+30
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,30 @@
1+
---
2+
description: Documentation for the Health Definition Custom Resources
3+
title: Health Record
4+
sidebar_label: Health Record
5+
id: healthrecord
6+
---
7+
8+
A Health Record details the result of a Health Check that has run on a given Destination. When a Health Record exists for a given Resource Request, Kratix will update the Resource Request to reflect the details in the Health Record.
9+
10+
```yaml
11+
apiVersion: platform.kratix.io/v1alpha1
12+
kind: HealthRecord
13+
metadata:
14+
name: healthrecord-example
15+
data:
16+
promiseRef:
17+
name: promise-name
18+
# A reference to the Resource Request the Health Check should be performed against
19+
resourceRef:
20+
name: request-name
21+
namespace: default
22+
# The condition of the Health Check
23+
# Can be unknown, ready, unhealthy, healthy or degraded
24+
state: ready
25+
# The timestamp of the last time the Heath Check was executed
26+
lastRun: 1531958400
27+
# Optional: any additional details
28+
details:
29+
example: data
30+
```

‎docs/main/03-reference/16-health-checks/_category_.json

+9
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,9 @@
1+
{
2+
"label": "Health Checks",
3+
"position": 16,
4+
"link": {
5+
"type": "doc",
6+
"id": "main/reference/health-checks/intro"
7+
}
8+
}
9+

‎docs/main/03-reference/16-kratix-config/_category_.json ‎docs/main/03-reference/17-kratix-config/_category_.json

File renamed without changes.

‎docs/main/03-reference/16-kratix-config/kratix-config.md ‎docs/main/03-reference/17-kratix-config/kratix-config.md

File renamed without changes.

‎docs/ske/01-kratix/10-ske-health-agent.mdx

+101
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,101 @@
1+
---
2+
title: SKE Health Agent
3+
description: Documentation about the SKE Health Agent
4+
---
5+
6+
The SKE Health Agent is a health check agent to be installed in Kubernetes Destinations where health checks can be executed.
7+
8+
The Agent is released separately from SKE. Its releases can be found [here](../releases/ske-health-agent).
9+
10+
## Features
11+
12+
The Agent will:
13+
14+
* Schedule the execution of Health Check Workflows from the Destination
15+
* Persist the data from a health check into a state store
16+
17+
## Requirements
18+
19+
The Agent will write the health information to a state store. The Platform cluster must have a GitOps agent listening to the state store, so the resource health can be applied back to the Platform cluster.
20+
21+
## Install
22+
23+
To install, run the command below, replacing VERSION with the target version:
24+
25+
```
26+
kubectl apply -f https://syntasso-enterprise-releases.s3-website.eu-west-2.amazonaws.com/#k8s-health-agent/<VERSION>/manifests/ske-health-agent.yaml
27+
```
28+
29+
:::warning
30+
31+
For the SKE Health Agent to work, you will need to make sure that your Destination cluster can access the Image Registry.
32+
33+
:::
34+
35+
You will also need to create a ConfigMap and Secret with the credentials to access the state store. The format will depend on the type os state store you wish to use. The agent currently support two different types of state stores: S3-compatible buckets and Git repositories.
36+
37+
To configure a Git repository, create a ConfigMap and Secret with the following content:
38+
39+
```yaml
40+
apiVersion: v1
41+
kind: ConfigMap
42+
metadata:
43+
name: health-state-store-config
44+
namespace: k8s-health-agent-system
45+
data:
46+
stateStoreKind: "GitStateStore"
47+
url: # address
48+
secretName: <secret name>
49+
branch: # optional (default: main)
50+
---
51+
apiVersion: v1
52+
kind: Secret
53+
metadata:
54+
name: <secret name>
55+
namespace: k8s-health-agent-system
56+
type: kubernetes.io/basic-auth
57+
stringData:
58+
# for basicAuth
59+
username: # username
60+
password: # password / API Token
61+
```
62+
63+
:::info
64+
65+
`ssh` method for authentication is not currently supported.
66+
67+
:::
68+
69+
To configure a S3-compatible bucket, create a ConfigMap and Secret with the following content:
70+
71+
```yaml
72+
apiVersion: v1
73+
kind: ConfigMap
74+
metadata:
75+
name: health-state-store-config
76+
namespace: k8s-health-agent-system
77+
data:
78+
stateStoreKind: "BucketStateStore"
79+
endpoint: # address
80+
bucketName: # bucket name
81+
authMethod: # accessKey or IAM (default: accessKey)
82+
secretName: <secret name> # required for accessKey
83+
path: # path within the bucket; optional
84+
insecure: # true or false (default: false); optional
85+
---
86+
apiVersion: v1
87+
kind: Secret
88+
metadata:
89+
name: <secret name>
90+
namespace: k8s-health-agent-system
91+
type: kubernetes.io/basic-auth
92+
stringData:
93+
accessKeyID: # accessKey ID
94+
secretAccessKey: # secret access key
95+
```
96+
97+
:::warning
98+
99+
The configuration should be created _after_ installing agent, otherwise the namespace will not exist.
100+
101+
:::

0 commit comments

Comments
 (0)