moby/vendor/github.com/Microsoft/hcsshim/README.md

# hcsshim

[![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), 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](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/main/docs/runtime-v2.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!"
```

### Containerd Shim V2

The V2 shims are the rewrite of the Windows containerd shim. The V1 shim
([`containerd-shim-runhcs-v1`](./cmd/containerd-shim-runhcs-v1)) is a single, monolithic
binary that handles LCOW (Linux Containers on Windows), Hyper-V WCOW (Windows Containers on Windows), process-isolated
WCOW and host-process containers. In the V2 model that monolith is split into focused,
per-platform shims, each backed 1:1 by a sandbox.

V2 shims are used with containerd in the same way as the V1 shim, but the
API surface they expose is different. The V1 shim implemented only the containerd
[Task API](https://github.com/containerd/containerd/blob/main/docs/runtime-v2.md),
and used it to manage both the sandbox lifecycle and the container/process (task)
lifecycle through a single service. Each V2 shim instead splits these responsibilities
across the two APIs that containerd now provides for this purpose: the
[Sandbox API](https://github.com/containerd/containerd/blob/main/docs/sandbox-api.md)
is used to manage the sandbox, while the
[Task API](https://github.com/containerd/containerd/blob/main/docs/runtime-v2.md)
is used to manage containers and processes running inside it. Internally each V2 shim
implements these as separate sandbox and task services, alongside an auxiliary
`shimdiag` service used for diagnostics.

All three shims honor the same CRI pod model. A task annotated with
`"io.kubernetes.cri.container-type": "sandbox"` is treated as the pause/infra container
that creates the pod; sibling workload tasks set `"io.kubernetes.cri.container-type":
"container"` and reference their pause via `"io.kubernetes.cri.sandbox-id"`. What a
"sandbox" *physically* corresponds to depends on the shim, and is described in each
subsection below.

#### containerd-shim-lcow-v2

- **Purpose:** Runs Linux Containers on Windows (LCOW) — a Linux utility VM hosting Linux
  containers.
- **Sandbox:** The Linux UVM. Each shim instance is backed 1:1 by a single UVM. This shim supports running
  *multiple pods in the same UVM*, so a single shim instance may host more than one
  CRI pods.
- **Tasks:** Linux containers and processes running inside the UVM, identified via the
  same CRI annotations described above.
- **Implementation:** [`./cmd/containerd-shim-lcow-v2`](./cmd/containerd-shim-lcow-v2).
- **Build Tag:** lcow
- **Platform requirement:** Windows Server 2025 (build 26100) or later.

#### containerd-shim-wcow-v2

- **Purpose:** Runs Hyper-V isolated Windows containers (WCOW) — a Windows utility VM hosting
  Process and/or Host Process Containers inside it.
- **Sandbox:** The Windows utility VM (UVM). Each shim instance is backed 1:1 by a single UVM.
- **Tasks:** the Windows containers and processes running inside the UVM, identified
  via the standard CRI annotations described above.
- **Implementation:** coming soon.
- **Build Tag:** wcow

#### containerd-shim-process-v2

- **Purpose:** Runs Process-isolated Windows Server containers and Host
  Process Containers — workloads that execute directly on the host with no utility VM.
- **Sandbox:** A *pause container*. The pause container is a minimal, long-lived
  container that owns the pod's shared resources (such as the network namespace) and
  keeps them alive while sibling workload containers are started, stopped or replaced.
  This is the standard Kubernetes pod model: the pause container is the sandbox that
  the rest of the pod attaches to.
- **Tasks:** the actual workload containers belonging to the pod, linked back to the
  pause via the `io.kubernetes.cri.sandbox-id` annotation.
- **Implementation:** coming soon.
- **Build Tag:** process

##### Building

The V2 shim sources are guarded by the build tags as mentioned above, so the tag must be passed
to `go build`. For example the `LCOW` shim has `lcow` tag-

```powershell
C:\> $env:GOOS="windows"
C:\> go build -tags lcow .\cmd\containerd-shim-lcow-v2
```

Place the resulting `containerd-shim-lcow-v2.exe` in the same directory as `containerd.exe`,
the same as for the V1 shim.

##### Running unit tests

The shim's unit tests (and the rest of the tagged packages) are run with the
shim specific build tag:

```powershell
C:\> go test -tags lcow ./...
```

##### Running parity tests

The repository ships parity tests under [`./test/parity`](./test/parity) that feed
identical inputs through the legacy V1 and the new V2 pipelines and assert that the
resulting HCS ComputeSystem documents are equivalent. They live in the `test` Go
module and are also built with the build tag:

```powershell
C:\> cd test
C:\> go test -tags lcow ./parity/...
```

## 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 [Microsoft CLA](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 require that contributors sign their commits
to certify they either authored the work themselves or otherwise have permission to use it in this project.

We also require that contributors sign their commits using  using [`git commit --signoff`][git-commit-s]
to certify they either authored the work themselves or otherwise have permission to use it in this project.
A range of commits can be signed off using [`git rebase --signoff`][git-rebase-s].

Please see  [the developer certificate](https://developercertificate.org) for more info,
as well as to make sure that you can attest to the rules listed.
Our CI uses the [DCO Github app](https://github.com/apps/dco) to ensure that all commits in a given PR are signed-off.

### Linting

Code must pass a linting stage, which uses [`golangci-lint`][lint].
Since `./test` is a separate Go module, the linter is run from both the root and the
`test` directories. Additionally, the linter is run with `GOOS` set to both `windows` and
`linux`.

The linting settings are stored in [`.golangci.yaml`](./.golangci.yaml), and can be run
automatically with VSCode by adding the following to your workspace or folder settings:

```json
    "go.lintTool": "golangci-lint",
    "go.lintOnSave": "package",
```

Additional editor [integrations options are also available][lint-ide].

Alternatively, `golangci-lint` can be [installed][lint-install] and run locally:

```shell
# use . or specify a path to only lint a package
# to show all lint errors, use flags "--max-issues-per-linter=0 --max-same-issues=0"
> golangci-lint run
```

To run across the entire repo for both `GOOS=windows` and `linux`:

```powershell
> foreach ( $goos in ('windows', 'linux') ) {
    foreach ( $repo in ('.', 'test') ) {
        pwsh -Command "cd $repo && go env -w GOOS=$goos && golangci-lint.exe run --verbose"
    }
}
```

### Go Generate

The pipeline checks that auto-generated code, via `go generate`, are up to date.
Similar to the [linting stage](#linting), `go generate` is run in both the root and test Go modules.

This can be done via:

```shell
> go generate ./...
> cd test && go generate ./...
```

## 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.

## Dependencies

This project requires Golang 1.18 or newer to build.

For system requirements to run this project, see the Microsoft docs on [Windows Container requirements](https://docs.microsoft.com/en-us/virtualization/windowscontainers/deploy-containers/system-requirements).

## Reporting Security Issues

Security issues and bugs should be reported privately, via email, to the Microsoft Security
Response Center (MSRC) at [secure@microsoft.com](mailto:secure@microsoft.com). You should
receive a response within 24 hours. If for some reason you do not, please follow up via
email to ensure we received your original message. Further information, including the
[MSRC PGP](https://technet.microsoft.com/en-us/security/dn606155) key, can be found in
the [Security TechCenter](https://technet.microsoft.com/en-us/security/default).

For additional details, see [Report a Computer Security Vulnerability](https://technet.microsoft.com/en-us/security/ff852094.aspx) on Technet

---------------
Copyright (c) 2018 Microsoft Corp.  All rights reserved.

[lint]: https://golangci-lint.run/
[lint-ide]: https://golangci-lint.run/usage/integrations/#editor-integration
[lint-install]: https://golangci-lint.run/usage/install/#local-installation

[git-commit-s]: https://git-scm.com/docs/git-commit#Documentation/git-commit.txt--s
[git-rebase-s]: https://git-scm.com/docs/git-rebase#Documentation/git-rebase.txt---signoff