@@ -57,6 +57,18 @@ keywords: "API, Docker, rcli, REST, documentation"

 * `POST /containers/create` no longer supports configuring a container-wide MAC address

   via the container's `Config.MacAddress` field. A container's MAC address can now only 

   be configured via endpoint settings when connecting to a network.

+* `GET /services` now returns `SwapBytes` and `MemorySwappiness` fields as part

+  of the `Resource` requirements.

+* `GET /services/{id}` now returns `SwapBytes` and `MemorySwappiness` fields as

+  part of the `Resource` requirements.

+* `POST /services/create` now accepts `SwapBytes` and `MemorySwappiness` fields

+  as part of the `Resource` requirements.

+* `POST /services/{id}/update` now accepts `SwapBytes` and `MemorySwappiness`

+  fields as part of the `Resource` requirements.

+* `GET /tasks` now  returns `SwapBytes` and `MemorySwappiness` fields as part

+  of the `Resource` requirements.

+* `GET /tasks/{id}` now  returns `SwapBytes` and `MemorySwappiness` fields as

+  part of the `Resource` requirements.

 ## v1.51 API changes

@@ -4287,6 +4287,29 @@ definitions:

           Reservations:

             description: "Define resources reservation."

             $ref: "#/definitions/ResourceObject"

+          SwapBytes:

+            description: |

+              Amount of swap in bytes - can only be used together with a memory limit.

+              If not specified, the default behaviour is to grant a swap space twice

+              as big as the memory limit.

+              Set to -1 to enable unlimited swap.

+            type: "integer"

+            format: "int64"

+            minimum: -1

+            x-nullable: true

+            x-omitempty: true

+          MemorySwappiness:

+            description: |

+              Tune the service's containers' memory swappiness (0 to 100).

+              If not specified, defaults to the containers' OS' default, generally 60,

+              or whatever value was predefined in the image.

+              Set to -1 to unset a previously set value.

+            type: "integer"

+            format: "int64"

+            minimum: -1

+            maximum: 100

+            x-nullable: true

+            x-omitempty: true

       RestartPolicy:

         description: |

           Specification for the restart policy which applies to containers

@@ -4287,6 +4287,29 @@ definitions:

           Reservations:

             description: "Define resources reservation."

             $ref: "#/definitions/ResourceObject"

+          SwapBytes:

+            description: |

+              Amount of swap in bytes - can only be used together with a memory limit.

+              If not specified, the default behaviour is to grant a swap space twice

+              as big as the memory limit.

+              Set to -1 to enable unlimited swap.

+            type: "integer"

+            format: "int64"

+            minimum: -1

+            x-nullable: true

+            x-omitempty: true

+          MemorySwappiness:

+            description: |

+              Tune the service's containers' memory swappiness (0 to 100).

+              If not specified, defaults to the containers' OS' default, generally 60,

+              or whatever value was predefined in the image.

+              Set to -1 to unset a previously set value.

+            type: "integer"

+            format: "int64"

+            minimum: -1

+            maximum: 100

+            x-nullable: true

+            x-omitempty: true

       RestartPolicy:

         description: |

           Specification for the restart policy which applies to containers

