Skip to content

Commit 1cd63bb

Browse files
stiv03stiv03
committed
Restructure and Add cf-app-health-check example to showcase health-check-interval
1 parent f3aed5c commit 1cd63bb

7 files changed

Lines changed: 170 additions & 6 deletions

File tree

‎README.adoc‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -25,6 +25,7 @@ Clone the repository, following the link:https://help.github.com/en/github/creat
2525
## Deploy CF Apps
2626
* link:/cf-app[Simple CF app example, managing app attributes & deploy parameters]
2727
* link:/cf-app-features[Managing CF app features with app-features parameter]
28+
* link:/cf-app-health-check[Configuring CF app health checks with health-check-* parameters]
2829
* link:/cf-app-docker[Docker images as cf apps]
2930
* link:/app-routes[Managing cf app routes]
3031
* link:/sharing-values-between-apps[Sharing configuration values between apps]

‎cf-app-health-check/README.adoc‎

Lines changed: 133 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,133 @@
1+
:toc:
2+
3+
# Configuring CF App Health Checks with MTA
4+
5+
This example shows how to configure Cloud Foundry application health checks through the MTA `health-check-*` parameters. Health checks determine when Cloud Foundry considers an app instance healthy after start and while it is running; misconfiguring them is a common cause of "app crashed" or "app never became healthy" failures on deploy.
6+
7+
## Official Documentation
8+
9+
For general information about module parameters, see:
10+
link:https://help.sap.com/docs/btp/sap-business-technology-platform/modules?locale=en-US#module-specific-parameters[SAP BTP Documentation - Module-Specific Parameters]
11+
12+
For the underlying Cloud Foundry concept, see:
13+
link:https://docs.cloudfoundry.org/devguide/deploy-apps/healthchecks.html[Cloud Foundry Docs - Using Application Health Checks]
14+
15+
## Overview
16+
17+
Four MTA parameters cover the full health-check surface of a CF application:
18+
19+
[cols="1,3", options="header"]
20+
|===
21+
| Parameter | Purpose
22+
| `health-check-type` | How CF probes the app: `http`, `port`, or `process`
23+
| `health-check-http-endpoint` | HTTP path CF requests when `health-check-type: http`
24+
| `health-check-timeout` | Seconds CF waits for the app to become healthy after start
25+
| `health-check-interval` | Seconds between successive health checks while the app runs
26+
|===
27+
28+
### Picking a `health-check-type`
29+
30+
[cols="1,3", options="header"]
31+
|===
32+
| Type | When to use it
33+
| `http` | The app serves HTTP and can respond with `2xx` on a known path. Pair with `health-check-http-endpoint`.
34+
| `port` | The app listens on the port CF assigns (`$PORT`) but does not serve HTTP, or you don't want to expose a health endpoint.
35+
| `process` | The app is not network-facing (worker, one-off task). CF only checks that the process is alive.
36+
|===
37+
38+
### About `health-check-interval`
39+
40+
`health-check-interval` is a newer MTA parameter, added in link:https://github.com/cloudfoundry/multiapps-controller/pull/1853[cloudfoundry/multiapps-controller#1853]. It maps to CF's v3 process `health_check.data.interval` field and controls how often the liveness check runs after the app is up. If you deploy this example against an older SAP Cloud Deployment service that predates that change, the parameter will be ignored (or reported as unknown). Omit the line in that case; the other three parameters have been supported for much longer.
41+
42+
## Try it out
43+
44+
### Deploy from directory
45+
This approach uses deployment descriptor `mtad.yaml` and ready application binaries `appBits.zip`:
46+
``` bash
47+
$ cf deploy ./ -f ;
48+
```
49+
50+
### Build and deploy
51+
This approach uses development descriptor `mta.yaml` and application binaries `appBits.zip` to build an MTAR archive:
52+
53+
``` bash
54+
$ mbt build -p cf -t . ;
55+
```
56+
57+
The built MTAR is then deployed:
58+
59+
``` bash
60+
$ cf deploy cf.app.health.check_0.0.0.mtar -f ;
61+
```
62+
63+
NOTE: See link:mta.yaml[mta.yaml] or link:mtad.yaml[mtad.yaml] for the full parameter set.
64+
65+
### Examine the result
66+
67+
#### List the deployed MTA
68+
```bash
69+
$ cf mta cf.app.health.check ;
70+
Showing health and status for multi-target app cf.app.health.check in org **** / space **** as ****...
71+
OK
72+
Version: 0.0.0
73+
Namespace:
74+
75+
Apps:
76+
name requested state instances memory disk urls
77+
my-health-checked-app-module STARTED 1/1 19.6M 5.3M orgname-spacename-my-health-checked-app-module.example.com
78+
```
79+
80+
#### Verify the health check landed on the CF process
81+
Inspect the `health_check` block on the app's web process. All four values from the MTA descriptor should be reflected here:
82+
83+
``` bash
84+
$ cf curl "/v3/apps/$(cf app my-health-checked-app-module --guid)/processes" ;
85+
{
86+
"resources": [
87+
{
88+
"type": "web",
89+
"instances": 1,
90+
"health_check": {
91+
"type": "http",
92+
"data": {
93+
"timeout": 180,
94+
"invocation_timeout": null,
95+
"interval": 15,
96+
"endpoint": "/index"
97+
}
98+
},
99+
...
100+
}
101+
]
102+
}
103+
```
104+
105+
If `interval` is `null` in the output despite being set in the descriptor, the deploy service is older than link:https://github.com/cloudfoundry/multiapps-controller/pull/1853[multiapps-controller#1853].
106+
107+
### Use Cases
108+
109+
Fast-recovering web app (frequent checks, short grace period):
110+
```yaml
111+
health-check-type: http
112+
health-check-http-endpoint: "/health"
113+
health-check-timeout: 30
114+
health-check-interval: 5
115+
```
116+
117+
Slow-starting app that only needs to open a port:
118+
```yaml
119+
health-check-type: port
120+
health-check-timeout: 300
121+
health-check-interval: 30
122+
```
123+
124+
Background worker with no listening port:
125+
```yaml
126+
health-check-type: process
127+
health-check-timeout: 60
128+
```
129+
130+
### Related Examples
131+
132+
* link:../cf-app[Simple CF app example, managing app attributes & deploy parameters]
133+
* link:../cf-app-features[Managing CF app features with app-features parameter]

