feat: Introduce guide on basic operations#250
Conversation
razvand
requested review from
Copilot,
craciunoiuc,
dragosgheorghioiu and
nurof3n
There was a problem hiding this comment.
Pull request overview
Adds a new “basic operations” guide and accompanying sample artifacts to demonstrate deploying and managing Unikraft Cloud instances/images via both the kraft CLI and direct Platform API calls.
Changes:
- Introduces a comprehensive
basic-ops/guide documenting common instance/image workflows. - Adds a minimal C HTTP server example with Dockerfile + Kraftfile for packaging/deployment.
- Adds shell scripts under
basic-ops/api/to exercise Platform API endpoints for instance lifecycle operations.
Reviewed changes
Copilot reviewed 20 out of 20 changed files in this pull request and generated 18 comments.
Show a summary per file
| File | Description |
|---|---|
| basic-ops/README.md | New end-to-end guide for CLI + API workflows (commands, outputs, and steps). |
| basic-ops/ukc.config.template | Template for UKC credentials/metro (to be sourced by scripts). |
| basic-ops/app.config | Centralized app/image/instance naming variables for scripts. |
| basic-ops/Kraftfile | Kraft spec for building/running the example via kraft cloud. |
| basic-ops/Dockerfile | Builds the example HTTP server into a minimal scratch-based rootfs. |
| basic-ops/http_server.c | Minimal HTTP server used as the deployed workload. |
| basic-ops/api/pkg-image.sh | Packages the image via kraft pkg. |
| basic-ops/api/push-image.sh | Pushes the packaged image to the registry. |
| basic-ops/api/list-images.sh | Lists images via the Platform API. |
| basic-ops/api/create-instance.sh | Creates an instance via the Platform API. |
| basic-ops/api/start-instance.sh | Starts an instance via the Platform API. |
| basic-ops/api/stop-instance.sh | Stops an instance via the Platform API. |
| basic-ops/api/delete-instance.sh | Deletes an instance via the Platform API. |
| basic-ops/api/list-instances.sh | Lists instances via the Platform API. |
| basic-ops/api/get-instance-info.sh | Fetches instance info via the Platform API. |
| basic-ops/api/get-instance-logs.sh | Fetches/decodes instance logs via the Platform API. |
| basic-ops/api/query.sh | Queries the deployed service using the discovered FQDN. |
| basic-ops/api/list-services.sh | Lists services via the Platform API. |
| basic-ops/api/get-image-sha.sh | Extracts the local packaged image index/digest via kraft pkg ls. |
| basic-ops/.gitignore | Prevents committing ukc.config credentials file. |
💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.
| Create a `ukc.config` file as a copy of the `ukc.config.template`. | ||
| Replace the `TODO` entries in the `ukc.config` file with your corresponding Unikraft Cloud configuration values: user, token and metro. | ||
|
|
||
| ## TLDR: Deploy and Operate and Instance |
There was a problem hiding this comment.
Section title has a grammatical typo: "Operate and Instance" should be "Operate an Instance" (or similar) for readability.
| ## TLDR: Deploy and Operate and Instance | |
| ## TLDR: Deploy and Operate an Instance |
|
|
||
| ## Detailed Operations with the Kraft CLI | ||
|
|
||
| Below are detailed commands to deploy and operate instances with the [`kraft` CLI](https://unikraft.org/docs/cli/install)). |
There was a problem hiding this comment.
There is an extra closing parenthesis in the markdown link ("...install))"), which breaks the rendered link.
| Below are detailed commands to deploy and operate instances with the [`kraft` CLI](https://unikraft.org/docs/cli/install)). | |
| Below are detailed commands to deploy and operate instances with the [`kraft` CLI](https://unikraft.org/docs/cli/install). |
| Before anything, make sure you source the Unikraft Cloud configuration file `ukc.config`: | ||
|
|
||
| ```console | ||
| source uk.config |
There was a problem hiding this comment.
The command sources uk.config, but the setup section and repository file are ukc.config. As written, users will get a "file not found" error.
| source uk.config | |
| source ukc.config |
| These scripts make HTTP requests (via `curl`) to the REST API exposed by the platform. | ||
|
|
||
| > [!NOTE] | ||
| > Image related operations are do not interact with the platform API. |
There was a problem hiding this comment.
Grammar issue: "Image related operations are do not interact" should be corrected (e.g., "Image-related operations do not interact...").
| > Image related operations are do not interact with the platform API. | |
| > Image-related operations do not interact with the platform API. |
| IMAGE_SHA=$(./api/get-image-sha.sh) | ||
|
|
There was a problem hiding this comment.
IMAGE_SHA is computed but never used, which is confusing and suggests the request payload is incomplete (especially since the image reference later hard-codes :latest). Either use IMAGE_SHA in the payload or remove it.
| IMAGE_SHA=$(./api/get-image-sha.sh) |
| curl \ | ||
| --insecure \ |
There was a problem hiding this comment.
All API calls pass --insecure, which disables TLS certificate verification and makes the examples vulnerable to MITM. Prefer verifying TLS by default and only document --insecure as an explicit troubleshooting option (or gate it behind an env var).
| curl \ | |
| --insecure \ | |
| # Set UKC_INSECURE=1 to disable TLS certificate verification (for troubleshooting only). | |
| if [ "${UKC_INSECURE}" = "1" ]; then | |
| INSECURE_FLAG="--insecure" | |
| else | |
| INSECURE_FLAG="" | |
| fi | |
| curl \ | |
| ${INSECURE_FLAG} \ |
There was a problem hiding this comment.
I think it should be removed completely for this guide
|
|
||
| 1. Packages the image locally. | ||
| 1. Pushes the image to the remote Unikraft Cloud image registry. | ||
| 1. Creates and starts an instance from the image. |
There was a problem hiding this comment.
Steps should be incremented here instead of 1,1,1.
| curl \ | ||
| --insecure \ |
There was a problem hiding this comment.
I think it should be removed completely for this guide
dragosgheorghioiu
force-pushed
the
razvand/feature/basic-ops
branch
from
88a20b9 to
7ff63d1
Compare
This guide presents the basic operations when working with Unikraft Cloud instances and images. Namely, it presents: - deploying an instance (and an image) - creating an image - pushing an image - creating an instance - starting an instance - listing instances - listing images - getting information about an instance - getting logs from an instance - stopping an instance - deleting an instance The guide explains how to do the above basic operations both using the `kraft` CLI tool and directly using the underlying Unikraft Cloud platform API. The target application in the guide is a simple C HTTP server. For now, the commands assume a current (March 2026) stable version of the Unikraft Cloud platform. The guide is to be updated when a new stable release comes about. Signed-off-by: Razvan Deaconescu <razvand@unikraft.io>
dragosgheorghioiu
force-pushed
the
razvand/feature/basic-ops
branch
from
7ff63d1 to
572b0a9
Compare
This guide presents the basic operations when working with Unikraft Cloud instances and images. Namely, it presents:
The guide explains how to do the above basic operations both using the
kraftCLI tool and directly using the underlying Unikraft Cloud platform API.The target application in the guide is a simple C HTTP server.
For now, the commands assume a current (March 2026) stable version of the Unikraft Cloud platform. The guide is to be updated when a new stable release comes about.