@@ -138,6 +138,17 @@ type DiscreteGenericResource struct {

 type ResourceRequirements struct {

 	Limits       *Limit     `json:",omitempty"`

 	Reservations *Resources `json:",omitempty"`

+

+	// Amount of swap in bytes - can only be used together with a memory limit

+	// -1 means unlimited

+	// a null pointer keeps the default behaviour of granting twice the memory

+	// amount in swap

+	SwapBytes *int64 `json:"SwapBytes,omitzero"`

+

+	// Tune container memory swappiness (0 to 100) - if not specified, defaults

+	// to the container OS's default - generally 60, or the value predefined in

+	// the image; set to -1 to unset a previously set value

+	MemorySwappiness *int64 `json:MemorySwappiness,omitzero"`

 }

 // Placement represents orchestration parameters.

@@ -178,13 +178,18 @@ func ServiceSpecToGRPC(s types.ServiceSpec) (swarmapi.ServiceSpec, error) {

 		taskNetworks = append(taskNetworks, netConfig)

 	}

+	resources, err := resourcesToGRPC(s.TaskTemplate.Resources)

+	if err != nil {

+		return swarmapi.ServiceSpec{}, err

+	}

+

 	spec := swarmapi.ServiceSpec{

 		Annotations: swarmapi.Annotations{

 			Name:   name,

 			Labels: s.Labels,

 		},

 		Task: swarmapi.TaskSpec{

-			Resources:   resourcesToGRPC(s.TaskTemplate.Resources),

+			Resources:   resources,

 			LogDriver:   driverToGRPC(s.TaskTemplate.LogDriver),

 			Networks:    taskNetworks,

 			ForceUpdate: s.TaskTemplate.ForceUpdate,

@@ -439,11 +444,20 @@ func resourcesFromGRPC(ts *swarmapi.TaskSpec) *types.ResourceRequirements {

 				GenericResources: GenericResourcesFromGRPC(res.Reservations.Generic),

 			}

 		}

+		resources.SwapBytes = int64PointerFromGRPC(res.SwapBytes)

+		resources.MemorySwappiness = int64PointerFromGRPC(res.MemorySwappiness)

 	}

 	return resources

 }

+func int64PointerFromGRPC(v *gogotypes.Int64Value) *int64 {

+	if v == nil {

+		return nil

+	}

+	return &v.Value

+}

+

 // GenericResourcesToGRPC converts a GenericResource to a GRPC GenericResource

 func GenericResourcesToGRPC(genericRes []types.GenericResource) []*swarmapi.GenericResource {

 	var generic []*swarmapi.GenericResource

@@ -462,7 +476,7 @@ func GenericResourcesToGRPC(genericRes []types.GenericResource) []*swarmapi.Gene

 	return generic

 }

-func resourcesToGRPC(res *types.ResourceRequirements) *swarmapi.ResourceRequirements {

+func resourcesToGRPC(res *types.ResourceRequirements) (*swarmapi.ResourceRequirements, error) {

 	var reqs *swarmapi.ResourceRequirements

 	if res != nil {

 		reqs = &swarmapi.ResourceRequirements{}

@@ -480,8 +494,21 @@ func resourcesToGRPC(res *types.ResourceRequirements) *swarmapi.ResourceRequirem

 				Generic:     GenericResourcesToGRPC(res.Reservations.GenericResources),

 			}

 		}

+		reqs.SwapBytes = int64PointerToGRPC(res.SwapBytes)

+		reqs.MemorySwappiness = int64PointerToGRPC(res.MemorySwappiness)

+

+		if reqs.SwapBytes != nil && (reqs.Limits == nil || reqs.Limits.MemoryBytes == 0) {

+			return nil, errors.New("memory swap provided, but no memory-limit was set")

+		}

+	}

+	return reqs, nil

+}

+

