terraform-provider-docker/docs/resources/service.md

page_title	subcategory	description
docker_service Resource - terraform-provider-docker		This resource manages the lifecycle of a Docker service. By default, the creation, update and delete of services are detached. With the Converge Config the behavior of the docker cli is imitated to guarantee tha for example, all tasks of a service are running or successfully updated or to inform terraform that a service could no be updated and was successfully rolled back.

docker_service (Resource)

This resource manages the lifecycle of a Docker service. By default, the creation, update and delete of services are detached. With the Converge Config the behavior of the docker cli is imitated to guarantee tha for example, all tasks of a service are running or successfully updated or to inform terraform that a service could no be updated and was successfully rolled back.

Example Usage

# Basic
## The following configuration starts a Docker Service with 
## - the given image, 
## - 1 replica
## - exposes the port `8080` in `vip` mode to the host machine
## - moreover, uses the `container` runtime

resource "docker_service" "foo" {
  name = "foo-service"

  task_spec {
    container_spec {
      image = "repo.mycompany.com:8080/foo-service:v1"
    }
  }

  endpoint_spec {
    ports {
      target_port = "8080"
    }
  }
}

# The following command is the equivalent:
# docker service create -d -p 8080 --name foo-service repo.mycompany.com:8080/foo-service:v1

# Advanced
## The following configuration shows the full capabilities of a Docker Service. 
# Currently, the [Docker API 1.32](https://docs.docker.com/engine/api/v1.32) is implemented.

resource "docker_volume" "test_volume" {
  name = "tftest-volume"
}

resource "docker_config" "service_config" {
  name = "tftest-full-myconfig"
  data = "ewogICJwcmVmaXgiOiAiMTIzIgp9"
}

resource "docker_secret" "service_secret" {
  name = "tftest-mysecret"
  data = "ewogICJrZXkiOiAiUVdFUlRZIgp9"
}

resource "docker_network" "test_network" {
  name   = "tftest-network"
  driver = "overlay"
}

resource "docker_service" "foo" {
  name = "tftest-service-basic"

  task_spec {
    container_spec {
      image = "repo.mycompany.com:8080/foo-service:v1"

      labels {
        label = "foo.bar"
        value = "baz"
      }

      command  = ["ls"]
      args     = ["-las"]
      hostname = "my-fancy-service"

      env = {
        MYFOO = "BAR"
      }

      dir    = "/root"
      user   = "root"
      groups = ["docker", "foogroup"]

      privileges {
        se_linux_context {
          disable = true
          user    = "user-label"
          role    = "role-label"
          type    = "type-label"
          level   = "level-label"
        }
      }

      read_only = true

      mounts {
        target    = "/mount/test"
        source    = docker_volume.test_volume.name
        type      = "volume"
        read_only = true

        bind_options {
          propagation = "private"
        }
      }

      mounts {
        # another mount
      }

      stop_signal       = "SIGTERM"
      stop_grace_period = "10s"

      healthcheck {
        test     = ["CMD", "curl", "-f", "http://localhost:8080/health"]
        interval = "5s"
        timeout  = "2s"
        retries  = 4
      }

      hosts {
        host = "testhost"
        ip   = "10.0.1.0"
      }

      dns_config {
        nameservers = ["8.8.8.8"]
        search      = ["example.org"]
        options     = ["timeout:3"]
      }

      secrets {
        secret_id   = docker_secret.service_secret.id
        secret_name = docker_secret.service_secret.name
        file_name   = "/secrets.json"
        file_uid    = "0"
        file_gid    = "0"
        file_mode   = 0777
      }

      secrets {
        # another secret
      }

      configs {
        config_id   = docker_config.service_config.id
        config_name = docker_config.service_config.name
        file_name   = "/configs.json"
      }

      configs {
        # another config
      }
    }

    resources {
      limits {
        nano_cpus    = 1000000
        memory_bytes = 536870912
      }

      reservation {
        nano_cpus    = 1000000
        memory_bytes = 536870912

        generic_resources {
          named_resources_spec = [
            "GPU=UUID1",
          ]

          discrete_resources_spec = [
            "SSD=3",
          ]
        }
      }
    }

    restart_policy = {
      condition    = "on-failure"
      delay        = "3s"
      max_attempts = 4
      window       = "10s"
    }

    placement {
      constraints = [
        "node.role==manager",
      ]

      prefs = [
        "spread=node.role.manager",
      ]

      max_replicas = 1
    }

    force_update = 0
    runtime      = "container"
    networks     = [docker_network.test_network.id]

    log_driver {
      name = "json-file"

      options {
        max-size = "10m"
        max-file = "3"
      }
    }
  }

  mode {
    replicated {
      replicas = 2
    }
  }

  update_config {
    parallelism       = 2
    delay             = "10s"
    failure_action    = "pause"
    monitor           = "5s"
    max_failure_ratio = "0.1"
    order             = "start-first"
  }

  rollback_config {
    parallelism       = 2
    delay             = "5ms"
    failure_action    = "pause"
    monitor           = "10h"
    max_failure_ratio = "0.9"
    order             = "stop-first"
  }

  endpoint_spec {
    mode = "vip"

    ports {
      name           = "random"
      protocol       = "tcp"
      target_port    = "8080"
      published_port = "8080"
      publish_mode   = "ingress"
    }

    ports {
      # another port
    }
  }
}

