feat(labels): add support for service and container labels in uc run and inspect commands

cmd/uc/service/inspect.go

@@ -3,6 +3,7 @@ package service
 import (
 	"context"
 	"fmt"
+	"maps"
 	"slices"
 	"time"
 
@@ -58,6 +59,16 @@ func inspect(ctx context.Context, uncli *cli.CLI, opts inspectOptions) error {
 	fmt.Printf("Service ID: %s\n", svc.ID)
 	fmt.Printf("Name:       %s\n", svc.Name)
 	fmt.Printf("Mode:       %s\n", svc.Mode)
+
+	spec := svc.Spec()
+	if len(spec.Labels) > 0 {
+		fmt.Println("Labels:")
+		printLabels(spec.Labels)
+	}
+	if len(spec.Container.Labels) > 0 {
+		fmt.Println("Container labels:")
+		printLabels(spec.Container.Labels)
+	}
 	fmt.Println()
 
 	// Combine regular and hook containers.
@@ -130,3 +141,10 @@ func inspect(ctx context.Context, uncli *cli.CLI, opts inspectOptions) error {
 	lipgloss.Println(t)
 	return nil
 }
+
+// printLabels prints the labels sorted by key followed by a blank line.
+func printLabels(labels map[string]string) {
+	for _, key := range slices.Sorted(maps.Keys(labels)) {
+		lipgloss.Println("  " + key + tui.Faint.Render("=") + labels[key])
+	}
+}

cmd/uc/service/run.go

@@ -21,13 +21,16 @@ import (
 type runOptions struct {
 	caddyfile         string
 	command           []string
+	containerLabels   []string
 	cpu               dockeropts.NanoCPUs
 	entrypoint        string
 	entrypointChanged bool
 	env               []string
 	image             string
+	labels            []string
 	machines          []string
 	memory            dockeropts.MemBytes
+	memoryReservation dockeropts.MemBytes
 	mode              string
 	shmSize           dockeropts.MemBytes
 	name              string
@@ -64,6 +67,9 @@ func NewRunCommand(groupID string) *cobra.Command {
 	cmd.Flags().StringVar(&opts.caddyfile, "caddyfile", "",
 		"Path to a custom Caddy config (Caddyfile) for the service. "+
 			"Cannot be used together with non-@host published ports.")
+	cmd.Flags().StringArrayVar(&opts.containerLabels, "container-label", nil,
+		"Set a Docker label on service containers. Can be specified multiple times.\n"+
+			"Format: key=value or just key for an empty value.")
 	cmd.Flags().VarP(&opts.cpu, "cpu", "",
 		"Maximum number of CPU cores a service container can use. Fractional values are allowed: "+
 			"0.5 for half a core or 2.25 for two and a quarter cores.")
@@ -72,6 +78,9 @@ func NewRunCommand(groupID string) *cobra.Command {
 	cmd.Flags().StringSliceVarP(&opts.env, "env", "e", nil,
 		"Set an environment variable for service containers. Can be specified multiple times.\n"+
 			"Format: VAR=value or just VAR to use the value from the local environment.")
+	cmd.Flags().StringArrayVarP(&opts.labels, "label", "l", nil,
+		"Set a service label. Service labels aren't applied to Docker containers, use --container-label for that.\n"+
+			"Can be specified multiple times. Format: key=value or just key for an empty value.")
 	cmd.Flags().StringVar(&opts.mode, "mode", api.ServiceModeReplicated,
 		fmt.Sprintf("Replication mode of the service: either '%s' (a specified number of containers across "+
 			"the machines) or '%s' (one container on every machine).",
@@ -83,6 +92,9 @@ func NewRunCommand(groupID string) *cobra.Command {
 		"Maximum amount of memory a service container can use. Value is a positive integer with optional unit suffix (b, k, m, g).\n"+
 			"Default unit is bytes if no suffix specified.\n"+
 			"Examples: 1073741824, 1024m, 1g (all equal 1 gibibyte)")
+	cmd.Flags().Var(&opts.memoryReservation, "memory-reservation",
+		"Minimum amount of memory reserved for a service container. Value is a positive integer with optional unit suffix (b, k, m, g).\n"+
+			"Default unit is bytes if no suffix specified.")
 	cmd.Flags().VarP(&opts.shmSize, "shm-size", "",
 		"Maximum amount of shared memory (mounted at /dev/shm) a service container can use. Value is a positive integer\n"+
 			"with optional unit suffix (b, k, m, g). Default unit is bytes if no suffix specified.\n"+
@@ -192,6 +204,15 @@ func prepareServiceSpec(opts runOptions) (api.ServiceSpec, error) {
 		return spec, err
 	}
 
+	labels, err := parseLabels(opts.labels)
+	if err != nil {
+		return spec, err
+	}
+	containerLabels, err := parseLabels(opts.containerLabels)
+	if err != nil {
+		return spec, err
+	}
+
 	switch opts.mode {
 	case api.ServiceModeReplicated, api.ServiceModeGlobal:
 	default:
@@ -232,17 +253,20 @@ func prepareServiceSpec(opts runOptions) (api.ServiceSpec, error) {
 			Command:    opts.command,
 			Env:        env,
 			Image:      opts.image,
+			Labels:     containerLabels,
 			Privileged: opts.privileged,
 			PullPolicy: opts.pull,
 			Resources: api.ContainerResources{
-				CPU:          opts.cpu.Value(),
-				Memory:       opts.memory.Value(),
-				SharedMemory: opts.shmSize.Value(),
-				Ulimits:      ulimits,
+				CPU:               opts.cpu.Value(),
+				Memory:            opts.memory.Value(),
+				MemoryReservation: opts.memoryReservation.Value(),
+				SharedMemory:      opts.shmSize.Value(),
+				Ulimits:           ulimits,
 			},
 			User:         opts.user,
 			VolumeMounts: mounts,
 		},
+		Labels:    labels,
 		Mode:      opts.mode,
 		Name:      opts.name,
 		Placement: placement,
@@ -301,6 +325,24 @@ func parseEnv(env []string) (api.EnvVars, error) {
 	return envVars, nil
 }
 
+// parseLabels parses labels from the command line arguments in the format "key=value" or just "key" for an empty value.
+func parseLabels(labels []string) (map[string]string, error) {
+	if len(labels) == 0 {
+		return nil, nil
+	}
+
+	result := make(map[string]string, len(labels))
+	for _, label := range labels {
+		key, value, _ := strings.Cut(label, "=")
+		if strings.TrimSpace(key) == "" {
+			return nil, fmt.Errorf("invalid label '%s': key must not be empty", label)
+		}
+		result[key] = value
+	}
+
+	return result, nil
+}
+
 // parseVolumeFlags parses volume flag values in Docker CLI format and returns VolumeSpecs and VolumeMounts.
 // It handles both named volumes (volume_name:/container/path[:ro|volume-nocopy])
 // and bind mounts (/host/path:/container/path[:ro]).

cmd/uc/service/run_test.go

@@ -0,0 +1,423 @@
+package service
+
+import (
+	"os"
+	"path/filepath"
+	"testing"
+
+	"github.com/docker/go-units"
+	"github.com/psviderski/uncloud/pkg/api"
+	"github.com/stretchr/testify/assert"
+	"github.com/stretchr/testify/require"
+)
+
+// validRunOptions returns the minimal options that produce a valid service spec.
+func validRunOptions() runOptions {
+	return runOptions{
+		image:    "nginx:1.27",
+		name:     "web",
+		mode:     api.ServiceModeReplicated,
+		pull:     api.PullPolicyMissing,
+		replicas: 1,
+	}
+}
+
+func TestParseLabels(t *testing.T) {
+	t.Parallel()
+
+	labels, err := parseLabels(nil)
+	require.NoError(t, err)
+	assert.Nil(t, labels)
+
+	labels, err = parseLabels([]string{"tier=frontend", "empty", "list=a,b", "expr=a=b", "tier=backend"})
+	require.NoError(t, err)
+	assert.Equal(t, map[string]string{
+		"tier":  "backend",
+		"empty": "",
+		"list":  "a,b",
+		"expr":  "a=b",
+	}, labels)
+
+	_, err = parseLabels([]string{"=value"})
+	require.ErrorContains(t, err, "key must not be empty")
+
+	_, err = parseLabels([]string{" \t =value"})
+	require.ErrorContains(t, err, "key must not be empty")
+
+	labels, err = parseLabels([]string{"key=value with spaces"})
+	require.NoError(t, err)
+	assert.Equal(t, map[string]string{"key": "value with spaces"}, labels)
+}
+
+func TestPrepareServiceSpec(t *testing.T) {
+	t.Parallel()
+
+	t.Run("minimal options", func(t *testing.T) {
+		t.Parallel()
+
+		spec, err := prepareServiceSpec(validRunOptions())
+		require.NoError(t, err)
+
+		assert.Equal(t, "web", spec.Name)
+		assert.Equal(t, api.ServiceModeReplicated, spec.Mode)
+		assert.EqualValues(t, 1, spec.Replicas)
+		assert.Equal(t, "nginx:1.27", spec.Container.Image)
+		assert.Equal(t, api.PullPolicyMissing, spec.Container.PullPolicy)
+		assert.Nil(t, spec.Caddy)
+		assert.Nil(t, spec.Labels)
+		assert.Nil(t, spec.Container.Labels)
+		assert.Nil(t, spec.Container.Entrypoint)
+		assert.Nil(t, spec.Container.Resources.Ulimits)
+		assert.Nil(t, spec.Placement.Machines)
+		assert.Empty(t, spec.Container.Env)
+		assert.Empty(t, spec.Ports)
+		assert.Empty(t, spec.Volumes)
+		assert.Empty(t, spec.Container.VolumeMounts)
+	})
+
+	t.Run("all options", func(t *testing.T) {
+		t.Parallel()
+
+		opts := validRunOptions()
+		opts.command = []string{"nginx", "-g", "daemon off;"}
+		opts.env = []string{"FOO=bar", "EMPTY=", "EXPR=a=b"}
+		opts.labels = []string{"tier=frontend"}
+		opts.containerLabels = []string{"logging=enabled"}
+		opts.machines = []string{"m1,m2", "m3"}
+		opts.privileged = true
+		opts.pull = api.PullPolicyAlways
+		opts.publish = []string{"app.example.com:8080/https", "53:5353/udp@host"}
+		opts.replicas = 3
+		opts.ulimits = []string{"nofile=1024:2048", "nproc=65535"}
+		opts.user = "1000:1000"
+		opts.volumes = []string{"data:/var/lib/data:ro"}
+		require.NoError(t, opts.cpu.Set("0.5"))
+		require.NoError(t, opts.memory.Set("128m"))
+		require.NoError(t, opts.memoryReservation.Set("32m"))
+		require.NoError(t, opts.shmSize.Set("64m"))
+
+		spec, err := prepareServiceSpec(opts)
+		require.NoError(t, err)
+
+		assert.Equal(t, api.ServiceSpec{
+			Container: api.ContainerSpec{
+				Command:    []string{"nginx", "-g", "daemon off;"},
+				Env:        api.EnvVars{"FOO": "bar", "EMPTY": "", "EXPR": "a=b"},
+				Image:      "nginx:1.27",
+				Labels:     map[string]string{"logging": "enabled"},
+				Privileged: true,
+				PullPolicy: api.PullPolicyAlways,
+				Resources: api.ContainerResources{
+					CPU:               500 * api.MilliCore,
+					Memory:            128 * units.MiB,
+					MemoryReservation: 32 * units.MiB,
+					SharedMemory:      64 * units.MiB,
+					Ulimits: map[string]api.Ulimit{
+						"nofile": {Soft: 1024, Hard: 2048},
+						"nproc":  {Soft: 65535, Hard: 65535},
+					},
+				},
+				User: "1000:1000",
+				VolumeMounts: []api.VolumeMount{
+					{VolumeName: "data", ContainerPath: "/var/lib/data", ReadOnly: true},
+				},
+			},
+			Labels:    map[string]string{"tier": "frontend"},
+			Mode:      api.ServiceModeReplicated,
+			Name:      "web",
+			Placement: api.Placement{Machines: []string{"m1", "m2", "m3"}},
+			Ports: []api.PortSpec{
+				{
+					Hostname:      "app.example.com",
+					ContainerPort: 8080,
+					Protocol:      api.ProtocolHTTPS,
+					Mode:          api.PortModeIngress,
+				},
+				{
+					PublishedPort: 53,
+					ContainerPort: 5353,
+					Protocol:      api.ProtocolUDP,
+					Mode:          api.PortModeHost,
+				},
+			},
+			Replicas: 3,
+			Volumes: []api.VolumeSpec{
+				{
+					Name:          "data",
+					Type:          api.VolumeTypeVolume,
+					VolumeOptions: &api.VolumeOptions{Name: "data"},
+				},
+			},
+		}, spec)
+	})
+
+	t.Run("generates a name when not specified", func(t *testing.T) {
+		t.Parallel()
+
+		opts := validRunOptions()
+		opts.name = ""
+		opts.image = "bitnami/nginx:latest"
+
+		spec, err := prepareServiceSpec(opts)
+		require.NoError(t, err)
+		assert.Regexp(t, `^nginx-[a-z0-9]{4}$`, spec.Name)
+	})
+
+	t.Run("keeps the specified name", func(t *testing.T) {
+		t.Parallel()
+
+		opts := validRunOptions()
+		opts.name = "custom"
+
+		spec, err := prepareServiceSpec(opts)
+		require.NoError(t, err)
+		assert.Equal(t, "custom", spec.Name)
+	})
+
+	t.Run("global mode", func(t *testing.T) {
+		t.Parallel()
+
+		opts := validRunOptions()
+		opts.mode = api.ServiceModeGlobal
+
+		spec, err := prepareServiceSpec(opts)
+		require.NoError(t, err)
+		assert.Equal(t, api.ServiceModeGlobal, spec.Mode)
+	})
+
+	t.Run("entrypoint", func(t *testing.T) {
+		t.Parallel()
+
+		opts := validRunOptions()
+		opts.entrypoint = "/bin/sh"
+		opts.entrypointChanged = true
+		spec, err := prepareServiceSpec(opts)
+		require.NoError(t, err)
+		assert.Equal(t, []string{"/bin/sh"}, spec.Container.Entrypoint)
+
+		// An explicitly empty entrypoint resets the one from the image.
+		opts = validRunOptions()
+		opts.entrypointChanged = true
+		spec, err = prepareServiceSpec(opts)
+		require.NoError(t, err)
+		assert.Equal(t, []string{""}, spec.Container.Entrypoint)
+	})
+
+	t.Run("env without a value is omitted when not set locally", func(t *testing.T) {
+		t.Parallel()
+
+		opts := validRunOptions()
+		opts.env = []string{"UNCLOUD_TEST_ENV_THAT_IS_NOT_SET"}
+
+		spec, err := prepareServiceSpec(opts)
+		require.NoError(t, err)
+		assert.NotContains(t, spec.Container.Env, "UNCLOUD_TEST_ENV_THAT_IS_NOT_SET")
+	})
+
+	t.Run("bind mount", func(t *testing.T) {
+		t.Parallel()
+
+		opts := validRunOptions()
+		opts.volumes = []string{"/data/uploads:/app/uploads"}
+
+		spec, err := prepareServiceSpec(opts)
+		require.NoError(t, err)
+
+		require.Len(t, spec.Volumes, 1)
+		assert.Regexp(t, `^bind-[a-z0-9]{4}$`, spec.Volumes[0].Name)
+		assert.Equal(t, api.VolumeTypeBind, spec.Volumes[0].Type)
+		require.NotNil(t, spec.Volumes[0].BindOptions)
+		assert.Equal(t, "/data/uploads", spec.Volumes[0].BindOptions.HostPath)
+		assert.True(t, spec.Volumes[0].BindOptions.CreateHostPath)
+
+		require.Len(t, spec.Container.VolumeMounts, 1)
+		assert.Equal(t, spec.Volumes[0].Name, spec.Container.VolumeMounts[0].VolumeName)
+		assert.Equal(t, "/app/uploads", spec.Container.VolumeMounts[0].ContainerPath)
+	})
+
+	t.Run("named volume mounted twice creates one volume", func(t *testing.T) {
+		t.Parallel()
+
+		opts := validRunOptions()
+		opts.volumes = []string{"data:/a", "data:/b"}
+
+		spec, err := prepareServiceSpec(opts)
+		require.NoError(t, err)
+		assert.Len(t, spec.Volumes, 1)
+		assert.Len(t, spec.Container.VolumeMounts, 2)
+	})
+
+	t.Run("caddyfile content is trimmed", func(t *testing.T) {
+		t.Parallel()
+
+		path := filepath.Join(t.TempDir(), "Caddyfile")
+		require.NoError(t, os.WriteFile(path, []byte("\nexample.com {\n}\n\n"), 0o600))
+
+		opts := validRunOptions()
+		opts.caddyfile = path
+
+		spec, err := prepareServiceSpec(opts)
+		require.NoError(t, err)
+		require.NotNil(t, spec.Caddy)
+		assert.Equal(t, "example.com {\n}", spec.Caddy.Config)
+	})
+
+	t.Run("empty caddyfile is ignored", func(t *testing.T) {
+		t.Parallel()
+
+		path := filepath.Join(t.TempDir(), "Caddyfile")
+		require.NoError(t, os.WriteFile(path, []byte(" \n"), 0o600))
+
+		opts := validRunOptions()
+		opts.caddyfile = path
+
+		spec, err := prepareServiceSpec(opts)
+		require.NoError(t, err)
+		assert.Nil(t, spec.Caddy)
+	})
+
+	t.Run("caddyfile can be used with host ports", func(t *testing.T) {
+		t.Parallel()
+
+		path := filepath.Join(t.TempDir(), "Caddyfile")
+		require.NoError(t, os.WriteFile(path, []byte("example.com {\n}"), 0o600))
+
+		opts := validRunOptions()
+		opts.caddyfile = path
+		opts.publish = []string{"53:5353/udp@host"}
+
+		_, err := prepareServiceSpec(opts)
+		require.NoError(t, err)
+	})
+}
+
+func TestPrepareServiceSpec_LocalEnv(t *testing.T) {
+	// Not parallel because t.Setenv changes the environment of the whole process.
+	t.Setenv("UNCLOUD_TEST_LOCAL_ENV", "from-local")
+
+	opts := validRunOptions()
+	opts.env = []string{"UNCLOUD_TEST_LOCAL_ENV"}
+
+	spec, err := prepareServiceSpec(opts)
+	require.NoError(t, err)
+	assert.Equal(t, "from-local", spec.Container.Env["UNCLOUD_TEST_LOCAL_ENV"])
+}
+
+func TestPrepareServiceSpec_Invalid(t *testing.T) {
+	t.Parallel()
+
+	caddyfile := filepath.Join(t.TempDir(), "Caddyfile")
+	require.NoError(t, os.WriteFile(caddyfile, []byte("example.com {\n}"), 0o600))
+
+	tests := []struct {
+		name    string
+		modify  func(opts *runOptions)
+		wantErr string
+	}{
+		{
+			name:    "invalid image",
+			modify:  func(opts *runOptions) { opts.image = "INVALID IMAGE" },
+			wantErr: "invalid image",
+		},
+		{
+			name:    "invalid name",
+			modify:  func(opts *runOptions) { opts.name = "Not_Valid" },
+			wantErr: "invalid service name",
+		},
+		{
+			name:    "invalid mode",
+			modify:  func(opts *runOptions) { opts.mode = "unknown" },
+			wantErr: "invalid replication mode: 'unknown'",
+		},
+		{
+			name:    "invalid pull policy",
+			modify:  func(opts *runOptions) { opts.pull = "sometimes" },
+			wantErr: "invalid pull policy: 'sometimes'",
+		},
+		{
+			name:    "invalid env",
+			modify:  func(opts *runOptions) { opts.env = []string{"=value"} },
+			wantErr: "invalid environment variable: '=value'",
+		},
+		{
+			name:    "invalid port",
+			modify:  func(opts *runOptions) { opts.publish = []string{"not-a-port"} },
+			wantErr: "invalid service port 'not-a-port'",
+		},
+		{
+			name:    "invalid ulimit",
+			modify:  func(opts *runOptions) { opts.ulimits = []string{"nofile"} },
+			wantErr: "invalid ulimit 'nofile'",
+		},
+		{
+			name:    "volume without a container path",
+			modify:  func(opts *runOptions) { opts.volumes = []string{"data"} },
+			wantErr: "invalid volume mount 'data'",
+		},
+		{
+			name:    "volume with a relative container path",
+			modify:  func(opts *runOptions) { opts.volumes = []string{"data:relative"} },
+			wantErr: "must be absolute path",
+		},
+		{
+			name:    "volume with an unknown option",
+			modify:  func(opts *runOptions) { opts.volumes = []string{"data:/data:unknown"} },
+			wantErr: "invalid option: 'unknown'",
+		},
+		{
+			name:    "missing caddyfile",
+			modify:  func(opts *runOptions) { opts.caddyfile = filepath.Join(os.TempDir(), "uncloud-test-no-such-file") },
+			wantErr: "read Caddyfile",
+		},
+		{
+			name: "caddyfile with an ingress port",
+			modify: func(opts *runOptions) {
+				opts.caddyfile = caddyfile
+				opts.publish = []string{"app.example.com:8080/https"}
+			},
+			wantErr: "cannot be specified simultaneously",
+		},
+		{
+			name:    "service label without a key",
+			modify:  func(opts *runOptions) { opts.labels = []string{"=value"} },
+			wantErr: "key must not be empty",
+		},
+		{
+			name:    "container label without a key",
+			modify:  func(opts *runOptions) { opts.containerLabels = []string{"=value"} },
+			wantErr: "key must not be empty",
+		},
+		{
+			name:    "service label with whitespace",
+			modify:  func(opts *runOptions) { opts.labels = []string{"my label=value"} },
+			wantErr: "invalid service labels: label 'my label' must not contain whitespace",
+		},
+		{
+			name:    "container label with whitespace",
+			modify:  func(opts *runOptions) { opts.containerLabels = []string{"my label=value"} },
+			wantErr: "invalid container labels: label 'my label' must not contain whitespace",
+		},
+		{
+			name:    "reserved service label",
+			modify:  func(opts *runOptions) { opts.labels = []string{api.LabelManaged + "=true"} },
+			wantErr: "invalid service labels",
+		},
+		{
+			name:    "reserved container label",
+			modify:  func(opts *runOptions) { opts.containerLabels = []string{api.LabelManaged + "=true"} },
+			wantErr: "invalid container labels",
+		},
+	}
+
+	for _, tt := range tests {
+		t.Run(tt.name, func(t *testing.T) {
+			t.Parallel()
+
+			opts := validRunOptions()
+			tt.modify(&opts)
+
+			_, err := prepareServiceSpec(opts)
+			require.ErrorContains(t, err, tt.wantErr)
+		})
+	}
+}