feat: add initial port mapping example

[stancu-anamaria]

No description provided.

[Copilot]

Pull request overview

Adds a new port-mapping/ example demonstrating how to expose an internal HTTP service (port 8080) via Unikraft Cloud port mapping to external 443 over TLS/HTTP, including both kraft CLI and direct API workflows.

Changes:

• Introduces a minimal Python HTTP server plus container/Kraft packaging files for deployment.
• Adds a step-by-step README covering deploy/operate flows via kraft CLI and via API helper scripts.
• Adds configuration templates (ukc.config.template, app.config) and API shell scripts for instance/image operations.

Reviewed changes

Copilot reviewed 15 out of 15 changed files in this pull request and generated 5 comments.

Show a summary per file

File	Description
port-mapping/ukc.config.template	Adds UKC user/token/metro config template and derived UKC_API base URL.
port-mapping/server.py	Adds a minimal HTTP server that listens on port 8080.
port-mapping/README.md	Documents CLI + API workflows for port mapping example.
port-mapping/Kraftfile	Defines Unikraft Cloud runtime, rootfs build, and command.
port-mapping/Dockerfile	Builds a Python slim OCI image containing the server.
port-mapping/app.config	Adds shared env vars for image/instance naming and port mapping.
port-mapping/api/stop-instance.sh	Adds API helper script to stop an instance.
port-mapping/api/start-instance.sh	Adds API helper script to start an instance.
port-mapping/api/query.sh	Adds API helper script to discover FQDN and query the service.
port-mapping/api/push-image.sh	Adds API workflow helper to push a packaged image.
port-mapping/api/pkg-image.sh	Adds API workflow helper to package an image.
port-mapping/api/get-instance-info.sh	Adds API helper script to list instance info.
port-mapping/api/delete-instance.sh	Adds API helper script to delete an instance.
port-mapping/api/create-instance.sh	Adds API helper script to create an instance with explicit port mapping.
port-mapping/.gitignore	Prevents committing the real ukc.config file.

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

[Roxanacmaria]

I reviewed the implementation and tested it on my side. Everything worked as expected, and I was able to follow the implementation without any issues. The code is clear, the documentation is easy to understand, and I did not encounter any problems while running the project.

Looks good to me. Nice work!

[Dan-Andrei-Simionescu]

I went through the code and tested the functionality locally. Everything behaves as intended. The code structure is clean, the instructions provided in the documentation are straightforward to follow.

[Copilot]

Pull request overview

Copilot reviewed 15 out of 15 changed files in this pull request and generated 4 comments.

Suppressed comments (10)

port-mapping/README.md:72

• kraft cloud instance get -o json returns the instance list directly, and its CLI representation exposes the address as .fqdn (as in basic-ops/README.md:326); it does not have the API wrapper .data.instances[] or .service_group.domains. This filter therefore produces no hostname and the following curl cannot query the app. Use the CLI-shaped filter here.

fqdn=https://$(kraft cloud instance get port-mapping-demo -o json 2>/dev/null | jq -r '.data.instances[] | select(.name == "port-mapping-demo") | .service_group.domains[0].fqdn')

port-mapping/README.md:16

• The overview promises instance-log retrieval as part of both the CLI and API workflows, but this change adds no api/get-instance-logs.sh and the API command lists contain no log request. As written, the API example cannot perform one of the advertised operations; add the API log operation or narrow the claim.

- getting logs from an instance

port-mapping/README.md:74

• -k disables TLS certificate verification for the HTTPS service, so this copy-paste command accepts a man-in-the-middle endpoint and undermines the security that the tls+http mapping is meant to demonstrate. Use normal certificate validation here, or clearly scope an exception to a known test certificate.

curl -k "$fqdn"

port-mapping/api/create-instance.sh:31

• This pipes curl directly into jq, so the pipeline returns jq's status rather than curl's. A connection failure therefore produces an apparently successful script with no error output, allowing the documented deployment flow to continue as if instance creation succeeded; capture and check the curl status before parsing.

	}" | jq

port-mapping/api/delete-instance.sh:24

• Although this tests the curl result, the final rm -f out err becomes the script's exit status, so a failed delete request is reported as success. Preserve the status before cleanup and exit with it so callers can detect the failure.

if test $? -ne 0; then
    cat err 1>&2
else
    cat out | jq
fi

port-mapping/api/get-instance-info.sh:17

• Although this tests the curl result, the final rm -f out err becomes the script's exit status, so network or JSON-processing failures are reported as success. Preserve the status before cleanup and exit with it; otherwise query.sh and callers cannot detect a failed request.

if test $? -ne 0; then
    cat err 1>&2
else
    cat out | jq
fi

port-mapping/api/query.sh:8

• The API query helper disables TLS certificate verification with -k, so its copy-paste output accepts a man-in-the-middle endpoint even though it is querying the HTTPS service. Remove the bypass or make it an explicitly documented test-only option.

curl -k "$fqdn"

port-mapping/api/start-instance.sh:20

• Although this tests the curl result, the final rm -f out err becomes the script's exit status, so a failed start request is reported as success. Preserve the status before cleanup and exit with it so the documented workflow can detect the failure.

if test $? -ne 0; then
    cat err 1>&2
else
    cat out | jq
fi

port-mapping/api/stop-instance.sh:20

• Although this tests the curl result, the final rm -f out err becomes the script's exit status, so a failed stop request is reported as success. Preserve the status before cleanup and exit with it so the documented workflow can detect the failure.

if test $? -ne 0; then
    cat err 1>&2
else
    cat out | jq
fi

port-mapping/server.py:20

• This new example has no end-to-end test, although TESTING.md states that each example owns a test_<example>.py and the analogous Python HTTP example is covered. Add a test that builds this image, deploys 443:8080/tls+http, and asserts the response so regressions in the port mapping and entrypoint are exercised.

    server = HTTPServer(("0.0.0.0", 8080), Handler)