Schema

Required

• name (String) Name of the service
• task_spec (Block List, Min: 1, Max: 1) User modifiable task configuration (see below for nested schema)

Optional

• auth (Block List, Max: 1) (see below for nested schema)
• converge_config (Block List, Max: 1) A configuration to ensure that a service converges aka reaches the desired that of all task up and running (see below for nested schema)
• endpoint_spec (Block List, Max: 1) Properties that can be configured to access and load balance a service (see below for nested schema)
• id (String) The ID of this resource.
• labels (Block Set) User-defined key/value metadata (see below for nested schema)
• mode (Block List, Max: 1) Scheduling mode for the service (see below for nested schema)
• rollback_config (Block List, Max: 1) Specification for the rollback strategy of the service (see below for nested schema)
• update_config (Block List, Max: 1) Specification for the update strategy of the service (see below for nested schema)

Nested Schema for task_spec

Required:

• container_spec (Block List, Min: 1, Max: 1) The spec for each container (see below for nested schema)

Optional:

• force_update (Number) A counter that triggers an update even if no relevant parameters have been changed. See https://github.com/docker/swarmkit/blob/master/api/specs.proto#L126
• log_driver (Block List, Max: 1) Specifies the log driver to use for tasks created from this spec. If not present, the default one for the swarm will be used, finally falling back to the engine default if not specified (see below for nested schema)
• networks (Set of String) Ids of the networks in which the container will be put in
• placement (Block List, Max: 1) The placement preferences (see below for nested schema)
• resources (Block List, Max: 1) Resource requirements which apply to each individual container created as part of the service (see below for nested schema)
• restart_policy (Block List, Max: 1) Specification for the restart policy which applies to containers created as part of this service. (see below for nested schema)
• runtime (String) Runtime is the type of runtime specified for the task executor. See https://github.com/moby/moby/blob/master/api/types/swarm/runtime.go

Nested Schema for task_spec.container_spec

Required:

• image (String) The image name to use for the containers of the service

Optional:

• args (List of String) Arguments to the command
• command (List of String) The command to be run in the image
• configs (Block Set) References to zero or more configs that will be exposed to the service (see below for nested schema)
• dir (String) The working directory for commands to run in
• dns_config (Block List, Max: 1) Specification for DNS related configurations in resolver configuration file (resolv.conf) (see below for nested schema)
• env (Map of String) A list of environment variables in the form VAR="value"
• groups (List of String) A list of additional groups that the container process will run as
• healthcheck (Block List, Max: 1) A test to perform to check that the container is healthy (see below for nested schema)
• hostname (String) The hostname to use for the container, as a valid RFC 1123 hostname
• hosts (Block Set) A list of hostname/IP mappings to add to the container's hosts file (see below for nested schema)
• isolation (String) Isolation technology of the containers running the service. (Windows only)
• labels (Block Set) User-defined key/value metadata (see below for nested schema)
• mounts (Block Set) Specification for mounts to be added to containers created as part of the service (see below for nested schema)
• privileges (Block List, Max: 1) Security options for the container (see below for nested schema)
• read_only (Boolean) Mount the container's root filesystem as read only
• secrets (Block Set) References to zero or more secrets that will be exposed to the service (see below for nested schema)
• stop_grace_period (String) Amount of time to wait for the container to terminate before forcefully removing it (ms|s|m|h)
• stop_signal (String) Signal to stop the container
• user (String) The user inside the container

Nested Schema for task_spec.container_spec.configs

Required:

• config_id (String) ID of the specific config that we're referencing
• file_name (String) Represents the final filename in the filesystem

Optional:

• config_name (String) Name of the config that this references, but this is just provided for lookup/display purposes. The config in the reference will be identified by its ID
• file_gid (String) Represents the file GID
• file_mode (Number) Represents represents the FileMode of the file
• file_uid (String) Represents the file UID

Nested Schema for task_spec.container_spec.dns_config

Required:

• nameservers (List of String) The IP addresses of the name servers

Optional:

• options (List of String) A list of internal resolver variables to be modified (e.g., debug, ndots:3, etc.)
• search (List of String) A search list for host-name lookup

Nested Schema for task_spec.container_spec.healthcheck

Required:

• test (List of String) The test to perform as list

Optional:

• interval (String) Time between running the check (ms|s|m|h)
• retries (Number) Consecutive failures needed to report unhealthy
• start_period (String) Start period for the container to initialize before counting retries towards unstable (ms|s|m|h)
• timeout (String) Maximum time to allow one check to run (ms|s|m|h)

Nested Schema for task_spec.container_spec.hosts

Required:

• host (String)
• ip (String)

Nested Schema for task_spec.container_spec.labels

Required:

• label (String) Name of the label
• value (String) Value of the label

Nested Schema for task_spec.container_spec.mounts

Required:

• target (String) Container path
• type (String) The mount type

Optional:

• bind_options (Block List, Max: 1) Optional configuration for the bind type (see below for nested schema)
• read_only (Boolean) Whether the mount should be read-only
• source (String) Mount source (e.g. a volume name, a host path)
• tmpfs_options (Block List, Max: 1) Optional configuration for the tmpfs type (see below for nested schema)
• volume_options (Block List, Max: 1) Optional configuration for the volume type (see below for nested schema)

Nested Schema for task_spec.container_spec.mounts.volume_options

Optional:

• propagation (String) A propagation mode with the value

Nested Schema for task_spec.container_spec.mounts.volume_options

Optional:

• mode (Number) The permission mode for the tmpfs mount in an integer
• size_bytes (Number) The size for the tmpfs mount in bytes

Nested Schema for task_spec.container_spec.mounts.volume_options

Optional:

• driver_name (String) Name of the driver to use to create the volume
• driver_options (Map of String) key/value map of driver specific options
• labels (Block Set) User-defined key/value metadata (see below for nested schema)
• no_copy (Boolean) Populate volume with data from the target

Nested Schema for task_spec.container_spec.mounts.volume_options.labels

Required:

• label (String) Name of the label
• value (String) Value of the label

Nested Schema for task_spec.container_spec.privileges

Optional:

• credential_spec (Block List, Max: 1) CredentialSpec for managed service account (Windows only) (see below for nested schema)
• se_linux_context (Block List, Max: 1) SELinux labels of the container (see below for nested schema)

Nested Schema for task_spec.container_spec.privileges.se_linux_context

Optional:

• file (String) Load credential spec from this file
• registry (String) Load credential spec from this value in the Windows registry

Nested Schema for task_spec.container_spec.privileges.se_linux_context

Optional:

• disable (Boolean) Disable SELinux
• level (String) SELinux level label
• role (String) SELinux role label
• type (String) SELinux type label
• user (String) SELinux user label

Nested Schema for task_spec.container_spec.secrets

Required:

• file_name (String) Represents the final filename in the filesystem
• secret_id (String) ID of the specific secret that we're referencing

Optional:

• file_gid (String) Represents the file GID
• file_mode (Number) Represents represents the FileMode of the file
• file_uid (String) Represents the file UID
• secret_name (String) Name of the secret that this references, but this is just provided for lookup/display purposes. The config in the reference will be identified by its ID

Nested Schema for task_spec.log_driver

Required:

• name (String) The logging driver to use

Optional:

• options (Map of String) The options for the logging driver

Nested Schema for task_spec.placement

Optional:

• constraints (Set of String) An array of constraints. e.g.: node.role==manager
• max_replicas (Number) Maximum number of replicas for per node (default value is 0, which is unlimited)
• platforms (Block Set) Platforms stores all the platforms that the service's image can run on (see below for nested schema)
• prefs (Set of String) Preferences provide a way to make the scheduler aware of factors such as topology. They are provided in order from highest to lowest precedence, e.g.: spread=node.role.manager