‎cf-app-health-check/appBits.zip‎

504 Bytes
Binary file not shown.

‎cf-app-health-check/mta.yaml‎

Lines changed: 18 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,18 @@
1+
ID: cf.app.health.check
2+
_schema-version: 3.3.0
3+
version: 0.0.0
4+
5+
modules:
6+
# CF app demonstrating the full set of health-check-* parameters
7+
- name: my-health-checked-app-module
8+
type: application
9+
path: "appBits.zip"
10+
parameters:
11+
memory: 1G
12+
disk-quota: 1G
13+
instances: 1
14+
# Health Check Configuration
15+
health-check-type: http # http / port / process
16+
health-check-http-endpoint: "/index" # only relevant when health-check-type is http
17+
health-check-timeout: 180 # seconds to wait for the first successful check after start
18+
health-check-interval: 15 # seconds between checks; requires a recent MultiApps Controller (see README)

‎cf-app-health-check/mtad.yaml‎

Lines changed: 18 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,18 @@
1+
_schema-version: 3.3.0
2+
ID: cf.app.health.check
3+
version: 0.0.0
4+
5+
modules:
6+
# CF app demonstrating the full set of health-check-* parameters in deployment descriptor
7+
- name: my-health-checked-app-module
8+
type: application
9+
path: "appBits.zip"
10+
parameters:
11+
memory: 1G
12+
disk-quota: 1G
13+
instances: 1
14+
# Health Check Configuration
15+
health-check-type: http # http / port / process
16+
health-check-http-endpoint: "/index" # only relevant when health-check-type is http
17+
health-check-timeout: 180 # seconds to wait for the first successful check after start
18+
health-check-interval: 15 # seconds between checks; requires a recent MultiApps Controller (see README)

‎cf-app/mta.yaml‎

Lines changed: 0 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -27,8 +27,5 @@ modules:
2727
routes: # if not defined, a default route would be auto assigned unless no-route is specified
2828
- route: ${default-host}.${default-domain}
2929
upload-timeout: 180 #seconds
30-
health-check-type: http #http/port/process
31-
health-check-http-endpoint: "/index" # the http route pinged
32-
health-check-timeout: 180 #seconds
3330
app-features:
3431
ssh: true

‎cf-app/mtad.yaml‎

Lines changed: 0 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -27,8 +27,5 @@ modules:
2727
routes: # if not defined, a default route would be auto assigned unless no-route is specified
2828
- route: ${default-host}.${default-domain}
2929
upload-timeout: 180 #seconds
30-
health-check-type: http #http/port/process
31-
health-check-http-endpoint: "/index" # the http route pinged
32-
health-check-timeout: 180 #seconds
3330
app-features:
3431
ssh: true

0 commit comments

Comments
 (0)