Skip to content

Commit 1b653ed

Browse files
abbi-gauravabbi-gaurav
committed
Apply review feedback
1 parent d038f89 commit 1b653ed

2 files changed

Lines changed: 219 additions & 210 deletions

File tree

‎from-zero-to-cap-on-kyma/README.md‎

Lines changed: 123 additions & 121 deletions
Original file line numberDiff line numberDiff line change
@@ -1,14 +1,15 @@
11
# Overview
22

3-
In this sample, we will start from scratch / zero to deploying an [CAP](https://cap.cloud.sap/docs/) NodeJS application on Kyma runtime.
3+
Using this sample, you start from scratch to deploy a [CAP](https://cap.cloud.sap/docs/) NodeJS application on SAP BTP, Kyma runtime.
44

55
![cap-bookshop](assets/cap-booksop.png)
66

7-
- You will create a sample Node.JS based CAP application (Bookshop)
8-
- Using cds, you will create the necessary artifacts and configurations required to deploy on Kyma.
9-
- Last, but not least, you will deploy and verify your running CAP application on SAP BTP, Kyma runtime.
7+
- You create a sample NodeJS-based CAP application, namely the Bookshop.
8+
- You use Core Data Services (CDS) to create the necessary artifacts and configurations required to deploy the application on Kyma.
9+
- You deploy and verify your running CAP application on SAP BTP, Kyma runtime.
1010

11-
> Note: For simplification most of the commands have been defined using the [Makefile](Makefile). In case you want to understand what the actual command is, run `make <command> --just-print`
11+
> [!Note]
12+
> For simplification most of the commands are defined using the [Makefile](Makefile). If you want to understand what the actual command is, run `make <command> --just-print`.
1213
1314
## Prerequisites
1415

@@ -24,177 +25,180 @@ In this sample, we will start from scratch / zero to deploying an [CAP](https://
2425

2526
## CAP Application
2627

27-
- Initialize the Cap Bookshop sample
28+
1. Initialize the CAP Bookshop sample.
2829

29-
```shell
30-
make init
31-
```
30+
```shell
31+
make init
32+
```
3233

33-
Let's take a minute to inspect our cap application. It is a simple Bookshop sample where you can access Book entries via API calls.
34+
The initialized application is a simple Bookshop sample where you can access Book entries using API calls.
35+
- Data model defined in [./bookshop/db/schema.cds](./bookshop/db/schema.cds). <!-- markdown-link-check-disable-line -->
36+
- CDS defined in [./bookshop/srv/cat-service.cds](./bookshop/srv/cat-service.cds). <!-- markdown-link-check-disable-line -->
3437

35-
- Data model defined in [./bookshop/db/schema.cds](./bookshop/db/schema.cds) <!-- markdown-link-check-disable-line -->
36-
- Core Data Service defined in [./bookshop/srv/cat-service.cds](./bookshop/srv/cat-service.cds) <!-- markdown-link-check-disable-line -->
38+
> [!NOTE]
39+
> CAP promotes getting started with minimal upfront setup, based on convention over configuration, and a grow-as-you-go approach, adding settings and tools later on, only when you need them. For more information, see [Introduction to CAP](https://cap.cloud.sap/docs/about/).
3740
38-
Directly from CAP website, *CAP promotes getting started with minimal upfront setup, based on convention over configuration, and a grow-as-you-go approach, adding settings and tools later on, only when you need them.*
41+
2. Run the application locally.
3942

40-
- Run the application locally
43+
```shell
44+
make run-local
45+
```
4146

42-
```shell
43-
make run-local
44-
```
47+
3. Access the CAP Srv at <http://localhost:4004>.
48+
4. Terminate the local running app with `^C`.
4549

46-
- Access the CAP Srv at <http://localhost:4004>
47-
- Terminate the local running app with `^C`
50+
## Deploying to Kyma
4851

49-
## Deploy to Kyma
52+
### Adding the Default Route for Application Router
5053

51-
### Add default route for App router
54+
1. Update the [bookshop/app/router/xs-app.json](bookshop/app/router/xs-app.json) to add a default route for the app router. This is required to access the CAP application via the URL. The end json should look as below: <!-- markdown-link-check-disable-line -->
5255

53-
- Update the [bookshop/app/router/xs-app.json](bookshop/app/router/xs-app.json) <!-- markdown-link-check-disable-line -->
54-
to add a default route for the app router. This is required to access the CAP application via the URL. The end json should look as below:
56+
```json
57+
{
58+
"welcomeFile": "/odata/v4/catalog/Books",
59+
"routes": [
60+
{
61+
"source": "^/(.*)$",
62+
"target": "$1",
63+
"destination": "srv-api",
64+
"csrfProtection": true
65+
}
66+
]
67+
}
68+
```
5569

56-
```json
57-
{
58-
"welcomeFile": "/odata/v4/catalog/Books",
59-
"routes": [
60-
{
61-
"source": "^/(.*)$",
62-
"target": "$1",
63-
"destination": "srv-api",
64-
"csrfProtection": true
65-
}
66-
]
67-
}
68-
```
70+
> [!Note]
71+
> The standalone Application Router is used to simplify the setup and **is not a must**. It should be also possible to use the managed approuter because your CAP APIs are exposed via Fiori or UI5 applications and accessed using workzone.
6972
70-
> Note: The standalone approuter is being used for a simpler sample and **is not a must**. It should be possible to use the managed approuter as well as have you CAP APIs being exposed via Fiori or UI5 applications and accessed using workzone.
73+
### Configuring Environment Variables
7174

72-
### Configure environment variables
75+
1. Set up the required environment variables:
7376

74-
- Set up required environment variables
77+
- In shell
7578

76-
- In shell
79+
```shell
80+
export KUBECONFIG=<your-kubeconfig-file-path>
81+
export NAMESPACE=<your-kyma-namespace>
82+
```
7783

78-
```shell
79-
export KUBECONFIG=<your-kubeconfig-file-path>
80-
export NAMESPACE=<your-kyma-namespace>
81-
```
84+
- In Windows powershell
8285

83-
- In Windows powershell
86+
```powershell
87+
$ENV:KUBECONFIG="<your-kubeconfig-file-path>"
88+
$ENV:NAMESPACE="<your-kyma-namespace>"
89+
```
8490

85-
```powershell
86-
$ENV:KUBECONFIG="<your-kubeconfig-file-path>"
87-
$ENV:NAMESPACE="<your-kyma-namespace>"
88-
```
91+
2. **[Mac users]** Export the DOCKER_HOST.
8992

90-
- For mac users, export the DOCKER_HOST
93+
```shell
94+
export DOCKER_HOST=unix://${HOME}/.docker/run/docker.sock
95+
```
9196

92-
```shell
93-
export DOCKER_HOST=unix://${HOME}/.docker/run/docker.sock
94-
```
97+
### Preparing for Deployment
9598

96-
### Prepare for deployment
99+
1. Do a basic check to see if the cluster is reachable. Running any of the basic commands such as `kubectl cluster-info` or `kubectl get pods` or `kubectl get namespaces` successfully should confirm that. If an error occurs, check your kubeconfig file and ensure that it is correctly set up to point to your Kyma cluster. Also, check if the cluster was provisioned successfully in the SAP BTP cockpit under your subaccount.
97100

98-
- Let's do a basic check to see if the cluster is reachable. Running any of the basic commands such as `kubectl cluster-info` or `kubectl get pods` or `kubectl get namespaces` successfully should confirm that. If an error occurs, please check your kubeconfig file and ensure that it is correctly set up to point to your Kyma cluster. Also check if the cluster was provisioned successfully in the SAP BTP Cockpit under your subaccount.
101+
2. Create a namespace. You can skip this step if you already have a namespace. You can use any non-system namespace of your choice to deploy the sample application.
99102

100-
- Let's do a bit of groundwork before we deploy our Helm Chart. In Kyma/Kubernetes, the workloads and required configurations will be deployed in namespaces.
103+
> [!Note]
104+
> The following are system namespaces:
105+
> - `kube-system`
106+
> - `istio-system`
107+
> - `kyma-system`
108+
> It is not recommended to deploy your applications in the system namespaces.
101109

102-
- We will create a namespace. You can skip this step if you already have a namespace. You can use any non-system namespace of your choice to deploy the sample application.
110+
```shell
111+
make create-namespace
112+
```
103113

104-
> Note: system namespaces are such as `kube-system`, `istio-system`, `kyma-system` etc. It is not recommended to deploy your applications in these namespaces.
114+
3. Enable Istio injection for the namespace. Set the kubeconfig context to point to the namespace and create the Docker image pull Secret.
105115

106-
```shell
107-
make create-namespace
108-
```
116+
```shell
117+
make prepare-kyma-for-deployment
118+
```
109119

110-
- Now let's enable Istio injection for the namespace. Set the kubeconfig context to point to the namespace and create the docker image pull secret.
120+
### Creating Helm Charts
111121

112-
```shell
113-
make prepare-kyma-for-deployment
114-
```
115-
116-
### Create Helm chart
117-
118-
Now that we have our artifacts in place, lets shift our focus to deploying the application.
122+
Having the artifacts in place, focus to deploying the application.
119123

120124
First we need the configurations to tell Kyma what and how we want to deploy.
121125

122-
We will use [Helm Charts](https://helm.sh/) to define the required configurations and then deploy them on Kyma runtime.
126+
The sample uses [Helm charts](https://helm.sh/) to define the required configurations and then deploy them on the Kyma runtime.
123127

124-
`cds` can intelligently inspect what all is defined in your cap application and generate the necessary configurations (Helm charts) to deploy it on Kyma runtime.
128+
`cds` can intelligently inspect what is defined in your CAP application and generate the necessary configurations (Helm charts) to deploy the application on Kyma runtime.
125129

126-
- Create Helm chart
130+
1. Create a Helm chart.
127131

128-
```shell
129-
make create-helm-chart
130-
```
132+
```shell
133+
make create-helm-chart
134+
```
131135

132-
Now take a moment to understand the generated Helm chart in the [chart](./bookshop/chart) directory. <!-- markdown-link-check-disable-line -->
136+
Take a moment to understand the generated Helm chart in the [chart](./bookshop/chart) directory. <!-- markdown-link-check-disable-line -->
133137

134-
Helm chart Structure will look as below. The full helm chart will be automatically generated by `cds` under `gen` folder.
135-
![helm-chart](assets/helm-chart-structure.png)
138+
The Helm chart structure should look as below. The full Helm chart is automatically generated by `cds` under the `gen` folder.
136139

137-
- [bookshop/chart/Chart.yaml](bookshop/chart/Chart.yaml) contains the details about the chart and all its dependencies. <!-- markdown-link-check-disable-line -->
138-
- [bookshop/chart/values.yaml](bookshop/chart/values.yaml) <!-- markdown-link-check-disable-line --> contains all the details to configure the chart deployment. You will notice that it has sections for `hana deployer`, `cap application` as well as required `service instances` and `service bindings`
140+
![helm-chart](assets/helm-chart-structure.png)
139141

140-
- Add Istio destination rule for approuter. Please check the [approuter documentation](https://www.npmjs.com/package/@sap/approuter) for details about `PLATFORM_COOKIE_NAME` configuration.
142+
- [bookshop/chart/Chart.yaml](bookshop/chart/Chart.yaml) contains the details about the chart and all its dependencies.<!-- markdown-link-check-disable-line -->
143+
- [bookshop/chart/values.yaml](bookshop/chart/values.yaml) <!-- markdown-link-check-disable-line --> contains all the details to configure the chart deployment. You will notice that it has sections for `hana deployer`, `cap application` as well as required `service instances` and `service bindings.`
141144

142-
```shell
143-
make add-istio-destination-rule
144-
```
145+
2. Add Istio Destination Rule for the Application Router. Please check the [Approuter documentation](https://www.npmjs.com/package/@sap/approuter) for details about the `PLATFORM_COOKIE_NAME` configuration.
145146

146-
- Update the [bookshop/chart/values.yaml](bookshop/chart/values.yaml) <!-- markdown-link-check-disable-line -->
147-
to add the environment variables for the **approuter section** that is used for cookie.
147+
```shell
148+
make add-istio-destination-rule
149+
```
148150

149-
```yaml
150-
health:
151-
liveness:
152-
path: /
153-
readiness:
154-
path: /
155-
env:
156-
PLATFORM_COOKIE_NAME: KYMA_APP_SESSION_ID # This is the cookie name used by the approuter to store session information
157-
```
151+
3. Update the [bookshop/chart/values.yaml](bookshop/chart/values.yaml) to add the environment variables for the **approuter section** that is used for cookies. <!-- markdown-link-check-disable-line -->
158152

159-
### Build and deploy
153+
```yaml
154+
health:
155+
liveness:
156+
path: /
157+
readiness:
158+
path: /
159+
env:
160+
PLATFORM_COOKIE_NAME: KYMA_APP_SESSION_ID # This is the cookie name used by the approuter to store session information
161+
```
160162

161-
- Add containerize
163+
### Building and Deploying
162164

163-
```shell
164-
make add-containerize
165-
```
165+
1. Add containerize.
166166

167-
- Build and deploy to Kyma runtime
167+
```shell
168+
make add-containerize
169+
```
168170

169-
```shell
170-
make cds-build-deploy
171-
```
171+
2. Build and deploy to Kyma runtime.
172172

173-
### Verify your deployment
173+
```shell
174+
make cds-build-deploy
175+
```
174176

175-
- Access the application via the app router URL. It will be of the form <https://bookshop-approuter-${NAMESPACE}.${KYMA_CLUSTER_DOMAIN}>
177+
### Verifying the Deployment
176178

177-
### Cleanup
179+
To verify your deployment, access the application using the app router URL. It should be similar to this one: <https://bookshop-approuter-${NAMESPACE}.${KYMA_CLUSTER_DOMAIN}>.
178180

179-
- Delete the helm chart. This will delete the helm chart. Thereby all deployed applications, service instances and their bindings will be cleaned.
181+
### Cleaning Up
180182

181-
```shell
182-
make undeploy
183-
```
183+
1. Delete the Helm chart. Deleting the Helm chart you remove all the deployed applications, service instances, and their bindings.
184184

185-
- Remove the namespace and bookshop cap application folder
185+
```shell
186+
make undeploy
187+
```
186188

187-
```shell
188-
make cleanup
189-
```
189+
2. Remove the namespace and the Bookshop CAP application folder.
190+
191+
```shell
192+
make cleanup
193+
```
190194

191195
## Detailed Path
192196

193-
For following the detailed path where you build the artifacts and deploy them step by step, please refer to [the detailed path](./the-detailed-path.md).
197+
For more information on the built artifacts and deploying them step by step, see [Detailed Path](./the-detailed-path.md).
194198

195199
## CAP Version
196200

197-
Latest verified on following CAP version.
201+
The sample uses the following CAP versions.
198202

199203
| bookshop | "Add your repository here" |
200204
|------------------------|----------------------------|
@@ -209,8 +213,6 @@ Latest verified on following CAP version.
209213
| @sap/eslint-plugin-cds | 3.2.0 |
210214
| Node.js | v22.11.0 |
211215

212-
## Takeaway
213-
214-
*CAP supports grow-as-you-go model. Once you have familiarized yourself with CAP basics, you can go further and add capabilities such as authentication, multitenancy, extensibility, messaging and many more.*
216+
## Related Information
215217

216-
You can explore CAP further on <https://cap.cloud.sap/docs/>
218+
[SAP Cloud Application Programming Model](https://cap.cloud.sap/docs/)

0 commit comments

Comments
 (0)