# <a name="windowsSpecificContainerConfiguration" />Windows-specific Container Configuration

This document describes the schema for the [Windows-specific section](config.md#platform-specific-configuration) of the [container configuration](config.md).
The Windows container specification uses APIs provided by the Windows Host Compute Service (HCS) to fulfill the spec.

## <a name="configWindowsLayerFolders" />LayerFolders

**`layerFolders`** (array of strings, REQUIRED) specifies a list of layer folders the container image relies on. The list is ordered from topmost layer to base layer with the last entry being the scratch.
`layerFolders` MUST contain at least one entry.

### Example

```json
"windows": {
    "layerFolders": [
        "C:\\Layers\\layer2",
        "C:\\Layers\\layer1",
        "C:\\Layers\\layer-base",
        "C:\\scratch",
    ]
}
```

## <a name="configWindowsDevices" />Devices

**`devices`** (array of objects, OPTIONAL) lists devices that MUST be available in the container.

Each entry has the following structure:

* **`id`** *(string, REQUIRED)* - specifies the device which the runtime MUST make available in the container.
* **`idType`** *(string, REQUIRED)* - tells the runtime how to interpret `id`. Today, Windows only supports a value of `class`, which identifies `id` as a [device interface class GUID][interfaceGUID].

[interfaceGUID]: https://docs.microsoft.com/en-us/windows-hardware/drivers/install/overview-of-device-interface-classes

### Example

```json
"windows": {
    "devices": [
        {
            "id": "24E552D7-6523-47F7-A647-D3465BF1F5CA",
            "idType": "class"
        },
        {
            "id": "5175d334-c371-4806-b3ba-71fd53c9258d",
            "idType": "class"
        }
    ]
}
```

## <a name="configWindowsResources" />Resources

You can configure a container's resource limits via the OPTIONAL `resources` field of the Windows configuration.

### <a name="configWindowsMemory" />Memory

`memory` is an OPTIONAL configuration for the container's memory usage.

The following parameters can be specified:

* **`limit`** *(uint64, OPTIONAL)* - sets limit of memory usage in bytes.

#### Example

```json
"windows": {
    "resources": {
        "memory": {
            "limit": 2097152
        }
    }
}
```

### <a name="configWindowsCpu" />CPU

`cpu` is an OPTIONAL configuration for the container's CPU usage.

The following parameters can be specified (mutually exclusive):

* **`count`** *(uint64, OPTIONAL)* - specifies the number of CPUs available to the container. It represents the fraction of the configured processor `count` in a container in relation to the processors available in the host. The fraction ultimately determines the portion of processor cycles that the threads in a container can use during each scheduling interval, as the number of cycles per 10,000 cycles.
* **`shares`** *(uint16, OPTIONAL)* - limits the share of processor time given to the container relative to other workloads on the processor. The processor `shares` (`weight` at the platform level) is a value between 0 and 10,000.
* **`maximum`** *(uint16, OPTIONAL)* - determines the portion of processor cycles that the threads in a container can use during each scheduling interval, as the number of cycles per 10,000 cycles. Set processor `maximum` to a percentage times 100.
* **`affinity`** *(array of objects, OPTIONAL)* - specifies the set of CPU to affinitize for this container.

  Each entry has the following structure:

  Ref: https://learn.microsoft.com/en-us/windows-hardware/drivers/ddi/miniport/ns-miniport-_group_affinity

  * **`mask`** *(uint64, REQUIRED)* - specifies the CPU mask relative to this CPU group.
  * **`group`** *(uint32, REQUIRED)* - specifies the processor group this mask refers to, as returned by GetLogicalProcessorInformationEx.

Ref: https://docs.microsoft.com/en-us/virtualization/api/hcs/schemareference#Container_Processor

#### Example

```json
"windows": {
    "resources": {
        "cpu": {
            "maximum": 5000
        }
    }
}
```

### <a name="configWindowsStorage" />Storage

`storage` is an OPTIONAL configuration for the container's storage usage.

The following parameters can be specified:

* **`iops`** *(uint64, OPTIONAL)* - specifies the maximum IO operations per second for the system drive of the container.
* **`bps`** *(uint64, OPTIONAL)* - specifies the maximum bytes per second for the system drive of the container.
* **`sandboxSize`** *(uint64, OPTIONAL)* - specifies the minimum size of the system drive in bytes.

#### Example

```json
"windows": {
    "resources": {
        "storage": {
            "iops": 50
        }
    }
}
```

## <a name="configWindowsNetwork" />Network

You can configure a container's networking options via the OPTIONAL `network` field of the Windows configuration.

The following parameters can be specified:

* **`endpointList`** *(array of strings, OPTIONAL)* - list of HNS (Host Network Service) endpoints that the container should connect to.
* **`allowUnqualifiedDNSQuery`** *(bool, OPTIONAL)* - specifies if unqualified DNS name resolution is allowed.
* **`DNSSearchList`** *(array of strings, OPTIONAL)* - comma separated list of DNS suffixes to use for name resolution.
* **`networkSharedContainerName`** *(string, OPTIONAL)* - name (ID) of the container that we will share with the network stack.
* **`networkNamespace`** *(string, OPTIONAL)* - name (ID) of the network namespace that will be used for the container. If a network namespace is specified no other parameter must be specified.

### Example

```json
"windows": {
    "network": {
        "endpointList": [
            "7a010682-17e0-4455-a838-02e5d9655fe6"
        ],
        "allowUnqualifiedDNSQuery": true,
        "DNSSearchList": [
            "a.com",
            "b.com"
        ],
        "networkSharedContainerName": "containerName",
        "networkNamespace": "168f3daf-efc6-4377-b20a-2c86764ba892"
    }
}
```

## <a name="configWindowsCredentialSpec" />Credential Spec

You can configure a container's group Managed Service Account (gMSA) via the OPTIONAL `credentialSpec` field of the Windows configuration.
The `credentialSpec` is a JSON object whose properties are implementation-defined.
For more information about gMSAs, see [Active Directory Service Accounts for Windows Containers][gMSAOverview].
For more information about tooling to generate a gMSA, see [Deployment Overview][gMSATooling].


[gMSAOverview]: https://aka.ms/windowscontainers/manage-serviceaccounts
[gMSATooling]: https://aka.ms/windowscontainers/credentialspec-tools

## <a name="configWindowsServicing" />Servicing

When a container terminates, the Host Compute Service indicates if a Windows update servicing operation is pending.
You can indicate that a container should be started in a mode to apply pending servicing operations via the OPTIONAL `servicing` field of the Windows configuration.

### Example

```json
"windows": {
    "servicing": true
}
```

## <a name="configWindowsIgnoreFlushesDuringBoot" />IgnoreFlushesDuringBoot

You can indicate that a container should be started in a mode where disk flushes are not performed during container boot via the OPTIONAL `ignoreFlushesDuringBoot` field of the Windows configuration.

### Example

```json
"windows": {
    "ignoreFlushesDuringBoot": true
}
```

## <a name="configWindowsHyperV" />HyperV

`hyperv` is an OPTIONAL field of the Windows configuration.
If present, the container MUST be run with Hyper-V isolation.
If omitted, the container MUST be run as a Windows Server container.

The following parameters can be specified:

* **`utilityVMPath`** *(string, OPTIONAL)* - specifies the path to the image used for the utility VM.
    This would be specified if using a base image which does not contain a utility VM image.
    If not supplied, the runtime will search the container filesystem layers from the bottom-most layer upwards, until it locates "UtilityVM", and default to that path.

### Example

```json
"windows": {
    "hyperv": {
        "utilityVMPath": "C:\\path\\to\\utilityvm"
    }
}
```