### Install Packages and Start libvirtd Source: https://github.com/liquidmetal-dev/flintlock/blob/main/userdocs/docs/getting-started/network.md Installs required packages for KVM networking and enables/starts the libvirt daemon. ```bash sudo apt install qemu qemu-kvm libvirt-clients libvirt-daemon-system virtinst bridge-utils sudo systemctl enable libvirtd sudo systemctl start libvirtd ``` -------------------------------- ### Install Containerd Source: https://github.com/liquidmetal-dev/flintlock/blob/main/hack/scripts/README.md Installs, configures, and starts the Containerd service. Development environments will keep state under 'dev' tagged paths. ```bash ./provision.sh containerd ``` -------------------------------- ### hammertime CLI Examples Source: https://github.com/liquidmetal-dev/flintlock/blob/main/userdocs/docs/getting-started/usage.md Examples of using the hammertime CLI tool to create, get, and delete MicroVMs. Ensure the server address and namespace are correctly specified. ```bash hammertime create -a 192.168.1.66:9090 -n my-microvm -ns my-namespace ``` ```bash hammertime get -a 192.168.1.66:9090 -i ``` ```bash hammertime create -a 192.168.1.66:9090 -f spec.json ``` ```bash hammertime delete -a 192.168.1.66:9090 --all ``` -------------------------------- ### Install Flintlockd Service Source: https://github.com/liquidmetal-dev/flintlock/blob/main/hack/scripts/README.md Installs and starts the Flintlockd service. This requires Containerd to be provisioned first. Development environments assume Containerd is already set up. ```bash ./provision.sh flintlock ``` -------------------------------- ### Start Local Development Server Source: https://github.com/liquidmetal-dev/flintlock/blob/main/userdocs/README.md Starts a local development server for live previewing changes. Changes are reflected without server restart. ```bash yarn start ``` -------------------------------- ### Start Containerd Service Source: https://github.com/liquidmetal-dev/flintlock/blob/main/userdocs/docs/getting-started/containerd.md Starts the containerd service using the custom configuration file. ```bash sudo containerd --config /etc/containerd/config-dev.toml ``` -------------------------------- ### Define and Start KVM Network Source: https://github.com/liquidmetal-dev/flintlock/blob/main/userdocs/docs/getting-started/network.md Defines the KVM network using the created XML file and starts the network. This makes the new network available for use. ```bash sudo virsh net-define flintlock.xml sudo virsh net-start flintlock ``` -------------------------------- ### Install Flintlock Provisioning Script Source: https://github.com/liquidmetal-dev/flintlock/blob/main/hack/scripts/README.md Download and make the `provision.sh` script executable if you haven't cloned the repository. ```bash # if you have cloned the repository ./hack/scripts/provision.sh --help # if you have not wget https://raw.githubusercontent.com/liquidmetal-dev/flintlock/main/hack/scripts/provision.sh chmod +x provision.sh ./provision.sh --help ``` -------------------------------- ### Run E2E Tests Locally Source: https://github.com/liquidmetal-dev/flintlock/blob/main/test/e2e/README.md Execute the end-to-end tests directly on your host machine. Ensure all dependencies are installed as per the Quick-Start guide. ```bash make test-e2e ``` -------------------------------- ### Install Devmapper Dependencies Source: https://github.com/liquidmetal-dev/flintlock/blob/main/userdocs/docs/getting-started/containerd.md Installs the necessary devmapper tools and bc for host provisioning. ```bash sudo apt update sudo apt install -y dmsetup bc sudo ./hack/scripts/provision.sh devpool ``` -------------------------------- ### Start Linux VM with Vagrant Source: https://github.com/liquidmetal-dev/flintlock/blob/main/userdocs/docs/getting-started/setup.md Start a new Linux virtual machine using Vagrant from within the cloned Flintlock repository. This command may take some time to complete. ```bash vagrant up ``` -------------------------------- ### Install Dependencies Source: https://github.com/liquidmetal-dev/flintlock/blob/main/test/tools/README.md Installs the necessary Python dependencies for the run.py tool. ```bash pip3 install -r test/tools/requirements.txt ``` -------------------------------- ### Install Project Dependencies Source: https://github.com/liquidmetal-dev/flintlock/blob/main/userdocs/README.md Installs the necessary dependencies for the project using Yarn. ```bash yarn ``` -------------------------------- ### Set KVM Network to Autostart Source: https://github.com/liquidmetal-dev/flintlock/blob/main/userdocs/docs/getting-started/network.md Configures the defined KVM network to automatically start on system boot. ```bash sudo virsh net-autostart flintlock ``` -------------------------------- ### Dockerfile for Kernel/Initrd Container Image Source: https://github.com/liquidmetal-dev/flintlock/blob/main/userdocs/docs/guides/images.md Example Dockerfile to create a container image containing the uncompressed kernel and initrd. This is a minimal example and may require adjustments based on specific needs. ```dockerfile FROM scratch COPY vmlinux initrd-generic / ``` -------------------------------- ### Table Test Case Naming (Good Example) Source: https://github.com/liquidmetal-dev/flintlock/blob/main/docs/adr/0284-testing-standards.md Shows how to use a 'name' field in table test cases for clear identification of each test scenario. ```go // good ... { name: "when 'kittens' and 'puppies' expect 'cuteness'", val1: "kitten", val2: "puppy", expected: "wowsocute" }, ... ``` -------------------------------- ### Example of Model Validation in Command Implementation Source: https://github.com/liquidmetal-dev/flintlock/blob/main/docs/adr/0003-grpc-validation.md This snippet shows an example of performing model validation within the implementation of a use case command. It demonstrates how to integrate validation logic directly into the application's core logic. ```go func (c *CreateApplicationCommand) Validate() error { return validation.ValidateStruct(c, validation.Field(&c.Name, validation.Required, validation.Length(1, 100)), validation.Field(&c.Version, validation.Required, validation.Length(1, 100)), ) } ``` -------------------------------- ### Example Error Log Source: https://github.com/liquidmetal-dev/flintlock/blob/main/userdocs/docs/troubleshooting/failed-to-reconcile-vmid.md Illustrates the typical log output when a VM reconciliation fails. ```log ERRO[0007] failed to reconcile vmid Hello/aa3b711d-4b60-4ba5-8069-0511c213308c: getting microvm spec for reconcile: getting vm spec from store: finding content in store: walking content store for aa3b711d-4b60-4ba5-8069-0511c213308c: context canceled controller=microvm ``` -------------------------------- ### Clear Test Function Naming (Good Example) Source: https://github.com/liquidmetal-dev/flintlock/blob/main/docs/adr/0284-testing-standards.md Demonstrates descriptive naming for test functions to improve readability and understanding of test cases. ```go // good func TestMyFunc_happyPath_returnsFooBar(t *testing.T) { func TestMyFunc_badInputX_returnsSomeError(t *testing.T) { ``` -------------------------------- ### Install Firecracker Source: https://github.com/liquidmetal-dev/flintlock/blob/main/hack/scripts/README.md Installs the latest release of Firecracker from its feature branch. ```bash ./provision.sh firecracker ``` -------------------------------- ### Go Package Import Order with gci Source: https://github.com/liquidmetal-dev/flintlock/blob/main/docs/adr/0246-linters.md Example demonstrating how gci organizes Go package imports for better readability. It shows imports from context, fmt, external, and internal packages. ```go import ( "context" "fmt" "github.com/sirupsen/logrus" "github.com/liquidmetal-dev/flintlock/core/errors" "github.com/liquidmetal-dev/flintlock/core/models" "github.com/liquidmetal-dev/flintlock/core/ports" "github.com/liquidmetal-dev/flintlock/pkg/log" ) ``` -------------------------------- ### Start Flintlockd Service Source: https://github.com/liquidmetal-dev/flintlock/blob/main/userdocs/docs/getting-started/flintlock.md Run the flintlockd service, specifying the containerd socket, parent interface, and enabling insecure mode. This command requires sudo privileges. ```bash sudo ./bin/flintlockd run \ --containerd-socket=/run/containerd-dev/containerd.sock \ --parent-iface="${NET_DEVICE}" \ --insecure ``` -------------------------------- ### Serve Flintlock Metrics Exporter Source: https://github.com/liquidmetal-dev/flintlock/blob/main/userdocs/docs/guides/metrics.md Starts the flintlock-metrics exporter, listening on a specified HTTP endpoint and connecting to containerd. Use this to expose MicroVM metrics for Prometheus. ```bash sudo ./bin/flintlock-metrics serve \ --containerd-socket=/run/containerd-dev/containerd.sock \ --http-endpoint=0.0.0.0:8000 ``` -------------------------------- ### Whitespace Formatting: Error Check with Empty Lines Source: https://github.com/liquidmetal-dev/flintlock/blob/main/docs/adr/0246-linters.md Example of an error check section formatted with empty lines to comply with whitespace linter rules. ```go vmState := NewState(*vmid, p.config.StateRoot, p.fs) pidPath := vmState.PIDPath() exists, err := afero.Exists(p.fs, pidPath) if err != nil { return ports.MicroVMStateUnknown, fmt.Errorf("checking pid file exists: %w", err) } if !exists { return ports.MicroVMStatePending, nil } ``` -------------------------------- ### Get Latest Git Tag Source: https://github.com/liquidmetal-dev/flintlock/blob/main/docs/releasing.md Displays the most recent tag in the repository. Use this to identify the current release version. ```bash git describe --tags --abbrev=0 ``` -------------------------------- ### Example of Model Validation During Request to Model Conversion Source: https://github.com/liquidmetal-dev/flintlock/blob/main/docs/adr/0003-grpc-validation.md This snippet illustrates performing model validation during the conversion process from a request type to the internal model. This approach ensures that the model is valid before it is used by the application logic. ```go func NewApplication(req *pb.Application) (*application.Application, error) { var app application.Application err := (&app).FromProto(req) if err != nil { return nil, err } if err := validation.ValidateStruct(&app, validation.Field(&app.Name, validation.Required, validation.Length(1, 100)), validation.Field(&app.Version, validation.Required, validation.Length(1, 100)), ); if err != nil { return nil, err } return &app, nil } ``` -------------------------------- ### Build Firecracker from Source Source: https://github.com/liquidmetal-dev/flintlock/blob/main/userdocs/docs/getting-started/firecracker.md Build Firecracker from the 'feature/macvtap' branch if you need to compile it yourself. This process uses a Docker container and does not require a local Rust installation. Ensure the compiled binaries are placed in a directory included in your system's PATH. ```bash git clone https://github.com/liquidmetal-dev/firecracker.git git fetch origin feature/macvtap git checkout -b feature/macvtap origin/feature/macvtap # This will build it in a docker container, no rust installation required. tools/devtool build # Any directories on $PATH. TARGET=~/local/bin toolbox=$(uname -m)-unknown-linux-musl cp build/cargo_target/${toolbox}/debug/{firecracker,jailer} ${TARGET} ``` -------------------------------- ### TODO/FIXME Comment Tracking with godox Source: https://github.com/liquidmetal-dev/flintlock/blob/main/docs/adr/0246-linters.md Example of using godox to mark code comments like TODO or FIXME with a GitHub issue reference. This ensures that such tasks are tracked. ```go // TODO: we may hide this within the firecracker plugin. #179 ``` -------------------------------- ### Ignoring 'exhaustivestruct' Linter for Cobra Commands Source: https://github.com/liquidmetal-dev/flintlock/blob/main/docs/adr/0246-linters.md This example demonstrates ignoring the 'exhaustivestruct' linter when not all fields of a struct need to be explicitly specified, particularly for Cobra commands. ```go //nolint:exhaustivestruct // I don't want to specify all values with nil. root.AddCommand(&cobra.Command{...}) ``` -------------------------------- ### Configure E2E Test Behavior Source: https://github.com/liquidmetal-dev/flintlock/blob/main/test/e2e/README.md Pass custom flags to the end-to-end tests to modify their behavior, such as skipping setup steps or adjusting log levels. Refer to params.go for a full list of flags. ```bash ./test/e2e/test.sh -level.flintlockd=9 ``` -------------------------------- ### Build Flintlock from Source Source: https://github.com/liquidmetal-dev/flintlock/blob/main/userdocs/docs/getting-started/flintlock.md Download Go modules and build the Flintlock binary. This is required if you are not using a pre-built release. ```bash go mod download make build ``` -------------------------------- ### Set up Loop Device Thinpool for Development Source: https://github.com/liquidmetal-dev/flintlock/blob/main/hack/scripts/README.md Provisions a loop-backed thinpool for development environments. No physical device is required. ```bash ./provision.sh devpool ``` -------------------------------- ### Set up Direct LVM Thinpool Source: https://github.com/liquidmetal-dev/flintlock/blob/main/hack/scripts/README.md Configures a direct LVM thinpool. Use the `--disk` option to specify an unused blank disk. ```bash ./provision.sh direct_lvm ``` -------------------------------- ### Provision Host for Flintlock Source: https://github.com/liquidmetal-dev/flintlock/blob/main/hack/scripts/README.md The `all` command provisions a complete production-ready host. Use options to skip apt packages, specify a thinpool, disk, or GRPC address. ```bash usage: ./hack/scripts/provision.sh Script to provision hosts for running flintlock microvms COMMANDS: all Complete setup for production ready host. Component versions can be configured by setting the FLINTLOCK, CONTAINERD and FIRECRACKER environment variables. OPTIONS: -y Autoapprove all prompts (danger) --skip-apt, -s Skip installation of apt packages --thinpool, -t Name of thinpool to create (default: flintlock or flintlock-dev) --disk, -d Name blank unpartioned disk to use for direct lvm thinpool (ignored if --dev set) --grpc-address, -a Address on which to start the Flintlock GRPC server (default: local ipv4 address) --parent-iface, -i Interface of the default route of the host --dev Set up development environment. Loop thinpools will be created. apt Install all apt packages required by flintlock firecracker Install firecracker from feature branch OPTIONS: --version, -v Version to install (default: latest) containerd Install, configure and start containerd service OPTIONS: --version, -v Version to install (default: latest) --thinpool, -t Name of thinpool to include in config toml (default: flintlock-thinpool) --dev Set up development environment. Containerd will keep state under 'dev' tagged paths. flintlock Install and start flintlockd service (note: will not succeed without containerd) OPTIONS: --version, -v Version to install (default: latest) --grpc-address, -a Address on which to start the GRPC server (default: local ipv4 address) --parent-iface, -i Interface of the default route of the host --dev Assumes containerd has been provisioned in a dev environment direct_lvm Set up direct_lvm thinpool OPTIONS: -y Autoapprove all prompts (danger) --thinpool, -t Name of thinpool to create (default: flintlock) --disk, -d Name blank unpartioned disk to use for direct lvm thinpool --skip-apt, -s Skip installation of apt packages devpool Set up loop device thinpool (development environments) OPTIONS: --thinpool, -t Name of thinpool to create (default: flintlock-dev) ``` -------------------------------- ### Minimal MicroVM Create Request with Defaults Source: https://github.com/liquidmetal-dev/flintlock/blob/main/docs/adr/0241-opinionated-api-changes.md This JSON demonstrates a minimal MicroVM create request that leverages the proposed default configurations. When these defaults are applied, only essential fields like ID, kernel, initrd, and interfaces need to be explicitly provided. ```json { "microvm": { "id": "mvm1", "kernel": { "image": "docker.io/richardcase/ubuntu-bionic-kernel:0.0.11", "filename": "vmlinux" }, "initrd": { "image": "docker.io/richardcase/ubuntu-bionic-kernel:0.0.11", "filename": "initrd-generic" }, "interfaces": [ { "type": 0 } ] } } ``` -------------------------------- ### List KVM Networks Source: https://github.com/liquidmetal-dev/flintlock/blob/main/userdocs/docs/getting-started/network.md Displays a list of all defined KVM networks, their status, and autostart configuration. ```bash virsh net-list ``` -------------------------------- ### Create and Push Volume Container Image Source: https://github.com/liquidmetal-dev/flintlock/blob/main/userdocs/docs/guides/images.md Create a Docker container image from the mounted root filesystem and push it to a registry. Replace 'myorg/ubuntu-bionic-volume:v0.0.1' with your desired image name and tag. ```bash sudo tar -C ./out/images/mount -c . | docker import - myorg/ubuntu-bionic-volume:v0.0.1 docker push myorg/ubuntu-bionic-volume:v0.0.1 ``` -------------------------------- ### Create a Device Source: https://github.com/liquidmetal-dev/flintlock/blob/main/test/tools/README.md Creates a new device within an existing project. Requires your organization ID and an existing project ID. The METAL_AUTH_TOKEN environment variable must be set. ```bash export METAL_AUTH_TOKEN= ./test/tools/run.py create-device --org-id --project-id ``` -------------------------------- ### Create Containerd Directories Source: https://github.com/liquidmetal-dev/flintlock/blob/main/userdocs/docs/getting-started/containerd.md Creates the necessary directories for the containerd state and devmapper snapshotter. ```bash sudo mkdir -p /var/lib/containerd-dev/snapshotter/devmapper sudo mkdir -p /run/containerd-dev/ ``` -------------------------------- ### Build Static Website Content Source: https://github.com/liquidmetal-dev/flintlock/blob/main/userdocs/README.md Generates the static content for the website into the 'build' directory, ready for hosting. ```bash yarn build ``` -------------------------------- ### Login to Buf Registry Source: https://github.com/liquidmetal-dev/flintlock/blob/main/docs/releasing.md Logs into the buf registry using provided credentials. The username is 'liquidmetal-dev' and the key is a generated token. ```bash buf registry login # username is liquidmetal-dev # key is the token you generated ``` -------------------------------- ### Deploy Website to GitHub Pages Source: https://github.com/liquidmetal-dev/flintlock/blob/main/userdocs/README.md Builds the website and pushes it to the 'gh-pages' branch, suitable for GitHub Pages hosting. Requires setting your GitHub username. ```bash GIT_USER= USE_SSH=true yarn deploy ``` -------------------------------- ### Run Unit Tests Source: https://github.com/liquidmetal-dev/flintlock/blob/main/CONTRIBUTING.md Execute all unit tests for the project. For tests requiring containerd, ensure the CTR_SOCK_PATH environment variable is set. ```bash make test ``` ```bash # start containerd export CTR_SOCK_PATH= make test ``` -------------------------------- ### Whitespace Formatting: With Empty Lines Source: https://github.com/liquidmetal-dev/flintlock/blob/main/docs/adr/0246-linters.md Demonstrates code that adheres to the whitespace linter rules by including empty lines between logical blocks for improved readability. ```go stdOutFile, err := p.fs.OpenFile(vmState.StdoutPath(), os.O_WRONLY|os.O_CREATE|os.O_APPEND, defaults.DataFilePerm) if err != nil { return nil, fmt.Errorf("opening stdout file %s: %w", vmState.StdoutPath(), err) } stdErrFile, err := p.fs.OpenFile(vmState.StderrPath(), os.O_WRONLY|os.O_CREATE|os.O_APPEND, defaults.DataFilePerm) if err != nil { return nil, fmt.Errorf("opening sterr file %s: %w", vmState.StderrPath(), err) } cmd.Stderr = stdErrFile cmd.Stdout = stdOutFile cmd.Stdin = &bytes.Buffer{} if !exists { if err = p.fs.MkdirAll(vmState.Root(), defaults.DataDirPerm); err != nil { return fmt.Errorf("creating state directory %s: %w", vmState.Root(), err) } } ``` -------------------------------- ### Clone Flintlock Repository Source: https://github.com/liquidmetal-dev/flintlock/blob/main/userdocs/docs/getting-started/setup.md Clone the Flintlock repository and navigate into the newly created directory. This is the first step for setting up the development environment. ```bash git clone https://github.com/liquidmetal-dev/flintlock cd !$ ``` -------------------------------- ### SSH into Vagrant VM Source: https://github.com/liquidmetal-dev/flintlock/blob/main/userdocs/docs/getting-started/setup.md Connect to the newly created Linux virtual machine via SSH. All subsequent tutorial steps should be performed within this VM. ```bash vagrant ssh ``` -------------------------------- ### grpcurl Script for MicroVM Creation Source: https://github.com/liquidmetal-dev/flintlock/blob/main/userdocs/docs/getting-started/usage.md This script uses grpcurl to send a CreateMicroVM request to the Flintlock server. It's a bare-bones method for interacting with gRPC endpoints. ```bash ./hack/scripts/send.sh \ --method CreateMicroVM ``` -------------------------------- ### CreateMicroVM Source: https://github.com/liquidmetal-dev/flintlock/blob/main/userdocs/docs/grpc/services/microvm/v1alpha1/proto.md Creates a new microVM with the specified configuration and metadata. ```APIDOC ## CreateMicroVM ### Description Creates a new microVM with the specified configuration and metadata. ### Method POST ### Endpoint /v1alpha1/microvms ### Request Body - **microvm** (CreateMicroVMRequest.MicroVMSpec) - Required - The specification for the microVM to be created. - **metadata** (map[string]any) - Optional - Metadata entries for the microVM. ### Response #### Success Response (200) - **microvm** (MicroVM) - The created microVM object. ``` -------------------------------- ### Create and Connect Tap Device Source: https://github.com/liquidmetal-dev/flintlock/blob/main/userdocs/docs/getting-started/network.md Creates a new tap device and connects it to the specified bridge. This allows MicroVMs to join the virtual network. ```bash TAPNAME=tap0 sudo ip tuntap add ${TAPNAME} mode tap sudo ip link set ${TAPNAME} master ${BRIDGE} up ``` -------------------------------- ### Run E2E Tests with Config File Source: https://github.com/liquidmetal-dev/flintlock/blob/main/test/tools/README.md Executes end-to-end tests using parameters specified in a YAML configuration file. The METAL_AUTH_TOKEN environment variable must be set. ```bash export METAL_AUTH_TOKEN= ./test/tools/run.py run-e2e --config-file ``` -------------------------------- ### Run End-to-End Tests Source: https://github.com/liquidmetal-dev/flintlock/blob/main/test/tools/README.md Executes end-to-end tests on a newly provisioned device. This includes creating infrastructure, running tests, and cleaning up resources. Set the METAL_AUTH_TOKEN environment variable and provide your organization ID. ```bash export METAL_AUTH_TOKEN= ./test/tools/run.py run-e2e --org-id ``` -------------------------------- ### Configure Containerd for Devmapper Source: https://github.com/liquidmetal-dev/flintlock/blob/main/userdocs/docs/getting-started/containerd.md Saves a TOML configuration file for a separate containerd instance, specifying the devmapper snapshotter and its parameters. ```bash cat << EOF >/etc/containerd/config-dev.toml version = 2 root = "/var/lib/containerd-dev" state = "/run/containerd-dev" [grpc] address = "/run/containerd-dev/containerd.sock" [metrics] address = "127.0.0.1:1338" [plugins] [plugins."io.containerd.snapshotter.v1.devmapper"] pool_name = "flintlock-dev-thinpool" root_path = "/var/lib/containerd-dev/snapshotter/devmapper" base_image_size = "10GB" discard_blocks = true [debug] level = "trace" EOF ``` -------------------------------- ### Mount Root Filesystem Source: https://github.com/liquidmetal-dev/flintlock/blob/main/userdocs/docs/guides/images.md Mount the downloaded and processed root filesystem to a specified directory. This is a prerequisite for creating volume container images. ```bash mkdir -p out/images/mount sudo mount -o loop out/images/bionic/bionic.rootfs ./out/images/mount ``` -------------------------------- ### Clone the Flintlock Repository Source: https://github.com/liquidmetal-dev/flintlock/blob/main/CONTRIBUTING.md Clone the Flintlock repository to your local machine. Ensure you replace '' with your GitHub username. ```bash git clone git@github.com:/flintlock.git ``` -------------------------------- ### Download Ubuntu Cloud Images Source: https://github.com/liquidmetal-dev/flintlock/blob/main/userdocs/docs/guides/images.md Use this script to download and process Ubuntu Server cloud images. The processed files will be available in the 'out/images' directory. ```bash ./hack/scripts/download_cloudimages.sh ``` -------------------------------- ### Running Flintlock Daemon with Verbosity Source: https://github.com/liquidmetal-dev/flintlock/blob/main/CONTRIBUTING.md When reporting bugs, it's often helpful to reproduce the issue with maximum logging verbosity. Ensure logs are formatted with code blocks. ```bash flintlockd --verbosity 9 ``` -------------------------------- ### Run E2E Tests on Equinix Metal Source: https://github.com/liquidmetal-dev/flintlock/blob/main/test/e2e/README.md Execute end-to-end tests on an Equinix Metal device. This method uses a Python script to provision a project and device, then runs the tests. Ensure your METAL_AUTH_TOKEN and EQUINIX_ORG_ID are set. ```bash export METAL_AUTH_TOKEN= export EQUINIX_ORG_ID= make test-e2e-metal ``` -------------------------------- ### Create Git Tag Source: https://github.com/liquidmetal-dev/flintlock/blob/main/docs/releasing.md Creates a new annotated Git tag for a specific release version. Ensure the RELEASE_VERSION variable is set correctly. ```bash RELEASE_VERSION=v0.1.0-alpha.1 git tag -s "${RELEASE_VERSION}" -m "${RELEASE_VERSION}" ``` -------------------------------- ### Create a New Feature Branch Source: https://github.com/liquidmetal-dev/flintlock/blob/main/CONTRIBUTING.md Before writing code, create a new topic branch from the main branch to base your work on. Replace '' with a descriptive name for your branch. ```bash git checkout -b ``` -------------------------------- ### Create KVM Network Configuration Source: https://github.com/liquidmetal-dev/flintlock/blob/main/userdocs/docs/getting-started/network.md Defines a new KVM network configuration in XML format, specifying bridge name, NAT settings, IP range, and DHCP configuration. This is useful for creating a dedicated network for MicroVMs. ```bash BRIDGE=flbr0 cat << EOF >flintlock-net.xml flintlock EOF ``` -------------------------------- ### Manually Set Network Interface Source: https://github.com/liquidmetal-dev/flintlock/blob/main/userdocs/docs/getting-started/flintlock.md Manually specify the parent network interface name for Flintlock. Replace `` with the actual interface name. ```bash NET_DEVICE= ``` -------------------------------- ### Whitespace Formatting: Without Empty Lines Source: https://github.com/liquidmetal-dev/flintlock/blob/main/docs/adr/0246-linters.md Demonstrates code that violates the whitespace linter rules by omitting necessary empty lines between logical blocks. ```go stdOutFile, err := p.fs.OpenFile(vmState.StdoutPath(), os.O_WRONLY|os.O_CREATE|os.O_APPEND, defaults.DataFilePerm) if err != nil { return nil, fmt.Errorf("opening stdout file %s: %w", vmState.StdoutPath(), err) } stdErrFile, err := p.fs.OpenFile(vmState.StderrPath(), os.O_WRONLY|os.O_CREATE|os.O_APPEND, defaults.DataFilePerm) if err != nil { return nil, fmt.Errorf("opening sterr file %s: %w", vmState.StderrPath(), err) } cmd.Stderr = stdErrFile cmd.Stdout = stdOutFile cmd.Stdin = &bytes.Buffer{} if !exists { if err = p.fs.MkdirAll(vmState.Root(), defaults.DataDirPerm); err != nil { return fmt.Errorf("creating state directory %s: %w", vmState.Root(), err) } } ``` -------------------------------- ### Interact with Containerd Daemon Source: https://github.com/liquidmetal-dev/flintlock/blob/main/userdocs/docs/getting-started/containerd.md Lists content using the ctr tool, specifying the address of the custom containerd socket and the namespace. ```bash sudo ctr \ --address=/run/containerd-dev/containerd.sock \ --namespace=flintlock \ content ls ``` -------------------------------- ### Run E2E Tests in Docker Source: https://github.com/liquidmetal-dev/flintlock/blob/main/test/e2e/README.md Run the end-to-end tests within a Docker container on your host. Note that the container requires high privileges and shares resources with the host. ```bash make test-e2e-docker ``` -------------------------------- ### Whitespace Formatting: Error Check with Empty Lines (Alternative) Source: https://github.com/liquidmetal-dev/flintlock/blob/main/docs/adr/0246-linters.md An alternative formatting of an error check section, also demonstrating the use of empty lines for whitespace linter compliance. ```go vmState := NewState(*vmid, p.config.StateRoot, p.fs) pidPath := vmState.PIDPath() exists, err := afero.Exists(p.fs, pidPath) if err != nil { return ports.MicroVMStateUnknown, fmt.Errorf("checking pid file exists: %w", err) } if !exists { return ports.MicroVMStatePending, nil } ``` -------------------------------- ### Identify Network Interface Source: https://github.com/liquidmetal-dev/flintlock/blob/main/userdocs/docs/getting-started/flintlock.md Automatically detect the default network device on the host system. This is useful for configuring Flintlock to use the correct parent interface. ```bash NET_DEVICE=$(ip route show | awk '/default/ {print $5}') ``` -------------------------------- ### Push Buf Tag Source: https://github.com/liquidmetal-dev/flintlock/blob/main/docs/releasing.md Pushes a new tag to the buf registry for gRPC API documentation. This command should be run after API changes are introduced. ```bash buf push --tag "${RELEASE_VERSION}" ``` -------------------------------- ### View KVM Network DHCP Leases Source: https://github.com/liquidmetal-dev/flintlock/blob/main/userdocs/docs/getting-started/network.md Shows the DHCP leases for a specific KVM network, useful for checking IP assignments to MicroVMs. ```bash sudo virsh net-dhcp-leases default ``` -------------------------------- ### Build Flintlock within a Docker Container Source: https://github.com/liquidmetal-dev/flintlock/blob/main/CONTRIBUTING.md Use this command to run Flintlock development commands inside a Docker container. This ensures a consistent environment and includes necessary tools. Note the high privileges required. ```bash docker run --rm -it \ --privileged \ --volume /dev:/dev \ --volume /run/udev/control:/run/udev/control \ --volume $(pwd):/src/flintlock \ --ipc=host \ --workdir=/src/flintlock \ liquidmetal-dev/flintlock-e2e:latest \ /bin/bash ``` -------------------------------- ### Create Containerd Alias Source: https://github.com/liquidmetal-dev/flintlock/blob/main/userdocs/docs/getting-started/containerd.md Creates a shell alias for easier access to the custom containerd socket. ```bash alias ctr-dev="sudo ctr --address=/run/containerd-dev/containerd.sock" ``` -------------------------------- ### ListMicroVMs Source: https://github.com/liquidmetal-dev/flintlock/blob/main/userdocs/docs/grpc/services/microvm/v1alpha1/proto.md Lists all microVMs within a specified namespace, optionally filtered by name. ```APIDOC ## ListMicroVMs ### Description Lists all microVMs within a specified namespace, optionally filtered by name. ### Method GET ### Endpoint /v1alpha1/microvms ### Parameters #### Query Parameters - **namespace** (string) - Required - The namespace to list microVMs from. - **name** (string) - Optional - A filter to match microVM names. ### Response #### Success Response (200) - **microvm** (array[MicroVM]) - A list of microVM objects. ``` -------------------------------- ### Push Changes to Fork Source: https://github.com/liquidmetal-dev/flintlock/blob/main/CONTRIBUTING.md Use this command to push your feature branch to your fork on GitHub. Ensure you replace `` with your remote's name (e.g., 'origin') and `` with your branch's name. ```bash git push ``` -------------------------------- ### Override Component Versions Source: https://github.com/liquidmetal-dev/flintlock/blob/main/hack/scripts/README.md Set environment variables to specify versions for Flintlock, Firecracker, and Containerd. ```bash export FLINTLOCK= export FIRECRACKER= export CONTAINERD= ``` -------------------------------- ### GetMicroVM Source: https://github.com/liquidmetal-dev/flintlock/blob/main/userdocs/docs/grpc/services/microvm/v1alpha1/proto.md Retrieves a microVM by its unique identifier. ```APIDOC ## GetMicroVM ### Description Retrieves a microVM by its unique identifier. ### Method GET ### Endpoint /v1alpha1/microvms/{uid} ### Parameters #### Path Parameters - **uid** (string) - Required - The unique identifier of the microVM to retrieve. ### Response #### Success Response (200) - **microvm** (MicroVM) - The requested microVM object. ``` -------------------------------- ### Pull Git Tags Source: https://github.com/liquidmetal-dev/flintlock/blob/main/docs/releasing.md Fetches all tags from the remote repository. This is a prerequisite for checking the latest release tag. ```bash git pull --tags ``` -------------------------------- ### Delete a Device Source: https://github.com/liquidmetal-dev/flintlock/blob/main/test/tools/README.md Deletes a specified device. Requires your organization ID and the device ID. The METAL_AUTH_TOKEN environment variable must be set. The associated project is not deleted. ```bash export METAL_AUTH_TOKEN= ./test/tools/run.py delete-device --org-id --device-id ``` -------------------------------- ### Ignoring 'gosec' Linter for Command Execution Source: https://github.com/liquidmetal-dev/flintlock/blob/main/docs/adr/0246-linters.md This snippet illustrates ignoring the 'gosec' linter when executing external commands, as the intent is to run arbitrary commands provided by the caller. ```go //nolint:gosec // The purpose of this call is to execute whatever the caller wants. process := exec.Command(options.Command, options.Args...) ``` -------------------------------- ### Gomega Assertion for Equality Source: https://github.com/liquidmetal-dev/flintlock/blob/main/docs/adr/0284-testing-standards.md Use the Equal matcher to check if a result matches an expected value. ```go Expect(result.Value).To(Equal(expectedValue)) ``` -------------------------------- ### ListMicroVMsStream Source: https://github.com/liquidmetal-dev/flintlock/blob/main/userdocs/docs/grpc/services/microvm/v1alpha1/proto.md Streams microVMs within a specified namespace, optionally filtered by name. This is a streaming endpoint. ```APIDOC ## ListMicroVMsStream ### Description Streams microVMs within a specified namespace, optionally filtered by name. This is a streaming endpoint. ### Method GET ### Endpoint /v1alpha1/microvms/stream ### Parameters #### Query Parameters - **namespace** (string) - Required - The namespace to stream microVMs from. - **name** (string) - Optional - A filter to match microVM names. ### Response #### Success Response (200) - **microvm** (MicroVM) - A stream of microVM objects. ``` -------------------------------- ### Using HTML Details Tags for Long Logs Source: https://github.com/liquidmetal-dev/flintlock/blob/main/CONTRIBUTING.md For logs exceeding 50 lines, use HTML details tags to collapse them, making the issue report more concise. Ensure sensitive information is redacted. ```html
Click to expand log ``` # Log lines... # More log lines... ```
``` -------------------------------- ### Gomega Assertion for Boolean Truthiness Source: https://github.com/liquidmetal-dev/flintlock/blob/main/docs/adr/0284-testing-standards.md Use the BeTrue matcher to assert that a boolean outcome is true. ```go Expect(outcome).To(BeTrue()) ``` -------------------------------- ### Push Git Tag Source: https://github.com/liquidmetal-dev/flintlock/blob/main/docs/releasing.md Pushes the newly created Git tag to the remote repository. This makes the tag available to others and triggers CI/CD processes. ```bash git push origin "${RELEASE_VERSION}" ``` -------------------------------- ### Highlighting Code Blocks in Markdown Source: https://github.com/liquidmetal-dev/flintlock/blob/main/CONTRIBUTING.md Use markdown code blocks to format code and logs for better readability. This is essential for clear communication in issues and pull requests. ```markdown ``` # Example of a code block print('Hello, world!') ``` ``` -------------------------------- ### Gomega Assertions for Errors Source: https://github.com/liquidmetal-dev/flintlock/blob/main/docs/adr/0284-testing-standards.md Use Gomega's HaveOccurred and NotTo matchers for asserting error states. NotTo is preferred over ToNot. ```go Expect(err).NotTo(HaveOccurred()) Expect(err).To(HaveOccurred()) ``` -------------------------------- ### Commit Message Format Source: https://github.com/liquidmetal-dev/flintlock/blob/main/CONTRIBUTING.md Follow this format for commit messages to clearly communicate the what, why, and how of your changes. Ensure subject lines are under 70 characters and body lines are wrapped at 80 characters. ```text ```text