Skip to content

Commit 0f0c1cc

Browse files
Abhishek9639Abhishek9639
authored
docs: add Microcks example (#289)
Signed-off-by: Abhishek <abhishekup082@gmail.com>
1 parent f69abfd commit 0f0c1cc

3 files changed

Lines changed: 330 additions & 0 deletions

File tree

‎content/en/docs/examples/included/microcks-score-compose.md‎

Lines changed: 134 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,134 @@
1+
---
2+
title: "Microcks"
3+
description: "How to deploy a containerized frontend application and use Microcks to mock a backend service with `score-compose` and `score-k8s`"
4+
headless: true
5+
toc_hide: true
6+
---
7+
8+
To begin, follow the [installation instructions](/docs/score-implementation/score-compose/installation) to install the latest version of `score-compose`.
9+
10+
## `init`
11+
12+
Initialize your current `score-compose` workspace, run the following command in your terminal:
13+
14+
```bash
15+
score-compose init --no-sample \
16+
--provisioners https://raw.githubusercontent.com/score-spec/community-provisioners/refs/heads/main/service/score-compose/10-service-with-microcks.provisioners.yaml \
17+
--patch-templates https://raw.githubusercontent.com/score-spec/community-patchers/refs/heads/main/score-compose/microcks.tpl
18+
```
19+
20+
The `init` command will create the `.score-compose` directory with the [default resource provisioners]({{< relref "/docs/score-implementation/score-compose/resources-provisioners/" >}}) available. We are also importing one external provisioner to seamlessly generate a Microcks mock for the backend service resource: [`service-with-microcks` provisioner](https://github.com/score-spec/community-provisioners/blob/main/service/score-compose/10-service-with-microcks.provisioners.yaml). The [`microcks.tpl` patch template](https://github.com/score-spec/community-patchers/blob/main/score-compose/microcks.tpl) is also injected to spin up the Microcks control plane container in the generated `compose.yaml`.
21+
22+
You can see the resource provisioners available by running this command:
23+
24+
```bash
25+
score-compose provisioners list
26+
```
27+
28+
The Score file example illustrated uses one resource type: `service`.
29+
30+
```none
31+
+---------+-------+-------------------------------------------+--------+-----------------------------------+
32+
| TYPE | CLASS | PARAMS |OUTPUTS | DESCRIPTION |
33+
+---------+-------+-------------------------------------------+--------+-----------------------------------+
34+
| service | (any) | port, artifacts, name, version | name, | Generates a Microcks mock for |
35+
| | | | url | an external service dependency |
36+
| | | | | using the provided OpenAPI spec. |
37+
+---------+-------+-------------------------------------------+--------+-----------------------------------+
38+
```
39+
40+
## `generate`
41+
42+
Convert the `score.yaml` file into a deployable `compose.yaml`, run the following command in your terminal:
43+
44+
```bash
45+
score-compose generate score.yaml
46+
```
47+
48+
The `generate` command will add the input `score.yaml` workload to the `.score-compose/state.yaml` state file and generate the output `compose.yaml`.
49+
50+
See the generated `compose.yaml` by running this command:
51+
52+
```bash
53+
cat compose.yaml
54+
```
55+
56+
If you make any modifications to the `score.yaml` file, run `score-compose generate score.yaml` to regenerate the output `compose.yaml`.
57+
58+
## `resources`
59+
60+
Get the information of the resources dependencies of the workload, run the following command:
61+
62+
```bash
63+
score-compose resources list
64+
```
65+
66+
```none
67+
+-----------------------------------+------------+
68+
| UID | OUTPUTS |
69+
+-----------------------------------+------------+
70+
| service.default#frontend.backend | name, url |
71+
+-----------------------------------+------------+
72+
```
73+
74+
At this stage, we can already see the value of the `service` resource (the mocked backend URL) generated by Microcks:
75+
76+
```bash
77+
score-compose resources get-outputs 'service.default#frontend.backend' --format '{{ .url }}'
78+
```
79+
80+
```none
81+
http://microcks:8080/rest/Order+Service+API/0.1.0
82+
```
83+
84+
## `docker compose`
85+
86+
Run `docker compose up` to execute the generated `compose.yaml` file:
87+
88+
```bash
89+
docker compose up -d --wait
90+
```
91+
92+
```none
93+
[+] Running 3/3
94+
✔ Container score-microcks-microcks-1 Started
95+
✔ Container score-microcks-backend-mock-1 Started
96+
✔ Container score-microcks-frontend-frontend-1 Started
97+
```
98+
99+
Three containers are deployed:
100+
101+
- **`frontend`** — The actual frontend application.
102+
- **`backend-mock`** — A `microcks-cli` sidecar that imports the OpenAPI spec into the Microcks control plane.
103+
- **`microcks`** — The Microcks control plane, which generates and serves the backend mock.
104+
105+
## `docker ps`
106+
107+
See the running containers:
108+
109+
```bash
110+
docker ps
111+
```
112+
113+
```none
114+
CONTAINER ID IMAGE COMMAND CREATED STATUS PORTS NAMES
115+
f8a17b908320 busybox "/bin/sh -c 'while t…" 20 seconds ago Up 16 seconds score-microcks-frontend-frontend-1
116+
3d6e626b3d6e quay.io/microcks/microcks-uber:latest-native "/cnb/process/web" 20 seconds ago Up 19 seconds 0.0.0.0:9090->8080/tcp score-microcks-microcks-1
117+
```
118+
119+
## `docker logs`
120+
121+
Verify that the frontend app is successfully calling the Microcks-mocked backend:
122+
123+
```bash
124+
docker logs score-microcks-frontend-frontend-1
125+
```
126+
127+
```none
128+
Hello http://microcks:8080/rest/Order+Service+API/0.1.0/orders!
129+
Hello http://microcks:8080/rest/Order+Service+API/0.1.0/orders!
130+
```
131+
132+
The frontend successfully resolves `${resources.backend.url}` to the Microcks-mocked endpoint and calls it — without the actual backend service running anywhere.
133+
134+
Congrats! You've successfully deployed, with the `score-compose` implementation, a containerized frontend workload whose external backend dependency is seamlessly mocked by Microcks. You provisioned everything through Docker, without writing the Docker Compose file by yourself.

‎content/en/docs/examples/included/microcks-score-k8s.md‎

Lines changed: 134 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,134 @@
1+
---
2+
title: "Microcks"
3+
description: "How to deploy a containerized frontend application using Microcks to mock a backend service with `score-k8s`"
4+
headless: true
5+
toc_hide: true
6+
---
7+
8+
To begin, follow the [installation instructions](/docs/score-implementation/score-k8s/installation) to install the latest version of `score-k8s`.
9+
10+
## `init`
11+
12+
Initialize your current `score-k8s` workspace, run the following command in your terminal:
13+
14+
```bash
15+
score-k8s init --no-sample \
16+
--provisioners https://raw.githubusercontent.com/score-spec/community-provisioners/refs/heads/main/service/score-k8s/10-service-with-microcks-cli.provisioners.yaml
17+
```
18+
19+
The `init` command will create the `.score-k8s` directory with the [default resource provisioners]({{< relref "/docs/score-implementation/score-k8s/resources-provisioners/" >}}) available. We are also importing the [`service-with-microcks-cli` provisioner](https://github.com/score-spec/community-provisioners/blob/main/service/score-k8s/10-service-with-microcks-cli.provisioners.yaml), which is responsible for importing the OpenAPI spec into the Microcks control plane already running in your Kubernetes cluster.
20+
21+
You can see the resource provisioners available by running this command:
22+
23+
```bash
24+
score-k8s provisioners list
25+
```
26+
27+
The Score file example illustrated uses one resource type: `service`.
28+
29+
```none
30+
+---------+-------+-------------------------------------------+--------+-----------------------------------+
31+
| TYPE | CLASS | PARAMS |OUTPUTS | DESCRIPTION |
32+
+---------+-------+-------------------------------------------+--------+-----------------------------------+
33+
| service | (any) | port, artifacts, name, version | name, | Imports an OpenAPI spec into a |
34+
| | | | url | running Microcks instance and |
35+
| | | | | returns the mock endpoint URL. |
36+
+---------+-------+-------------------------------------------+--------+-----------------------------------+
37+
```
38+
39+
## `generate`
40+
41+
_You will need to have access to a Kubernetes cluster to execute the following commands. You can follow [these instructions](/docs/how-to/score-k8s/kind-cluster/) if you want to set up a Kind cluster. Your Kubernetes cluster should also have [Microcks installed](https://microcks.io/documentation/guides/installation/kind-helm/) in it._
42+
43+
_This is where the `service` provisioner will be invoked. Under the hood, it uses the [`microcks` CLI](https://microcks.io/documentation/guides/installation/cli/) to import the OpenAPI spec into Microcks (see the [`service-with-microcks-cli` provisioner](https://github.com/score-spec/community-provisioners/blob/main/service/score-k8s/10-service-with-microcks-cli.provisioners.yaml#L29)). You will need the `microcks` CLI installed locally on your machine (outside of the cluster)._
44+
45+
Convert the `score.yaml` file into a deployable `manifests.yaml`, run the following command in your terminal:
46+
47+
```bash
48+
score-k8s generate score.yaml
49+
```
50+
51+
The `generate` command will add the input `score.yaml` workload to the `.score-k8s/state.yaml` state file and generate the output `manifests.yaml`.
52+
53+
See the generated `manifests.yaml` by running this command:
54+
55+
```bash
56+
cat manifests.yaml
57+
```
58+
59+
If you make any modifications to the `score.yaml` file, run `score-k8s generate score.yaml` to regenerate the output `manifests.yaml`.
60+
61+
## `resources`
62+
63+
Get the information of the resources dependencies of the workload, run the following command:
64+
65+
```bash
66+
score-k8s resources list
67+
```
68+
69+
```none
70+
+-----------------------------------+------------+
71+
| UID | OUTPUTS |
72+
+-----------------------------------+------------+
73+
| service.default#frontend.backend | name, url |
74+
+-----------------------------------+------------+
75+
```
76+
77+
At this stage, we can already see the value of the `service` resource (the Microcks-provided mock URL in cluster):
78+
79+
```bash
80+
score-k8s resources get-outputs 'service.default#frontend.backend' --format '{{ .url }}'
81+
```
82+
83+
```none
84+
http://microcks.microcks.svc.cluster.local:8080/rest/Order+Service+API/0.1.0
85+
```
86+
87+
## `kubectl apply`
88+
89+
Run `kubectl apply` to execute the generated `manifests.yaml` file:
90+
91+
```bash
92+
kubectl apply -f manifests.yaml
93+
```
94+
95+
```none
96+
deployment.apps/frontend created
97+
service/frontend created
98+
```
99+
100+
## `kubectl get all`
101+
102+
See the running pods:
103+
104+
```bash
105+
kubectl get all
106+
```
107+
108+
```none
109+
NAME READY STATUS RESTARTS AGE
110+
pod/frontend-7d9f8b6c4d-xk2pv 1/1 Running 0 30s
111+
112+
NAME TYPE CLUSTER-IP EXTERNAL-IP PORT(S) AGE
113+
service/frontend ClusterIP 10.96.142.101 <none> 80/TCP 30s
114+
115+
NAME READY UP-TO-DATE AVAILABLE AGE
116+
deployment.apps/frontend 1/1 1 1 30s
117+
```
118+
119+
## `kubectl logs`
120+
121+
Verify that the frontend app is successfully calling the Microcks-mocked backend running inside the cluster:
122+
123+
```bash
124+
kubectl logs deploy/frontend
125+
```
126+
127+
```none
128+
Hello http://microcks.microcks.svc.cluster.local:8080/rest/Order+Service+API/0.1.0/orders!
129+
Hello http://microcks.microcks.svc.cluster.local:8080/rest/Order+Service+API/0.1.0/orders!
130+
```
131+
132+
The frontend successfully resolves `${resources.backend.url}` to the Microcks control plane running in the cluster, using the same `score.yaml` file that was used locally with `score-compose` — no changes required.
133+
134+
Congrats! You've successfully deployed, with the `score-k8s` implementation, a containerized frontend workload whose external backend dependency is seamlessly mocked by Microcks running in Kubernetes. You provisioned the Kubernetes manifests through `kubectl`, without writing them by yourself.

‎content/en/docs/examples/microcks.md‎

Lines changed: 62 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,62 @@
1+
---
2+
title: "Microcks"
3+
linkTitle: "Microcks"
4+
description: "How to deploy a containerized frontend application using Microcks to mock a backend service with `score-compose` and `score-k8s`"
5+
weight: 9
6+
---
7+
8+
## Overview
9+
10+
In this example we will walk you through how you can deploy a containerized frontend application using [Microcks](https://microcks.io/) to mock an external backend service dependency, and this with both `score-compose` and `score-k8s`.
11+
12+
```mermaid
13+
flowchart TD
14+
frontend-workload(Frontend) --> backend-mock[[backend-mock - Microcks]]
15+
subgraph Workloads
16+
frontend-workload
17+
end
18+
backend-mock --> microcks[(Microcks)]
19+
```
20+
21+
## Score file
22+
23+
Open your IDE and paste in the following `score.yaml` file, which describes a simple frontend application that references a backend service resource via its [OpenAPI specification](https://github.com/mathieu-benoit/score-microcks/blob/main/resources/backend-openapi.yaml). The demo code can be found [here](https://github.com/mathieu-benoit/score-microcks).
24+
25+
```yaml
26+
apiVersion: score.dev/v1b1
27+
metadata:
28+
name: frontend
29+
containers:
30+
frontend:
31+
image: busybox
32+
command: ["/bin/sh"]
33+
args: ["-c", "while true; do echo Hello $BACKEND_SVC!; sleep 5; done"]
34+
variables:
35+
BACKEND_SVC: ${resources.backend.url}/orders
36+
resources:
37+
backend:
38+
type: service
39+
params:
40+
port: 8181
41+
artifacts: resources/backend-openapi.yaml:true
42+
name: Order Service API
43+
version: 0.1.0
44+
```
45+
46+
In the `resources` section, the `backend` resource of type `service` declares the external backend dependency. The Developer only needs to know _that_ a backend service exists and _what_ its OpenAPI spec looks like — Microcks handles generating a realistic mock at deployment time, resolving `${resources.backend.url}` automatically.
47+
48+
## Deployment with `score-compose` and `score-k8s`
49+
50+
From here, we will now see how to deploy this exact same Score file with either with `score-compose` or with `score-k8s`:
51+
52+
{{< tabs name="deployments">}}
53+
{{< tab name="score-compose" include="./included/microcks-score-compose.md" />}}
54+
{{< tab name="score-k8s" include="./included/microcks-score-k8s.md" />}}
55+
{{< /tabs >}}
56+
57+
## Next steps
58+
59+
- [**Deep dive with the associated blog post**](https://itnext.io/unifying-inner-outer-loops-to-bridge-the-gaps-between-devs-ops-with-containers-microcks-d28603342f4b): Go through the step-by-step guide to understand the concepts of bridging inner and outer development loops with Containers, Microcks, and Score.
60+
- [**Watch the Score + Microcks session at KubeCon EU 2026**](https://sched.co/2CVxb): _Unifying Inner & Outer Loops To Bridge the Gaps Between Devs & Ops With Microcks + Score_ — Laurent Broudoux (Microcks) & Mathieu Benoit (Docker), showing a more advanced use case.
61+
- [**Explore more examples**](/examples/): Check out more examples to dive into further use cases and experiment with different configurations.
62+
- [**Join the Score community**]({{< relref "/docs/community" >}}): Connect with fellow Score developers on our CNCF Slack channel or start find your way to contribute to Score.

0 commit comments

Comments
 (0)