-
Notifications
You must be signed in to change notification settings - Fork 0
Commit
This commit does not belong to any branch on this repository, and may belong to a fork outside of the repository.
- Loading branch information
Showing
1 changed file
with
14 additions
and
199 deletions.
There are no files selected for viewing
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -1,210 +1,25 @@ | ||
| # Ankaios Maestro challenge development environment | ||
| # Amadeus | ||
|
|
||
| Don't feel like reading instructions? No problem, watch the video explaining the development environment and use the instructions as a reference. | ||
| > This project shows how the (software) infrastructure of the car adapts to different environment settings | ||
| [](https://youtu.be/XQVlIctChkI) | ||
| Setting: Vehicle which is capable to get trailiers attached | ||
|
|
||
| ## Architectural Overview | ||
| Question: Is it possible that the software in the car adapts to the attached trailiers | ||
|
|
||
|  | ||
| Scenario: | ||
|
|
||
| This repository provides a starter template for solving the Maestro challenges using the [Ankaios](https://github.com/eclipse-ankaios/ankaios) workload orchestrator. | ||
| It contains a pre-configured devcontainer that makes it easy for you to start developing and building container applications managed by Ankaios. | ||
| Two different trailers: One basic trailer and one with a fridge. | ||
|
|
||
| The container is designed to have an immediately running environment. Once triggered, all workloads are initially started and sample data is exchanged between them. | ||
| - When a basic trailer is connected, the weight of the trailer is sent. | ||
| - When the trailer of the fridge is connected, additionaly, the temperature is sent. | ||
|
|
||
| ## Links | ||
|
|
||
| - [Ankaios docs](https://eclipse-ankaios.github.io/ankaios/0.2/) | ||
| - [Ankaios quickstart](https://eclipse-ankaios.github.io/ankaios/0.2/usage/quickstart/) | ||
| - [Podman](https://docs.podman.io/en/v4.6.1/) | ||
| - [What are devcontainers?](https://containers.dev/) | ||
|
|
||
| ## Prerequisites | ||
|
|
||
| - Docker [Installation instructions](https://docs.docker.com/get-docker/) | ||
|
|
||
| ## Development environment | ||
|
|
||
| The following is provided inside the devcontainer: | ||
|
|
||
| - Ankaios executables (`ank-server`, `ank-agent` and `ank`) | ||
|
|
||
| - Podman 4.6.2 | ||
|
|
||
| - Pre-configured Ankaios startup config [startupState.yaml](./config/startupState.yaml) | ||
|
|
||
| - Automation scripts for starting and stopping all workloads of the challenge: | ||
| - run_maestro.sh | ||
| - shutdown_maestro.sh | ||
|
|
||
| - REST API providing resource usage statistics for the sample scenario about intelligent orchestrator | ||
|
|
||
| - Exposed port: | ||
| - 25551: for optionally using the Ankaios CLI outside of the devcontainer | ||
|
|
||
| - [Ankaios Control Interface dependencies](#ankaios-control-interface-dependencies) | ||
|
|
||
| All services are running in the host network meaning those can be accessed by `localhost:<port>`. We recommend that you set the network mode to host for all your developed workloads as well. | ||
|
|
||
| ## Ankaios Control Interface dependencies | ||
|
|
||
| The devcontainer includes also dependencies for developing applications using the [Ankaios Control Interface](https://eclipse-ankaios.github.io/ankaios/0.2/reference/control-interface/): | ||
|
|
||
| - protobuf compiler | ||
| - grpcurl | ||
| - Ankaios protobuf file (under `/usr/local/lib/ankaios/ankaios.proto`) | ||
|
|
||
| Those dependencies are needed for use-cases in which your app needs to use the [Ankaios Control Interface](https://eclipse-ankaios.github.io/ankaios/0.2/reference/control-interface/) to be able to communicate with the Ankaios cluster via the API. An example use-case would be to write a workload that shall request Ankaios to dynamically start another workload. You can find example workload applications written in various programming languages inside the Eclipse Ankaios repository [here](https://github.com/eclipse-ankaios/ankaios/tree/v0.2.0-rc1/examples). | ||
|
|
||
| ## Run devcontainer with VSCode | ||
|
|
||
| ### Prerequisites | ||
|
|
||
| - [Remote Development](https://marketplace.visualstudio.com/items?itemName=ms-vscode-remote.vscode-remote-extensionpack) extension installed in VSCode | ||
|
|
||
| Open the subfolder containing this README file in VSCode: | ||
|
|
||
| ```shell | ||
| code . | ||
| ``` | ||
|
|
||
| VSCode detects automatically that a `.devcontainer` folder exists inside this subfolder. | ||
| Please confirm the dialog to reopen VSCode inside the devcontainer. | ||
| Afterwards, open a new terminal inside the devcontainer in VSCode. | ||
|
|
||
| ## Run devcontainer without VSCode | ||
|
|
||
| Navigate to the subfolder containing this README file and run the following command to build the devcontainer image: | ||
|
|
||
| ```shell | ||
| docker build -t custom-ankaios-dev:0.1 --target dev -f .devcontainer/Dockerfile . | ||
| ``` | ||
|
|
||
| Start the devcontainer with the required mount points: | ||
|
|
||
| ```shell | ||
| docker run -it --privileged --name custom_ankaios_dev -v <absolute/path/to>/maestro-challenge/eclipse-ankaios:/workspaces/app -v <absolute/path/to>/maestro-challenge/in-vehicle-stack:/workspaces/app/in-vehicle-stack -p 25551:25551 --workdir /workspaces/app custom-ankaios-dev:0.1 /bin/bash | ||
| ``` | ||
|
|
||
| ## Startup check before development | ||
|
|
||
| Before starting active development we recommend you start once Ankaios with the current startup config [startupState.yaml](./config/startupState.yaml) and sample applications. | ||
|
|
||
| **Note:** If you have selected a sample scenario requiring resource usage statistics like cpu or memory usage, uncomment the `resource_monitor` config part in the Ankaios startup config [startupState.yaml](./config/startupState.yaml). If you are using MacOS, please remove the `--pid host` and `--cgroups enabled` parameters from the config part. For more details, see [here](../scenarios/intelligent_orchestrator_use_case/ankaios_resource_statistics_app/README.md). | ||
|
|
||
| 1. Log in into the Microsoft container registry | ||
|
|
||
| ```shell | ||
| podman login sdvblueprint.azurecr.io | ||
| ``` | ||
| ## CI-Checks | ||
|
|
||
| 2. Start Ankaios with all workloads inside the startup config: | ||
| - Basic Dockerfile build checks as well as integration tests: <https://github.com/Eclipse-SDV-Hackathon-Accenture/amadeus/blob/main/.github/workflows/check.yml> | ||
| - Linting of files: <https://github.com/Eclipse-SDV-Hackathon-Accenture/amadeus/blob/main/.github/workflows/lint.yml> | ||
|
|
||
| ```shell | ||
| run_maestro.sh | ||
| ``` | ||
| See <https://github.com/Eclipse-SDV-Hackathon-Accenture/amadeus/actions> for the current checks. | ||
|
|
||
| 3. Next, use the Ankaios CLI to verify that all initial workloads are up and running: | ||
|
|
||
| ```shell | ||
| ank get workloads | ||
| ``` | ||
|
|
||
| 4. Verify that all initial workloads inside the startup config have execution state "Running". | ||
|
|
||
| The output looks similar to the following: | ||
|
|
||
| ```shell | ||
| WORKLOAD NAME AGENT RUNTIME EXECUTION STATE | ||
| digital_twin_cloud_sync agent_A podman Running | ||
| digital_twin_vehicle agent_A podman Running | ||
| dynamic_topic_management agent_A podman Running | ||
| mqtt_broker agent_A podman Running | ||
| service_discovery agent_A podman Running | ||
| ``` | ||
|
|
||
| 5. Only for the **Smart Trailer scenario**, do the following extra steps: | ||
| - Inside the devcontainer, run the script `start_trailer_applications_ankaios.sh`: | ||
|
|
||
| ```shell | ||
| start_trailer_applications_ankaios.sh | ||
| ``` | ||
|
|
||
| - In another terminal window inside the devcontainer, add the following workload by using the Ankaios CLI to simulate the Smart Trailer connected signal: | ||
|
|
||
| ```shell | ||
| ank run workload trailer_connected_provider --runtime podman --config $'image: sdvblueprint.azurecr.io/sdvblueprint/in-vehicle-stack/trailer_connected_provider:0.1.0\ncommandOptions: ["--network", "host", "--name", "trailer_connected_provider"]' --agent agent_A | ||
| ``` | ||
|
|
||
| - Verify the output of the terminal window of the `start_trailer_applications_ankaios.sh` script. The output should look like the following: | ||
|
|
||
| ```shell | ||
| Trailer is connected! Starting workloads to manage it | ||
| Called Ankaios to start the Trailer Properties Digital Twin Provider and Smart Trailer Application | ||
| Check Ankaios status with 'ank get workloads' | ||
| ``` | ||
|
|
||
| - Check the execution states of the newly added workloads by using the Ankaios CLI. | ||
|
|
||
| ```shell | ||
| ank get workloads | ||
| ``` | ||
|
|
||
| - Run `podman logs -f smart_trailer_application` to check the sample data output of the Smart Trailer App. Feel free to check the logs of the other workloads too. | ||
|
|
||
| 6. Stop Ankaios and clean up all workloads by running: | ||
|
|
||
| ```shell | ||
| shutdown_maestro.sh | ||
| ``` | ||
|
|
||
| ## Customizing Devcontainer | ||
|
|
||
| You can customize the devcontainer depending on your preferred programming language, tools and frameworks. | ||
|
|
||
| To customize the devcontainer add your specific dev dependencies to `.devcontainer/Dockerfile` (starting from line 7). | ||
|
|
||
| Rebuild the container image. | ||
|
|
||
| ## Workload development | ||
|
|
||
| After customizing the devcontainer, start the development of your workload apps. | ||
|
|
||
| - Write your code | ||
| - Write a [Dockerfile](https://docs.docker.com/engine/reference/builder/) for each workload | ||
| - Build a container image for each workload with [podman build](https://docs.podman.io/en/v4.6.1/markdown/podman-build.1.html) | ||
| - For the Smart Trailer scenario, replace the image URIs within the script [start_trailer_applications_ankaios.sh](../in-vehicle-stack/scenarios/smart_trailer_use_case/scripts/start_trailer_applications_ankaios.sh) | ||
| - If required, extend the Ankaios startup config [startupState.yaml](./config/startupState.yaml) by adding config parts for your workloads | ||
|
|
||
| Start and stop all workloads according to the section [Startup check before development](#startup-check-before-development). | ||
| Use the Ankaios ClI to check the workload states. For more details display the help of Ankaios CLI by running: | ||
|
|
||
| ```shell | ||
| ank --help | ||
| ``` | ||
|
|
||
| Use the [podman logs](https://docs.podman.io/en/v4.6.1/markdown/podman-logs.1.html) command to check the logs of your container applications for debugging purposes. | ||
|
|
||
| ```shell | ||
| podman ps -a | ||
| podman logs -f <container_name|container_id> | ||
| ``` | ||
|
|
||
| ## Ankaios logs | ||
|
|
||
| There are log files for debugging purposes of Ankaios server and agent. | ||
|
|
||
| The Ankaios server logs can be viewed by executing the following command: | ||
|
|
||
| ```shell | ||
| tail -f /var/log/ankaios-server.log | ||
| ``` | ||
|
|
||
| The Ankaios agent logs can be viewed by executing the following command: | ||
|
|
||
| ```shell | ||
| tail -f /var/log/ankaios-agent_A.log | ||
| ``` | ||
| ## Links | ||
|
|
||
| <!-- markdownlint-disable-file MD024 --> | ||
| - The basic settinsg is written at <https://github.com/Eclipse-SDV-Hackathon-Accenture/maestro-challenge>. |