schema1.go

Documentation: github.com/Microsoft/hcsshim/internal/hcs/schema1

     1  //go:build windows
     2  
     3  package schema1
     4  
     5  import (
     6  	"encoding/json"
     7  	"time"
     8  
     9  	"github.com/Microsoft/go-winio/pkg/guid"
    10  	hcsschema "github.com/Microsoft/hcsshim/internal/hcs/schema2"
    11  )
    12  
    13  // ProcessConfig is used as both the input of Container.CreateProcess
    14  // and to convert the parameters to JSON for passing onto the HCS
    15  type ProcessConfig struct {
    16  	ApplicationName   string            `json:",omitempty"`
    17  	CommandLine       string            `json:",omitempty"`
    18  	CommandArgs       []string          `json:",omitempty"` // Used by Linux Containers on Windows
    19  	User              string            `json:",omitempty"`
    20  	WorkingDirectory  string            `json:",omitempty"`
    21  	Environment       map[string]string `json:",omitempty"`
    22  	EmulateConsole    bool              `json:",omitempty"`
    23  	CreateStdInPipe   bool              `json:",omitempty"`
    24  	CreateStdOutPipe  bool              `json:",omitempty"`
    25  	CreateStdErrPipe  bool              `json:",omitempty"`
    26  	ConsoleSize       [2]uint           `json:",omitempty"`
    27  	CreateInUtilityVm bool              `json:",omitempty"` // Used by Linux Containers on Windows
    28  	OCISpecification  *json.RawMessage  `json:",omitempty"` // Used by Linux Containers on Windows
    29  }
    30  
    31  type Layer struct {
    32  	ID   string
    33  	Path string
    34  }
    35  
    36  type MappedDir struct {
    37  	HostPath          string
    38  	ContainerPath     string
    39  	ReadOnly          bool
    40  	BandwidthMaximum  uint64
    41  	IOPSMaximum       uint64
    42  	CreateInUtilityVM bool
    43  	// LinuxMetadata - Support added in 1803/RS4+.
    44  	LinuxMetadata bool `json:",omitempty"`
    45  }
    46  
    47  type MappedPipe struct {
    48  	HostPath          string
    49  	ContainerPipeName string
    50  }
    51  
    52  type HvRuntime struct {
    53  	ImagePath           string `json:",omitempty"`
    54  	SkipTemplate        bool   `json:",omitempty"`
    55  	LinuxInitrdFile     string `json:",omitempty"` // File under ImagePath on host containing an initrd image for starting a Linux utility VM
    56  	LinuxKernelFile     string `json:",omitempty"` // File under ImagePath on host containing a kernel for starting a Linux utility VM
    57  	LinuxBootParameters string `json:",omitempty"` // Additional boot parameters for starting a Linux Utility VM in initrd mode
    58  	BootSource          string `json:",omitempty"` // "Vhd" for Linux Utility VM booting from VHD
    59  	WritableBootSource  bool   `json:",omitempty"` // Linux Utility VM booting from VHD
    60  }
    61  
    62  type MappedVirtualDisk struct {
    63  	HostPath          string `json:",omitempty"` // Path to VHD on the host
    64  	ContainerPath     string // Platform-specific mount point path in the container
    65  	CreateInUtilityVM bool   `json:",omitempty"`
    66  	ReadOnly          bool   `json:",omitempty"`
    67  	Cache             string `json:",omitempty"` // "" (Unspecified); "Disabled"; "Enabled"; "Private"; "PrivateAllowSharing"
    68  	AttachOnly        bool   `json:",omitempty"`
    69  }
    70  
    71  // AssignedDevice represents a device that has been directly assigned to a container
    72  //
    73  // NOTE: Support added in RS5
    74  type AssignedDevice struct {
    75  	//  InterfaceClassGUID of the device to assign to container.
    76  	InterfaceClassGUID string `json:"InterfaceClassGuid,omitempty"`
    77  }
    78  
    79  // ContainerConfig is used as both the input of CreateContainer
    80  // and to convert the parameters to JSON for passing onto the HCS
    81  type ContainerConfig struct {
    82  	SystemType                  string              // HCS requires this to be hard-coded to "Container"
    83  	Name                        string              // Name of the container. We use the docker ID.
    84  	Owner                       string              `json:",omitempty"` // The management platform that created this container
    85  	VolumePath                  string              `json:",omitempty"` // Windows volume path for scratch space. Used by Windows Server Containers only. Format \\?\\Volume{GUID}
    86  	IgnoreFlushesDuringBoot     bool                `json:",omitempty"` // Optimization hint for container startup in Windows
    87  	LayerFolderPath             string              `json:",omitempty"` // Where the layer folders are located. Used by Windows Server Containers only. Format  %root%\windowsfilter\containerID
    88  	Layers                      []Layer             // List of storage layers. Required for Windows Server and Hyper-V Containers. Format ID=GUID;Path=%root%\windowsfilter\layerID
    89  	Credentials                 string              `json:",omitempty"` // Credentials information
    90  	ProcessorCount              uint32              `json:",omitempty"` // Number of processors to assign to the container.
    91  	ProcessorWeight             uint64              `json:",omitempty"` // CPU shares (relative weight to other containers with cpu shares). Range is from 1 to 10000. A value of 0 results in default shares.
    92  	ProcessorMaximum            int64               `json:",omitempty"` // Specifies the portion of processor cycles that this container can use as a percentage times 100. Range is from 1 to 10000. A value of 0 results in no limit.
    93  	StorageIOPSMaximum          uint64              `json:",omitempty"` // Maximum Storage IOPS
    94  	StorageBandwidthMaximum     uint64              `json:",omitempty"` // Maximum Storage Bandwidth in bytes per second
    95  	StorageSandboxSize          uint64              `json:",omitempty"` // Size in bytes that the container system drive should be expanded to if smaller
    96  	MemoryMaximumInMB           int64               `json:",omitempty"` // Maximum memory available to the container in Megabytes
    97  	HostName                    string              `json:",omitempty"` // Hostname
    98  	MappedDirectories           []MappedDir         `json:",omitempty"` // List of mapped directories (volumes/mounts)
    99  	MappedPipes                 []MappedPipe        `json:",omitempty"` // List of mapped Windows named pipes
   100  	HvPartition                 bool                // True if it a Hyper-V Container
   101  	NetworkSharedContainerName  string              `json:",omitempty"` // Name (ID) of the container that we will share the network stack with.
   102  	EndpointList                []string            `json:",omitempty"` // List of networking endpoints to be attached to container
   103  	HvRuntime                   *HvRuntime          `json:",omitempty"` // Hyper-V container settings. Used by Hyper-V containers only. Format ImagePath=%root%\BaseLayerID\UtilityVM
   104  	Servicing                   bool                `json:",omitempty"` // True if this container is for servicing
   105  	AllowUnqualifiedDNSQuery    bool                `json:",omitempty"` // True to allow unqualified DNS name resolution
   106  	DNSSearchList               string              `json:",omitempty"` // Comma separated list of DNS suffixes to use for name resolution
   107  	ContainerType               string              `json:",omitempty"` // "Linux" for Linux containers on Windows. Omitted otherwise.
   108  	TerminateOnLastHandleClosed bool                `json:",omitempty"` // Should HCS terminate the container once all handles have been closed
   109  	MappedVirtualDisks          []MappedVirtualDisk `json:",omitempty"` // Array of virtual disks to mount at start
   110  	AssignedDevices             []AssignedDevice    `json:",omitempty"` // Array of devices to assign. NOTE: Support added in RS5
   111  }
   112  
   113  type ComputeSystemQuery struct {
   114  	IDs    []string `json:"Ids,omitempty"`
   115  	Types  []string `json:",omitempty"`
   116  	Names  []string `json:",omitempty"`
   117  	Owners []string `json:",omitempty"`
   118  }
   119  
   120  type PropertyType string
   121  
   122  const (
   123  	PropertyTypeStatistics        PropertyType = "Statistics"        // V1 and V2
   124  	PropertyTypeProcessList       PropertyType = "ProcessList"       // V1 and V2
   125  	PropertyTypeMappedVirtualDisk PropertyType = "MappedVirtualDisk" // Not supported in V2 schema call
   126  	PropertyTypeGuestConnection   PropertyType = "GuestConnection"   // V1 and V2. Nil return from HCS before RS5
   127  )
   128  
   129  type PropertyQuery struct {
   130  	PropertyTypes []PropertyType `json:",omitempty"`
   131  }
   132  
   133  // ContainerProperties holds the properties for a container and the processes running in that container
   134  type ContainerProperties struct {
   135  	ID                           string `json:"Id"`
   136  	State                        string
   137  	Name                         string
   138  	SystemType                   string
   139  	RuntimeOSType                string `json:"RuntimeOsType,omitempty"`
   140  	Owner                        string
   141  	SiloGUID                     string                              `json:"SiloGuid,omitempty"`
   142  	RuntimeID                    guid.GUID                           `json:"RuntimeId,omitempty"`
   143  	IsRuntimeTemplate            bool                                `json:",omitempty"`
   144  	RuntimeImagePath             string                              `json:",omitempty"`
   145  	Stopped                      bool                                `json:",omitempty"`
   146  	ExitType                     string                              `json:",omitempty"`
   147  	AreUpdatesPending            bool                                `json:",omitempty"`
   148  	ObRoot                       string                              `json:",omitempty"`
   149  	Statistics                   Statistics                          `json:",omitempty"`
   150  	ProcessList                  []ProcessListItem                   `json:",omitempty"`
   151  	MappedVirtualDiskControllers map[int]MappedVirtualDiskController `json:",omitempty"`
   152  	GuestConnectionInfo          GuestConnectionInfo                 `json:",omitempty"`
   153  }
   154  
   155  // MemoryStats holds the memory statistics for a container
   156  type MemoryStats struct {
   157  	UsageCommitBytes            uint64 `json:"MemoryUsageCommitBytes,omitempty"`
   158  	UsageCommitPeakBytes        uint64 `json:"MemoryUsageCommitPeakBytes,omitempty"`
   159  	UsagePrivateWorkingSetBytes uint64 `json:"MemoryUsagePrivateWorkingSetBytes,omitempty"`
   160  }
   161  
   162  // ProcessorStats holds the processor statistics for a container
   163  type ProcessorStats struct {
   164  	TotalRuntime100ns  uint64 `json:",omitempty"`
   165  	RuntimeUser100ns   uint64 `json:",omitempty"`
   166  	RuntimeKernel100ns uint64 `json:",omitempty"`
   167  }
   168  
   169  // StorageStats holds the storage statistics for a container
   170  type StorageStats struct {
   171  	ReadCountNormalized  uint64 `json:",omitempty"`
   172  	ReadSizeBytes        uint64 `json:",omitempty"`
   173  	WriteCountNormalized uint64 `json:",omitempty"`
   174  	WriteSizeBytes       uint64 `json:",omitempty"`
   175  }
   176  
   177  // NetworkStats holds the network statistics for a container
   178  type NetworkStats struct {
   179  	BytesReceived          uint64 `json:",omitempty"`
   180  	BytesSent              uint64 `json:",omitempty"`
   181  	PacketsReceived        uint64 `json:",omitempty"`
   182  	PacketsSent            uint64 `json:",omitempty"`
   183  	DroppedPacketsIncoming uint64 `json:",omitempty"`
   184  	DroppedPacketsOutgoing uint64 `json:",omitempty"`
   185  	EndpointId             string `json:",omitempty"`
   186  	InstanceId             string `json:",omitempty"`
   187  }
   188  
   189  // Statistics is the structure returned by a statistics call on a container
   190  type Statistics struct {
   191  	Timestamp          time.Time      `json:",omitempty"`
   192  	ContainerStartTime time.Time      `json:",omitempty"`
   193  	Uptime100ns        uint64         `json:",omitempty"`
   194  	Memory             MemoryStats    `json:",omitempty"`
   195  	Processor          ProcessorStats `json:",omitempty"`
   196  	Storage            StorageStats   `json:",omitempty"`
   197  	Network            []NetworkStats `json:",omitempty"`
   198  }
   199  
   200  // ProcessList is the structure of an item returned by a ProcessList call on a container
   201  type ProcessListItem struct {
   202  	CreateTimestamp              time.Time `json:",omitempty"`
   203  	ImageName                    string    `json:",omitempty"`
   204  	KernelTime100ns              uint64    `json:",omitempty"`
   205  	MemoryCommitBytes            uint64    `json:",omitempty"`
   206  	MemoryWorkingSetPrivateBytes uint64    `json:",omitempty"`
   207  	MemoryWorkingSetSharedBytes  uint64    `json:",omitempty"`
   208  	ProcessId                    uint32    `json:",omitempty"`
   209  	UserTime100ns                uint64    `json:",omitempty"`
   210  }
   211  
   212  // MappedVirtualDiskController is the structure of an item returned by a MappedVirtualDiskList call on a container
   213  type MappedVirtualDiskController struct {
   214  	MappedVirtualDisks map[int]MappedVirtualDisk `json:",omitempty"`
   215  }
   216  
   217  // GuestDefinedCapabilities is part of the GuestConnectionInfo returned by a GuestConnection call on a utility VM
   218  type GuestDefinedCapabilities struct {
   219  	NamespaceAddRequestSupported  bool `json:",omitempty"`
   220  	SignalProcessSupported        bool `json:",omitempty"`
   221  	DumpStacksSupported           bool `json:",omitempty"`
   222  	DeleteContainerStateSupported bool `json:",omitempty"`
   223  	UpdateContainerSupported      bool `json:",omitempty"`
   224  }
   225  
   226  // GuestConnectionInfo is the structure of an iterm return by a GuestConnection call on a utility VM
   227  type GuestConnectionInfo struct {
   228  	SupportedSchemaVersions  []hcsschema.Version      `json:",omitempty"`
   229  	ProtocolVersion          uint32                   `json:",omitempty"`
   230  	GuestDefinedCapabilities GuestDefinedCapabilities `json:",omitempty"`
   231  }
   232  
   233  // Type of Request Support in ModifySystem
   234  type RequestType string
   235  
   236  // Type of Resource Support in ModifySystem
   237  type ResourceType string
   238  
   239  // RequestType const
   240  const (
   241  	Add     RequestType  = "Add"
   242  	Remove  RequestType  = "Remove"
   243  	Network ResourceType = "Network"
   244  )
   245  
   246  // ResourceModificationRequestResponse is the structure used to send request to the container to modify the system
   247  // Supported resource types are Network and Request Types are Add/Remove
   248  type ResourceModificationRequestResponse struct {
   249  	Resource ResourceType `json:"ResourceType"`
   250  	Data     interface{}  `json:"Settings"`
   251  	Request  RequestType  `json:"RequestType,omitempty"`
   252  }
   253
View as plain text