hcsshim

package module
v0.12.3 Latest Latest
Warning

This package is not in the latest version of its module.

Go to latest
Published: Apr 19, 2024 License: MIT Imports: 1 Imported by: 549

README

hcsshim

Build status

This package contains the Golang interface for using the Windows Host Compute Service (HCS) to launch and manage Windows Containers. 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 (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 and 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.

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.

C:\> $env:GOOS="linux"
C:\> go build .\cmd\gcs\

or on a Linux machine

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

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:

> ls ./out/
delta.tar.gz  initrd.img  rootfs.tar.gz
Containerd Shim

For info on the Runtime V2 API.

Contrary to the typical Linux architecture of shim -> runc, the runhcs shim is used both to launch and manage the lifetime of containers.

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:

.\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:

C:\> ctr.exe run --runtime io.containerd.runhcs.v1 --rm mcr.microsoft.com/windows/nanoserver:2004 windows-test cmd /c "echo Hello World!"

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.

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

Please see the developer certificate for more info, as well as to make sure that you can attest to the rules listed. Our CI uses the DCO Github app to ensure that all commits in a given PR are signed-off.

Linting

Code must pass a linting stage, which uses golangci-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, and can be run automatically with VSCode by adding the following to your workspace or folder settings:

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

Additional editor integrations options are also available.

Alternatively, golangci-lint can be installed and run locally:

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

> 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, go generate is run in both the root and test Go modules.

This can be done via:

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

Code of Conduct

This project has adopted the Microsoft Open Source Code of Conduct. For more information see the Code of Conduct FAQ or contact 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.

Reporting Security Issues

Security issues and bugs should be reported privately, via email, to the Microsoft Security Response Center (MSRC) at 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 key, can be found in the Security TechCenter.

For additional details, see Report a Computer Security Vulnerability on Technet


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

Documentation

Index

Constants

View Source
const (
	Nat                  = hns.Nat
	ACL                  = hns.ACL
	PA                   = hns.PA
	VLAN                 = hns.VLAN
	VSID                 = hns.VSID
	VNet                 = hns.VNet
	L2Driver             = hns.L2Driver
	Isolation            = hns.Isolation
	QOS                  = hns.QOS
	OutboundNat          = hns.OutboundNat
	ExternalLoadBalancer = hns.ExternalLoadBalancer
	Route                = hns.Route
	Proxy                = hns.Proxy
)

RequestType const

View Source
const (
	Allow = hns.Allow
	Block = hns.Block

	In  = hns.In
	Out = hns.Out

	Host   = hns.Host
	Switch = hns.Switch
)

Variables

This section is empty.

Functions

This section is empty.

Types

type ACLPolicy added in v0.5.27

type ACLPolicy = hns.ACLPolicy

type ActionType added in v0.5.27

type ActionType = hns.ActionType

type DirectionType added in v0.5.27

type DirectionType = hns.DirectionType

type IsolationPolicy added in v0.5.27

type IsolationPolicy = hns.IsolationPolicy

type NatPolicy

type NatPolicy = hns.NatPolicy

type OutboundNatPolicy added in v0.5.27

type OutboundNatPolicy = hns.OutboundNatPolicy

type PaPolicy added in v0.5.2

type PaPolicy = hns.PaPolicy

type Policy added in v0.5.27

type Policy = hns.Policy

type PolicyType added in v0.5.27

type PolicyType = hns.PolicyType

Type of Request Support in ModifySystem

type ProxyPolicy added in v0.8.8

type ProxyPolicy = hns.ProxyPolicy

type QosPolicy

type QosPolicy = hns.QosPolicy

type RuleType added in v0.5.27

type RuleType = hns.RuleType

type VlanPolicy added in v0.3.2

type VlanPolicy = hns.VlanPolicy

type VsidPolicy added in v0.3.2

type VsidPolicy = hns.VsidPolicy

Directories

Path Synopsis
cmd
gcs
Package computestorage is a wrapper around the HCS storage APIs.
Package computestorage is a wrapper around the HCS storage APIs.
ext4
Package hcn is a shim for the Host Compute Networking (HCN) service, which manages networking for Windows Server containers and Hyper-V containers.
Package hcn is a shim for the Host Compute Networking (HCN) service, which manages networking for Windows Server containers and Hyper-V containers.
internal
annotations
This package contains annotations that are not exposed to end users and mainly for testing and debugging purposes.
This package contains annotations that are not exposed to end users and mainly for testing and debugging purposes.
appargs
Package appargs provides argument validation routines for use with github.com/urfave/cli.
Package appargs provides argument validation routines for use with github.com/urfave/cli.
cmd
Package cmd provides functionality used to execute commands inside of containers or UVMs, and to connect an upstream client to those commands for handling in/out/err IO.
Package cmd provides functionality used to execute commands inside of containers or UVMs, and to connect an upstream client to those commands for handling in/out/err IO.
cni
computeagent
Code generated by protoc-gen-go-ttrpc.
Code generated by protoc-gen-go-ttrpc.
computeagent/mock
Package computeagent_mock is a generated GoMock package.
Package computeagent_mock is a generated GoMock package.
cow
credentials
Package credentials holds the necessary structs and functions for adding and removing Container Credential Guard instances (shortened to CCG normally) for V2 HCS schema containers.
Package credentials holds the necessary structs and functions for adding and removing Container Credential Guard instances (shortened to CCG normally) for V2 HCS schema containers.
exec
Package exec implements a minimalized external process launcher.
Package exec implements a minimalized external process launcher.
extendedtask
Code generated by protoc-gen-go-ttrpc.
Code generated by protoc-gen-go-ttrpc.
gcs
guest/bridge
Package bridge defines the bridge struct, which implements the control loop and functions of the GCS's bridge client.
Package bridge defines the bridge struct, which implements the control loop and functions of the GCS's bridge client.
guest/kmsg
Package kmsg contains support for parsing Linux kernel log entries read from /dev/kmsg.
Package kmsg contains support for parsing Linux kernel log entries read from /dev/kmsg.
guest/linux
Package linux contains definitions required for making a linux ioctl.
Package linux contains definitions required for making a linux ioctl.
guest/prot
Package prot defines any structures used in the communication between the HCS and the GCS.
Package prot defines any structures used in the communication between the HCS and the GCS.
guest/runtime
Package runtime defines the interface between the GCS and an OCI container runtime.
Package runtime defines the interface between the GCS and an OCI container runtime.
guest/runtime/runc
Package runc defines an implementation of the Runtime interface which uses runC as the container runtime.
Package runc defines an implementation of the Runtime interface which uses runC as the container runtime.
guest/spec
Package spec encapsulates a number of GCS specific oci spec modifications, e.g., networking mounts, sandbox path substitutions in guest etc.
Package spec encapsulates a number of GCS specific oci spec modifications, e.g., networking mounts, sandbox path substitutions in guest etc.
guest/transport
Package transport defines the interfaces describing a connection-like data transport mechanism.
Package transport defines the interfaces describing a connection-like data transport mechanism.
hcs
hns
jobobject
This package provides higher level constructs for the win32 job object API.
This package provides higher level constructs for the win32 job object API.
layers
Package layers deals with container layer mounting/unmounting for LCOW and WCOW
Package layers deals with container layer mounting/unmounting for LCOW and WCOW
log
ncproxyttrpc
Code generated by protoc-gen-go-ttrpc.
Code generated by protoc-gen-go-ttrpc.
oc
oci
resources
Package resources handles creating, updating, and releasing resources on a container
Package resources handles creating, updating, and releasing resources on a container
shimdiag
Code generated by protoc-gen-go-ttrpc.
Code generated by protoc-gen-go-ttrpc.
uvm
This package describes the external interface for utility VMs.
This package describes the external interface for utility VMs.
uvm/scsi
Package scsi handles SCSI device attachment and mounting for VMs.
Package scsi handles SCSI device attachment and mounting for VMs.
vhdx
vhdx package adds the utility methods necessary to deal with the vhdx that are used as the scratch space for the containers and the uvm.
vhdx package adds the utility methods necessary to deal with the vhdx that are used as the scratch space for the containers and the uvm.
vm
vmservice
Code generated by protoc-gen-go-ttrpc.
Code generated by protoc-gen-go-ttrpc.
wclayer
Package wclayer provides bindings to HCS's legacy layer management API and provides a higher level interface around these calls for container layer management.
Package wclayer provides bindings to HCS's legacy layer management API and provides a higher level interface around these calls for container layer management.
wclayer/cim
This package provides utilities for working with container image layers in the cim format via the wclayer APIs.
This package provides utilities for working with container image layers in the cim format via the wclayer APIs.
winapi
Package winapi contains various low-level bindings to Windows APIs.
Package winapi contains various low-level bindings to Windows APIs.
pkg
amdsevsnp
Package amdsevsnp contains minimal functionality required to fetch attestation reports inside an enlightened guest.
Package amdsevsnp contains minimal functionality required to fetch attestation reports inside an enlightened guest.
cimfs
This package provides simple go wrappers on top of the win32 CIMFS mount APIs.
This package provides simple go wrappers on top of the win32 CIMFS mount APIs.
cimfs/format
format package maintains some basic structures to allows us to read header of a cim file.
format package maintains some basic structures to allows us to read header of a cim file.
ncproxy/nodenetsvc/v0/mock
Package nodenetsvc_v0_mock is a generated GoMock package.
Package nodenetsvc_v0_mock is a generated GoMock package.
ncproxy/nodenetsvc/v1
Package v1 contains the proto and compiled go files for the node network service v1 implementation.
Package v1 contains the proto and compiled go files for the node network service v1 implementation.
ncproxy/nodenetsvc/v1/mock
Package nodenetsvc_v1_mock is a generated GoMock package.
Package nodenetsvc_v1_mock is a generated GoMock package.
ociwclayer
Package ociwclayer provides functions for importing and exporting Windows container layers from and to their OCI tar representation.
Package ociwclayer provides functions for importing and exporting Windows container layers from and to their OCI tar representation.
test module

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL