---
# generated by https://github.com/hashicorp/terraform-plugin-docs
page_title: "docker_service Resource - terraform-provider-docker"
subcategory: ""
description: |-
  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.
---
<!-- Bug: Type and Name are switched -->
# 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](#convergeconfig) 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

```terraform
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:

```shell
#!/bin/bash
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,
with a `volume`, `config`, `secret` and `network`

```terraform
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 generated by tfplugindocs -->
## 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](#nestedblock--task_spec))

### Optional

- **auth** (Block List, Max: 1) Configuration for the authentication for pulling the images of the service (see [below for nested schema](#nestedblock--auth))
- **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](#nestedblock--converge_config))
- **endpoint_spec** (Block List, Max: 1) Properties that can be configured to access and load balance a service (see [below for nested schema](#nestedblock--endpoint_spec))
- **id** (String) The ID of this resource.
- **labels** (Block Set) User-defined key/value metadata (see [below for nested schema](#nestedblock--labels))
- **mode** (Block List, Max: 1) Scheduling mode for the service (see [below for nested schema](#nestedblock--mode))
- **rollback_config** (Block List, Max: 1) Specification for the rollback strategy of the service (see [below for nested schema](#nestedblock--rollback_config))
- **update_config** (Block List, Max: 1) Specification for the update strategy of the service (see [below for nested schema](#nestedblock--update_config))

<a id="nestedblock--task_spec"></a>
### Nested Schema for `task_spec`

Required:

- **container_spec** (Block List, Min: 1, Max: 1) The spec for each container (see [below for nested schema](#nestedblock--task_spec--container_spec))

Optional:

- **force_update** (Number) A counter that triggers an update even if no relevant parameters have been changed. See the [spec](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](#nestedblock--task_spec--log_driver))
- **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](#nestedblock--task_spec--placement))
- **resources** (Block List, Max: 1) Resource requirements which apply to each individual container created as part of the service (see [below for nested schema](#nestedblock--task_spec--resources))
- **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](#nestedblock--task_spec--restart_policy))
- **runtime** (String) Runtime is the type of runtime specified for the task executor. See the [types](https://github.com/moby/moby/blob/master/api/types/swarm/runtime.go).

<a id="nestedblock--task_spec--container_spec"></a>
### 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](#nestedblock--task_spec--container_spec--configs))
- **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](#nestedblock--task_spec--container_spec--dns_config))
- **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](#nestedblock--task_spec--container_spec--healthcheck))
- **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](#nestedblock--task_spec--container_spec--hosts))
- **isolation** (String) Isolation technology of the containers running the service. (Windows only). Defaults to `default`.
- **labels** (Block Set) User-defined key/value metadata (see [below for nested schema](#nestedblock--task_spec--container_spec--labels))
- **mounts** (Block Set) Specification for mounts to be added to containers created as part of the service (see [below for nested schema](#nestedblock--task_spec--container_spec--mounts))
- **privileges** (Block List, Max: 1) Security options for the container (see [below for nested schema](#nestedblock--task_spec--container_spec--privileges))
- **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](#nestedblock--task_spec--container_spec--secrets))
- **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

<a id="nestedblock--task_spec--container_spec--configs"></a>
### 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. Defaults to `0`.
- **file_mode** (Number) Represents represents the FileMode of the file. Defaults to `0o444`.
- **file_uid** (String) Represents the file UID. Defaults to `0`.


<a id="nestedblock--task_spec--container_spec--dns_config"></a>
### 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


<a id="nestedblock--task_spec--container_spec--healthcheck"></a>
### 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). Defaults to `0s`.
- **retries** (Number) Consecutive failures needed to report unhealthy. Defaults to `0`
- **start_period** (String) Start period for the container to initialize before counting retries towards unstable (ms|s|m|h). Defaults to `0s`.
- **timeout** (String) Maximum time to allow one check to run (ms|s|m|h). Defaults to `0s`.


<a id="nestedblock--task_spec--container_spec--hosts"></a>
### Nested Schema for `task_spec.container_spec.hosts`

Required:

- **host** (String) The name of the host
- **ip** (String) The ip of the host


<a id="nestedblock--task_spec--container_spec--labels"></a>
### Nested Schema for `task_spec.container_spec.labels`

Required:

- **label** (String) Name of the label
- **value** (String) Value of the label


<a id="nestedblock--task_spec--container_spec--mounts"></a>
### 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](#nestedblock--task_spec--container_spec--mounts--bind_options))
- **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](#nestedblock--task_spec--container_spec--mounts--tmpfs_options))
- **volume_options** (Block List, Max: 1) Optional configuration for the volume type (see [below for nested schema](#nestedblock--task_spec--container_spec--mounts--volume_options))

<a id="nestedblock--task_spec--container_spec--mounts--bind_options"></a>
### Nested Schema for `task_spec.container_spec.mounts.volume_options`

Optional:

- **propagation** (String) A propagation mode with the value


<a id="nestedblock--task_spec--container_spec--mounts--tmpfs_options"></a>
### 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


<a id="nestedblock--task_spec--container_spec--mounts--volume_options"></a>
### 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](#nestedblock--task_spec--container_spec--mounts--volume_options--labels))
- **no_copy** (Boolean) Populate volume with data from the target

<a id="nestedblock--task_spec--container_spec--mounts--volume_options--labels"></a>
### Nested Schema for `task_spec.container_spec.mounts.volume_options.labels`

Required:

- **label** (String) Name of the label
- **value** (String) Value of the label




<a id="nestedblock--task_spec--container_spec--privileges"></a>
### 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](#nestedblock--task_spec--container_spec--privileges--credential_spec))
- **se_linux_context** (Block List, Max: 1) SELinux labels of the container (see [below for nested schema](#nestedblock--task_spec--container_spec--privileges--se_linux_context))

<a id="nestedblock--task_spec--container_spec--privileges--credential_spec"></a>
### 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


<a id="nestedblock--task_spec--container_spec--privileges--se_linux_context"></a>
### 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



<a id="nestedblock--task_spec--container_spec--secrets"></a>
### 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. Defaults to `0`
- **file_mode** (Number) Represents represents the FileMode of the file. Defaults to `0o444`
- **file_uid** (String) Represents the file UID. Defaults to `0`
- **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



<a id="nestedblock--task_spec--log_driver"></a>
### 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


<a id="nestedblock--task_spec--placement"></a>
### 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](#nestedblock--task_spec--placement--platforms))
- **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

<a id="nestedblock--task_spec--placement--platforms"></a>
### Nested Schema for `task_spec.placement.platforms`

Required:

- **architecture** (String) The architecture, e.g. `amd64`
- **os** (String) The operation system, e.g. `linux`



<a id="nestedblock--task_spec--resources"></a>
### 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](#nestedblock--task_spec--resources--limits))
- **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](#nestedblock--task_spec--resources--reservation))

<a id="nestedblock--task_spec--resources--limits"></a>
### 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


<a id="nestedblock--task_spec--resources--reservation"></a>
### 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](#nestedblock--task_spec--resources--reservation--generic_resources))
- **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

<a id="nestedblock--task_spec--resources--reservation--generic_resources"></a>
### 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




<a id="nestedblock--task_spec--restart_policy"></a>
### 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)



<a id="nestedblock--auth"></a>
### Nested Schema for `auth`

Required:

- **server_address** (String) The address of the server for the authentication

Optional:

- **password** (String, Sensitive) The password
- **username** (String) The username


<a id="nestedblock--converge_config"></a>
### Nested Schema for `converge_config`

Optional:

- **delay** (String) The interval to check if the desired state is reached (ms|s). Defaults to `7s`.
- **timeout** (String) The timeout of the service to reach the desired state (s|m). Defaults to `3m`


<a id="nestedblock--endpoint_spec"></a>
### 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](#nestedblock--endpoint_spec--ports))

<a id="nestedblock--endpoint_spec--ports"></a>
### 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'. Defaults to `tcp`.
- **publish_mode** (String) Represents the mode in which the port is to be published: 'ingress' or 'host'. Defaults to `ingress`.
- **published_port** (Number) The port on the swarm hosts



<a id="nestedblock--labels"></a>
### Nested Schema for `labels`

Required:

- **label** (String) Name of the label
- **value** (String) Value of the label


<a id="nestedblock--mode"></a>
### Nested Schema for `mode`

Optional:

- **global** (Boolean) The global service mode. Defaults to `false`
- **replicated** (Block List, Max: 1) The replicated service mode (see [below for nested schema](#nestedblock--mode--replicated))

<a id="nestedblock--mode--replicated"></a>
### Nested Schema for `mode.replicated`

Optional:

- **replicas** (Number) The amount of replicas of the service. Defaults to `1`



<a id="nestedblock--rollback_config"></a>
### Nested Schema for `rollback_config`

Optional:

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


<a id="nestedblock--update_config"></a>
### Nested Schema for `update_config`

Optional:

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

## Import

Import is supported using the following syntax by providing the `id`:

```shell
#!/bin/bash
terraform import docker_service.foo id
```

### Example

Assuming you created a `service` as follows

```shell
#!/bin/bash
docker service create --name foo -p 8080:80 nginx
# prints th ID
4pcphbxkfn2rffhbhe6czytgi
```

you provide the definition for the resource as follows

```terraform
resource "docker_service" "foo" {
  name = "foo"

  task_spec {
    container_spec {
      image = "nginx"
    }
  }

  endpoint_spec {
    ports {
      target_port    = "80"
      published_port = "8080"

    }
  }
}
```

then the import command is as follows

```shell
#!/bin/bash
terraform import docker_service.foo 4pcphbxkfn2rffhbhe6czytgi
```