config-windows.md

Windows-specific Container Configuration

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

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

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

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.

Example

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

Resources

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

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

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

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.

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

Example

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

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

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

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

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

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. For more information about tooling to generate a gMSA, see Deployment Overview.

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

"windows": {
    "servicing": true
}

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

"windows": {
    "ignoreFlushesDuringBoot": true
}

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

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