diff --git a/README.md b/README.md index 95c3003656..86959fbf27 100644 --- a/README.md +++ b/README.md @@ -2,9 +2,63 @@ [![Build status](https://github.com/microsoft/hcsshim/actions/workflows/ci.yml/badge.svg?branch=master)](https://github.com/microsoft/hcsshim/actions?query=branch%3Amaster) -This package contains the Golang interface for using the Windows [Host Compute Service](https://techcommunity.microsoft.com/t5/containers/introducing-the-host-compute-service-hcs/ba-p/382332) (HCS) to launch and manage [Windows Containers](https://docs.microsoft.com/en-us/virtualization/windowscontainers/about/). It also contains other helpers and functions for managing Windows Containers such as the Golang interface for the Host Network Service (HNS). +This package contains the Golang interface for using the Windows [Host Compute Service](https://techcommunity.microsoft.com/t5/containers/introducing-the-host-compute-service-hcs/ba-p/382332) (HCS) to launch and manage [Windows Containers](https://docs.microsoft.com/en-us/virtualization/windowscontainers/about/). It also contains other helpers and functions for managing Windows Containers such as the Golang interface for the Host Network Service (HNS), as well as code for the [guest agent](./internal/guest/README.md) (commonly referred to as the GCS or Guest Compute Service in the codebase) used to support running Linux Hyper-V containers. -It is primarily used in the [Moby Project](https://github.com/moby/moby), but it can be freely used by other projects as well. +It is primarily used in the [Moby](https://github.com/moby/moby) and [Containerd](https://github.com/containerd/containerd) projects, but it can be freely used by other projects as well. + +## Building + +While this repository can be used as a library of sorts to call the HCS apis, there are a couple binaries built out of the repository as well. The main ones being the Linux guest agent, and an implementation of the [runtime v2 containerd shim api](https://github.com/containerd/containerd/blob/master/runtime/v2/README.md). +### Linux Hyper-V Container Guest Agent + +To build the Linux guest agent itself all that's needed is to set your GOOS to "Linux" and build out of ./cmd/gcs. +```powershell +C:\> $env:GOOS="linux" +C:\> go build .\cmd\gcs\ +``` + +or on a Linux machine +```sh +> go build ./cmd/gcs +``` + +If you want it to be packaged inside of a rootfs to boot with alongside all of the other tools then you'll need to provide a rootfs that it can be packaged inside of. An easy way is to export the rootfs of a container. + +```sh +docker pull busybox +docker run --name base_image_container busybox +docker export base_image_container | gzip > base.tar.gz +BASE=./base.tar.gz +make all +``` + +If the build is successful, in the `./out` folder you should see: +```sh +> ls ./out/ +delta.tar.gz initrd.img rootfs.tar.gz +``` + +### Containerd Shim +For info on the Runtime V2 API: https://github.com/containerd/containerd/blob/master/runtime/v2/README.md. + +Contrary to the typical Linux architecture of shim -> runc, the runhcs shim is used both to launch and manage the lifetime of containers. + +```powershell +C:\> $env:GOOS="windows" +C:\> go build .\cmd\containerd-shim-runhcs-v1 +``` + +Then place the binary in the same directory that Containerd is located at in your environment. A default Containerd configuration file can be generated by running: +```powershell +.\containerd.exe config default | Out-File "C:\Program Files\containerd\config.toml" -Encoding ascii +``` + +This config file will already have the shim set as the default runtime for cri interactions. + +To trial using the shim out with ctr.exe: +```powershell +C:\> ctr.exe run --runtime io.containerd.runhcs.v1 --rm mcr.microsoft.com/windows/nanoserver:2004 windows-test cmd /c "echo Hello World!" +``` ## Contributing @@ -16,7 +70,7 @@ When you submit a pull request, a CLA-bot will automatically determine whether y a CLA and decorate the PR appropriately (e.g., label, comment). Simply follow the instructions provided by the bot. You will only need to do this once across all repos using our CLA. -We also ask that contributors [sign their commits](https://git-scm.com/docs/git-commit) using `git commit -s` or `git commit --signoff` to certify they either authored the work themselves or otherwise have permission to use it in this project. +We also ask that contributors [sign their commits](https://git-scm.com/docs/git-commit) using `git commit -s` or `git commit --signoff` to certify they either authored the work themselves or otherwise have permission to use it in this project. ## Code of Conduct diff --git a/internal/guest/README.md b/internal/guest/README.md new file mode 100644 index 0000000000..444c9bb4ae --- /dev/null +++ b/internal/guest/README.md @@ -0,0 +1,6 @@ +# Background +The packages in this directory comprise most of the code used to build the guest side agent for Linux Hyper-V containers on Windows (LCOW). The guest agent is designed to run inside a custom Linux OS for supporting Linux container payloads. It's a process that is designed to be connected to from a host machine to carry out requests for running containers in the Linux guest. + +The two binaries of importance that are built from this code are the [main guest agent](../../cmd/gcs/main.go) that facilitates communication between the host and guest and a [generic tools binary](../../cmd/gcstools/main.go) for additional functionality for device scenarios. + +As most of the rest of the repository is designed in part to run on Windows, the guest package tries to serve as a separation between the two. Any guest side LCOW specific feature work should end up here. \ No newline at end of file diff --git a/opengcs/README.md b/opengcs/README.md deleted file mode 100644 index acc247fa90..0000000000 --- a/opengcs/README.md +++ /dev/null @@ -1,34 +0,0 @@ - -# Open Guest Compute Service (opengcs) [![Build Status](https://github.com/microsoft/opengcs/actions/workflows/ci.yml/badge.svg)](https://github.com/microsoft/opengcs/actions/workflows/ci.yml) - -Open Guest Compute Service is a Linux open source project to further the development of a production quality implementation of Linux Hyper-V containers on Windows (LCOW). It's designed to run inside a custom Linux OS for supporting Linux container payload. - -# LCOW v1 (deprecated) - -The original version of `LCOW v1` was designed to run directly through `Docker` against the `HCS` (Host Compute Service) on Windows. This workflow is no longer supported by this repository however it has not been intentionally broken. If you would like to continue to use `LCOW v1` there is a branch `lcow_v1` that is the LKG branch previous to the removal of `LCOW v1` from the `master` branchline. All future efforts are focused on `LCOW v2`. - -# LCOW v2 - -The primary difference between `LCOW v1` and `LCOW v2` is that `v1` was designed to hide the concept of the Utility VM. The caller created a _Linux container_ and operated on the container as if it was natively running on Windows. In the background a lightweight Utility VM was created that actually hosted the container but this was not visible and its resources not controllable via the caller. Although this works, it severely limited certain abilities such as the concept of Kubernetes pod or placing multiple LCOW containers in a single hypervisor boundary and set of resources. - -Thus `LCOW v2` was created which has two primary differences. -- The Utility VM backing the Linux containers is a first class construct. Thus it can be managed in a lifetime separate from the actual containers running in it. -- The communication from host to guest is no longer done via the platform. This means that `LCOW v2` can iterate simply by improving its host/guest protocol with no need for taking Windows updates. - -The focus of `LCOW v2` as a replacement of `LCOW v1` is through the coordination and work that has gone into [containerd/containerd](https://github.com/containerd/containerd) and its [Runtime V2](https://github.com/containerd/containerd/tree/master/runtime/v2) interface. To see our `containerd` hostside shim please look here [Microsoft/hcsshim/cmd/containerd-shim-runhcs-v1](https://github.com/microsoft/hcsshim/tree/master/cmd/containerd-shim-runhcs-v1). - -# Contributing - -This project welcomes contributions and suggestions. Most contributions require you to agree to a -Contributor License Agreement (CLA) declaring that you have the right to, and actually do, grant us -the rights to use your contribution. For details, visit https://cla.microsoft.com. - -When you submit a pull request, a CLA-bot will automatically determine whether you need to provide -a CLA and decorate the PR appropriately (e.g., label, comment). Simply follow the instructions -provided by the bot. You will only need to do this once across all repos using our CLA. - -We also ask that contributors [sign their commits](https://git-scm.com/docs/git-commit) using `git commit -s` or `git commit --signoff` to certify they either authored the work themselves or otherwise have permission to use it in this project. - -# Code of Conduct - -This project has adopted the [Microsoft Open Source Code of Conduct](https://opensource.microsoft.com/codeofconduct/). For more information see the [Code of Conduct FAQ](https://opensource.microsoft.com/codeofconduct/faq/) or contact [opencode@microsoft.com](mailto:opencode@microsoft.com) with any additional questions or comments.