Skip to content

Modern Docker Management, Designed for Everyone

11.3 KB
Raw Blame
package swarm

import (
	"cmp"
	"context"
	"fmt"
	"maps"
	"slices"
	"strings"

	composegotypes "github.com/compose-spec/compose-go/v2/types"
	projecttypes "github.com/getarcaneapp/arcane/types/v2/project"
	swarmtypes "github.com/getarcaneapp/arcane/types/v2/swarm"
	"github.com/moby/moby/api/types/swarm"
	dockerclient "github.com/moby/moby/client"

	"github.com/getarcaneapp/arcane/backend/v2/pkg/projects"
)

// StackDeployOptions controls how a swarm stack is deployed.
type StackDeployOptions struct {
	RegistryAuthForImage func(context.Context, string) (string, error)
	PathMapper           *projects.PathMapper
	Name                 string
	ComposeContent       string
	OverrideContent      string
	EnvContent           string
	ResolveImage         string
	WorkingDir           string
	WithRegistryAuth     bool
	Prune                bool
}

// DeployStack deploys a Compose-defined stack to Docker Swarm using the Engine API.
//
// It validates the stack name, loads the Compose project with environment
// interpolation, ensures required swarm-scoped networks, configs, and secrets
// exist, creates or updates services to match the desired state, optionally
// prunes services no longer declared by the stack, and removes stale managed
// configs and secrets after reconciliation.
//
// ctx controls cancellation for Compose loading and Docker API calls.
// dockerClient must target a swarm manager capable of creating and updating stack resources.
// opts provides the stack name, compose content, optional env content, registry-auth behavior, pruning, and image-resolution mode.
//
// Returns nil when the stack has been reconciled successfully.
// Returns an error if the stack name is empty, the compose or env content is
// invalid, a referenced resource cannot be inspected or created, or any Docker
// API call required to reconcile the stack fails.
func DeployStack(ctx context.Context, dockerClient *dockerclient.Client, opts StackDeployOptions) error {
	stackName := strings.TrimSpace(opts.Name)
	if err := validateStackNameInternal(stackName); err != nil {
		return invalidStackErrorInternal(err)
	}
	ns := namespace{name: stackName}
	resolveMode, err := normalizeResolveImageModeInternal(opts.ResolveImage)
	if err != nil {
		return invalidStackErrorInternal(err)
	}

	project, err := projects.LoadComposeProjectFromContent(ctx, projecttypes.ComposeContentOptions{
		ProjectName:     stackName,
		ComposeContent:  opts.ComposeContent,
		OverrideContent: opts.OverrideContent,
		EnvContent:      opts.EnvContent,
		WorkingDir:      opts.WorkingDir,
		PathMapper:      opts.PathMapper,
	})
	if err != nil {
		return invalidStackErrorInternal(err)
	}
	if project.Name == "" {
		project.Name = stackName
	}

	stackLabels := map[string]string{swarmtypes.StackNamespaceLabel: stackName}

	networkNameByKey, err := ensureSwarmNetworksInternal(ctx, dockerClient, project, ns, stackLabels)
	if err != nil {
		return err
	}

	if ensureSwarmVolumesErr := ensureSwarmVolumesInternal(ctx, dockerClient, project, ns, stackLabels); ensureSwarmVolumesErr != nil {
		return ensureSwarmVolumesErr
	}

	configPlans, err := planConfigsInternal(project, ns)
	if err != nil {
		return invalidStackErrorInternal(err)
	}
	configMetaByKey, err := ensurePlannedFileResourcesInternal(
		ctx,
		configPlans,
		stackLabels,
		configFileResourceAdapterInternal(dockerClient),
	)
	if err != nil {
		return err
	}

	secretPlans, err := planSecretsInternal(project, ns)
	if err != nil {
		return invalidStackErrorInternal(err)
	}
	secretMetaByKey, err := ensurePlannedFileResourcesInternal(
		ctx,
		secretPlans,
		stackLabels,
		secretFileResourceAdapterInternal(dockerClient),
	)
	if err != nil {
		return err
	}

	existingServices, err := listStackServicesInternal(ctx, dockerClient, stackName)
	if err != nil {
		return err
	}

	desiredServices, err := reconcileStackServicesInternal(
		ctx,
		dockerClient,
		project,
		ns,
		stackLabels,
		networkNameByKey,
		configMetaByKey,
		secretMetaByKey,
		existingServices,
		opts,
		resolveMode,
	)
	if err != nil {
		return err
	}

	if opts.Prune {
		for _, name := range slices.Sorted(maps.Keys(existingServices)) {
			svc := existingServices[name]
			if _, ok := desiredServices[name]; ok {
				continue
			}
			if _, serviceRemoveErr := dockerClient.ServiceRemove(ctx, svc.ID, dockerclient.ServiceRemoveOptions{}); serviceRemoveErr != nil {
				return fmt.Errorf("failed to remove swarm service %s: %w", name, serviceRemoveErr)
			}
		}
	}

	if cleanupStackResourcesErr := cleanupStackResourcesInternal(ctx, dockerClient, stackName, configMetaByKey, secretMetaByKey); cleanupStackResourcesErr != nil {
		return cleanupStackResourcesErr
	}

	return nil
}

func reconcileStackServicesInternal(
	ctx context.Context,
	dockerClient *dockerclient.Client,
	project *composegotypes.Project,
	ns namespace,
	stackLabels map[string]string,
	networkNameByKey map[string]string,
	configMetaByKey map[string]resourceMeta,
	secretMetaByKey map[string]resourceMeta,
	existingServices map[string]swarm.Service,
	opts StackDeployOptions,
	resolveMode string,
) (map[string]struct{}, error) {
	desiredServices := map[string]struct{}{}

	for _, key := range slices.Sorted(maps.Keys(project.Services)) {
		service := project.Services[key]
		service.Name = cmp.Or(service.Name, key)
		spec, err := buildServiceSpecInternal(service, ns, stackLabels, networkNameByKey, configMetaByKey, secretMetaByKey, project.Volumes)
		if err != nil {
			return nil, invalidStackErrorInternal(fmt.Errorf("service %s: %w", service.Name, err))
		}
		desiredServices[spec.Name] = struct{}{}

		if existing, ok := existingServices[spec.Name]; ok {
			if updateSwarmServiceErr := updateSwarmServiceInternal(ctx, dockerClient, existing, spec, opts.WithRegistryAuth, opts.RegistryAuthForImage, resolveMode); updateSwarmServiceErr != nil {
				return nil, updateSwarmServiceErr
			}
			continue
		}

		if createSwarmServiceErr := createSwarmServiceInternal(ctx, dockerClient, spec, opts.WithRegistryAuth, opts.RegistryAuthForImage, resolveMode); createSwarmServiceErr != nil {
			return nil, createSwarmServiceErr
		}
	}

	return desiredServices, nil
}

func listStackServicesInternal(ctx context.Context, dockerClient *dockerclient.Client, stackName string) (map[string]swarm.Service, error) {
	filter := make(dockerclient.Filters).Add("label", fmt.Sprintf("%s=%s", swarmtypes.StackNamespaceLabel, stackName))
	servicesResult, err := dockerClient.ServiceList(ctx, dockerclient.ServiceListOptions{Filters: filter})
	if err != nil {
		return nil, fmt.Errorf("failed to list swarm services: %w", err)
	}
	services := servicesResult.Items

	byName := make(map[string]swarm.Service, len(services))
	for _, service := range services {
		byName[service.Spec.Name] = service
	}
	return byName, nil
}

func createSwarmServiceInternal(
	ctx context.Context,
	dockerClient *dockerclient.Client,
	spec swarm.ServiceSpec,
	withRegistryAuth bool,
	registryAuthForImage func(context.Context, string) (string, error),
	resolveMode string,
) error {
	encodedRegistryAuth, err := resolveRegistryAuthForSpecInternal(ctx, spec, withRegistryAuth, registryAuthForImage)
	if err != nil {
		return err
	}
	queryRegistry := encodedRegistryAuth != "" || shouldQueryRegistryOnCreateInternal(resolveMode)
	opts := dockerclient.ServiceCreateOptions{
		Spec:          spec,
		QueryRegistry: queryRegistry,
	}
	opts.EncodedRegistryAuth = cmp.Or(encodedRegistryAuth, opts.EncodedRegistryAuth)
	if _, serviceCreateErr := dockerClient.ServiceCreate(ctx, opts); serviceCreateErr != nil {
		return fmt.Errorf("failed to create swarm service %s: %w", spec.Name, serviceCreateErr)
	}
	return nil
}

