diff --git a/content/en/docs/examples/included/microcks-score-compose.md b/content/en/docs/examples/included/microcks-score-compose.md new file mode 100644 index 00000000..fbb4e58d --- /dev/null +++ b/content/en/docs/examples/included/microcks-score-compose.md @@ -0,0 +1,134 @@ +--- +title: "Microcks" +description: "How to deploy a containerized frontend application and use Microcks to mock a backend service with `score-compose` and `score-k8s`" +headless: true +toc_hide: true +--- + +To begin, follow the [installation instructions](/docs/score-implementation/score-compose/installation) to install the latest version of `score-compose`. + +## `init` + +Initialize your current `score-compose` workspace, run the following command in your terminal: + +```bash +score-compose init --no-sample \ + --provisioners https://raw.githubusercontent.com/score-spec/community-provisioners/refs/heads/main/service/score-compose/10-service-with-microcks.provisioners.yaml \ + --patch-templates https://raw.githubusercontent.com/score-spec/community-patchers/refs/heads/main/score-compose/microcks.tpl +``` + +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`. + +You can see the resource provisioners available by running this command: + +```bash +score-compose provisioners list +``` + +The Score file example illustrated uses one resource type: `service`. + +```none ++---------+-------+-------------------------------------------+--------+-----------------------------------+ +| TYPE | CLASS | PARAMS |OUTPUTS | DESCRIPTION | ++---------+-------+-------------------------------------------+--------+-----------------------------------+ +| service | (any) | port, artifacts, name, version | name, | Generates a Microcks mock for | +| | | | url | an external service dependency | +| | | | | using the provided OpenAPI spec. | ++---------+-------+-------------------------------------------+--------+-----------------------------------+ +``` + +## `generate` + +Convert the `score.yaml` file into a deployable `compose.yaml`, run the following command in your terminal: + +```bash +score-compose generate score.yaml +``` + +The `generate` command will add the input `score.yaml` workload to the `.score-compose/state.yaml` state file and generate the output `compose.yaml`. + +See the generated `compose.yaml` by running this command: + +```bash +cat compose.yaml +``` + +If you make any modifications to the `score.yaml` file, run `score-compose generate score.yaml` to regenerate the output `compose.yaml`. + +## `resources` + +Get the information of the resources dependencies of the workload, run the following command: + +```bash +score-compose resources list +``` + +```none ++-----------------------------------+------------+ +| UID | OUTPUTS | ++-----------------------------------+------------+ +| service.default#frontend.backend | name, url | ++-----------------------------------+------------+ +``` + +At this stage, we can already see the value of the `service` resource (the mocked backend URL) generated by Microcks: + +```bash +score-compose resources get-outputs 'service.default#frontend.backend' --format '{{ .url }}' +``` + +```none +http://microcks:8080/rest/Order+Service+API/0.1.0 +``` + +## `docker compose` + +Run `docker compose up` to execute the generated `compose.yaml` file: + +```bash +docker compose up -d --wait +``` + +```none +[+] Running 3/3 + ✔ Container score-microcks-microcks-1 Started + ✔ Container score-microcks-backend-mock-1 Started + ✔ Container score-microcks-frontend-frontend-1 Started +``` + +Three containers are deployed: + +- **`frontend`** — The actual frontend application. +- **`backend-mock`** — A `microcks-cli` sidecar that imports the OpenAPI spec into the Microcks control plane. +- **`microcks`** — The Microcks control plane, which generates and serves the backend mock. + +## `docker ps` + +See the running containers: + +```bash +docker ps +``` + +```none +CONTAINER ID IMAGE COMMAND CREATED STATUS PORTS NAMES +f8a17b908320 busybox "/bin/sh -c 'while t…" 20 seconds ago Up 16 seconds score-microcks-frontend-frontend-1 +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 +``` + +## `docker logs` + +Verify that the frontend app is successfully calling the Microcks-mocked backend: + +```bash +docker logs score-microcks-frontend-frontend-1 +``` + +```none +Hello http://microcks:8080/rest/Order+Service+API/0.1.0/orders! +Hello http://microcks:8080/rest/Order+Service+API/0.1.0/orders! +``` + +The frontend successfully resolves `${resources.backend.url}` to the Microcks-mocked endpoint and calls it — without the actual backend service running anywhere. + +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. diff --git a/content/en/docs/examples/included/microcks-score-k8s.md b/content/en/docs/examples/included/microcks-score-k8s.md new file mode 100644 index 00000000..d6e819ad --- /dev/null +++ b/content/en/docs/examples/included/microcks-score-k8s.md @@ -0,0 +1,134 @@ +--- +title: "Microcks" +description: "How to deploy a containerized frontend application using Microcks to mock a backend service with `score-k8s`" +headless: true +toc_hide: true +--- + +To begin, follow the [installation instructions](/docs/score-implementation/score-k8s/installation) to install the latest version of `score-k8s`. + +## `init` + +Initialize your current `score-k8s` workspace, run the following command in your terminal: + +```bash +score-k8s init --no-sample \ + --provisioners https://raw.githubusercontent.com/score-spec/community-provisioners/refs/heads/main/service/score-k8s/10-service-with-microcks-cli.provisioners.yaml +``` + +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. + +You can see the resource provisioners available by running this command: + +```bash +score-k8s provisioners list +``` + +The Score file example illustrated uses one resource type: `service`. + +```none ++---------+-------+-------------------------------------------+--------+-----------------------------------+ +| TYPE | CLASS | PARAMS |OUTPUTS | DESCRIPTION | ++---------+-------+-------------------------------------------+--------+-----------------------------------+ +| service | (any) | port, artifacts, name, version | name, | Imports an OpenAPI spec into a | +| | | | url | running Microcks instance and | +| | | | | returns the mock endpoint URL. | ++---------+-------+-------------------------------------------+--------+-----------------------------------+ +``` + +## `generate` + +_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._ + +_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)._ + +Convert the `score.yaml` file into a deployable `manifests.yaml`, run the following command in your terminal: + +```bash +score-k8s generate score.yaml +``` + +The `generate` command will add the input `score.yaml` workload to the `.score-k8s/state.yaml` state file and generate the output `manifests.yaml`. + +See the generated `manifests.yaml` by running this command: + +```bash +cat manifests.yaml +``` + +If you make any modifications to the `score.yaml` file, run `score-k8s generate score.yaml` to regenerate the output `manifests.yaml`. + +## `resources` + +Get the information of the resources dependencies of the workload, run the following command: + +```bash +score-k8s resources list +``` + +```none ++-----------------------------------+------------+ +| UID | OUTPUTS | ++-----------------------------------+------------+ +| service.default#frontend.backend | name, url | ++-----------------------------------+------------+ +``` + +At this stage, we can already see the value of the `service` resource (the Microcks-provided mock URL in cluster): + +```bash +score-k8s resources get-outputs 'service.default#frontend.backend' --format '{{ .url }}' +``` + +```none +http://microcks.microcks.svc.cluster.local:8080/rest/Order+Service+API/0.1.0 +``` + +## `kubectl apply` + +Run `kubectl apply` to execute the generated `manifests.yaml` file: + +```bash +kubectl apply -f manifests.yaml +``` + +```none +deployment.apps/frontend created +service/frontend created +``` + +## `kubectl get all` + +See the running pods: + +```bash +kubectl get all +``` + +```none +NAME READY STATUS RESTARTS AGE +pod/frontend-7d9f8b6c4d-xk2pv 1/1 Running 0 30s + +NAME TYPE CLUSTER-IP EXTERNAL-IP PORT(S) AGE +service/frontend ClusterIP 10.96.142.101 80/TCP 30s + +NAME READY UP-TO-DATE AVAILABLE AGE +deployment.apps/frontend 1/1 1 1 30s +``` + +## `kubectl logs` + +Verify that the frontend app is successfully calling the Microcks-mocked backend running inside the cluster: + +```bash +kubectl logs deploy/frontend +``` + +```none +Hello http://microcks.microcks.svc.cluster.local:8080/rest/Order+Service+API/0.1.0/orders! +Hello http://microcks.microcks.svc.cluster.local:8080/rest/Order+Service+API/0.1.0/orders! +``` + +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. + +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. diff --git a/content/en/docs/examples/microcks.md b/content/en/docs/examples/microcks.md new file mode 100644 index 00000000..b81d0649 --- /dev/null +++ b/content/en/docs/examples/microcks.md @@ -0,0 +1,62 @@ +--- +title: "Microcks" +linkTitle: "Microcks" +description: "How to deploy a containerized frontend application using Microcks to mock a backend service with `score-compose` and `score-k8s`" +weight: 9 +--- + +## Overview + +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`. + +```mermaid +flowchart TD + frontend-workload(Frontend) --> backend-mock[[backend-mock - Microcks]] + subgraph Workloads + frontend-workload + end + backend-mock --> microcks[(Microcks)] +``` + +## Score file + +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). + +```yaml +apiVersion: score.dev/v1b1 +metadata: + name: frontend +containers: + frontend: + image: busybox + command: ["/bin/sh"] + args: ["-c", "while true; do echo Hello $BACKEND_SVC!; sleep 5; done"] + variables: + BACKEND_SVC: ${resources.backend.url}/orders +resources: + backend: + type: service + params: + port: 8181 + artifacts: resources/backend-openapi.yaml:true + name: Order Service API + version: 0.1.0 +``` + +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. + +## Deployment with `score-compose` and `score-k8s` + +From here, we will now see how to deploy this exact same Score file with either with `score-compose` or with `score-k8s`: + +{{< tabs name="deployments">}} +{{< tab name="score-compose" include="./included/microcks-score-compose.md" />}} +{{< tab name="score-k8s" include="./included/microcks-score-k8s.md" />}} +{{< /tabs >}} + +## Next steps + +- [**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. +- [**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. +- [**Explore more examples**](/examples/): Check out more examples to dive into further use cases and experiment with different configurations. +- [**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.