github.com/tonistiigi/docker@v0.10.1-0.20240229224939-974013b0dc6a/client/container_create.go (about)

     1  package client // import "github.com/docker/docker/client"
     2  
     3  import (
     4  	"context"
     5  	"encoding/json"
     6  	"net/url"
     7  	"path"
     8  
     9  	"github.com/docker/docker/api/types/container"
    10  	"github.com/docker/docker/api/types/network"
    11  	"github.com/docker/docker/api/types/versions"
    12  	ocispec "github.com/opencontainers/image-spec/specs-go/v1"
    13  )
    14  
    15  type configWrapper struct {
    16  	*container.Config
    17  	HostConfig       *container.HostConfig
    18  	NetworkingConfig *network.NetworkingConfig
    19  }
    20  
    21  // ContainerCreate creates a new container based on the given configuration.
    22  // It can be associated with a name, but it's not mandatory.
    23  func (cli *Client) ContainerCreate(ctx context.Context, config *container.Config, hostConfig *container.HostConfig, networkingConfig *network.NetworkingConfig, platform *ocispec.Platform, containerName string) (container.CreateResponse, error) {
    24  	var response container.CreateResponse
    25  
    26  	// Make sure we negotiated (if the client is configured to do so),
    27  	// as code below contains API-version specific handling of options.
    28  	//
    29  	// Normally, version-negotiation (if enabled) would not happen until
    30  	// the API request is made.
    31  	if err := cli.checkVersion(ctx); err != nil {
    32  		return response, err
    33  	}
    34  
    35  	if err := cli.NewVersionError(ctx, "1.25", "stop timeout"); config != nil && config.StopTimeout != nil && err != nil {
    36  		return response, err
    37  	}
    38  	if err := cli.NewVersionError(ctx, "1.41", "specify container image platform"); platform != nil && err != nil {
    39  		return response, err
    40  	}
    41  	if err := cli.NewVersionError(ctx, "1.44", "specify health-check start interval"); config != nil && config.Healthcheck != nil && config.Healthcheck.StartInterval != 0 && err != nil {
    42  		return response, err
    43  	}
    44  	if err := cli.NewVersionError(ctx, "1.44", "specify mac-address per network"); hasEndpointSpecificMacAddress(networkingConfig) && err != nil {
    45  		return response, err
    46  	}
    47  
    48  	if hostConfig != nil {
    49  		if versions.LessThan(cli.ClientVersion(), "1.25") {
    50  			// When using API 1.24 and under, the client is responsible for removing the container
    51  			hostConfig.AutoRemove = false
    52  		}
    53  		if versions.GreaterThanOrEqualTo(cli.ClientVersion(), "1.42") || versions.LessThan(cli.ClientVersion(), "1.40") {
    54  			// KernelMemory was added in API 1.40, and deprecated in API 1.42
    55  			hostConfig.KernelMemory = 0
    56  		}
    57  		if platform != nil && platform.OS == "linux" && versions.LessThan(cli.ClientVersion(), "1.42") {
    58  			// When using API under 1.42, the Linux daemon doesn't respect the ConsoleSize
    59  			hostConfig.ConsoleSize = [2]uint{0, 0}
    60  		}
    61  	}
    62  
    63  	// Since API 1.44, the container-wide MacAddress is deprecated and will trigger a WARNING if it's specified.
    64  	if versions.GreaterThanOrEqualTo(cli.ClientVersion(), "1.44") {
    65  		config.MacAddress = "" //nolint:staticcheck // ignore SA1019: field is deprecated, but still used on API < v1.44.
    66  	}
    67  
    68  	query := url.Values{}
    69  	if p := formatPlatform(platform); p != "" {
    70  		query.Set("platform", p)
    71  	}
    72  
    73  	if containerName != "" {
    74  		query.Set("name", containerName)
    75  	}
    76  
    77  	body := configWrapper{
    78  		Config:           config,
    79  		HostConfig:       hostConfig,
    80  		NetworkingConfig: networkingConfig,
    81  	}
    82  
    83  	serverResp, err := cli.post(ctx, "/containers/create", query, body, nil)
    84  	defer ensureReaderClosed(serverResp)
    85  	if err != nil {
    86  		return response, err
    87  	}
    88  
    89  	err = json.NewDecoder(serverResp.body).Decode(&response)
    90  	return response, err
    91  }
    92  
    93  // formatPlatform returns a formatted string representing platform (e.g. linux/arm/v7).
    94  //
    95  // Similar to containerd's platforms.Format(), but does allow components to be
    96  // omitted (e.g. pass "architecture" only, without "os":
    97  // https://github.com/containerd/containerd/blob/v1.5.2/platforms/platforms.go#L243-L263
    98  func formatPlatform(platform *ocispec.Platform) string {
    99  	if platform == nil {
   100  		return ""
   101  	}
   102  	return path.Join(platform.OS, platform.Architecture, platform.Variant)
   103  }
   104  
   105  // hasEndpointSpecificMacAddress checks whether one of the endpoint in networkingConfig has a MacAddress defined.
   106  func hasEndpointSpecificMacAddress(networkingConfig *network.NetworkingConfig) bool {
   107  	if networkingConfig == nil {
   108  		return false
   109  	}
   110  	for _, endpoint := range networkingConfig.EndpointsConfig {
   111  		if endpoint.MacAddress != "" {
   112  			return true
   113  		}
   114  	}
   115  	return false
   116  }