Service Configuration Details: Runtime Environment, Command Updates, and Image Versioning

$ docker service remove my_web ``` ## Service configuration details The following sections provide details about service configuration. This topic does not cover every flag or scenario. In almost every instance where you can define a configuration at service creation, you can also update an existing service's configuration in a similar way. See the command-line references for [`docker service create`](/reference/cli/docker/service/create.md) and [`docker service update`](/reference/cli/docker/service/update.md), or run one of those commands with the `--help` flag. ### Configure the runtime environment You can configure the following options for the runtime environment in the container: * Environment variables using the `--env` flag * The working directory inside the container using the `--workdir` flag * The username or UID using the `--user` flag The following service's containers have an environment variable `$MYVAR` set to `myvalue`, run from the `/tmp/` directory, and run as the `my_user` user. ```console $ docker service create --name helloworld \ --env MYVAR=myvalue \ --workdir /tmp \ --user my_user \ alpine ping docker.com ``` ### Update the command an existing service runs To update the command an existing service runs, you can use the `--args` flag. The following example updates an existing service called `helloworld` so that it runs the command `ping docker.com` instead of whatever command it was running before: ```console $ docker service update --args "ping docker.com" helloworld ``` ### Specify the image version a service should use When you create a service without specifying any details about the version of the image to use, the service uses the version tagged with the `latest` tag. You can force the service to use a specific version of the image in a few different ways, depending on your desired outcome. An image version can be expressed in several different ways: - If you specify a tag, the manager (or the Docker client, if you use [content trust](../security/trust/_index.md)) resolves that tag to a digest. When the request to create a container task is received on a worker node, the worker node only sees the digest, not the tag. ```console $ docker service create --name="myservice" ubuntu:16.04 ``` Some tags represent discrete releases, such as `ubuntu:16.04`. Tags like this almost always resolve to a stable digest over time. It is recommended that you use this kind of tag when possible. Other types of tags, such as `latest` or `nightly`, may resolve to a new digest often, depending on how often an image's author updates the tag. It is not recommended to run services using a tag which is updated frequently, to prevent different service replica tasks from using different image versions. - If you don't specify a version at all, by convention the image's `latest` tag is resolved to a digest. Workers use the image at this digest when creating the service task. Thus, the following two commands are equivalent: ```console $ docker service create --name="myservice" ubuntu $ docker service create --name="myservice" ubuntu:latest ``` - If you specify a digest directly, that exact version of the image is always used when creating service tasks. ```console $ docker service create \ --name="myservice" \ ubuntu:16.04@sha256:35bc48a1ca97c3971611dc4662d08d131869daa692acb281c7e9e052924e38b1 ``` When you create a service, the image's tag is resolved to the specific digest the tag points to **at the time of service creation**. Worker nodes for that service use that specific digest forever unless the service is explicitly updated. This feature is particularly important if you do use often-changing tags such as `latest`, because it ensures that all service tasks use the same version of the image. > [!NOTE]> > > If [content trust](../security/trust/_index.md) is > enabled, the client actually resolves the image's tag to a digest before > contacting the swarm manager, to verify that the image is signed.

This section delves into Docker service configuration, covering runtime environment settings (environment variables, working directory, user), updating service commands with `--args`, and specifying image versions using tags and digests. It highlights the importance of using stable tags for consistent service deployment and explains how Docker resolves image tags to digests at service creation to ensure uniform image versions across tasks.