Nested Schema for task_spec.placement.platforms

Required:

• architecture (String) The architecture, e.g. amd64
• os (String) The operation system, e.g. linux

Nested Schema for task_spec.resources

Optional:

• limits (Block List, Max: 1) Describes the resources which can be advertised by a node and requested by a task (see below for nested schema)
• reservation (Block List, Max: 1) An object describing the resources which can be advertised by a node and requested by a task (see below for nested schema)

Nested Schema for task_spec.resources.limits

Optional:

• memory_bytes (Number) The amounf of memory in bytes the container allocates
• nano_cpus (Number) CPU shares in units of 1/1e9 (or 10^-9) of the CPU. Should be at least 1000000

Nested Schema for task_spec.resources.reservation

Optional:

• generic_resources (Block List, Max: 1) User-defined resources can be either Integer resources (e.g, SSD=3) or String resources (e.g, GPU=UUID1) (see below for nested schema)
• memory_bytes (Number) The amounf of memory in bytes the container allocates
• nano_cpus (Number) CPU shares in units of 1/1e9 (or 10^-9) of the CPU. Should be at least 1000000

Nested Schema for task_spec.resources.reservation.nano_cpus

Optional:

• discrete_resources_spec (Set of String) The Integer resources
• named_resources_spec (Set of String) The String resources

Nested Schema for task_spec.restart_policy

Optional:

• condition (String) Condition for restart
• delay (String) Delay between restart attempts (ms|s|m|h)
• max_attempts (Number) Maximum attempts to restart a given container before giving up (default value is 0, which is ignored)
• window (String) The time window used to evaluate the restart policy (default value is 0, which is unbounded) (ms|s|m|h)

Nested Schema for auth

Required:

• server_address (String)

Optional:

• password (String, Sensitive)
• username (String)

Nested Schema for converge_config

Optional:

• delay (String) The interval to check if the desired state is reached (ms|s). Default: 7s
• timeout (String) The timeout of the service to reach the desired state (s|m). Default: 3m

Nested Schema for endpoint_spec

Optional:

• mode (String) The mode of resolution to use for internal load balancing between tasks
• ports (Block List) List of exposed ports that this service is accessible on from the outside. Ports can only be provided if 'vip' resolution mode is used (see below for nested schema)

Nested Schema for endpoint_spec.ports

Required:

• target_port (Number) The port inside the container

Optional:

• name (String) A random name for the port
• protocol (String) Rrepresents the protocol of a port: 'tcp', 'udp' or 'sctp'
• publish_mode (String) Represents the mode in which the port is to be published: 'ingress' or 'host'
• published_port (Number) The port on the swarm hosts

Nested Schema for labels

Required:

• label (String) Name of the label
• value (String) Value of the label

Nested Schema for mode

Optional:

• global (Boolean) The global service mode
• replicated (Block List, Max: 1) The replicated service mode (see below for nested schema)

Nested Schema for mode.replicated

Optional:

• replicas (Number) The amount of replicas of the service

Nested Schema for rollback_config

Optional:

• delay (String) Delay between task rollbacks (ns|us|ms|s|m|h)
• failure_action (String) Action on rollback failure: pause | continue
• max_failure_ratio (String) Failure rate to tolerate during a rollback
• monitor (String) Duration after each task rollback to monitor for failure (ns|us|ms|s|m|h)
• order (String) Rollback order: either 'stop-first' or 'start-first'
• parallelism (Number) Maximum number of tasks to be rollbacked in one iteration

Nested Schema for update_config

Optional:

• delay (String) Delay between task updates (ns|us|ms|s|m|h)
• failure_action (String) Action on update failure: pause | continue | rollback
• max_failure_ratio (String) Failure rate to tolerate during an update
• monitor (String) Duration after each task update to monitor for failure (ns|us|ms|s|m|h)
• order (String) Update order: either 'stop-first' or 'start-first'
• parallelism (Number) Maximum number of tasks to be updated in one iteration

Import

Import is supported using the following syntax:

#!/bin/bash

## A Docker service can be imported using the long id, 
## e.g. for a service with the short id `55ba873dd`:

$ terraform import docker_service.foo "$(docker service inspect -f {{.ID}} 55b)"