k8s.io/kubernetes@v1.29.3/test/images/windows/README.md (about)

     1  # Windows image builder helpers
     2  
     3  Currently, the image building process implies using a Linux node with docker buildx, which
     4  allows us to build multiarch images, as well as building Windows images. An additional benefit
     5  to this approach is that we wouldn't have to create a new Windows node for each new Windows
     6  release (you cannot spawn containers with an OS version newer than the host OS version),
     7  simplifying the building process.
     8  
     9  However, there are few constraints when it comes to building Windows images using docker buildx:
    10  you cannot use any `RUN` or `WORKDIR` instructions in the Windows stage in the image Dockerfile,
    11  but there are a few cases in which we need to `RUN` some commands. As a workaround to this, we
    12  can simply build some helper images using a Windows docker node, publish it, and then use them
    13  in the regular Image Builder which will only have to use a Linux node. This folder contains
    14  such helper images.
    15  
    16  
    17  ## Windows node(s) setup
    18  
    19  In order to build your own helper images, a node with Windows 10 or Windows Server 2019
    20  with the latest updates installed is required. The node will have to have Docker installed,
    21  preferably version 18.06.0 or newer.
    22  
    23  Remote management must be configured for the node's Docker daemon. Exposing the Docker daemon
    24  without requiring any authentication is not recommended, and thus, it must be configured with
    25  TLS to ensure that only authorised users can interact with it. For this, the following
    26  `powershell` script can be executed:
    27  
    28  ```powershell
    29  mkdir .docker
    30  docker run --isolation=hyperv --user=ContainerAdministrator --rm `
    31    -e SERVER_NAME=$(hostname) `
    32    -e IP_ADDRESSES=127.0.0.1,YOUR_WINDOWS_BUILD_NODE_IP `
    33    -v "c:\programdata\docker:c:\programdata\docker" `
    34    -v "$env:USERPROFILE\.docker:c:\users\containeradministrator\.docker" stefanscherer/dockertls-windows:2.5.5
    35  # restart the Docker daemon.
    36  Restart-Service docker
    37  ```
    38  
    39  For more information about the above commands, you can check [here](https://hub.docker.com/r/stefanscherer/dockertls-windows/).
    40  
    41  A firewall rule to allow connections to the Docker daemon is necessary:
    42  
    43  ```powershell
    44  New-NetFirewallRule -DisplayName 'Docker SSL Inbound' -Profile @('Domain', 'Public', 'Private') -Direction Inbound -Action Allow -Protocol TCP -LocalPort 2376
    45  ```
    46  
    47  If your Windows build node is hosted by a cloud provider, make sure the port `2376` is open for the node.
    48  For example, in Azure, this is done by running the following command:
    49  
    50  ```console
    51  az vm open-port -g GROUP-NAME -n NODE-NAME --port 2376
    52  ```
    53  
    54  The `ca.pem`, `cert.pem`, and `key.pem` files that can be found in `$env:USERPROFILE\.docker`
    55  will have to copied to the `~/.docker/` on the Linux build node.
    56  
    57  ```powershell
    58  scp.exe $env:USERPROFILE\.docker\*.pem ubuntu@YOUR_LINUX_BUILD_NODE:/home/ubuntu/.docker/
    59  ```
    60  
    61  After all this, the Linux build node should be able to connect to the Windows build node:
    62  
    63  ```bash
    64  docker --tlsverify --tlscacert ~/.docker/ca.pem --tlscert ~/.docker/cert.pem --tlskey ~/.docker/key.pem -H "$REMOTE_DOCKER_URL" version
    65  ```
    66  
    67  For more information and troubleshooting about enabling Docker remote management, see
    68  [here](https://docs.microsoft.com/en-us/virtualization/windowscontainers/management/manage_remotehost)
    69  
    70  Finally, the node must be able to push the images to the desired container registry, make sure you are
    71  authenticated with the registry you're pushing to.
    72  
    73  
    74  ### Additional configuration
    75  
    76  The `powershell-helper` image uses `mcr.microsoft.com/windows/nanoserver:1809` as a base image.
    77  Note that `docker buildx` has an issue pulling cross-registry images when building images, and in
    78  order to circumvent this issue, the make target `all-push-as-linux` will push a Linux cache image
    79  which will contain only the necessary bits, and this cache image can then be used in the regular
    80  image building process. As an additional benefit, using a Linux cache image will be faster.
    81  
    82  In order to build the Linux cache image, `docker buildx` is needed. For more information about it
    83  can be read [here](../README.md).
    84  
    85  
    86  ## Building images
    87  
    88  The images are built through `make`:
    89  
    90  ```bash
    91  make REGISTRY=foo_registry REMOTE_DOCKER_URL=$REMOTE_DOCKER_URL all-push-as-linux
    92  ```