diff --git a/.github/workflows/build.yml b/.github/workflows/build.yml index 50a3c33739db..cc169ecacbba 100644 --- a/.github/workflows/build.yml +++ b/.github/workflows/build.yml @@ -11,6 +11,11 @@ on: - main pull_request: +env: + # Use edge release of buildx (latest RC, fallback to latest stable) + SETUP_BUILDX_VERSION: edge + SETUP_BUILDKIT_IMAGE: "moby/buildkit:latest" + permissions: contents: read # to fetch code (actions/checkout) @@ -24,6 +29,9 @@ jobs: - name: Set up Docker Buildx uses: docker/setup-buildx-action@v3 + with: + version: ${{ env.SETUP_BUILDX_VERSION }} + driver-opts: image=${{ env.SETUP_BUILDKIT_IMAGE }} - name: Build uses: docker/bake-action@v5 diff --git a/.github/workflows/deploy.yml b/.github/workflows/deploy.yml index 8be67f66a23f..a4e6d9b9047d 100644 --- a/.github/workflows/deploy.yml +++ b/.github/workflows/deploy.yml @@ -12,6 +12,11 @@ on: - main - published +env: + # Use edge release of buildx (latest RC, fallback to latest stable) + SETUP_BUILDX_VERSION: edge + SETUP_BUILDKIT_IMAGE: "moby/buildkit:latest" + # these permissions are needed to interact with GitHub's OIDC Token endpoint. permissions: id-token: write @@ -80,6 +85,9 @@ jobs: - name: Set up Docker Buildx uses: docker/setup-buildx-action@v3 + with: + version: ${{ env.SETUP_BUILDX_VERSION }} + driver-opts: image=${{ env.SETUP_BUILDKIT_IMAGE }} - name: Build website uses: docker/bake-action@v5 diff --git a/.github/workflows/validate-upstream.yml b/.github/workflows/validate-upstream.yml index 408cea0c8171..79c048f6284d 100644 --- a/.github/workflows/validate-upstream.yml +++ b/.github/workflows/validate-upstream.yml @@ -23,6 +23,11 @@ on: type: boolean required: false +env: + # Use edge release of buildx (latest RC, fallback to latest stable) + SETUP_BUILDX_VERSION: edge + SETUP_BUILDKIT_IMAGE: "moby/buildkit:latest" + jobs: run: runs-on: ubuntu-24.04 @@ -80,6 +85,9 @@ jobs: - name: Set up Docker Buildx uses: docker/setup-buildx-action@v3 + with: + version: ${{ env.SETUP_BUILDX_VERSION }} + driver-opts: image=${{ env.SETUP_BUILDKIT_IMAGE }} - name: Validate uses: docker/bake-action@v5 diff --git a/_vale/Docker/Acronyms.yml b/_vale/Docker/Acronyms.yml index 9aa3cbb47f33..a2a89350e103 100644 --- a/_vale/Docker/Acronyms.yml +++ b/_vale/Docker/Acronyms.yml @@ -15,6 +15,7 @@ exceptions: - AUFS - AWS - BIOS + - BPF - CI - CISA - CLI @@ -52,6 +53,7 @@ exceptions: - HTTP - HTTPS - IAM + - ID - IDE - IP - JAR @@ -75,6 +77,7 @@ exceptions: - PATH - PDF - PEM + - PID - PHP - POSIX - POST diff --git a/_vale/config/vocabularies/Docker/accept.txt b/_vale/config/vocabularies/Docker/accept.txt index 0c2dbff70528..e3cd77f88634 100644 --- a/_vale/config/vocabularies/Docker/accept.txt +++ b/_vale/config/vocabularies/Docker/accept.txt @@ -1,4 +1,4 @@ -(?-i)[A-Z]{2,}s +(?-i)[A-Z]{2,}'?s Amazon Anchore Apple @@ -21,6 +21,7 @@ Datadog Ddosify Debootstrap Dev Environments? +Dev Django Docker Build Cloud Docker Business @@ -71,6 +72,7 @@ Nuxeo OAuth OTel Okta +Paketo PKG Postgres PowerShell @@ -82,6 +84,7 @@ Snyk Solr SonarQube Syft +Sysbox Sysdig Testcontainers Traefik @@ -95,6 +98,7 @@ Zscaler Zsh [Aa]utobuild [Bb]uildx +[Bb]uildpack(s)? [Cc]odenames? [Cc]ompose [Dd]istroless @@ -109,13 +113,16 @@ Zsh [Nn]amespace [Oo]nboarding [Pp]aravirtualization +[Pp]rocfs [Pp]roxied [Pp]roxying [Rr]eal-time [Rr]untimes? [Ss]andbox(ed)? +[Ss]eccomp [Ss]wappable [Ss]warm +[Ss]ysfs [Tt]oolchains? [Vv]irtiofs [Vv]irtualize @@ -144,10 +151,13 @@ minikube monorepos? musl nameserver +namespace +namespacing npm osquery osxfs pgAdmin +rootful runc snapshotters? stdin diff --git a/_vendor/github.com/docker/compose/v2/docs/reference/compose.md b/_vendor/github.com/docker/compose/v2/docs/reference/compose.md index 5a69a01b508f..d625c253e675 100644 --- a/_vendor/github.com/docker/compose/v2/docs/reference/compose.md +++ b/_vendor/github.com/docker/compose/v2/docs/reference/compose.md @@ -13,6 +13,7 @@ Define and run multi-container applications with Docker |:--------------------------------|:----------------------------------------------------------------------------------------| | [`attach`](compose_attach.md) | Attach local standard input, output, and error streams to a service's running container | | [`build`](compose_build.md) | Build or rebuild services | +| [`commit`](compose_commit.md) | Create a new image from a service container's changes | | [`config`](compose_config.md) | Parse, resolve and render compose file in canonical format | | [`cp`](compose_cp.md) | Copy files/folders between a service container and the local filesystem | | [`create`](compose_create.md) | Creates containers for a service | diff --git a/_vendor/github.com/docker/compose/v2/docs/reference/compose_commit.md b/_vendor/github.com/docker/compose/v2/docs/reference/compose_commit.md new file mode 100644 index 000000000000..1aad40931f94 --- /dev/null +++ b/_vendor/github.com/docker/compose/v2/docs/reference/compose_commit.md @@ -0,0 +1,19 @@ +# docker compose commit + + +Create a new image from a service container's changes + +### Options + +| Name | Type | Default | Description | +|:------------------|:---------|:--------|:-----------------------------------------------------------| +| `-a`, `--author` | `string` | | Author (e.g., "John Hannibal Smith ") | +| `-c`, `--change` | `list` | | Apply Dockerfile instruction to the created image | +| `--dry-run` | `bool` | | Execute command in dry run mode | +| `--index` | `int` | `0` | index of the container if service has multiple replicas. | +| `-m`, `--message` | `string` | | Commit message | +| `-p`, `--pause` | `bool` | `true` | Pause container during commit | + + + + diff --git a/_vendor/github.com/docker/compose/v2/docs/reference/compose_up.md b/_vendor/github.com/docker/compose/v2/docs/reference/compose_up.md index 295000734b1e..410ec84b52d8 100644 --- a/_vendor/github.com/docker/compose/v2/docs/reference/compose_up.md +++ b/_vendor/github.com/docker/compose/v2/docs/reference/compose_up.md @@ -51,7 +51,7 @@ If the process is interrupted using `SIGINT` (ctrl + C) or `SIGTERM`, the contai | `-t`, `--timeout` | `int` | `0` | Use this timeout in seconds for container shutdown when attached or when containers are already running | | `--timestamps` | `bool` | | Show timestamps | | `--wait` | `bool` | | Wait for services to be running\|healthy. Implies detached mode. | -| `--wait-timeout` | `int` | `0` | Maximum duration to wait for the project to be running\|healthy | +| `--wait-timeout` | `int` | `0` | Maximum duration in seconds to wait for the project to be running\|healthy | | `-w`, `--watch` | `bool` | | Watch source code and rebuild/refresh containers when files are updated. | diff --git a/_vendor/github.com/docker/compose/v2/docs/reference/docker_compose.yaml b/_vendor/github.com/docker/compose/v2/docs/reference/docker_compose.yaml index f59ec4a04b2c..1c6fb4970e79 100644 --- a/_vendor/github.com/docker/compose/v2/docs/reference/docker_compose.yaml +++ b/_vendor/github.com/docker/compose/v2/docs/reference/docker_compose.yaml @@ -7,6 +7,7 @@ plink: docker.yaml cname: - docker compose attach - docker compose build + - docker compose commit - docker compose config - docker compose cp - docker compose create @@ -39,6 +40,7 @@ cname: clink: - docker_compose_attach.yaml - docker_compose_build.yaml + - docker_compose_commit.yaml - docker_compose_config.yaml - docker_compose_cp.yaml - docker_compose_create.yaml diff --git a/_vendor/github.com/docker/compose/v2/docs/reference/docker_compose_commit.yaml b/_vendor/github.com/docker/compose/v2/docs/reference/docker_compose_commit.yaml new file mode 100644 index 000000000000..95f4834a97b1 --- /dev/null +++ b/_vendor/github.com/docker/compose/v2/docs/reference/docker_compose_commit.yaml @@ -0,0 +1,76 @@ +command: docker compose commit +short: Create a new image from a service container's changes +long: Create a new image from a service container's changes +usage: docker compose commit [OPTIONS] SERVICE [REPOSITORY[:TAG]] +pname: docker compose +plink: docker_compose.yaml +options: + - option: author + shorthand: a + value_type: string + description: Author (e.g., "John Hannibal Smith ") + deprecated: false + hidden: false + experimental: false + experimentalcli: false + kubernetes: false + swarm: false + - option: change + shorthand: c + value_type: list + description: Apply Dockerfile instruction to the created image + deprecated: false + hidden: false + experimental: false + experimentalcli: false + kubernetes: false + swarm: false + - option: index + value_type: int + default_value: "0" + description: index of the container if service has multiple replicas. + deprecated: false + hidden: false + experimental: false + experimentalcli: false + kubernetes: false + swarm: false + - option: message + shorthand: m + value_type: string + description: Commit message + deprecated: false + hidden: false + experimental: false + experimentalcli: false + kubernetes: false + swarm: false + - option: pause + shorthand: p + value_type: bool + default_value: "true" + description: Pause container during commit + deprecated: false + hidden: false + experimental: false + experimentalcli: false + kubernetes: false + swarm: false +inherited_options: + - option: dry-run + value_type: bool + default_value: "false" + description: Execute command in dry run mode + deprecated: false + hidden: false + experimental: false + experimentalcli: false + kubernetes: false + swarm: false +deprecated: false +hidden: false +experimental: false +experimentalcli: false +kubernetes: false +swarm: false + diff --git a/_vendor/github.com/docker/compose/v2/docs/reference/docker_compose_up.yaml b/_vendor/github.com/docker/compose/v2/docs/reference/docker_compose_up.yaml index 4c895f6a65b4..1474cfe2ee6a 100644 --- a/_vendor/github.com/docker/compose/v2/docs/reference/docker_compose_up.yaml +++ b/_vendor/github.com/docker/compose/v2/docs/reference/docker_compose_up.yaml @@ -289,7 +289,8 @@ options: - option: wait-timeout value_type: int default_value: "0" - description: Maximum duration to wait for the project to be running|healthy + description: | + Maximum duration in seconds to wait for the project to be running|healthy deprecated: false hidden: false experimental: false diff --git a/_vendor/modules.txt b/_vendor/modules.txt index aaf838f5fdd0..e08dfe562a2f 100644 --- a/_vendor/modules.txt +++ b/_vendor/modules.txt @@ -2,5 +2,5 @@ # github.com/moby/buildkit v0.18.0 # github.com/docker/buildx v0.19.1 # github.com/docker/cli v27.4.0-rc.2+incompatible -# github.com/docker/compose/v2 v2.30.3 +# github.com/docker/compose/v2 v2.31.0 # github.com/docker/scout-cli v1.15.0 diff --git a/content/manuals/_index.md b/content/manuals/_index.md index af786bfcf751..7ef904dfb118 100644 --- a/content/manuals/_index.md +++ b/content/manuals/_index.md @@ -7,16 +7,13 @@ url: /manuals/ layout: wide params: icon: description + sidebar: + groups: + - Open source + - Products + - Platform notoc: true - development: - - title: Docker Desktop - description: Your command center for container development. - icon: /assets/icons/Whale.svg - link: /desktop/ - - title: Docker Compose - description: Define and run multi-container applications. - icon: /assets/icons/Compose.svg - link: /compose/ + open-source: - title: Docker Build description: Build and ship any application anywhere. icon: build @@ -25,11 +22,19 @@ params: description: The industry-leading container runtime. icon: developer_board link: /engine/ - - title: Docker Extensions - description: Customize your Docker Desktop workflow. - icon: extension - link: /extensions/ - services: + - title: Docker Compose + description: Define and run multi-container applications. + icon: /assets/icons/Compose.svg + link: /compose/ + products: + - title: Docker Desktop + description: Your command center for container development. + icon: /assets/icons/Whale.svg + link: /desktop/ + - title: Build Cloud + description: Build your images faster in the cloud. + icon: /assets/images/logo-build-cloud.svg + link: /build-cloud/ - title: Docker Hub description: Discover, share, and integrate container images. icon: hub @@ -38,50 +43,63 @@ params: description: Image analysis and policy evaluation. icon: /assets/icons/Scout.svg link: /scout/ - - title: Trusted content - description: Curated, high-quality content from trusted sources. - icon: verified - link: /trusted-content/ - - title: Build Cloud - description: Build your images faster in the cloud. - icon: /assets/images/logo-build-cloud.svg - link: /build-cloud/ - admin: + - title: Docker for GitHub Copilot + description: Integrate Docker's capabilities with GitHub Copilot. + icon: chat + link: /copilot/ + - title: Docker Extensions + description: Customize your Docker Desktop workflow. + icon: extension + link: /extensions/ + - title: Testcontainers cloud + description: Run integration tests, with real dependencies, in the cloud. + icon: package_2 + link: https://testcontainers.com/cloud/docs/ + platform: - title: Administration description: Centralized observability for companies and organizations. icon: admin_panel_settings link: /admin/ - - title: Security - description: Security guardrails for both administrators and developers. - icon: lock - link: /security/ - title: Billing description: Manage billing and payment methods. icon: payments link: /billing/ + - title: Accounts + description: Manage your Docker account. + icon: account_circle + link: /accounts/ + - title: Security + description: Security guardrails for both administrators and developers. + icon: lock + link: /security/ - title: Subscription description: Commercial use licenses for Docker products. icon: card_membership link: /subscription/ + - title: Trusted content + description: Curated, high-quality content from trusted sources. + icon: verified + link: /trusted-content/ --- This section contains user guides on how to install, set up, configure, and use Docker products. -## Developer tools +## Open source -Software development and containerization technologies. +Open source development and containerization technologies. -{{< grid items=development >}} +{{< grid items=open-source >}} -## Services +## Products -Artifact management and supply chain security. +End-to-end developer solutions for innovative teams. -{{< grid items=services >}} +{{< grid items=products >}} -## Administration and accounts +## Platform -Administration and subscription management for organizations. +Documentation related to the Docker platform, such as administration and +subscription management for organizations. -{{< grid items=admin >}} +{{< grid items=platform >}} diff --git a/content/manuals/accounts/_index.md b/content/manuals/accounts/_index.md index b4b2b0a307e1..6da49ef20b43 100644 --- a/content/manuals/accounts/_index.md +++ b/content/manuals/accounts/_index.md @@ -1,8 +1,10 @@ --- title: Docker accounts -weight: 200 description: Learn how to create and manage your Docker account. keywords: accounts, docker ID, account management, account settings, docker account, docker home +params: + sidebar: + group: Platform grid: - title: Create a Docker ID description: Get started with Docker and create an account. diff --git a/content/manuals/admin/_index.md b/content/manuals/admin/_index.md index f32ba7a7876d..72f14268db76 100644 --- a/content/manuals/admin/_index.md +++ b/content/manuals/admin/_index.md @@ -1,8 +1,10 @@ --- title: Administration -weight: 200 description: Discover manuals on administration for accounts, organizations, and companies. keywords: admin, administration, company, organization, Admin Console, user accounts, account management +params: + sidebar: + group: Platform grid: - title: Company administration description: Explore how to manage a company. diff --git a/content/manuals/billing/_index.md b/content/manuals/billing/_index.md index 5a046e414a36..57e0b2359e26 100644 --- a/content/manuals/billing/_index.md +++ b/content/manuals/billing/_index.md @@ -1,9 +1,11 @@ --- title: Billing and payments linkTitle: Billing -weight: 200 description: Discover information on billing and payment processes for Docker subscriptions. keywords: billing, invoice, payment, subscription +params: + sidebar: + group: Platform grid_core: - title: Get started description: Learn how to set up a Docker Core subscription for a personal account or organization. diff --git a/content/manuals/build-cloud/_index.md b/content/manuals/build-cloud/_index.md index 4280dabab5e1..3c31b1be7ffe 100644 --- a/content/manuals/build-cloud/_index.md +++ b/content/manuals/build-cloud/_index.md @@ -1,8 +1,11 @@ --- title: Docker Build Cloud -weight: 100 +weight: 20 description: Find documentation on Docker Build Cloud to help you build your container images faster, both locally and in CI keywords: build, cloud, cloud build, remote builder +params: + sidebar: + group: Products aliases: - /build/cloud/faq/ - /build/cloud/ diff --git a/content/manuals/build/_index.md b/content/manuals/build/_index.md index 88bf30532407..c4af3ceb1af8 100644 --- a/content/manuals/build/_index.md +++ b/content/manuals/build/_index.md @@ -1,8 +1,11 @@ --- title: Docker Build -weight: 100 +weight: 20 description: Get an overview of Docker Build to package and bundle your code and ship it anywhere keywords: build, buildx, buildkit +params: + sidebar: + group: Open source grid: - title: Packaging your software description: 'Build and package your application to run it anywhere: locally or diff --git a/content/manuals/cloud/index.md b/content/manuals/cloud/index.md index df096fb61e1e..7f6517780766 100644 --- a/content/manuals/cloud/index.md +++ b/content/manuals/cloud/index.md @@ -2,6 +2,9 @@ title: Cloud integrations description: ACI and ECS integration information keywords: compose, ACI, ECS, amazon, cloud integration +params: + sidebar: + group: Products aliases: - /engine/context/aci-integration/ - /cloud/aci-integration/ diff --git a/content/manuals/compose/_index.md b/content/manuals/compose/_index.md index 88d396af20d3..71c95c12a21c 100644 --- a/content/manuals/compose/_index.md +++ b/content/manuals/compose/_index.md @@ -1,11 +1,14 @@ --- title: Docker Compose -weight: 100 +weight: 30 description: Learn how to use Docker Compose to define and run multi-container applications with this detailed introduction to the tool. keywords: docker compose, docker-compose, docker compose command, docker compose files, docker compose documentation, using docker compose, compose container, docker compose service +params: + sidebar: + group: Open source grid: - title: Why use Compose? description: Understand Docker Compose's key benefits diff --git a/content/manuals/compose/releases/release-notes.md b/content/manuals/compose/releases/release-notes.md index 43524bc4fd6e..ff14e92aca6d 100644 --- a/content/manuals/compose/releases/release-notes.md +++ b/content/manuals/compose/releases/release-notes.md @@ -13,6 +13,25 @@ aliases: For more detailed information, see the [release notes in the Compose repo](https://github.com/docker/compose/releases/). +## 2.31.0 + +{{< release-date date="2024-11-28" >}} + +### Update + +- Dependencies upgrade: bump compose-go to v2.4.5 +- Dependencies upgrade: bump docker engine and cli to v27.4.0-rc.2 +- Dependencies upgrade: bump buildx to v0.18.0 +- Dependencies upgrade: bump buildkit to v0.17.1 + +### Bug fixes and enhancements + +- Added the ability to use Docker Buildx Bake to build Docker Compose services +- Added `commit` command to create new images from running containers +- Fixed an issue where network changes were not detected +- Fixed an issue where containers stopped sequentially which slowed down the restart process + + ## 2.30.3 {{< release-date date="2024-11-07" >}} diff --git a/content/manuals/copilot/_index.md b/content/manuals/copilot/_index.md index 08f501b1113f..e38267582a8b 100644 --- a/content/manuals/copilot/_index.md +++ b/content/manuals/copilot/_index.md @@ -2,10 +2,11 @@ title: Docker for GitHub Copilot params: sidebar: + group: Products badge: color: violet text: EA -weight: 100 +weight: 50 description: | Learn how to streamline Docker-related tasks with the Docker for GitHub Copilot extension. This integration helps you generate Docker assets, analyze diff --git a/content/manuals/desktop/_index.md b/content/manuals/desktop/_index.md index 0a27c2138169..17c87b9cfcd5 100644 --- a/content/manuals/desktop/_index.md +++ b/content/manuals/desktop/_index.md @@ -1,9 +1,12 @@ --- title: Docker Desktop -weight: 100 +weight: 10 description: Explore Docker Desktop, what it has to offer, and its key features. Take the next step by downloading or find additional resources keywords: how to use docker desktop, what is docker desktop used for, what does docker desktop do, using docker desktop +params: + sidebar: + group: Products grid: - title: Install Docker Desktop description: | diff --git a/content/manuals/desktop/release-notes.md b/content/manuals/desktop/release-notes.md index ff285bfe1e4d..1dfd38bdebcc 100644 --- a/content/manuals/desktop/release-notes.md +++ b/content/manuals/desktop/release-notes.md @@ -529,8 +529,6 @@ For more information, see [microsoft/WSL#11794](https://github.com/microsoft/WSL {{< release-date date="2024-05-06" >}} -{{< desktop-install all=true beta_win_arm=true version="4.30.0" build_path="/149282/" >}} - ### New #### For all platforms @@ -611,8 +609,6 @@ This can be resolved by adding the user to the **docker-users** group. Before st {{< release-date date="2024-04-08" >}} -{{< desktop-install all=true version="4.29.0" build_path="/145265/" >}} - ### New - You can now enforce Rosetta usage via [Settings Management](/manuals/security/for-admins/hardened-desktop/settings-management/_index.md). diff --git a/content/manuals/docker-hub/_index.md b/content/manuals/docker-hub/_index.md index d79348764054..c6ab1a08381d 100644 --- a/content/manuals/docker-hub/_index.md +++ b/content/manuals/docker-hub/_index.md @@ -2,7 +2,10 @@ description: Get an overview on Docker Hub to find and share container images keywords: docker hub, hub, repositories title: Docker Hub -weight: 100 +weight: 30 +params: + sidebar: + group: Products grid: - title: Quickstart description: Step-by-step instructions on getting started on Docker Hub. @@ -46,4 +49,4 @@ In addition to the graphical interface, you can interact with Docker Hub using the [Docker Hub API](../../reference/api/hub/latest.md) or experimental [Docker Hub CLI tool](https://github.com/docker/hub-tool#readme). -{{< grid >}} \ No newline at end of file +{{< grid >}} diff --git a/content/manuals/engine/_index.md b/content/manuals/engine/_index.md index 68846eb6a3c7..febf3717d814 100644 --- a/content/manuals/engine/_index.md +++ b/content/manuals/engine/_index.md @@ -1,8 +1,11 @@ --- title: Docker Engine -weight: 100 +weight: 10 description: Find a comprehensive overview of Docker Engine, including how to install, storage details, networking, and more keywords: Engine +params: + sidebar: + group: Open source grid: - title: Install Docker Engine description: Learn how to install the open source Docker Engine for your distribution. diff --git a/content/manuals/extensions/_index.md b/content/manuals/extensions/_index.md index a538211d29b9..92beb943cb36 100644 --- a/content/manuals/extensions/_index.md +++ b/content/manuals/extensions/_index.md @@ -1,8 +1,11 @@ --- title: Docker Extensions -weight: 100 +weight: 60 description: Extensions keywords: Docker Extensions, Docker Desktop, Linux, Mac, Windows +params: + sidebar: + group: Products aliases: - /desktop/extensions/ --- diff --git a/content/manuals/harmonia/_index.md b/content/manuals/harmonia/_index.md index 3a2a72b3b111..84c0dadbddca 100644 --- a/content/manuals/harmonia/_index.md +++ b/content/manuals/harmonia/_index.md @@ -3,6 +3,9 @@ title: Project Harmonia description: Learn how you can run your applications in the cloud with Project Harmonia keywords: run, cloud, docker desktop, resources sitemap: false +params: + sidebar: + group: Products aliases: - /run-cloud/ --- diff --git a/content/manuals/registry.md b/content/manuals/registry.md index c0e93f323c44..ac668945ee49 100644 --- a/content/manuals/registry.md +++ b/content/manuals/registry.md @@ -2,6 +2,9 @@ title: Registry description: The Docker Hub registry implementation keywords: registry, distribution, docker hub, spec, schema, api, manifest, auth +params: + sidebar: + group: Open source aliases: - /registry/compatibility/ - /registry/configuration/ diff --git a/content/manuals/release-lifecycle.md b/content/manuals/release-lifecycle.md index b5b7c22bb040..4b54d2cc3c3d 100644 --- a/content/manuals/release-lifecycle.md +++ b/content/manuals/release-lifecycle.md @@ -4,6 +4,9 @@ linkTitle: Release lifecycle description: Describes the various stages of feature lifecycle from beta to GA. keywords: beta, GA, Early Access, +params: + sidebar: + group: Products --- This page details Docker's product release lifecycle and how Docker defines each stage. It also provides information on the product retirement process. Features and products may progress through some or all of these phases. diff --git a/content/manuals/scout/_index.md b/content/manuals/scout/_index.md index e08c4253be81..81a56203f2d5 100644 --- a/content/manuals/scout/_index.md +++ b/content/manuals/scout/_index.md @@ -1,11 +1,14 @@ --- title: Docker Scout -weight: 100 +weight: 40 keywords: scout, supply chain, vulnerabilities, packages, cves, scan, analysis, analyze description: Get an overview on Docker Scout to proactively enhance your software supply chain security aliases: - /engine/scan/ +params: + sidebar: + group: Products grid: - title: Quickstart link: /scout/quickstart/ diff --git a/content/manuals/security/_index.md b/content/manuals/security/_index.md index 22879e3535d1..c7d4dc29a9f6 100644 --- a/content/manuals/security/_index.md +++ b/content/manuals/security/_index.md @@ -1,8 +1,10 @@ --- title: Security -weight: 200 description: Learn about security features Docker has to offer and explore best practices keywords: docker, docker hub, docker desktop, security +params: + sidebar: + group: Platform grid_admins: - title: Settings Management description: Learn how Settings Management can secure your developers' workflows. diff --git a/content/manuals/security/for-admins/hardened-desktop/enhanced-container-isolation/_index.md b/content/manuals/security/for-admins/hardened-desktop/enhanced-container-isolation/_index.md index d4b1941e6102..f08fd5383b2c 100644 --- a/content/manuals/security/for-admins/hardened-desktop/enhanced-container-isolation/_index.md +++ b/content/manuals/security/for-admins/hardened-desktop/enhanced-container-isolation/_index.md @@ -13,49 +13,41 @@ weight: 20 > > Enhanced Container Isolation is available to Docker Business customers only. -Enhanced Container Isolation provides an additional layer of security to prevent malicious workloads running in containers from compromising Docker Desktop or the host. +Enhanced Container Isolation (ECI) provides an additional layer of security to prevent malicious workloads running in containers from compromising Docker Desktop or the host. -It uses a variety of advanced techniques to harden container isolation, but without impacting developer productivity. It is available with [Docker Desktop 4.13.0 and later](/manuals/desktop/release-notes.md). +It uses a variety of advanced techniques to harden container isolation, but without impacting developer productivity. -These techniques include: -- Running all containers unprivileged through the Linux user-namespace, even those launched with the `--privileged` flag. This makes it harder for malicious container workloads to escape the container and infect the Docker Desktop VM and host. -- Ensuring Docker Desktop VM immutability (e.g., its internal settings can't be modified by containers or users). -- Vetting some critical system calls to prevent container escapes, and partially virtualizing portions of `/proc` and `/sys` inside the container for further isolation. -- Preventing user console access to the Docker Desktop VM. - -When Enhanced Container Isolation is enabled, these mechanisms are applied automatically and with minimal functional or performance impact to developers. Developers continue to use Docker Desktop as usual, but the containers they launch are more strongly isolated. - -Enhanced Container Isolation ensures stronger container isolation and also locks in any security configurations that have been created by IT admins, for instance through [Registry Access Management policies](/manuals/security/for-admins/hardened-desktop/registry-access-management.md) or with [Settings Management](../settings-management/_index.md). +Enhanced Container Isolation ensures stronger container isolation and also locks in any security configurations that have been created by administrators, for instance through [Registry Access Management policies](/manuals/security/for-admins/hardened-desktop/registry-access-management.md) or with [Settings Management](../settings-management/_index.md). > [!NOTE] > -> Enhanced Container Isolation is in addition to other container security techniques used by Docker. For example, reduced Linux Capabilities, Seccomp, AppArmor. +> ECI is in addition to other container security techniques used by Docker. For example, reduced Linux Capabilities, seccomp, and AppArmor. -### Who is it for? +## Who is it for? - For organizations and developers that want to prevent container attacks and reduce vulnerabilities in developer environments. - For organizations that want to ensure stronger container isolation that is easy and intuitive to implement on developers' machines. -### What happens when Enhanced Container Isolation is turned on? +## What happens when Enhanced Container Isolation is turned on? -When Enhanced Container Isolation is turned on, the following features are enabled: +When Enhanced Container Isolation is turned on, the following features and security techniques are enabled: -- All user containers are automatically run in Linux User Namespaces which ensures stronger isolation. Each container runs in a dedicated Linux user-namespace. +- All user containers are automatically run in Linux user namespaces which ensures stronger isolation. Each container runs in a dedicated Linux user-namespace. - The root user in the container maps to an unprivileged user inside the Docker Desktop Linux VM. -- Containers become harder to breach. For example, sensitive system calls are vetted and portions of `/proc` and `/sys` are emulated. +- Containers become harder to breach. For example, sensitive system calls are vetted and portions of `/proc` and `/sys` are emulated inside the container. - Users can continue using containers as usual, including bind mounting host directories, volumes, etc. - No change in the way developers run containers, and no special container images are required. -- Privileged containers (e.g., `--privileged` flag) work, but they are only privileged within the container's Linux User Namespace, not in the Docker Desktop VM. Therefore they can't be used to breach the Docker Desktop VM. +- Privileged containers (e.g., `--privileged` flag) work, but they are only privileged within the container's Linux user namespace, not in the Docker Desktop VM. Therefore they can't be used to breach the Docker Desktop VM. - Docker-in-Docker and even Kubernetes-in-Docker works, but run unprivileged inside the Docker Desktop Linux VM. In addition, the following restrictions are imposed: - Containers can no longer share namespaces with the Docker Desktop VM (e.g., `--network=host`, `--pid=host` are disallowed). - Containers can no longer modify configuration files inside the Docker Desktop VM (e.g., mounting any VM directory into the container is disallowed). -- Containers can no longer access the Docker engine (e.g., mounting the Docker engine's socket into the container is restricted); this prevents malicious containers from gaining control of the Docker engine. Admins can relax this for [trusted container images](config.md). +- Containers can no longer access the Docker Engine. For example, mounting the Docker Engine's socket into the container is restricted which prevents malicious containers from gaining control of the Docker Engine. Administrators can relax this for [trusted container images](config.md). - Console access to the Docker Desktop VM is forbidden for all users. -These features and restrictions ensure that containers are better secured at runtime, with minimal impact to developer experience and productivity. +These features and restrictions ensure that containers are better secured at runtime, with minimal impact to developer experience and productivity. Developers can continue to use Docker Desktop as usual, but the containers they launch are more strongly isolated. For more information on how Enhanced Container Isolation work, see [How does it work](how-eci-works.md). @@ -65,20 +57,9 @@ For more information on how Enhanced Container Isolation work, see [How does it > Kubernetes pods and Extension containers. For more information on known > limitations and workarounds, see [FAQs](faq.md). -### What host OSes / platforms is Enhanced Container Isolation supported on? - -Enhanced Container Isolation (ECI) was introduced in Docker Desktop 4.13, for all platforms (Windows, Mac, and Linux). - -For Windows hosts, ECI works with both the Docker Desktop Hyper-V and WSL 2 backends, as follows: - -- Docker Desktop 4.19 or prior: ECI only works with Hyper-V. -- Docker Desktop 4.20 or later: ECI Works with both Hyper-V and WSL 2 (with WSL version 1.1.3.0 and above). +## How do I enable Enhanced Container Isolation? -See [ECI Support for WSL](limitations.md#eci-support-for-wsl) for further info as well as security caveats when using Enhanced Container Isolation on WSL 2. - -### How do I enable Enhanced Container Isolation? - -#### As a developer +### As a developer To enable Enhanced Container Isolation as a developer: 1. Ensure your organization has a Docker Business subscription. @@ -92,19 +73,13 @@ To enable Enhanced Container Isolation as a developer: > > Enhanced Container Isolation does not protect containers created prior to enabling ECI. For more information on known limitations and workarounds, see [FAQs](faq.md). -#### As an admin - -##### Prerequisite +### As an administrator -To enable Enhanced Container Isolation as an admin, you first need to [enforce -sign-in](/manuals/security/for-admins/enforce-sign-in/_index.md). This is -because the Enhanced Container Isolation feature requires a Docker Business -subscription and therefore your Docker Desktop users must authenticate to your -organization for this configuration to take effect. +#### Prerequisite -Enforcing sign-in ensures that your Docker Desktop developers always authenticate to your organization. +You first need to [enforce sign-in](/manuals/security/for-admins/enforce-sign-in/_index.md) to ensure that all Docker Desktop developers authenticate with your organization. Since Settings Management requires a Docker Business subscription, enforced sign-in guarantees that only authenticated users have access and that the feature consistently takes effect across all users, even though it may still work without enforced sign-in. -##### Setup +#### Setup [Create and configure the `admin-settings.json` file](/manuals/security/for-admins/hardened-desktop/settings-management/configure-json-file.md) and specify: @@ -118,13 +93,13 @@ Enforcing sign-in ensures that your Docker Desktop developers always authenticat } ``` -By setting `"value": true`, the admin ensures ECI is enabled by default. By -setting `"locked": true`, the admin ensures ECI can't be disabled by -developers. If you wish to give developers the ability to disable the feature, +Setting `"value": true` ensures ECI is enabled by default. By +setting `"locked": true`, ECI can't be disabled by +developers. If you want to give developers the ability to disable the feature, set `"locked": false`. -In addition, starting with Docker Desktop 4.27, admins can also configure Docker -socket mount permissions for containers, as described [here](config.md). +In addition, you can also [configure Docker +socket mount permissions for containers](config.md). For this to take effect: @@ -135,12 +110,12 @@ For this to take effect: > > Selecting **Restart** from the Docker menu isn't enough as it only restarts some components of Docker Desktop. +## What do users see when this setting is enforced by an administrator? + > [!TIP] > > You can now also configure these settings in the [Docker Admin Console](/manuals/security/for-admins/hardened-desktop/settings-management/configure-admin-console.md). -### What do users see when this setting is enforced by an admin? - When Enhanced Container Isolation is enabled, users see: - **Use Enhanced Container Isolation** toggled on in **Settings** > **General**. - Containers run within a Linux user namespace. diff --git a/content/manuals/security/for-admins/hardened-desktop/enhanced-container-isolation/config.md b/content/manuals/security/for-admins/hardened-desktop/enhanced-container-isolation/config.md index c377a3030eeb..fed2ca9f1343 100644 --- a/content/manuals/security/for-admins/hardened-desktop/enhanced-container-isolation/config.md +++ b/content/manuals/security/for-admins/hardened-desktop/enhanced-container-isolation/config.md @@ -8,16 +8,9 @@ aliases: weight: 30 --- -> [!NOTE] -> -> This feature is available with Docker Desktop version 4.27 (and later) on Mac, Linux, and Windows (Hyper-V). -> For Windows with WSL 2, this feature requires Docker Desktop 4.28 and later. - -This page describes optional, advanced configurations for ECI, once ECI is enabled. - ## Docker socket mount permissions -By default, when ECI is enabled, Docker Desktop does not allow bind-mounting the +By default, when Enhanced Container Isolation (ECI) is enabled, Docker Desktop does not allow bind-mounting the Docker Engine socket into containers: ```console @@ -25,8 +18,8 @@ $ docker run -it --rm -v /var/run/docker.sock:/var/run/docker.sock docker:cli docker: Error response from daemon: enhanced container isolation: docker socket mount denied for container with image "docker.io/library/docker"; image is not in the allowed list; if you wish to allow it, configure the docker socket image list in the Docker Desktop settings. ``` This prevents malicious containers from gaining access to the Docker Engine, as -such access could allow them to perform supply chain attacks (e.g., build and -push malicious images into the organization's repositories) or similar. +such access could allow them to perform supply chain attacks. For example, build and +push malicious images into the organization's repositories or similar. However, some legitimate use cases require containers to have access to the Docker Engine socket. For example, the popular [Testcontainers](https://testcontainers.com/) @@ -35,11 +28,12 @@ manage them or perform post-test cleanup. Similarly, some Buildpack frameworks, for example [Paketo](https://paketo.io/), require Docker socket bind-mounts into containers. -Starting with Docker Desktop 4.27, admins can optionally configure ECI to allow +Administrators can optionally configure ECI to allow bind mounting the Docker Engine socket into containers, but in a controlled way. This can be done via the Docker Socket mount permissions section in the -[admin-settings.json](../settings-management/_index.md) file. For example: +[`admin-settings.json`](../settings-management/configure-json-file.md) file. For example: + ```json { @@ -75,8 +69,8 @@ described below. ### Image list The `imageList` is a list of container images that are allowed to bind-mount the -Docker socket. By default the list is empty (i.e., no containers are allowed to -bind-mount the Docker socket when ECI is enabled). However, an admin can add +Docker socket. By default the list is empty, no containers are allowed to +bind-mount the Docker socket when ECI is enabled. However, an administrator can add images to the list, using either of these formats: | Image Reference Format | Description | @@ -87,7 +81,7 @@ images to the list, using either of these formats: The image name follows the standard convention, so it can point to any registry and repository. -In the example above, the image list was configured with three images: +In the previous example, the image list was configured with three images: ```json "imageList": { @@ -111,11 +105,10 @@ $ docker run -it -v /var/run/docker.sock:/var/run/docker.sock docker:cli sh > [!TIP] > -> Be restrictive on the images you allow, as described in [Recommendations](#recommendations) below. +> Be restrictive with the images you allow, as described in [Recommendations](#recommendations). -In general, it's easier to specify the image using the tag wildcard format -(e.g., `:*`) because then `imageList` doesn't need to be updated whenever a new version of the -image is used. Alternatively, you can use an immutable tag (e.g., `:latest`), +In general, it's easier to specify the image using the tag wildcard format, for example `:*`, because then `imageList` doesn't need to be updated whenever a new version of the +image is used. Alternatively, you can use an immutable tag, for example `:latest`, but it does not always work as well as the wildcard because, for example, Testcontainers uses specific versions of the image, not necessarily the latest one. @@ -126,8 +119,7 @@ memory. Then, when a container is started with a Docker socket bind-mount, Docker Desktop checks if the container's image digest matches one of the allowed digests. If so, the container is allowed to start, otherwise it's blocked. -Note that due to the digest comparison mentioned in the prior paragraph, it's -not possible to bypass the Docker socket mount permissions by retagging a +Due to the digest comparison, it's not possible to bypass the Docker socket mount permissions by re-tagging a disallowed image to the name of an allowed one. In other words, if a user does: @@ -143,11 +135,9 @@ ones in the repository. ### Docker Socket Mount Permissions for derived images -> [!NOTE] -> -> This feature is available with Docker Desktop version 4.34 and later. +{{ introduced desktop 4.34.0 "../../../../desktop/release-notes.md#4340" }} -As described in the prior section, admins can configure the list of container +As described in the prior section, administrators can configure the list of container images that are allowed to mount the Docker socket via the `imageList`. This works for most scenarios, but not always, because it requires knowing upfront @@ -164,7 +154,7 @@ also apply to any local images derived (i.e., built from) an image in the That is, if a local image called "myLocalImage" is built from "myBaseImage" (i.e., has a Dockerfile with a `FROM myBaseImage`), then if "myBaseImage" is in the `imageList`, both "myBaseImage" and "myLocalImage" are allowed to mount the -Docker socket (i.e., ECI won't block the mount). +Docker socket. For example, to enable Paketo buildpacks to work with Docker Desktop and ECI, simply add the following image to the `imageList`: @@ -192,7 +182,7 @@ A couple of caveats: * The `allowDerivedImages` setting only applies to local-only images built from an allowed image. That is, the derived image must not be present in a remote - repository (because if it were, you would just list it's name in the `imageList`). + repository because if it were, you would just list its name in the `imageList`. * For derived image checking to work, the parent image (i.e., the image in the `imageList`) must be present locally (i.e., must have been explicitly pulled @@ -339,17 +329,16 @@ Whether to configure the list as an allow or deny list depends on the use case. | Unsupported command | Description | | :------------------- | :---------- | -| compose | Docker compose | -| dev | Docker dev environments | -| extension | Manages Docker extensions | -| feedback | Send feedback to Docker | -| init | Creates Docker-related starter files | -| manifest | Manages Docker image manifests | -| plugins | Manages plugins | -| sbom | View Software Bill of Materials (SBOM) | -| scan | Docker Scan | -| scout | Docker Scout | -| trust | Manage trust on Docker images | +| `compose` | Docker Compose | +| `dev` | Dev environments | +| `extension` | Manages Docker Extensions | +| `feedback` | Send feedback to Docker | +| `init` | Creates Docker-related starter files | +| `manifest` | Manages Docker image manifests | +| `plugin` | Manages plugins | +| `sbom` | View Software Bill of Materials (SBOM) | +| `scout` | Docker Scout | +| `trust` | Manage trust on Docker images | > [!NOTE] > diff --git a/content/manuals/security/for-admins/hardened-desktop/enhanced-container-isolation/faq.md b/content/manuals/security/for-admins/hardened-desktop/enhanced-container-isolation/faq.md index dde563e71b84..a2f7048eee31 100644 --- a/content/manuals/security/for-admins/hardened-desktop/enhanced-container-isolation/faq.md +++ b/content/manuals/security/for-admins/hardened-desktop/enhanced-container-isolation/faq.md @@ -1,5 +1,5 @@ --- -title: Enhanced Container Isolation (ECI) FAQs +title: Enhanced Container Isolation FAQs linkTitle: FAQs description: Frequently asked questions for Enhanced Container Isolation keywords: enhanced container isolation, security, faq, sysbox, Docker Desktop @@ -26,12 +26,12 @@ minimum. Yes, you can use the `--privileged` flag in containers but unlike privileged containers without ECI, the container can only use it's elevated privileges to access resources assigned to the container. It can't access global kernel -resources in the Docker Desktop Linux VM. This allows you to run privileged +resources in the Docker Desktop Linux VM. This lets you run privileged containers securely (including Docker-in-Docker). For more information, see [Key features and benefits](features-benefits.md#privileged-containers-are-also-secured). ### Will all privileged container workloads run with ECI? -No. Privileged container workloads that wish to access global kernel resources +No. Privileged container workloads that want to access global kernel resources inside the Docker Desktop Linux VM won't work. For example, you can't use a privileged container to load a kernel module. @@ -61,7 +61,7 @@ when using [Testcontainers](https://testcontainers.com/) for local testing. To enable such use cases, it's possible to configure ECI to allow Docker socket mounts into containers, but only for your chosen (i.e,. trusted) container images, and -even restrict what commands the container can send to the Docker engine via the socket. +even restrict what commands the container can send to the Docker Engine via the socket. See [ECI Docker socket mount permissions](config.md#docker-socket-mount-permissions). ### Does ECI protect all containers launched with Docker Desktop? @@ -84,12 +84,12 @@ and [Dev Environments containers](/manuals/desktop/features/dev-environments/_in ### Does ECI protect containers launched prior to enabling ECI? -No. Containers created prior to switching on ECI are not protected. Therefore, we -recommend removing all containers prior to switching on ECI. +No. Containers created prior to switching on ECI are not protected. Therefore, it is +recommended you remove all containers prior to switching on ECI. ### Does ECI affect the performance of containers? -ECI has very little impact on the performance of +ECI has little impact on the performance of containers. The exception is for containers that perform lots of `mount` and `umount` system calls, as these are trapped and vetted by the Sysbox container runtime to ensure they are not being used to breach the container's filesystem. @@ -101,10 +101,10 @@ containers deployed by Docker Desktop users. If a user attempts to override the runtime (e.g., `docker run --runtime=runc`), this request is ignored and the container is created through the Sysbox runtime. -The reason `runc` is disallowed with ECI because it allows users to run as "true +The reason `runc` is disallowed is it lets users run as "true root" on the Docker Desktop Linux VM, thereby providing them with implicit control of the VM and the ability to modify the administrative configurations -for Docker Desktop, for example. +for Docker Desktop. ### How is ECI different from Docker Engine's userns-remap mode? diff --git a/content/manuals/security/for-admins/hardened-desktop/enhanced-container-isolation/features-benefits.md b/content/manuals/security/for-admins/hardened-desktop/enhanced-container-isolation/features-benefits.md index 494e2d4a745e..87e58442a36e 100644 --- a/content/manuals/security/for-admins/hardened-desktop/enhanced-container-isolation/features-benefits.md +++ b/content/manuals/security/for-admins/hardened-desktop/enhanced-container-isolation/features-benefits.md @@ -7,9 +7,9 @@ aliases: weight: 20 --- -### Linux User Namespace on all containers +## Linux user namespace on all containers -With Enhanced Container Isolation, all user containers leverage the [Linux user-namespace](https://man7.org/linux/man-pages/man7/user_namespaces.7.html) +With Enhanced Container Isolation, all user containers leverage the [Linux user namespace](https://man7.org/linux/man-pages/man7/user_namespaces.7.html) for extra isolation. This means that the root user in the container maps to an unprivileged user in the Docker Desktop Linux VM. @@ -21,7 +21,7 @@ $ docker run -it --rm --name=first alpine 0 100000 65536 ``` -The output `0 100000 65536` is the signature of the Linux user-namespace. It +The output `0 100000 65536` is the signature of the Linux user namespace. It means that the root user (0) in the container is mapped to unprivileged user 100000 in the Docker Desktop Linux VM, and the mapping extends for a continuous range of 64K user IDs. The same applies to group IDs. @@ -44,28 +44,25 @@ $ docker run -it --rm alpine 0 0 4294967295 ``` -By virtue of using the Linux user-namespace, Enhanced Container Isolation +By virtue of using the Linux user namespace, Enhanced Container Isolation ensures the container processes never run as user ID 0 (true root) in the Linux VM. In fact they never run with any valid user-ID in the Linux VM. Thus, their Linux capabilities are constrained to resources within the container only, increasing isolation significantly compared to regular containers, both container-to-host and cross-container isolation. -### Privileged containers are also secured +## Privileged containers are also secured Privileged containers `docker run --privileged ...` are insecure because they give the container full access to the Linux kernel. That is, the container runs as true root with all capabilities enabled, seccomp and AppArmor restrictions are disabled, all hardware devices are exposed, for example. -For organizations that wish to secure Docker Desktop on their developer's -machines, privileged containers are problematic as they allow container -workloads whether benign or malicious to gain control of the Linux kernel -inside the Docker Desktop VM and thus modify security related settings, for example registry +Organizations aiming to secure Docker Desktop on developers' machines face challenges with privileged containers. These containers, whether running benign or malicious workloads, can gain control of the Linux kernel within the Docker Desktop VM, potentially altering security related settings, for example registry access management, and network proxies. With Enhanced Container Isolation, privileged containers can no longer do -this. The combination of the Linux user-namespace and other security techniques +this. The combination of the Linux user namespace and other security techniques used by Sysbox ensures that processes inside a privileged container can only access resources assigned to the container. @@ -74,13 +71,12 @@ access resources assigned to the container. > Enhanced Container Isolation does not prevent users from launching privileged > containers, but rather runs them securely by ensuring that they can only > modify resources associated with the container. Privileged workloads that -> modify global kernel settings, for example loading a kernel module or changing BPF +> modify global kernel settings, for example loading a kernel module or changing Berkeley Packet Filters (BPF) > settings will not work properly as they will receive "permission > denied" error when attempting such operations. For example, Enhanced Container Isolation ensures privileged containers can't -access Docker Desktop network settings in the Linux VM configured via Berkeley -Packet Filters (BPF): +access Docker Desktop network settings in the Linux VM configured via BPF: ```console $ docker run --privileged djs55/bpftool map show @@ -105,13 +101,13 @@ example Docker-in-Docker, Kubernetes-in-Docker, etc. With Enhanced Container Isolation you can still run such workloads but do so much more securely than before. -### Containers can't share namespaces with the Linux VM +## Containers can't share namespaces with the Linux VM When Enhanced Container Isolation is enabled, containers can't share Linux -namespaces with the host (e.g., pid, network, uts, etc.) as that essentially +namespaces with the host (e.g., PID, network, uts, etc.) as that essentially breaks isolation. -For example, sharing the pid namespace fails: +For example, sharing the PID namespace fails: ```console $ docker run -it --rm --pid=host alpine @@ -125,7 +121,7 @@ $ docker run -it --rm --network=host alpine docker: Error response from daemon: failed to create shim task: OCI runtime create failed: error in the container spec: invalid or unsupported container spec: sysbox containers can't share a network namespace with the host (because they use the linux user-namespace for isolation): unknown. ``` -In addition, the `--userns=host` flag, used to disable the user-namespace on the +In addition, the `--userns=host` flag, used to disable the user namespace on the container, is ignored: ```console @@ -138,7 +134,7 @@ Finally, Docker build `--network=host` and Docker buildx entitlements (`network.host`, `security.insecure`) are not allowed. Builds that require these won't work properly. -### Bind mount restrictions +## Bind mount restrictions When Enhanced Container Isolation is enabled, Docker Desktop users can continue to bind mount host directories into containers as configured via **Settings** > @@ -147,7 +143,7 @@ arbitrary Linux VM directories into containers. This prevents containers from modifying sensitive files inside the Docker Desktop Linux VM, files that can hold configurations for registry access -management, proxies, docker engine configurations, and more. +management, proxies, Docker Engine configurations, and more. For example, the following bind mount of the Docker Engine's configuration file (`/etc/docker/daemon.json` inside the Linux VM) into a container is restricted @@ -162,7 +158,7 @@ In contrast, without Enhanced Container Isolation this mount works and gives the container full read and write access to the Docker Engine's configuration. Of course, bind mounts of host files continue to work as usual. For example, -assuming a user configures Docker Desktop to file share her $HOME directory, +assuming a user configures Docker Desktop to file share her `$HOME` directory, she can bind mount it into the container: ```console @@ -173,16 +169,16 @@ $ docker run -it --rm -v $HOME:/mnt alpine > [!NOTE] > > By default, Enhanced Container Isolation won't allow bind mounting the Docker Engine socket -> (/var/run/docker.sock) into a container, as doing so essentially grants the +> (`/var/run/docker.sock`) into a container, as doing so essentially grants the > container control of Docker Engine, thus breaking container isolation. However, > as some legitimate use cases require this, it's possible to relax > this restriction for trusted container images. See [Docker socket mount permissions](config.md#docker-socket-mount-permissions). -### Vetting sensitive system calls +## Vetting sensitive system calls Another feature of Enhanced Container Isolation is that it intercepts and vets a few highly sensitive system calls inside containers, such as `mount` and -`umount`. This ensures that processes that have capabilities to execute these +`umount`. This ensures that processes that have capabilities to execute these system calls can't use them to breach the container. For example, a container that has `CAP_SYS_ADMIN` (required to execute the @@ -200,7 +196,7 @@ read-only, it can't be changed from within the container to read-write, even if ensures container processes can't use `mount`, or `umount`, to breach the container's root filesystem. -Note however that in the example above the container can still create mounts +Note however that in the previous example the container can still create mounts within the container, and mount them read-only or read-write as needed. Those mounts are allowed since they occur within the container, and therefore don't breach it's root filesystem: @@ -226,10 +222,10 @@ that it does not affect the performance of containers in the great majority of cases. It intercepts control-path system calls that are rarely used in most container workloads but data-path system calls are not intercepted. -### Filesystem user-ID mappings +## Filesystem user-ID mappings -As mentioned above, Enhanced Container Isolation enables the Linux -user-namespace on all containers and this ensures that the container's user-ID +As mentioned, ECI enables the Linux +user namespace on all containers. This ensures that the container's user-ID range (0->64K) maps to an unprivileged range of "real" user-IDs in the Docker Desktop Linux VM (e.g., 100000->165535). @@ -240,29 +236,28 @@ group-IDs. In addition, if a container is stopped and restarted, there is no guarantee it will receive the same mapping as before. This is by design and further improves security. -However the above presents a problem when mounting Docker volumes into -containers, as the files written to such volumes will have the real -user/group-IDs and will therefore won't be accessible across a container's +However this presents a problem when mounting Docker volumes into +containers. Files written to such volumes have the real +user/group-IDs and therefore won't be accessible across a container's start/stop/restart, or between containers due to the different real user-ID/group-ID of each container. To solve this problem, Sysbox uses "filesystem user-ID remapping" via the Linux -Kernel's ID-mapped mounts feature (added in 2021) or an alternative module -called shiftfs. These technologies map filesystem accesses from the container's +Kernel's ID-mapped mounts feature (added in 2021) or an alternative `shiftsfs` module. These technologies map filesystem accesses from the container's real user-ID (e.g., range 100000->165535) to the range (0->65535) inside Docker Desktop's Linux VM. This way, volumes can now be mounted or shared across containers, even if each container uses an exclusive range of user-IDs. Users need not worry about the container's real user-IDs. -Note that although filesystem user-ID remapping may cause containers to access -Linux VM files mounted into the container with real user-ID 0 (i.e., root), the -[restricted mounts feature](#bind-mount-restrictions) described above ensures -that no Linux VM sensitive files can be mounted into the container. +Although filesystem user-ID remapping may cause containers to access +Linux VM files mounted into the container with real user-ID 0, the +[restricted mounts feature](#bind-mount-restrictions) ensures +that sensitive Linux VM files can't be mounted into the container. -### Procfs & Sysfs Emulation +## Procfs & sysfs emulation Another feature of Enhanced Container Isolation is that inside each container, -the procfs ("/proc") and sysfs ("/sys") filesystems are partially emulated. This +the `/proc` and `/sys` filesystems are partially emulated. This serves several purposes, such as hiding sensitive host information inside the container and namespacing host kernel resources that are not yet namespaced by the Linux kernel itself. diff --git a/content/manuals/security/for-admins/hardened-desktop/enhanced-container-isolation/how-eci-works.md b/content/manuals/security/for-admins/hardened-desktop/enhanced-container-isolation/how-eci-works.md index 8311006ffe2a..9b8c3b65fdcd 100644 --- a/content/manuals/security/for-admins/hardened-desktop/enhanced-container-isolation/how-eci-works.md +++ b/content/manuals/security/for-admins/hardened-desktop/enhanced-container-isolation/how-eci-works.md @@ -12,9 +12,6 @@ container runtime](https://github.com/nestybox/sysbox). Sysbox is a fork of the standard OCI runc runtime that was modified to enhance standard container isolation and workloads. For more details see [Under the hood](#under-the-hood). -Starting with version 4.13, Docker Desktop includes a customized version of -Sysbox. - When [Enhanced Container Isolation is enabled](index.md#how-do-i-enable-enhanced-container-isolation), containers created by users through `docker run` or `docker create` are automatically launched using Sysbox instead of the standard OCI runc runtime. Users need not @@ -28,11 +25,10 @@ to breach the Docker Desktop Virtual Machine (VM) or other containers. > [!NOTE] > > When Enhanced Container Isolation is enabled in Docker Desktop, the Docker CLI -> "--runtime" flag is ignored. Docker's default runtime continues to be "runc", +> `--runtime` flag is ignored. Docker's default runtime continues to be `runc`, > but all user containers are implicitly launched with Sysbox. -Enhanced Container Isolation is not the same as Docker Engine's userns-remap -mode or Rootless Docker. This is explained further below. +Enhanced Container Isolation is not the same as [Docker Engine's userns-remap mode or Rootless Docker](#enhanced-container-isolation-versus-user-namespace-remapping). ### Under the hood @@ -42,23 +38,23 @@ Sysbox enhances container isolation by using techniques such as: * Restricting the container from mounting sensitive VM directories. * Vetting sensitive system-calls between the container and the Linux kernel. * Mapping filesystem user/group IDs between the container's user-namespace and the Linux VM. -* Emulating portions of the procfs and sysfs filesystems inside the container. +* Emulating portions of the `/proc` and `/sys` filesystems inside the container. Some of these are made possible by recent advances in the Linux kernel which Docker Desktop now incorporates. Sysbox applies these techniques with minimal functional or performance impact to containers. These techniques complement Docker's traditional container security mechanisms -such as using other Linux namespaces, cgroups, restricted Linux capabilities, -seccomp, and AppArmor. They add a strong layer of isolation between the +such as using other Linux namespaces, cgroups, restricted Linux Capabilities, +Seccomp, and AppArmor. They add a strong layer of isolation between the container and the Linux kernel inside the Docker Desktop VM. For more information, see [Key features and benefits](features-benefits.md). -### Enhanced Container Isolation vs Docker Userns-Remap Mode +### Enhanced Container Isolation versus user namespace remapping The Docker Engine includes a feature called [userns-remap mode](/engine/security/userns-remap/) -that enables the user-namespace in all containers. However it suffers from a few +that enables the user namespace in all containers. However it suffers from a few [limitations](/engine/security/userns-remap/) and it's not supported within Docker Desktop. @@ -70,16 +66,16 @@ exclusive user-namespace mappings per container automatically and adds several other [container isolation features](#under-the-hood) meant to secure Docker Desktop in organizations with stringent security requirements. -### Enhanced Container Isolation vs Rootless Docker +### Enhanced Container Isolation versus Rootless Docker -[Rootless Docker](/engine/security/rootless/) allows the Docker Engine, and by +[Rootless Docker](/engine/security/rootless/) lets Docker Engine, and by extension the containers, to run without root privileges natively on a Linux host. This -allows non-root users to install and run Docker natively on Linux. +lets non-root users to install and run Docker natively on Linux. Rootless Docker is not supported within Docker Desktop. While it's a valuable feature when running Docker natively on Linux, its value within Docker Desktop is reduced since Docker Desktop runs the Docker Engine within a Linux VM. That -is, Docker Desktop already allows non-root host users to run Docker and +is, Docker Desktop already lets non-root host users to run Docker and isolates the Docker Engine from the host using a virtual machine. Unlike Rootless Docker, Enhanced Container Isolation does not run Docker Engine diff --git a/content/manuals/security/for-admins/hardened-desktop/enhanced-container-isolation/limitations.md b/content/manuals/security/for-admins/hardened-desktop/enhanced-container-isolation/limitations.md index c167bf03bbeb..758e5389701d 100644 --- a/content/manuals/security/for-admins/hardened-desktop/enhanced-container-isolation/limitations.md +++ b/content/manuals/security/for-admins/hardened-desktop/enhanced-container-isolation/limitations.md @@ -8,14 +8,6 @@ weight: 50 ### ECI support for WSL -Prior to Docker Desktop 4.20, Enhanced Container Isolation (ECI) on -Windows hosts was only supported when Docker Desktop was configured to use -Hyper-V to create the Docker Desktop Linux VM. ECI was not supported when Docker -Desktop was configured to use Windows Subsystem for Linux (aka WSL). - -Starting with Docker Desktop 4.20, ECI is supported when Docker Desktop is -configured to use either Hyper-V or WSL 2. - > [!NOTE] > > Docker Desktop requires WSL 2 version 1.1.3.0 or later. To get the current @@ -23,29 +15,28 @@ configured to use either Hyper-V or WSL 2. > it returns a version number prior to 1.1.3.0, update WSL to the latest version > by typing `wsl --update` in a Windows command or PowerShell terminal. -Note however that ECI on WSL is not as secure as on Hyper-V because: +ECI on WSL is not as secure as on Hyper-V because: -* While ECI on WSL still hardens containers so that malicious workloads can't +- While ECI on WSL still hardens containers so that malicious workloads can't easily breach Docker Desktop's Linux VM, ECI on WSL can't prevent Docker Desktop users from breaching the Docker Desktop Linux VM. Such users can trivially access that VM (as root) with the `wsl -d docker-desktop` command, and use that access to modify Docker Engine settings inside the VM. This gives - Docker Desktop users control of the Docker Desktop VM and allows them to - bypass Docker Desktop configs set by admins via the + Docker Desktop users control of the Docker Desktop VM and lets them bypass Docker Desktop configs set by administrators via the [settings-management](../settings-management/_index.md) feature. In contrast, - ECI on Hyper-V does not allow Docker Desktop users to breach the Docker + ECI on Hyper-V does not let Docker Desktop users to breach the Docker Desktop Linux VM. -* With WSL 2, all WSL 2 distributions on the same Windows host share the same instance +- With WSL 2, all WSL 2 distributions on the same Windows host share the same instance of the Linux kernel. As a result, Docker Desktop can't ensure the integrity of the kernel in the Docker Desktop Linux VM since another WSL 2 distribution could modify shared kernel settings. In contrast, when using Hyper-V, the Docker Desktop Linux VM has a dedicated kernel that is solely under the control of Docker Desktop. -The table below summarizes this. +The following table summarizes this. -| Security Feature | ECI on WSL | ECI on Hyper-V | Comment | +| Security feature | ECI on WSL | ECI on Hyper-V | Comment | | -------------------------------------------------- | ------------ | ---------------- | --------------------- | | Strongly secure containers | Yes | Yes | Makes it harder for malicious container workloads to breach the Docker Desktop Linux VM and host. | | Docker Desktop Linux VM protected from user access | No | Yes | On WSL, users can access Docker Engine directly or bypass Docker Desktop security settings. | @@ -54,26 +45,20 @@ The table below summarizes this. In general, using ECI with Hyper-V is more secure than with WSL 2. But WSL 2 offers advantages for performance and resource utilization on the host machine, and it's an excellent way for users to run their favorite Linux distribution on -Windows hosts and access Docker from within (see Docker Desktop's WSL distribution -integration feature, enabled via the Dashboard's **Settings** > **Resources** > **WSL Integration**). +Windows hosts and access Docker from within. -### ECI protection for Docker Builds with the "Docker" driver +### ECI protection for Docker builds with the "docker" driver Prior to Docker Desktop 4.30, `docker build` commands that use the buildx -`docker` driver (the default) are not protected by ECI (i.e., the build runs -rootful inside the Docker Desktop VM). +`docker` driver (the default) are not protected by ECI, in other words the build runs +rootful inside the Docker Desktop VM. Starting with Docker Desktop 4.30, `docker build` commands that use the buildx -`docker` driver are protected by ECI (i.e., the build runs rootless inside -the Docker Desktop VM), except when Docker Desktop is configured to use WSL 2 -(on Windows hosts). We expect to improve on this in future versions of Docker -Desktop. +`docker` driver are protected by ECI, except when Docker Desktop is configured to use WSL 2 +(on Windows hosts). Note that `docker build` commands that use the `docker-container` driver are -always protected by ECI (i.e., the build runs inside a rootless Docker -container). This is true since Docker Desktop 4.19 (when ECI was introduced) and -on all platforms where Docker Desktop is supported (Windows with WSL or Hyper-V, -Mac, and Linux). +always protected by ECI. ### Docker Build and Buildx have some restrictions @@ -98,17 +83,15 @@ arrangements are needed, just enable ECI and run the KinD tool as usual. Extension containers are also not yet protected by ECI. Ensure you extension containers come from trusted entities to avoid issues. -### Docker Desktop dev environments are not yet protected +### Docker Desktop Dev Environments are not yet protected Containers launched by the Docker Desktop Dev Environments feature are not yet -protected either. We expect to improve on this in future versions of Docker -Desktop. +protected. ### Docker Debug containers are not yet protected [Docker Debug](https://docs.docker.com/reference/cli/docker/debug/) containers -are not yet protected by ECI. We expect to improve on this in future versions of -Docker Desktop. +are not yet protected by ECI. ### Native Windows containers are not supported diff --git a/content/manuals/subscription/_index.md b/content/manuals/subscription/_index.md index 5dd811215130..906eca32b382 100644 --- a/content/manuals/subscription/_index.md +++ b/content/manuals/subscription/_index.md @@ -1,8 +1,10 @@ --- title: Subscription -weight: 200 description: Learn about subscription features and how to manage your subscription keywords: Docker, pricing, billing, Pro, Team, business, subscription, tier, plan +params: + sidebar: + group: Platform grid_subscriptions: - title: Docker Core subscriptions and features description: Explore what you can do with your Docker subscription. diff --git a/content/manuals/tcc.md b/content/manuals/tcc.md index a89e26d1252b..242eb05bf6e2 100644 --- a/content/manuals/tcc.md +++ b/content/manuals/tcc.md @@ -1,7 +1,8 @@ --- title: Testcontainers Cloud -weight: 200 +weight: 70 params: sidebar: + group: Products goto: "https://testcontainers.com/cloud/docs/" --- diff --git a/content/manuals/trusted-content/_index.md b/content/manuals/trusted-content/_index.md index cf8ffc177cd4..4fa05af44256 100644 --- a/content/manuals/trusted-content/_index.md +++ b/content/manuals/trusted-content/_index.md @@ -1,8 +1,10 @@ --- title: Trusted content -weight: 200 description: Optimize your development workflow with secure base images from our selection of trusted content keywords: doi, dvp, dsos, open source, security, base images +params: + sidebar: + group: Platform grid: - title: Docker Official Images description: A curated set of Docker repositories hosted on Docker Hub. diff --git a/go.mod b/go.mod index 491345ccc8ef..a31fba6d9ac3 100644 --- a/go.mod +++ b/go.mod @@ -5,7 +5,7 @@ go 1.23.1 require ( github.com/docker/buildx v0.19.1 // indirect github.com/docker/cli v27.4.0-rc.2+incompatible // indirect - github.com/docker/compose/v2 v2.30.3 // indirect + github.com/docker/compose/v2 v2.31.0 // indirect github.com/docker/scout-cli v1.15.0 // indirect github.com/moby/buildkit v0.18.0 // indirect github.com/moby/moby v27.3.1+incompatible // indirect @@ -14,7 +14,7 @@ require ( replace ( github.com/docker/buildx => github.com/docker/buildx v0.19.1 github.com/docker/cli => github.com/docker/cli v27.3.2-0.20241107125754-eb986ae71b0c+incompatible - github.com/docker/compose/v2 => github.com/docker/compose/v2 v2.30.3 + github.com/docker/compose/v2 => github.com/docker/compose/v2 v2.31.0 github.com/docker/scout-cli => github.com/docker/scout-cli v1.15.0 github.com/moby/buildkit => github.com/moby/buildkit v0.18.0 github.com/moby/moby => github.com/moby/moby v27.3.1+incompatible diff --git a/go.sum b/go.sum index 9fcba6476bfb..414887bca944 100644 --- a/go.sum +++ b/go.sum @@ -184,6 +184,8 @@ github.com/docker/compose/v2 v2.30.2 h1:7PypFsyl5wjlSeOyx3LCb8XMcAGkb+D0fqM47OIK github.com/docker/compose/v2 v2.30.2/go.mod h1:ND4+yaNoJ3Jh1OgrEO64uzMq/VKRqBkMS8zpb65Fve8= github.com/docker/compose/v2 v2.30.3 h1:e8H7xGLCZOeFo46GEtyDGHlkBbNgXqbXKIXPOSL8cfU= github.com/docker/compose/v2 v2.30.3/go.mod h1:ayPsSsRSc5WpVFehPrTDFuljAydxaf8g0aM9UKbaMXk= +github.com/docker/compose/v2 v2.31.0 h1:8Sm0c4MjIhksguxIA5koYMXoTJDAp/CaZ1cdZrMvMdw= +github.com/docker/compose/v2 v2.31.0/go.mod h1:oQq3UDEdsnB3AUO72AxaoeLbkCgmUu1+8tLzvmphmXA= github.com/docker/distribution v2.8.2+incompatible h1:T3de5rq0dB1j30rp0sA2rER+m322EBzniBPB6ZIzuh8= github.com/docker/distribution v2.8.2+incompatible/go.mod h1:J2gT2udsDAN96Uj4KfcMRqY0/ypR+oyYUYmja8H+y+w= github.com/docker/distribution v2.8.3+incompatible h1:AtKxIZ36LoNK51+Z6RpzLpddBirtxJnzDrHLEKxTAYk= diff --git a/hugo_stats.json b/hugo_stats.json index dde209194f37..0cc860b06650 100644 --- a/hugo_stats.json +++ b/hugo_stats.json @@ -515,6 +515,7 @@ "transition", "truncate", "underline-offset-2", + "uppercase", "w-2", "w-8", "w-[1200px]", diff --git a/layouts/partials/sidebar/sections.html b/layouts/partials/sidebar/sections.html index fff61376a828..988c4557eeef 100644 --- a/layouts/partials/sidebar/sections.html +++ b/layouts/partials/sidebar/sections.html @@ -2,7 +2,6 @@