+func int64PointerToGRPC(v *int64) *gogotypes.Int64Value {

+	if v == nil {

+		return nil

 	}

-	return reqs

+	return &gogotypes.Int64Value{Value: *v}

 }

 func restartPolicyFromGRPC(p *swarmapi.RestartPolicy) *types.RestartPolicy {

@@ -527,6 +527,20 @@ func (c *containerConfig) resources() container.Resources {

 	if r.Limits.MemoryBytes > 0 {

 		resources.Memory = r.Limits.MemoryBytes

+

+		if r.SwapBytes != nil {

+			if swapBytes := r.SwapBytes.Value; swapBytes == -1 {

+				// means unlimited

+				resources.MemorySwap = -1

+			} else if swapBytes >= 0 {

+				// resources.MemorySwap is actually the sum of the memory + the swap

+				resources.MemorySwap = resources.Memory + swapBytes

+			}

+		}

+	}

+

+	if r.MemorySwappiness != nil {

+		resources.MemorySwappiness = &r.MemorySwappiness.Value

 	}

 	if r.Limits.NanoCPUs > 0 {

@@ -77,6 +77,14 @@ func adjustForAPIVersion(cliVersion string, service *serviceWithLegacy) {

 	if cliVersion == "" {

 		return

 	}

+

+	if versions.LessThan(cliVersion, "1.52") {

+		if service.TaskTemplate.Resources != nil {

+			service.TaskTemplate.Resources.SwapBytes = nil

+			service.TaskTemplate.Resources.MemorySwappiness = nil

+		}

+	}

+

 	if versions.LessThan(cliVersion, "1.46") {

 		if service.TaskTemplate.ContainerSpec != nil {

 			for i, mount := range service.TaskTemplate.ContainerSpec.Mounts {

@@ -11,6 +11,9 @@ import (

 func TestAdjustForAPIVersion(t *testing.T) {

 	expectedSysctls := map[string]string{"foo": "bar"}

+	swapBytes := int64(12)

+	memorySwappiness := int64(28)

+

 	// testing the negative -- does this leave everything else alone? -- is

 	// prohibitively time-consuming to write, because it would need an object

 	// with literally every field filled in.

@@ -66,6 +69,8 @@ func TestAdjustForAPIVersion(t *testing.T) {

 				Limits: &swarm.Limit{

 					Pids: 300,

 				},

+				SwapBytes:        &swapBytes,

+				MemorySwappiness: &memorySwappiness,

 			},

 		},

 	}

@@ -73,6 +78,16 @@ func TestAdjustForAPIVersion(t *testing.T) {

 	spec := &serviceWithLegacy{

 		ServiceSpec: serviceSpec,

 	}

+

+	adjustForAPIVersion("1.52", spec)

+	if spec.TaskTemplate.Resources.MemorySwappiness == nil {

+		t.Error("SwapBytes was stripped from spec")

+	}

+

+	if spec.TaskTemplate.Resources.SwapBytes == nil {

+		t.Error("MemorySwappiness was stripped from spec")

+	}

+

 	adjustForAPIVersion("1.46", spec)

 	if !reflect.DeepEqual(

 		spec.TaskTemplate.ContainerSpec.Mounts[0].TmpfsOptions.Options,

@@ -142,4 +157,11 @@ func TestAdjustForAPIVersion(t *testing.T) {

 	if len(spec.TaskTemplate.ContainerSpec.Ulimits) != 0 {

 		t.Error("Ulimits were not stripped from spec")

 	}

+	if spec.TaskTemplate.Resources.MemorySwappiness != nil {

+		t.Error("SwapBytes was not stripped from spec")

+	}

+

+	if spec.TaskTemplate.Resources.SwapBytes != nil {

+		t.Error("MemorySwappiness was not stripped from spec")

+	}

 }

@@ -202,6 +202,21 @@ func ServiceWithPidsLimit(limit int64) ServiceSpecOpt {

 	}

 }

+func ServiceWithMemorySwap(swap *int64, memoryLimit int64) ServiceSpecOpt {

+	return func(spec *swarmtypes.ServiceSpec) {

+		ensureResources(spec)

+		spec.TaskTemplate.Resources.SwapBytes = swap

+		spec.TaskTemplate.Resources.Limits.MemoryBytes = memoryLimit

+	}

+}

+

+func ServiceWithMemorySwappiness(swappiness *int64) ServiceSpecOpt {

+	return func(spec *swarmtypes.ServiceSpec) {

+		ensureResources(spec)

+		spec.TaskTemplate.Resources.MemorySwappiness = swappiness

+	}

+}

+

 // GetRunningTasks gets the list of running tasks for a service

 func GetRunningTasks(ctx context.Context, t *testing.T, c client.ServiceAPIClient, serviceID string) []swarmtypes.Task {

 	t.Helper()

@@ -8,6 +8,7 @@ import (

 	"time"

 	cerrdefs "github.com/containerd/errdefs"

+	"github.com/docker/go-units"

 	"github.com/moby/moby/api/types/container"

 	swarmtypes "github.com/moby/moby/api/types/swarm"

 	"github.com/moby/moby/client"

@@ -464,3 +465,162 @@ func TestCreateServiceCapabilities(t *testing.T) {

 	assert.DeepEqual(t, result.Service.Spec.TaskTemplate.ContainerSpec.CapabilityAdd, capAdd)

 	assert.DeepEqual(t, result.Service.Spec.TaskTemplate.ContainerSpec.CapabilityDrop, capDrop)

 }

+

+func TestCreateServiceMemorySwap(t *testing.T) {

+	ctx := setupTest(t)

+	d := swarm.NewSwarm(ctx, t, testEnv)

+	defer d.Stop(t)

+	apiClient := d.NewClientT(t)

+	defer apiClient.Close()

+

+	toPtr := func(v int64) *int64 { return &v }

+	tests := []struct {

+		testName string

+

+		swapSpec  *int64

+		limitSpec int64

+

+		// as reported by Docker

+		expectedDockerSwap int64

+	}{

+		{

+			testName: "default",

+		},

+		{

+			testName:           "memory-limit and memory-swap",

+			swapSpec:           toPtr(1 * units.MiB),

+			limitSpec:          20 * units.MiB,

+			expectedDockerSwap: 21 * units.MiB,

+		},

+		{

+			testName:           "memory-limit alone - should default to twice as much swap",

+			limitSpec:          20 * units.MiB,

+			expectedDockerSwap: 40 * units.MiB,

+		},

+		{

+			testName:           "memory-limit and zero memory-swap",

+			swapSpec:           toPtr(0),

+			limitSpec:          20 * units.MiB,

+			expectedDockerSwap: 20 * units.MiB,

+		},

+		{

+			testName:           "memory-limit and unlimited memory-swap",

+			swapSpec:           toPtr(-1),

+			limitSpec:          20 * units.MiB,

+			expectedDockerSwap: -1,

+		},

+	}

+

+	for _, testCase := range tests {

+		t.Run("service create with "+testCase.testName, func(t *testing.T) {

+			serviceID := swarm.CreateService(

+				ctx, t, d,

+				swarm.ServiceWithMemorySwap(testCase.swapSpec, testCase.limitSpec),

+			)

+			poll.WaitOn(t, swarm.RunningTasksCount(ctx, apiClient, serviceID, 1))

+

+			service, _, err := apiClient.ServiceInspectWithRaw(ctx, serviceID, client.ServiceInspectOptions{})

+			assert.NilError(t, err)

+

+			filter := make(client.Filters)

+			filter.Add("service", serviceID)

+			tasks, err := apiClient.TaskList(ctx, client.TaskListOptions{

+				Filters: filter,

+			})

+			assert.NilError(t, err)

+			assert.Check(t, is.Equal(len(tasks), 1))

+			task := tasks[0]

+

+			if testCase.swapSpec == nil {

+				assert.Check(t, is.Nil(task.Spec.Resources.SwapBytes))

+				assert.Check(t, is.Nil(service.Spec.TaskTemplate.Resources.SwapBytes))

+			} else {

+				assert.Equal(t, *testCase.swapSpec, *task.Spec.Resources.SwapBytes)

+				assert.Equal(t, *testCase.swapSpec, *service.Spec.TaskTemplate.Resources.SwapBytes)

+			}

+

+			// if the host supports it (see https://github.com/moby/moby/blob/v17.03.2-ce/daemon/daemon_unix.go#L290-L294)

+			// then check that the swap option is set on the container, and properly reported by the group FS as well

+			if testEnv.DaemonInfo.SwapLimit {

+				ctnr, err := apiClient.ContainerInspect(ctx, task.Status.ContainerStatus.ContainerID)

+				assert.NilError(t, err)

+				assert.Equal(t, testCase.expectedDockerSwap, ctnr.HostConfig.Resources.MemorySwap)

+			}

+		})

+	}

+

+	t.Run("cannot create a service with a memory swap option without setting a memory limit", func(t *testing.T) {

+		serviceOpts := func(spec *swarmtypes.ServiceSpec) {

+			if spec.TaskTemplate.Resources == nil {

+				spec.TaskTemplate.Resources = &swarmtypes.ResourceRequirements{}

+			}

+			spec.TaskTemplate.Resources.SwapBytes = toPtr(10 * units.MiB)

+		}

+

+		spec := swarm.CreateServiceSpec(t, serviceOpts)

+		_, err := apiClient.ServiceCreate(context.Background(), spec, client.ServiceCreateOptions{})

+

+		assert.ErrorContains(t, err, "memory swap provided, but no memory-limit was set")

+	})

+}

+

+func TestCreateServiceMemorySwappiness(t *testing.T) {

+	ctx := setupTest(t)

+	d := swarm.NewSwarm(ctx, t, testEnv)

+	defer d.Stop(t)

+	apiClient := d.NewClientT(t)

+	defer apiClient.Close()

+

+	toPtr := func(v int64) *int64 { return &v }

+

+	tests := []struct {

+		testName       string

+		swappinessSpec *int64

+	}{

+		{testName: "default"},

+		{testName: "zero memory-swappiness", swappinessSpec: toPtr(0)},

+		{testName: "memory-swappiness", swappinessSpec: toPtr(28)},

+	}

+

+	for _, testCase := range tests {

+		t.Run("service create with "+testCase.testName, func(t *testing.T) {

+			serviceID := swarm.CreateService(

+				ctx, t, d,

+				swarm.ServiceWithMemorySwappiness(testCase.swappinessSpec),

+			)

+			poll.WaitOn(t, swarm.RunningTasksCount(ctx, apiClient, serviceID, 1))

+

+			filter := make(client.Filters)

+			filter.Add("service", serviceID)

+			tasks, err := apiClient.TaskList(ctx, client.TaskListOptions{

+				Filters: filter,

+			})

+			assert.NilError(t, err)

+			assert.Check(t, is.Equal(len(tasks), 1))

+			task := tasks[0]

+

+			service, _, err := apiClient.ServiceInspectWithRaw(ctx, serviceID, client.ServiceInspectOptions{})

+			assert.NilError(t, err)

+

+			// An earlier version of this test also inspected the container

+			// created by Swarm to ensure that MemorySwappiness was set on its

+			// HostConfig. However, on systems that do not support

+			// MemorySwappiness (the Github Actions platform is one, in late

+			// 2025), that field in the HostConfig is nilled out, and a warning

+			// is returned. Swarm doesn't do anything with the warning, so the

+			// setting is silently ignored. Getting the raw SysInfo can show if

+			// MemorySwappiness is supported, but that field is not present in

+			// a regular Info API call, and so is not part of

+			// testEnv.DaemonInfo and cannot be checked (easily) here. So,

+			// ultimately, we'll skip that check in the integration test.

+

+			if testCase.swappinessSpec == nil {

+				assert.Check(t, is.Nil(task.Spec.Resources.MemorySwappiness))

+				assert.Check(t, is.Nil(service.Spec.TaskTemplate.Resources.MemorySwappiness))

+			} else {

+				assert.Equal(t, *testCase.swappinessSpec, *task.Spec.Resources.MemorySwappiness)

+				assert.Equal(t, *testCase.swappinessSpec, *service.Spec.TaskTemplate.Resources.MemorySwappiness)

+			}

+		})

+	}

+}

@@ -138,6 +138,17 @@ type DiscreteGenericResource struct {

 type ResourceRequirements struct {

 	Limits       *Limit     `json:",omitempty"`

 	Reservations *Resources `json:",omitempty"`

+

+	// Amount of swap in bytes - can only be used together with a memory limit

+	// -1 means unlimited

+	// a null pointer keeps the default behaviour of granting twice the memory

+	// amount in swap

+	SwapBytes *int64 `json:"SwapBytes,omitzero"`

+

+	// Tune container memory swappiness (0 to 100) - if not specified, defaults

+	// to the container OS's default - generally 60, or the value predefined in

+	// the image; set to -1 to unset a previously set value

+	MemorySwappiness *int64 `json:MemorySwappiness,omitzero"`

 }

 // Placement represents orchestration parameters.