func updateSwarmServiceInternal(
	ctx context.Context,
	dockerClient *dockerclient.Client,
	existing swarm.Service,
	spec swarm.ServiceSpec,
	withRegistryAuth bool,
	registryAuthForImage func(context.Context, string) (string, error),
	resolveMode string,
) error {
	encodedRegistryAuth, err := resolveRegistryAuthForSpecInternal(ctx, spec, withRegistryAuth, registryAuthForImage)
	if err != nil {
		return err
	}
	queryRegistry := encodedRegistryAuth != "" || shouldQueryRegistryOnUpdateInternal(resolveMode, existing, spec)
	if !queryRegistry {
		preserveExistingResolvedImageInternal(&spec, existing)
	}
	// Do not force task rescheduling on no-op updates.
	spec.TaskTemplate.ForceUpdate = existing.Spec.TaskTemplate.ForceUpdate

	opts := dockerclient.ServiceUpdateOptions{
		Version:       existing.Version,
		Spec:          spec,
		QueryRegistry: queryRegistry,
	}
	if encodedRegistryAuth != "" {
		opts.EncodedRegistryAuth = encodedRegistryAuth
		opts.RegistryAuthFrom = swarm.RegistryAuthFromSpec
	} else {
		opts.RegistryAuthFrom = swarm.RegistryAuthFromPreviousSpec
	}

	if _, serviceUpdateErr := dockerClient.ServiceUpdate(ctx, existing.ID, opts); serviceUpdateErr != nil {
		if strings.Contains(serviceUpdateErr.Error(), "service does not have a previous spec") {
			opts.RegistryAuthFrom = ""
			if _, retryErr := dockerClient.ServiceUpdate(ctx, existing.ID, opts); retryErr != nil {
				return fmt.Errorf("failed to update swarm service %s: %w", spec.Name, retryErr)
			}
			return nil
		}
		return fmt.Errorf("failed to update swarm service %s: %w", spec.Name, serviceUpdateErr)
	}
	return nil
}

func normalizeResolveImageModeInternal(value string) (string, error) {
	mode := strings.ToLower(strings.TrimSpace(value))
	if mode == "" {
		return resolveImageAlways, nil
	}
	switch mode {
	case resolveImageAlways, resolveImageChanged, resolveImageNever:
		return mode, nil
	default:
		return "", fmt.Errorf("invalid resolve image mode %q: expected always, changed, or never", value)
	}
}

func shouldQueryRegistryOnCreateInternal(resolveMode string) bool {
	return resolveMode == resolveImageAlways || resolveMode == resolveImageChanged
}

func shouldQueryRegistryOnUpdateInternal(resolveMode string, existing swarm.Service, desired swarm.ServiceSpec) bool {
	switch resolveMode {
	case resolveImageAlways:
		return true
	case resolveImageChanged:
		desiredImage := stripImageDigestInternal(resolveServiceImageInternal(desired))
		existingImage := stripImageDigestInternal(resolveServiceImageInternal(existing.Spec))
		return desiredImage != "" && desiredImage != existingImage
	default:
		return false
	}
}

func resolveServiceImageInternal(spec swarm.ServiceSpec) string {
	if spec.TaskTemplate.ContainerSpec == nil {
		return ""
	}
	return spec.TaskTemplate.ContainerSpec.Image
}

func preserveExistingResolvedImageInternal(spec *swarm.ServiceSpec, existing swarm.Service) {
	if spec.TaskTemplate.ContainerSpec == nil || existing.Spec.TaskTemplate.ContainerSpec == nil {
		return
	}
	if stripImageDigestInternal(resolveServiceImageInternal(*spec)) == stripImageDigestInternal(resolveServiceImageInternal(existing.Spec)) {
		spec.TaskTemplate.ContainerSpec.Image = existing.Spec.TaskTemplate.ContainerSpec.Image
	}
}

func stripImageDigestInternal(image string) string {
	image, _, _ = strings.Cut(strings.TrimSpace(image), "@")
	return image
}

func resolveRegistryAuthForSpecInternal(
	ctx context.Context,
	spec swarm.ServiceSpec,
	withRegistryAuth bool,
	registryAuthForImage func(context.Context, string) (string, error),
) (string, error) {
	if !withRegistryAuth || registryAuthForImage == nil {
		return "", nil
	}

	image := resolveServiceImageInternal(spec)
	if strings.TrimSpace(image) == "" {
		return "", nil
	}

	encodedRegistryAuth, err := registryAuthForImage(ctx, image)
	if err != nil {
		return "", fmt.Errorf("failed to resolve registry auth for image %s: %w", image, err)
	}

	return encodedRegistryAuth, nil
}