diff --git a/Dockerfile b/Dockerfile index 63fb421190..b133731198 100644 --- a/Dockerfile +++ b/Dockerfile @@ -30,8 +30,8 @@ COPY . ${SOURCE} ## To get master from svn the svn branch needs to be 'trunk'. To get a branch from svn it needs to be 'branches/branchname' # Engine -ENV ENGINE_SVN_BRANCH="branches/17.09.x" -ENV ENGINE_BRANCH="17.09.x" +ENV ENGINE_SVN_BRANCH="branches/18.09.x" +ENV ENGINE_BRANCH="18.09.x" # Distribution ENV DISTRIBUTION_SVN_BRANCH="branches/release/2.6" @@ -80,6 +80,7 @@ COPY --from=docs/docker.github.io:v17.03 ${TARGET} ${TARGET} COPY --from=docs/docker.github.io:v17.06 ${TARGET} ${TARGET} COPY --from=docs/docker.github.io:v17.09 ${TARGET} ${TARGET} COPY --from=docs/docker.github.io:v17.12 ${TARGET} ${TARGET} +COPY --from=docs/docker.github.io:v18.03 ${TARGET} ${TARGET} # Get the built docs output from the previous build stage # This ordering means all previous layers can come from cache unless an archive diff --git a/README.md b/README.md index f6c9bacd60..c54fc72817 100644 --- a/README.md +++ b/README.md @@ -309,6 +309,13 @@ instance. Be sure to compress the images *before* adding them to the repository, doing it afterwards actually worsens the impact on the Git repo (but still optimizes the bandwidth during browsing). +## Beta content disclaimer +```bash +> BETA DISCLAIMER +> +> This is beta content. It is not yet complete and should be considered a work in progress. This content is subject to change without notice. +``` + ## Building archives and the live published docs All the images described below are automatically built using Docker Hub. To diff --git a/_config.yml b/_config.yml index a280a272b0..d10163795a 100644 --- a/_config.yml +++ b/_config.yml @@ -13,26 +13,28 @@ safe: false lsi: false url: https://docs.docker.com # This needs to have all the directories you expect to be in the archives (delivered by docs-base in the Dockerfile) -keep_files: ["v1.4", "v1.5", "v1.6", "v1.7", "v1.8", "v1.9", "v1.10", "v1.11", "v1.12", "v1.13", "v17.03", "v17.06", "v17.09", "v17.12"] +keep_files: ["v1.4", "v1.5", "v1.6", "v1.7", "v1.8", "v1.9", "v1.10", "v1.11", "v1.12", "v1.13", "v17.03", "v17.06", "v17.09", "v17.12", "v18.03"] exclude: ["_scripts", "apidocs/layouts", "Gemfile", "hooks"] # Component versions -- address like site.docker_ce_stable_version # You can't have - characters in these for non-YAML reasons -latest_stable_docker_engine_api_version: "1.37" -docker_ce_stable_version: "18.03" -docker_ce_edge_version: "18.05" -docker_ee_version: "17.06" +latest_stable_docker_engine_api_version: "1.39" +docker_ce_stable_version: "18.09" +docker_ce_edge_version: "18.09" +docker_ee_version: "2.1" compose_version: "1.23.1" -machine_version: "0.14.0" +machine_version: "0.16.0" distribution_version: "2.6" -dtr_version: "2.5" -ucp_version: "3.0" +dtr_version: "2.6" +ucp_version: "3.1" ucp_versions: - - version: "3.0" + - version: "3.1" path: /ee/ucp/ latest: true + - version: "3.0" + path: /datacenter/ucp/3.0/guides/ - version: "2.2" path: /datacenter/ucp/2.2/guides/ - version: "2.1" @@ -43,9 +45,11 @@ ucp_versions: path: /datacenter/ucp/1.1/overview/ dtr_versions: - - version: "2.5" + - version: "2.6" path: /ee/dtr/ latest: true + - version: "2.5" + path: /datacenter/dtr/2.5/guides/ - version: "2.4" path: /datacenter/dtr/2.4/guides/ - version: "2.3" @@ -58,7 +62,7 @@ dtr_versions: path: /datacenter/dtr/2.0/ tablabels: - dee-2.0: Docker Enterprise Edition 2.0 Beta2 + dee-2.0: Docker Enterprise Edition 2.0 ucp-3.0: Universal Control Plane 3.0 ucp-2.2: Universal Control Plane 2.2 dtr-2.5: Docker Trusted Registry 2.5 @@ -80,8 +84,7 @@ plugins: - jekyll-sitemap defaults: - - - scope: + - scope: path: "" type: "pages" values: @@ -100,6 +103,13 @@ defaults: - scope: path: "ee/dtr" values: + dtr_org: "docker" + dtr_repo: "dtr" + dtr_version: "2.6.0" + - scope: + path: "datacenter/dtr/2.5" + values: + hide_from_sitemap: true dtr_org: "docker" dtr_repo: "dtr" dtr_version: "2.5.6" @@ -138,16 +148,23 @@ defaults: values: ucp_org: "docker" ucp_repo: "ucp" - ucp_version: "3.0.6" + ucp_version: "3.1.0" - scope: # This is a bit of a hack for the get-support.md topic. path: "ee" values: ucp_org: "docker" ucp_repo: "ucp" dtr_repo: "dtr" + ucp_version: "3.1.0" + dtr_version: "2.6.0" + dtr_latest_image: "docker/dtr:2.6.0" + - scope: + path: "datacenter/ucp/3.0" + values: + hide_from_sitemap: true + ucp_org: "docker" + ucp_repo: "ucp" ucp_version: "3.0.6" - dtr_version: "2.5.0" - dtr_latest_image: "docker/dtr:2.5.6" - scope: path: "datacenter/ucp/2.2" values: diff --git a/_data/ddc_offline_files_2.yaml b/_data/ddc_offline_files_2.yaml index 3ff6d9e6fd..8032b1e1ce 100644 --- a/_data/ddc_offline_files_2.yaml +++ b/_data/ddc_offline_files_2.yaml @@ -3,6 +3,17 @@ # environment that can't access the internet # Used by _includes/components/ddc_url_list_2.html +- product: "ucp" + version: "3.1" + tar-files: + - description: "3.1.0 Linux" + url: https://packages.docker.com/caas/ucp_images_3.1.0.tar.gz + - description: "3.1.0 Windows Server 2016 LTSC" + url: https://packages.docker.com/caas/ucp_images_win_2016_3.1.0.tar.gz + - description: "3.1.0 Windows Server 1709" + url: https://packages.docker.com/caas/ucp_images_win_1709_3.1.0.tar.gz + - description: "3.1.0 Windows Server 1803" + url: https://packages.docker.com/caas/ucp_images_win_1803_3.1.0.tar.gz - product: "ucp" version: "3.0" tar-files: @@ -74,19 +85,19 @@ - description: "2.2.13 IBM Z" url: https://packages.docker.com/caas/ucp_images_s390x_2.2.13.tar.gz - description: "2.2.13 Windows" - url: https://packages.docker.com/caas/ucp_images_win_2.2.13.tar.gz + url: https://packages.docker.com/caas/ucp_images_win_2.2.13.tar.gz - description: "2.2.12 Linux" url: https://packages.docker.com/caas/ucp_images_2.2.12.tar.gz - description: "2.2.12 IBM Z" url: https://packages.docker.com/caas/ucp_images_s390x_2.2.12.tar.gz - description: "2.2.12 Windows" - url: https://packages.docker.com/caas/ucp_images_win_2.2.12.tar.gz + url: https://packages.docker.com/caas/ucp_images_win_2.2.12.tar.gz - description: "2.2.11 Linux" url: https://packages.docker.com/caas/ucp_images_2.2.11.tar.gz - description: "2.2.11 IBM Z" url: https://packages.docker.com/caas/ucp_images_s390x_2.2.11.tar.gz - description: "2.2.11 Windows" - url: https://packages.docker.com/caas/ucp_images_win_2.2.11.tar.gz + url: https://packages.docker.com/caas/ucp_images_win_2.2.11.tar.gz - description: "2.2.10 Linux" url: https://packages.docker.com/caas/ucp_images_2.2.10.tar.gz - description: "2.2.10 IBM Z" @@ -141,6 +152,11 @@ url: https://packages.docker.com/caas/ucp_images_s390x_2.2.0.tar.gz - description: "2.2.0 Windows" url: https://packages.docker.com/caas/ucp_images_win_2.2.0.tar.gz +- product: "dtr" + version: "2.6" + tar-files: + - description: "DTR 2.6.0 Linux x86" + url: https://packages.docker.com/caas/dtr_images_2.6.0.tar.gz - product: "dtr" version: "2.5" tar-files: @@ -193,9 +209,9 @@ version: "2.3" tar-files: - description: "DTR 2.3.9" - url: https://packages.docker.com/caas/dtr_images_2.3.9.tar.gz + url: https://packages.docker.com/caas/dtr_images_2.3.9.tar.gz - description: "DTR 2.3.8" - url: https://packages.docker.com/caas/dtr_images_2.3.8.tar.gz + url: https://packages.docker.com/caas/dtr_images_2.3.8.tar.gz - description: "DTR 2.3.7" url: https://packages.docker.com/caas/dtr_images_2.3.7.tar.gz - description: "DTR 2.3.6" @@ -212,3 +228,4 @@ url: https://packages.docker.com/caas/dtr-2.3.1.tar.gz - description: "DTR 2.3.0" url: https://packages.docker.com/caas/dtr-2.3.0.tar.gz + diff --git a/_data/docsarchive/archives.yaml b/_data/docsarchive/archives.yaml index f51b6dcf94..3069fd3570 100644 --- a/_data/docsarchive/archives.yaml +++ b/_data/docsarchive/archives.yaml @@ -1,5 +1,5 @@ - archive: - name: v18.03 + name: v18.09 image: docs/docker.github.io:latest current: true # When you make a new stable archive version, move the edge one to be second in @@ -7,6 +7,9 @@ - archive: name: edge image: docs/docker.github.io:latest +- archive: + name: v18.03 + image: docs/docker.github.io:v18.03 - archive: name: v17.12 image: docs/docker.github.io:v17.12 diff --git a/_data/toc.yaml b/_data/toc.yaml index 29cf6a81cf..e744cc5aec 100644 --- a/_data/toc.yaml +++ b/_data/toc.yaml @@ -124,7 +124,7 @@ guides: - path: /toolbox/faqs/troubleshoot/ title: Troubleshooting - title: Release notes - path: /release-notes/docker-ce/ + path: /engine/release-notes/ nosync: true - sectiontitle: Docker EE section: @@ -145,10 +145,12 @@ guides: - path: /install/windows/docker-ee/ title: Microsoft Windows Server - title: Release notes - path: /ee/engine/release-notes/ + path: /engine/release-notes/ nosync: true - sectiontitle: Compatibility between Docker versions section: + - path: /engine/ce-ee-node-activate/ + title: CE-EE Node Activate - path: /engine/migration/ title: Migrate to Docker 1.10 - path: /engine/breaking_changes/ @@ -187,6 +189,8 @@ guides: title: Best practices for writing Dockerfiles - path: /develop/develop-images/baseimages/ title: Create a base image + - path: /develop/develop-images/build_enhancements/ + title: Docker build enhancements for 18.09 - path: /develop/develop-images/multistage-build/ title: Use multi-stage builds - path: /engine/reference/builder/ @@ -1295,53 +1299,53 @@ reference: nosync: true - sectiontitle: DTR CLI section: - - path: /reference/dtr/2.5/cli/ + - path: /reference/dtr/2.6/cli/ title: Overview - - path: /reference/dtr/2.5/cli/backup/ + - path: /reference/dtr/2.6/cli/backup/ title: backup - - path: /reference/dtr/2.5/cli/destroy/ + - path: /reference/dtr/2.6/cli/destroy/ title: destroy - - path: /reference/dtr/2.5/cli/emergency-repair/ + - path: /reference/dtr/2.6/cli/emergency-repair/ title: emergency-repair - - path: /reference/dtr/2.5/cli/install/ + - path: /reference/dtr/2.6/cli/install/ title: install - - path: /reference/dtr/2.5/cli/join/ + - path: /reference/dtr/2.6/cli/join/ title: join - - path: /reference/dtr/2.5/cli/reconfigure/ + - path: /reference/dtr/2.6/cli/reconfigure/ title: reconfigure - - path: /reference/dtr/2.5/cli/remove/ + - path: /reference/dtr/2.6/cli/remove/ title: remove - - path: /reference/dtr/2.5/cli/restore/ + - path: /reference/dtr/2.6/cli/restore/ title: restore - - path: /reference/dtr/2.5/cli/upgrade/ + - path: /reference/dtr/2.6/cli/upgrade/ title: upgrade - sectiontitle: UCP CLI section: - - path: /reference/ucp/3.0/cli/ + - path: /reference/ucp/3.1/cli/ title: docker/ucp overview - - path: /reference/ucp/3.0/cli/backup/ + - path: /reference/ucp/3.1/cli/backup/ title: backup - - path: /reference/ucp/3.0/cli/dump-certs/ + - path: /reference/ucp/3.1/cli/dump-certs/ title: dump-certs - - path: /reference/ucp/3.0/cli/example-config/ + - path: /reference/ucp/3.1/cli/example-config/ title: example-config - - path: /reference/ucp/3.0/cli/id/ + - path: /reference/ucp/3.1/cli/id/ title: id - - path: /reference/ucp/3.0/cli/images/ + - path: /reference/ucp/3.1/cli/images/ title: images - - path: /reference/ucp/3.0/cli/install/ + - path: /reference/ucp/3.1/cli/install/ title: install - - path: /reference/ucp/3.0/cli/restart/ + - path: /reference/ucp/3.1/cli/restart/ title: restart - - path: /reference/ucp/3.0/cli/restore/ + - path: /reference/ucp/3.1/cli/restore/ title: restore - - path: /reference/ucp/3.0/cli/stop/ + - path: /reference/ucp/3.1/cli/stop/ title: stop - - path: /reference/ucp/3.0/cli/support/ + - path: /reference/ucp/3.1/cli/support/ title: support - - path: /reference/ucp/3.0/cli/uninstall-ucp/ + - path: /reference/ucp/3.1/cli/uninstall-ucp/ title: uninstall-ucp - - path: /reference/ucp/3.0/cli/upgrade/ + - path: /reference/ucp/3.1/cli/upgrade/ title: upgrade - sectiontitle: Application Programming Interfaces (APIs) @@ -1401,9 +1405,9 @@ reference: - path: /engine/api/v1.18/ title: v1.18 reference - title: DTR API - path: /reference/dtr/2.5/api/ + path: /reference/dtr/2.6/api/ - title: UCP API - path: /reference/ucp/3.0/api/ + path: /reference/ucp/3.1/api/ - title: Registry API path: /registry/spec/api/ nosync: true @@ -1520,7 +1524,7 @@ manuals: title: Install Docker EE Engine nosync: true - title: Release notes - path: /ee/engine/release-notes/ + path: /engine/release-notes/ - sectiontitle: Universal Control Plane section: - path: /ee/ucp/ @@ -1555,10 +1559,18 @@ manuals: title: Add labels to cluster nodes - path: /ee/ucp/admin/configure/add-sans-to-cluster/ title: Add SANs to cluster certificates + - path: /ee/ucp/admin/configure/collect-cluster-metrics/ + title: Collect UCP cluster metrics with Prometheus + - path: /ee/ucp/admin/configure/configure-rbac-kube/ + title: Configure native Kubernetes role-based access control + - path: /ee/ucp/admin/configure/create-audit-logs/ + title: Create UCP audit logs + - path: /ee/ucp/admin/configure/enable-saml-authentication/ + title: Enable SAML authentication + - path: /ee/ucp/admin/configure/enable-helm-tiller/ + title: Enable Helm and Tiller with UCP - path: /ee/ucp/admin/configure/external-auth/ title: Integrate with LDAP - - path: /ee/ucp/admin/configure/external-auth/enable-ldap-config-file/ - title: Integrate with LDAP by using a configuration file - path: /ee/ucp/admin/configure/license-your-installation/ title: License your installation - path: /ee/ucp/admin/configure/restrict-services-to-worker-nodes/ @@ -1610,7 +1622,7 @@ manuals: - path: /ee/ucp/admin/backups-and-disaster-recovery/ title: Backups and disaster recovery - title: CLI reference - path: /reference/ucp/3.0/cli/ + path: /reference/ucp/3.1/cli/ nosync: true - sectiontitle: Authorize role-based access section: @@ -1654,6 +1666,8 @@ manuals: title: CLI-based access - path: /ee/ucp/user-access/kubectl/ title: Install the Kubernetes CLI + - path: /ee/ucp/deploy-application-package + title: Deploy an application package - sectiontitle: Deploy apps with Swarm section: - title: Deploy a single service @@ -1708,6 +1722,8 @@ manuals: path: /ee/ucp/interlock/upgrade/ - sectiontitle: Deploy apps with Kubernetes section: + - title: Access Kubernetes Resources + path: /ee/ucp/kubernetes/kube-resources/ - title: Deploy a workload path: /ee/ucp/kubernetes/ - title: Deploy a Compose-based app @@ -1718,13 +1734,180 @@ manuals: path: /ee/ucp/kubernetes/create-service-account/ - title: Install a CNI plugin path: /ee/ucp/kubernetes/install-cni-plugin/ + - title: Kubernetes network encryption + path: /ee/ucp/kubernetes/kubernetes-network-encryption/ - title: API reference - path: /reference/ucp/3.0/api/ + path: /reference/ucp/3.1/api/ nosync: true - path: /ee/ucp/release-notes/ title: Release notes - sectiontitle: Previous versions section: + - sectiontitle: Universal Control Plane 3.0 + section: + - path: /datacenter/ucp/3.0/guides/ + title: Universal Control Plane overview + - path: /datacenter/ucp/3.0/guides/architecture/ + title: Architecture + - sectiontitle: Administration + section: + - sectiontitle: Install + section: + - path: /datacenter/ucp/3.0/guides/admin/install/system-requirements/ + title: System requirements + - path: /datacenter/ucp/3.0/guides/admin/install/plan-installation/ + title: Plan your installation + - path: /datacenter/ucp/3.0/guides/admin/install/ + title: Install + - path: /datacenter/ucp/3.0/guides/admin/install/install-offline/ + title: Install offline + - path: /datacenter/ucp/3.0/guides/admin/install/upgrade/ + title: Upgrade + - path: /datacenter/ucp/3.0/guides/admin/install/upgrade-offline/ + title: Upgrade offline + - path: /datacenter/ucp/3.0/guides/admin/install/uninstall/ + title: Uninstall + - path: /datacenter/ucp/3.0/guides/admin/install/architecture-specific-images/ + title: Architecture-specific images + - sectiontitle: Configure + section: + - path: /datacenter/ucp/3.0/guides/admin/configure/add-labels-to-cluster-nodes/ + title: Add labels to cluster nodes + - path: /datacenter/ucp/3.0/guides/admin/configure/add-sans-to-cluster/ + title: Add SANs to cluster certificates + - path: /datacenter/ucp/3.0/guides/admin/configure/join-windows-worker-nodes/ + title: Join Windows worker nodes to a swarm + - path: /datacenter/ucp/3.0/guides/admin/configure/integrate-with-dtr/ + title: Integrate with Docker Trusted Registry + - path: /datacenter/ucp/3.0/guides/admin/configure/external-auth/ + title: Integrate with LDAP + - path: /datacenter/ucp/3.0/guides/admin/configure/external-auth/enable-ldap-config-file/ + title: Integrate with LDAP by using a configuration file + - path: /datacenter/ucp/3.0/guides/admin/configure/license-your-installation/ + title: License your installation + - path: /datacenter/ucp/3.0/guides/admin/configure/restrict-services-to-worker-nodes/ + title: Restrict services to worker nodes + - path: /datacenter/ucp/3.0/guides/admin/configure/run-only-the-images-you-trust/ + title: Run only the images you trust + - path: /datacenter/ucp/3.0/guides/admin/configure/scale-your-cluster/ + title: Scale your cluster + - path: /datacenter/ucp/3.0/guides/admin/configure/set-session-timeout/ + title: Set the user's session timeout + - path: /datacenter/ucp/3.0/guides/admin/configure/set-up-high-availability/ + title: Set up high availability + - path: /datacenter/ucp/3.0/guides/admin/configure/store-logs-in-an-external-system/ + title: Store logs in an external system + - path: /datacenter/ucp/3.0/guides/admin/configure/ucp-configuration-file/ + title: UCP configuration file + - path: /datacenter/ucp/3.0/guides/admin/configure/use-a-load-balancer/ + title: Use a load balancer + - path: /datacenter/ucp/3.0/guides/admin/configure/use-node-local-network-in-swarm/ + title: Use a local node network in a swarm + - path: /datacenter/ucp/3.0/guides/admin/configure/use-domain-names-to-access-services/ + title: Use domain names to access services + - path: /datacenter/ucp/3.0/guides/admin/configure/use-your-own-tls-certificates/ + title: Use your own TLS certificates + - sectiontitle: Monitor and troubleshoot + section: + - path: /datacenter/ucp/3.0/guides/admin/monitor-and-troubleshoot/ + title: Monitor the cluster status + - path: /datacenter/ucp/3.0/admin/monitor-and-troubleshoot/troubleshoot-node-messages/ + title: Troubleshoot node messages + - path: /datacenter/ucp/3.0/guides/admin/monitor-and-troubleshoot/troubleshoot-with-logs/ + title: Troubleshoot with logs + - path: /datacenter/ucp/3.0/guides/admin/monitor-and-troubleshoot/troubleshoot-configurations/ + title: Troubleshoot configurations + - path: /datacenter/ucp/3.0/guides/admin/backups-and-disaster-recovery/ + title: Backups and disaster recovery + - sectiontitle: CLI reference + section: + - path: /datacenter/ucp/3.0/reference/cli/ + title: docker/ucp overview + - path: /datacenter/ucp/3.0/reference/cli/backup/ + title: backup + - path: /datacenter/ucp/3.0/reference/cli/dump-certs/ + title: dump-certs + - path: /datacenter/ucp/3.0/reference/cli/example-config/ + title: example-config + - path: /datacenter/ucp/3.0/reference/cli/id/ + title: id + - path: /datacenter/ucp/3.0/reference/cli/images/ + title: images + - path: /datacenter/ucp/3.0/reference/cli/install/ + title: install + - path: /datacenter/ucp/3.0/reference/cli/restart/ + title: restart + - path: /datacenter/ucp/3.0/reference/cli/restore/ + title: restore + - path: /datacenter/ucp/3.0/reference/cli/stop/ + title: stop + - path: /datacenter/ucp/3.0/reference/cli/support/ + title: support + - path: /datacenter/ucp/3.0/reference/cli/uninstall-ucp/ + title: uninstall-ucp + - path: /datacenter/ucp/3.0/reference/cli/upgrade/ + title: upgrade + - sectiontitle: Access control + section: + - path: /datacenter/ucp/3.0/guides/access-control/ + title: Access control model + - path: /datacenter/ucp/3.0/guides/access-control/create-and-manage-users/ + title: Create and manage users + - path: /datacenter/ucp/3.0/guides/access-control/create-and-manage-teams/ + title: Create and manage teams + - path: /datacenter/ucp/3.0/guides/access-control/deploy-view-only-service/ + title: Deploy a service with view-only access across an organization + - path: /datacenter/ucp/3.0/guides/access-control/grant-permissions/ + title: Grant permissions to users based on roles + - path: /datacenter/ucp/3.0/guides/access-control/isolate-nodes-between-teams/ + title: Isolate swarm nodes to a specific team + - path: /datacenter/ucp/3.0/guides/access-control/isolate-volumes-between-teams/ + title: Isolate volumes between two different teams + - path: /datacenter/ucp/3.0/guides/access-control/manage-access-with-collections/ + title: Manage access to resources by using collections + - path: /datacenter/ucp/3.0/guides/access-control/access-control-node/ + title: Node access control + - path: /datacenter/ucp/3.0/guides/access-control/permission-levels/ + title: Permission levels + - path: /datacenter/ucp/3.0/guides/access-control/access-control-design-ee-standard/ + title: Access control design with Docker EE Standard + - path: /datacenter/ucp/3.0/guides/access-control/access-control-design-ee-advanced/ + title: Access control design with Docker EE Advanced + - path: /datacenter/ucp/3.0/guides/access-control/recover-a-user-password/ + title: Recover a user password + - sectiontitle: User guides + section: + - sectiontitle: Access UCP + section: + - path: /datacenter/ucp/3.0/guides/user/access-ucp/ + title: Web-based access + - path: /datacenter/ucp/3.0/guides/user/access-ucp/cli-based-access/ + title: CLI-based access + - sectiontitle: Deploy an application + section: + - path: /datacenter/ucp/3.0/guides/user/services/deploy-a-service/ + title: Deploy a service + - path: /datacenter/ucp/3.0/guides/user/services/use-domain-names-to-access-services/ + title: Use domain names to access services + - path: /datacenter/ucp/3.0/guides/user/services/ + title: Deploy an app from the UI + - path: /datacenter/ucp/3.0/guides/user/services/deploy-app-cli/ + title: Deploy an app from the CLI + - path: /datacenter/ucp/3.0/guides/user/services/deploy-stack-to-collection/ + title: Deploy application resources to a collection + - sectiontitle: Secrets + section: + - path: /datacenter/ucp/3.0/guides/user/secrets/ + title: Manage secrets + - path: /datacenter/ucp/3.0/guides/user/secrets/grant-revoke-access/ + title: Grant access to secrets + - path: /datacenter/ucp/3.0/reference/api/ + title: API reference + - path: /ee/ucp/release-notes/ + title: Release notes + nosync: true + - path: /datacenter/ucp/3.0/guides/get-support/ + title: Get support - sectiontitle: Universal Control Plane 2.2 section: - path: /datacenter/ucp/2.2/guides/ @@ -2326,6 +2509,16 @@ manuals: title: Create and manage organizations - path: /ee/dtr/admin/manage-users/permission-levels/ title: Permission levels + - sectiontitle: Manage jobs + section: + - path: /ee/dtr/admin/manage-jobs/job-queue/ + title: Job Queue + - path: /ee/dtr/admin/manage-jobs/audit-jobs-via-ui/ + title: Audit Jobs with the Web Interface + - path: /ee/dtr/admin/manage-jobs/audit-jobs-via-api/ + title: Audit Jobs with the API + - path: /ee/dtr/admin/manage-jobs/auto-delete-job-logs/ + title: Enable Auto-Deletion of Job Logs - sectiontitle: Monitor and troubleshoot section: - path: /ee/dtr/admin/monitor-and-troubleshoot/ @@ -2334,8 +2527,6 @@ manuals: title: Check Notary audit logs - path: /ee/dtr/admin/monitor-and-troubleshoot/troubleshoot-with-logs/ title: Troubleshoot with logs - - path: /ee/dtr/admin/monitor-and-troubleshoot/troubleshoot-batch-jobs/ - title: Troubleshoot batch jobs - sectiontitle: Disaster recovery section: - title: Overview @@ -2349,7 +2540,7 @@ manuals: - title: Restore from a backup path: /ee/dtr/admin/disaster-recovery/restore-from-backup/ - title: CLI reference - path: /reference/dtr/2.5/cli/ + path: /reference/dtr/2.6/cli/ nosync: true - sectiontitle: User guides section: @@ -2365,6 +2556,8 @@ manuals: section: - path: /ee/dtr/user/manage-images/ title: Create a repository + - path: /ee/dtr/user/manage-images/review-repository-info/ + title: Review repository info - path: /ee/dtr/user/manage-images/pull-and-push-images/ title: Pull and push images - path: /ee/dtr/user/manage-images/delete-images/ @@ -2395,17 +2588,166 @@ manuals: path: /ee/dtr/user/promotion-policies/pull-mirror/ - title: Template reference path: /ee/dtr/user/promotion-policies/templates/ + - sectiontitle: Manage repository events + section: + - title: Audit repository events + path: /ee/dtr/user/audit-repository-events/ + - title: Auto-delete repository events + path: /ee/dtr/admin/configure/auto-delete-repo-events/ - path: /ee/dtr/user/create-and-manage-webhooks/ title: Create and manage webhooks - title: Manage access tokens path: /ee/dtr/user/access-tokens/ + - title: Tag pruning + path: /ee/dtr/user/tag-pruning/ - title: API reference - path: /reference/dtr/2.5/api/ + path: /reference/dtr/2.6/api/ nosync: true - path: /ee/dtr/release-notes/ title: Release notes - sectiontitle: Previous versions section: + - sectiontitle: Docker Trusted Registry 2.5 + section: + - path: /datacenter/dtr/2.5/guides/ + title: Docker Trusted Registry overview + - path: /datacenter/dtr/2.5/guides/architecture/ + title: Architecture + - sectiontitle: Administration + section: + - sectiontitle: Install + section: + - path: /datacenter/dtr/2.5/guides/admin/install/system-requirements/ + title: System requirements + - path: /datacenter/dtr/2.5/guides/admin/install/ + title: Install + - path: /datacenter/dtr/2.5/guides/admin/install/install-offline/ + title: Install offline + - path: /datacenter/dtr/2.5/guides/admin/upgrade/ + title: Upgrade + - path: /datacenter/dtr/2.5/guides/admin/install/uninstall/ + title: Uninstall + - sectiontitle: Configure + section: + - path: /datacenter/dtr/2.5/guides/admin/configure/license-your-installation/ + title: License your installation + - path: /datacenter/dtr/2.5/guides/admin/configure/use-your-own-tls-certificates/ + title: Use your own TLS certificates + - path: /datacenter/dtr/2.5/guides/admin/configure/enable-single-sign-on/ + title: Enable single sign-on + - sectiontitle: External storage + section: + - path: /datacenter/dtr/2.5/guides/admin/configure/external-storage/ + title: Overview + - path: /datacenter/dtr/2.5/guides/admin/configure/external-storage/s3/ + title: S3 + - path: /datacenter/dtr/2.5/guides/admin/configure/external-storage/nfs/ + title: NFS + - path: /datacenter/dtr/2.5/guides/admin/configure/set-up-high-availability/ + title: Set up high availability + - path: /datacenter/dtr/2.5/guides/admin/configure/use-a-load-balancer/ + title: Use a load balancer + - path: /datacenter/dtr/2.5/guides/admin/configure/set-up-vulnerability-scans/ + title: Set up vulnerability scans + - sectiontitle: Deploy caches + section: + - path: /datacenter/dtr/2.5/guides/admin/configure/deploy-caches/ + title: Overview + - path: /datacenter/dtr/2.5/guides/admin/configure/deploy-caches/tls/ + title: Deploy caches with TLS + - path: /datacenter/dtr/2.5/guides/admin/configure/deploy-caches/chaining/ + title: Chain multiple caches + - path: /datacenter/dtr/2.5/guides/admin/configure/garbage-collection/ + title: Garbage collection + - path: /datacenter/dtr/2.5/guides/admin/configure/use-a-web-proxy/ + title: Use a web proxy + - sectiontitle: Manage users + section: + - path: /datacenter/dtr/2.5/guides/admin/manage-users/ + title: Authentication and authorization + - path: /datacenter/dtr/2.5/guides/admin/manage-users/create-and-manage-users/ + title: Create and manage users + - path: /datacenter/dtr/2.5/guides/admin/manage-users/create-and-manage-teams/ + title: Create and manage teams + - path: /datacenter/dtr/2.5/guides/admin/manage-users/create-and-manage-orgs/ + title: Create and manage organizations + - path: /datacenter/dtr/2.5/guides/admin/manage-users/permission-levels/ + title: Permission levels + - sectiontitle: Monitor and troubleshoot + section: + - path: /datacenter/dtr/2.5/guides/admin/monitor-and-troubleshoot/ + title: Monitor the cluster status + - path: /datacenter/dtr/2.5/guides/admin/monitor-and-troubleshoot/notary-audit-logs/ + title: Check Notary audit logs + - path: /datacenter/dtr/2.5/guides/admin/monitor-and-troubleshoot/troubleshoot-with-logs/ + title: Troubleshoot with logs + - path: /datacenter/dtr/2.5/guides/admin/monitor-and-troubleshoot/troubleshoot-batch-jobs/ + title: Troubleshoot batch jobs + - path: /datacenter/dtr/2.5/guides/admin/backups-and-disaster-recovery/ + title: Backups and disaster recovery + - sectiontitle: CLI reference + section: + - path: /datacenter/dtr/2.5/reference/cli/ + title: Overview + - path: /datacenter/dtr/2.5/reference/cli/backup/ + title: backup + - path: /datacenter/dtr/2.5/reference/cli/destroy/ + title: destroy + - path: /datacenter/dtr/2.5/reference/cli/images/ + title: images + - path: /datacenter/dtr/2.5/reference/cli/install/ + title: install + - path: /datacenter/dtr/2.5/reference/cli/join/ + title: join + - path: /datacenter/dtr/2.5/reference/cli/reconfigure/ + title: reconfigure + - path: /datacenter/dtr/2.5/reference/cli/remove/ + title: remove + - path: /datacenter/dtr/2.5/reference/cli/restore/ + title: restore + - path: /datacenter/dtr/2.5/reference/cli/upgrade/ + title: upgrade + - sectiontitle: User guides + section: + - sectiontitle: Access DTR + section: + - path: /datacenter/dtr/2.5/guides/user/access-dtr/ + title: Configure your Docker daemon + - path: /datacenter/dtr/2.5/guides/user/access-dtr/configure-your-notary-client/ + title: Configure your Notary client + - path: /datacenter/dtr/2.5/guides/user/access-dtr/use-a-cache/ + title: Use a cache + - sectiontitle: Manage images + section: + - path: /datacenter/dtr/2.5/guides/user/manage-images/ + title: Create a repository + - path: /datacenter/dtr/2.5/guides/user/manage-images/pull-and-push-images/ + title: Pull and push images + - path: /datacenter/dtr/2.5/guides/user/manage-images/delete-images/ + title: Delete images + - path: /datacenter/dtr/2.5/guides/user/manage-images/scan-images-for-vulnerabilities/ + title: Scan images for vulnerabilities + - path: /datacenter/dtr/2.5/guides/user/manage-images/prevent-tags-from-being-overwritten/ + title: Prevent tags from being overwritten + - sectiontitle: Sign images + section: + - path: /datacenter/dtr/2.5/guides/user/manage-images/sign-images/ + title: Sign an image + - path: /datacenter/dtr/2.5/guides/user/manage-images/sign-images/delegate-image-signing/ + title: Delegate image signing + - path: /datacenter/dtr/2.5/guides/user/manage-images/sign-images/manage-trusted-repositories/ + title: Manage trusted repositories + - path: /datacenter/dtr/2.5/guides/user/create-and-manage-webhooks/ + title: Create and manage webhooks + - path: /datacenter/dtr/2.5/guides/user/create-promotion-policies/ + title: Create promotion policies + - path: /datacenter/dtr/2.5/reference/api/ + title: API reference + - path: /ee/dtr/release-notes/ + title: Release notes + nosync: true + - path: /datacenter/dtr/2.5/guides/support/ + title: Get support - sectiontitle: Docker Trusted Registry 2.4 section: - path: /datacenter/dtr/2.4/guides/ @@ -3427,11 +3769,9 @@ manuals: section: - path: /release-notes/ title: Overview - - path: /ee/engine/release-notes/ - title: Docker EE + - path: /engine/release-notes/ + title: Docker EE and CE nosync: true - - path: /release-notes/docker-ce/ - title: Docker CE - path: /cs-engine/1.13/release-notes/ title: CS Docker Engine nosync: true diff --git a/_includes/docker_ce_ee.md b/_includes/docker_ce_ee.md index a70e3da450..7549036074 100644 --- a/_includes/docker_ce_ee.md +++ b/_includes/docker_ce_ee.md @@ -1,9 +1,9 @@ {% assign green-check = '![yes](/install/images/green-check.svg){: style="height: 14px; margin: 0 auto"}' %} -| Capabilities | Community Edition | Enterprise Edition Basic | Enterprise Edition Standard | Enterprise Edition Advanced | -|:------------------------------------------------------------------|:------------------|:-------------------------|:----------------------------|:----------------------------| -| Container engine and built in orchestration, networking, security | {{green-check}} | {{green-check}} | {{green-check}} | {{green-check}} | -| Certified infrastructure, plugins and ISV containers | | {{green-check}} | {{green-check}} | {{green-check}} | -| Image management | | | {{green-check}} | {{green-check}} | -| Container app management | | | {{green-check}} | {{green-check}} | -| Image security scanning | | | | {{green-check}} | +| Capabilities | Docker Engine - Community | Docker Engine - Enterprise | Docker Enterprise | +|:---------------------------------------------------------------------|:------------------:|:-------------------------:|:----------------------------:| +| Container engine and built in orchestration, networking, security | {{green-check}} | {{green-check}} | {{green-check}} | +| Certified infrastructure, plugins and ISV containers | | {{green-check}} | {{green-check}} | +| Image management | | | {{green-check}} | +| Container app management | | | {{green-check}} | +| Image security scanning | | | {{green-check}} | diff --git a/_includes/ee-linux-install-reuse.md b/_includes/ee-linux-install-reuse.md index 896115fc79..38aa83ed50 100644 --- a/_includes/ee-linux-install-reuse.md +++ b/_includes/ee-linux-install-reuse.md @@ -137,20 +137,12 @@ You only need to set up the repository once, after which you can install Docker {% elsif section == "install-using-yum-repo" %} -There are currently two versions of Docker EE Engine available: +> ***NOTE:*** If you need to run Docker EE 2.0, please see the following instructions: +> * [18.03](https://docs.docker.com/v18.03/ee/supported-platforms/) - Older Docker EE Engine only release +> * [17.06](https://docs.docker.com/v17.06/engine/installation/) - Docker Enterprise Edition 2.0 (Docker Engine, +> UCP, and DTR). -* 18.03 - Use this version if you're only running Docker EE Engine. -* 17.06 - Use this version if you're using Docker Enterprise Edition 2.0 (Docker -Engine, UCP, and DTR). - -1. By default, Docker EE Engine 17.06 is installed. If you want to install the -18.03 version run: - - ```bash - sudo yum-config-manager --enable docker-ee-stable-18.03 - ``` - -2. Install the latest patch release, or go to the next step to install a specific version: +1. Install the latest patch release, or go to the next step to install a specific version: ```bash $ sudo yum -y install docker-ee @@ -158,27 +150,34 @@ Engine, UCP, and DTR). If prompted to accept the GPG key, verify that the fingerprint matches `{{ gpg-fingerprint }}`, and if so, accept it. -3. To install a _specific version_ of Docker EE (recommended in production), list versions and install: + +2. To install a _specific version_ of Docker EE (recommended in production), list versions and install: a. List and sort the versions available in your repo. This example sorts results by version number, highest to lowest, and is truncated: ```bash $ sudo yum list docker-ee --showduplicates | sort -r - docker-ee.x86_64 {{ site.docker_ee_version }}.ee.2-1.el7.{{ linux-dist }} docker-ee-stable-17.06 + docker-ee.x86_64 {{ site.docker_ee_version }}.ee.2-1.el7.{{ linux-dist }} docker-ee-stable-18.09 ``` The list returned depends on which repositories you enabled, and is specific to your version of {{ linux-dist-long }} (indicated by `.el7` in this example). - b. Install a specific version by its **fully qualified package name** which is the package name (`docker-ee`) plus the version string (2nd column) up to the hyphen, for example: `docker-ee-17.06.1.ee.2` + b. Install a specific version by its **fully qualified package name** which is the package name (`docker-ee`) plus the version string (2nd column) up to the hyphen, for example: `docker-ee-18.09.0` ```bash $ sudo yum -y install ``` + For example, if you want to install the 18.09 version run the following: + + ```bash + sudo yum-config-manager --enable docker-ee-stable-18.09.0 + ``` + Docker is installed but not started. The `docker` group is created, but no users are added to the group. -4. Start Docker: +3. Start Docker: > If using `devicemapper`, ensure it is properly configured before starting Docker, per the [storage guide](/storage/storagedriver/device-mapper-driver/){: target="_blank" class="_" }. @@ -186,7 +185,7 @@ Engine, UCP, and DTR). $ sudo systemctl start docker ``` -5. Verify that Docker EE is installed correctly by running the `hello-world` +4. Verify that Docker EE is installed correctly by running the `hello-world` image. This command downloads a test image, runs it in a container, prints an informational message, and exits: diff --git a/_scripts/fetch-upstream-resources.sh b/_scripts/fetch-upstream-resources.sh index 22569faa4d..207fcffade 100755 --- a/_scripts/fetch-upstream-resources.sh +++ b/_scripts/fetch-upstream-resources.sh @@ -67,9 +67,9 @@ done < <(cat ${SOURCE}/_config.yml |grep '_version:' |grep '^[a-z].*') sedi "s/{{ site.latest_stable_docker_engine_api_version }}/$latest_stable_docker_engine_api_version/g" ${SOURCE}/_data/toc.yaml # Engine stable -ENGINE_SVN_BRANCH="branches/18.03" -ENGINE_BRANCH="18.03" -ENGINE_EDGE_BRANCH="18.05" +ENGINE_SVN_BRANCH="branches/18.09" +ENGINE_BRANCH="18.09" +ENGINE_EDGE_BRANCH="18.09" # Distribution DISTRIBUTION_SVN_BRANCH="branches/release/2.6" @@ -147,6 +147,8 @@ wget -O ${SOURCE}/engine/api/v1.34/swagger.yaml https://raw.githubusercontent.co wget -O ${SOURCE}/engine/api/v1.35/swagger.yaml https://raw.githubusercontent.com/docker/docker-ce/17.12/components/engine/api/swagger.yaml || (echo "Failed 1.35 swagger download or the 1.35 directory doesn't exist" && exit -1) wget -O ${SOURCE}/engine/api/v1.36/swagger.yaml https://raw.githubusercontent.com/docker/docker-ce/18.02/components/engine/api/swagger.yaml || (echo "Failed 1.36 swagger download or the 1.36 directory doesn't exist" && exit -1) wget -O ${SOURCE}/engine/api/v1.37/swagger.yaml https://raw.githubusercontent.com/docker/docker-ce/18.03/components/engine/api/swagger.yaml || (echo "Failed 1.37 swagger download or the 1.37 directory doesn't exist" && exit -1) +wget -O ${SOURCE}/engine/api/v1.38/swagger.yaml https://raw.githubusercontent.com/docker/docker-ce/18.06/components/engine/api/swagger.yaml || (echo "Failed 1.38 swagger download or the 1.38 directory doesn't exist" && exit -1) +wget -O ${SOURCE}/engine/api/v1.39/swagger.yaml https://raw.githubusercontent.com/docker/docker-ce/18.09/components/engine/api/swagger.yaml || (echo "Failed 1.39 swagger download or the 1.39 directory doesn't exist" && exit -1) # Get dockerd.md for stable and edge, from upstream wget -O ${SOURCE}/engine/reference/commandline/dockerd.md https://raw.githubusercontent.com/docker/docker-ce/"$ENGINE_BRANCH"/components/cli/docs/reference/commandline/dockerd.md || (echo "Failed to fetch stable dockerd.md" && exit -1) diff --git a/compose/rails.md b/compose/rails.md index 19d96dd112..d3f071f78a 100644 --- a/compose/rails.md +++ b/compose/rails.md @@ -9,10 +9,7 @@ a Rails/PostgreSQL app. Before starting, [install Compose](install.md). ### Define the project -Start by setting up the four files needed to build the app. First, since -your app is going to run inside a Docker container containing all of its -dependencies, define exactly what needs to be included in the -container. This is done using a file called `Dockerfile`. To begin with, the +Start by setting up the four files needed to build the app. App will run inside a Docker container containing its dependencies. Defining dependencies is done using a file called `Dockerfile`. To begin with, the Dockerfile consists of: FROM ruby:2.5 diff --git a/config/thirdparty/prometheus.md b/config/thirdparty/prometheus.md index bfce2007bf..5eb6fd560d 100644 --- a/config/thirdparty/prometheus.md +++ b/config/thirdparty/prometheus.md @@ -17,6 +17,7 @@ container, and monitor your Docker instance using Prometheus. Currently, you can only monitor Docker itself. You cannot currently monitor your application using the Docker target. + ## Configure Docker To configure the Docker daemon as a Prometheus target, you need to specify the @@ -49,7 +50,7 @@ Docker now exposes Prometheus-compatible metrics on port 9323. ## Configure and run Prometheus -In this example, Prometheus runs as a Docker service on a Docker swarm. +Prometheus runs as a Docker service on a Docker swarm. > **Prerequisites** > diff --git a/datacenter/dtr/2.5/guides/admin/backups-and-disaster-recovery.md b/datacenter/dtr/2.5/guides/admin/backups-and-disaster-recovery.md new file mode 100644 index 0000000000..725d45c18c --- /dev/null +++ b/datacenter/dtr/2.5/guides/admin/backups-and-disaster-recovery.md @@ -0,0 +1,239 @@ +--- +title: DTR backups and recovery +description: Learn how to back up your Docker Trusted Registry cluster, and to recover your cluster from an existing backup. +keywords: registry, high-availability, backup, recovery +--- + +{% assign image_backup_file = "backup-images.tar" %} +{% assign metadata_backup_file = "backup-metadata.tar" %} + +DTR requires that a majority (n/2 + 1) of its replicas are healthy at all times +for it to work. So if a majority of replicas is unhealthy or lost, the only +way to restore DTR to a working state, is by recovering from a backup. This +is why it's important to ensure replicas are healthy and perform frequent +backups. + +## Data managed by DTR + +Docker Trusted Registry maintains data about: + +| Data | Description | +|:-----------------------------------|:--------------------------------------------------------------------------------------------------------------------------------------------------| +| Configurations | The DTR cluster configurations | +| Repository metadata | The metadata about the repositories and images deployed | +| Access control to repos and images | Permissions for teams and repositories | +| Notary data | Notary tags and signatures | +| Scan results | Security scanning results for images | +| Certificates and keys | The certificates, public keys, and private keys that are used for mutual TLS communication | +| Images content | The images you push to DTR. This can be stored on the filesystem of the node running DTR, or other storage system, depending on the configuration | + +This data is persisted on the host running DTR, using named volumes. +[Learn more about DTR named volumes](../architecture.md). + +To perform a backup of a DTR node, run the `docker/dtr backup` command. This +command backups up the following data: + +| Data | Backed up | Description | +|:-----------------------------------|:----------|:---------------------------------------------------------------| +| Configurations | yes | DTR settings | +| Repository metadata | yes | Metadata like image architecture and size | +| Access control to repos and images | yes | Data about who has access to which images | +| Notary data | yes | Signatures and digests for images that are signed | +| Scan results | yes | Information about vulnerabilities in your images | +| Certificates and keys | yes | TLS certificates and keys used by DTR | +| Image content | no | Needs to be backed up separately, depends on DTR configuration | +| Users, orgs, teams | no | Create a UCP backup to backup this data | +| Vulnerability database | no | Can be re-downloaded after a restore | + + +## Backup DTR data + +To create a backup of DTR you need to: + +1. Backup image content +2. Backup DTR metadata + +You should always create backups from the same DTR replica, to ensure a smoother +restore. + +### Backup image content + +Since you can configure the storage backend that DTR uses to store images, +the way you backup images depends on the storage backend you're using. + +If you've configured DTR to store images on the local filesystem or NFS mount, +you can backup the images by using ssh to log into a node where DTR is running, +and creating a tar archive of the [dtr-registry volume](../architecture.md): + +```none +sudo tar -cf {{ image_backup_file }} \ + {% raw %}$(dirname $(docker volume inspect --format '{{.Mountpoint}}' dtr-registry-)){% endraw %} +``` + +If you're using a different storage backend, follow the best practices +recommended for that system. + + +### Backup DTR metadata + +To create a DTR backup, load your UCP client bundle, and run the following +command, replacing the placeholders for the real values: + +```none +read -sp 'ucp password: ' UCP_PASSWORD; \ +docker run --log-driver none -i --rm \ + --env UCP_PASSWORD=$UCP_PASSWORD \ + {{ page.dtr_org }}/{{ page.dtr_repo }}:{{ page.dtr_version }} backup \ + --ucp-url \ + --ucp-insecure-tls \ + --ucp-username \ + --existing-replica-id > {{ metadata_backup_file }} +``` + +Where: + +* `` is the url you use to access UCP +* `` is the username of a UCP administrator +* `` is the id of the DTR replica to backup + + +This prompts you for the UCP password, backups up the DTR metadata and saves the +result into a tar archive. You can learn more about the supported flags in +the [reference documentation](../../reference/cli/backup.md). + +The backup command doesn't stop DTR, so that you can take frequent backups +without affecting your users. Also, the backup contains sensitive information +like private keys, so you can encrypt the backup by running: + +```none +gpg --symmetric {{ metadata_backup_file }} +``` + +This prompts you for a password to encrypt the backup, copies the backup file +and encrypts it. + +### Test your backups + +To validate that the backup was correctly performed, you can print the contents +of the tar file created. The backup of the images should look like: + +```none +tar -tf {{ image_backup_file }} + +dtr-backup-v{{ page.dtr_version }}/ +dtr-backup-v{{ page.dtr_version }}/rethink/ +dtr-backup-v{{ page.dtr_version }}/rethink/layers/ +``` + +And the backup of the DTR metadata should look like: + +```none +tar -tf {{ metadata_backup_file }} + +# The archive should look like this +dtr-backup-v{{ page.dtr_version }}/ +dtr-backup-v{{ page.dtr_version }}/rethink/ +dtr-backup-v{{ page.dtr_version }}/rethink/properties/ +dtr-backup-v{{ page.dtr_version }}/rethink/properties/0 +``` + +If you've encrypted the metadata backup, you can use: + +```none +gpg -d {{ metadata_backup_file }} | tar -t +``` + +You can also create a backup of a UCP cluster and restore it into a new +cluster. Then restore DTR on that new cluster to confirm that everything is +working as expected. + +## Restore DTR data + +If your DTR has a majority of unhealthy replicas, the one way to restore it to +a working state is by restoring from an existing backup. + +To restore DTR, you need to: + +1. Stop any DTR containers that might be running +2. Restore the images from a backup +3. Restore DTR metadata from a backup +4. Re-fetch the vulnerability database + +You need to restore DTR on the same UCP cluster where you've created the +backup. If you restore on a different UCP cluster, all DTR resources will be +owned by users that don't exist, so you can't manage the resources, +even though they're stored in the DTR data store. + +When restoring, you need to use the same version of the `docker/dtr` image +that you've used when creating the update. Other versions are not guaranteed +to work. + +### Stop DTR containers + +Start by removing any DTR container that is still running: + +```none +docker run -it --rm \ + {{ page.dtr_org }}/{{ page.dtr_repo }}:{{ page.dtr_version }} destroy \ + --ucp-insecure-tls +``` + +### Restore images + +If you had DTR configured to store images on the local filesystem, you can +extract your backup: + +```none +sudo tar -xf {{ image_backup_file }} -C / +``` + +If you're using a different storage backend, follow the best practices +recommended for that system. When restoring the DTR metadata, DTR will be +deployed with the same configurations it had when creating the backup. + + +### Restore DTR metadata + +You can restore the DTR metadata with the `docker/dtr restore` command. This +performs a fresh installation of DTR, and reconfigures it with +the configuration created during a backup. + +Load your UCP client bundle, and run the following command, replacing the +placeholders for the real values: + +```none +read -sp 'ucp password: ' UCP_PASSWORD; \ +docker run -i --rm \ + --env UCP_PASSWORD=$UCP_PASSWORD \ + {{ page.dtr_org }}/{{ page.dtr_repo }}:{{ page.dtr_version }} restore \ + --ucp-url \ + --ucp-insecure-tls \ + --ucp-username \ + --ucp-node \ + --replica-id \ + --dtr-external-url < {{ metadata_backup_file }} +``` + +Where: + +* `` is the url you use to access UCP +* `` is the username of a UCP administrator +* `` is the hostname of the node where you've restored the images +* `` the id of the replica you backed up +* ``the url that clients use to access DTR + +If you're using NFS as a storage backend, also include `--nfs-storage-url` as +part of your restore command, otherwise DTR is restored but starts using a +local volume to persist your Docker images. + +### Re-fetch the vulnerability database + +If you're scanning images, you now need to download the vulnerability database. + +After you successfully restore DTR, you can join new replicas the same way you +would after a fresh installation. [Learn more](configure/set-up-vulnerability-scans.md). + +## Where to go next + +* [Set up high availability](configure/set-up-high-availability.md) +* [DTR architecture](../architecture.md) diff --git a/datacenter/dtr/2.5/guides/admin/configure/deploy-caches/chaining.md b/datacenter/dtr/2.5/guides/admin/configure/deploy-caches/chaining.md new file mode 100644 index 0000000000..a4bdcf7a42 --- /dev/null +++ b/datacenter/dtr/2.5/guides/admin/configure/deploy-caches/chaining.md @@ -0,0 +1,75 @@ +--- +title: Chain multiple caches +description: Learn how to deploy and chain multiple caches for Docker Trusted Registry, to cover multiple regions or offices +keywords: dtr, tls +--- + +If your users are distributed geographically, consider chaining multiple DTR +caches together for faster pulls. + +![cache chaining](../../../images/chaining-1.svg) + +Too many levels of chaining might slow down pulls, so you should try different +configurations and benchmark them, to find out the right configuration. + +This example shows how to configure two caches. A dedicated cache for +the Asia region that pulls images directly from DTR, and a cache for China, that +pulls images from the Asia cache. + +## Cache for the Asia region + +This cache has TLS, and pulls images directly from DTR: + +``` +version: 0.1 +storage: + delete: + enabled: true + filesystem: + rootdirectory: /var/lib/registry +http: + addr: :5000 + tls: + certificate: /certs/asia-ca.pem + key: /certs/asia-key.pem +middleware: + registry: + - name: downstream + options: + blobttl: 24h + upstreams: + - https:// + cas: + - /certs/dtr-ca.pem +``` + +## Cache for the China region + +This cache has TLS, and pulls images from the Asia cache: + +``` +version: 0.1 +storage: + delete: + enabled: true + filesystem: + rootdirectory: /var/lib/registry +http: + addr: :5000 + tls: + certificate: /certs/china-ca.pem + key: /certs/china-key.pem +middleware: + registry: + - name: downstream + options: + blobttl: 24h + upstreams: + - https:// + cas: + - /certs/asia-cache-ca.pem +``` + +Since the China cache doesn't need to communicate directly with DTR, +it only needs to trust the CA certificates for the next hop, in this case +the CA certificate used by the Asia cache. diff --git a/datacenter/dtr/2.5/guides/admin/configure/deploy-caches/index.md b/datacenter/dtr/2.5/guides/admin/configure/deploy-caches/index.md new file mode 100644 index 0000000000..3c4bc06611 --- /dev/null +++ b/datacenter/dtr/2.5/guides/admin/configure/deploy-caches/index.md @@ -0,0 +1,224 @@ +--- +title: Deploy DTR caches +description: Learn how to deploy and configure DTR caches, so that users can pull images faster. +keywords: registry, dtr, cache +--- + + +You can configure DTR to have multiple caches. Once you've deployed caches, +users can configure their DTR user account to specify which cache to pull from. + +Then, when users pull from DTR, they are redirected to pull from the cache +configured on their user account. By deploying caches geographically closer to remote +offices and low connectivity areas, users can pull images faster. + +User requests are authenticated when pulling from a cache. Users can only pull +images from a cache if they have access. And if the image has changed in DTR, +users will pull the latest version, not an outdated one. + +## How caches work + +After you've deployed the caches, users can configure which cache to +pull from on their DTR user settings page. + +![](../../../images/cache-docker-images-1.svg) + +When users try to pull an image by running +`docker pull //`, the following happens: + +1. The Docker client makes a request to DTR which in turn authenticates the +request +2. The Docker client requests the image manifest to DTR. This ensures that +users will always pull the correct image, and not an outdated version +3. The Docker client requests the layer blobs to DTR, which becomes signed +and redirected to the cache configured by the user +4. If the blob exists on the cache it is sent to the user. Otherwise, the cache +pulls it from DTR and sends it to the user + +When a user pushes an image, that image is pushed directly to DTR. A cache +will only store the image when a user tries to pull the image using that cache. + +## Configure the cache + +DTR caches are based on Docker Registry, and use the same configuration +file format. +[Learn more about the configuration options](/registry/configuration.md). + +The DTR cache extends the Docker Registry configuration file format by +introducing a new middleware called `downstream` that has three configuration +options: `blobttl`, `upstreams`, and `cas`: + +```none +# Settings that you would include in a +# Docker Registry configuration file followed by + +middleware: + registry: + - name: downstream + options: + blobttl: 24h + upstreams: + - + cas: + - +``` + +Below you can find the description for each parameter, specific to DTR caches. + + + + + + + + + + + + + + + + + + + + + + +
ParameterRequiredDescription
+ blobttl + + no + +The TTL for blobs in the cache. This field takes a positive integer and an optional suffix indicating the unit of time. If +this field is configured, "storage.delete.enabled" must be configured to true. Possible units are: +
    +
  • ns (nanoseconds)
    • +
  • us (microseconds)
    • +
  • ms (milliseconds)
    • +
  • s (seconds)
    • +
  • m (minutes)
    • +
  • h (hours)
    • +
+ If you omit the suffix, the system interprets the value as nanoseconds. +
+ cas + + no + + An optional list of absolute paths to PEM-encoded CA certificates of upstream registries or content caches. +
+ upstreams + + yes + + A list of externally-reachable addresses for upstream registries of content caches. If more than one host is specified, it will pull from registries in round-robin order. +
+ +## Deploy a simple cache + +You can deploy a Docker Content Cache on any host that has Docker installed. +The only requirements are that: + +* Users need to have access to both DTR and the cache +* The cache needs access to DTR + +![](../../../images/cache-docker-images-2.svg) + +On the host where the cache will be deployed, create a `config.yml` file with +the following content: + +``` +version: 0.1 +storage: + delete: + enabled: true + filesystem: + rootdirectory: /var/lib/registry +http: + addr: :5000 +middleware: + registry: + - name: downstream + options: + blobttl: 24h + upstreams: + - https:// + cas: + - /certs/dtr-ca.pem +``` + +This configures the cache to store the images in the directory +`/var/lib/registry`, exposes the cache service on port 5000, and configures the +cache to delete images that are not pulled in the last 24 hours. It also +defines where DTR can be reached, and which CA certificates should be trusted. + +Now we need to download the CA certificate used by DTR. For this, run: + +``` +curl -k https:///ca > dtr-ca.pem +``` + +Now that we've got the cache configuration file and DTR CA certificate, we can +deploy the cache by running: + +```none +docker run --detach --restart always \ + --name dtr-cache \ + --publish 5000:5000 \ + --volume $(pwd)/dtr-ca.pem:/certs/dtr-ca.pem \ + --volume $(pwd)/config.yml:/config.yml \ + {{ page.dtr_org }}/dtr-content-cache:{{ page.dtr_version }} /config.yml +``` + +You can also run the command in interactive mode instead of detached by +replacing `--detached` with `--interactive`. This allows you to +see the logs generated by the container and troubleshoot misconfigurations. + +Now that you've deployed a cache, you need to configure DTR to know about it. +This is done using the `POST /api/v0/content_caches` API. You can use the +DTR interactive API documentation to use this API. + +In the DTR web UI, click the top-right menu, and choose **API docs**. + +![](../../../images/cache-docker-images-2.png){: .with-border} + +Navigate to the `POST /api/v0/content_caches` line and click it to expand. +In the **body** field include: + +``` +{ + "name": "region-us", + "host": "http://:5000" +} +``` + +Click the **Try it out!** button to make the API call. + +![](../../../images/cache-docker-images-3.png){: .with-border} + +Now that DTR knows about the cache we've created, we just need to configure +our DTR user settings to start using that cache. + +In the DTR web UI, navigate to your **user profile**, click the **Settings** +tab, and change the **Content Cache** settings to use the **region-us** cache. + +![](../../../images/cache-docker-images-4.png){: .with-border} + +You can also automate this through the `/api/v0/accounts/{username}/settings` +API. + +Now when you pull images, you use the cache. To test this, try pulling +an image from DTR. You can inspect the logs of the cache service, to validate +that the cache is being used, and troubleshoot problems. + +In the host where you've deployed the `region-us` cache, run: + +``` +docker container logs dtr-cache +``` + +## Where to go next + +* [Deploy caches with TLS](tls.md) diff --git a/datacenter/dtr/2.5/guides/admin/configure/deploy-caches/tls.md b/datacenter/dtr/2.5/guides/admin/configure/deploy-caches/tls.md new file mode 100644 index 0000000000..1087dc6186 --- /dev/null +++ b/datacenter/dtr/2.5/guides/admin/configure/deploy-caches/tls.md @@ -0,0 +1,93 @@ +--- +title: Deploy caches with TLS +description: Learn how to deploy and secure caches for Docker Trusted Registry, leveraging TLS +keywords: dtr, tls +--- + +When running DTR caches on a production environment, you should secure them +with TLS. In this example we're going to deploy a DTR cache that uses TLS. + +DTR caches use the same configuration file format used by Docker Registry. +You can learn more about the supported configuration in the +[Docker Registry documentation](/registry/configuration.md#tls). + + +## Get the TLS certificate and keys + +Before deploying a DTR cache with TLS you need to obtain a public key +certificate for the domain name where you deploy the cache, as well as +the public and private key files for that certificate. + +Once you have then, transfer those file to the host where you plan to deploy +the DTR cache. + + +## Create the cache configuration + +Use SSH to log into the host where you plan to deploy the DTR cache, and navigate to +the directory where you've stored the TLS certificate and keys. + +Create the `config.yml` file with the following content: + +``` +version: 0.1 +storage: + delete: + enabled: true + filesystem: + rootdirectory: /var/lib/registry +http: + addr: :5000 + tls: + certificate: /certs/dtr-cache-ca.pem + key: /certs/dtr-cache-key.pem +middleware: + registry: + - name: downstream + options: + blobttl: 24h + upstreams: + - https:// + cas: + - /certs/dtr-ca.pem +``` + +The configuration file mentions: + +* /certs/dtr-cache-ca.pem: this is the public key certificate the cache will use +* /certs/dtr-cache-key.pem: this is the TLS private key +* /certs/dtr-ca.pem is the CA certificate used by DTR + +Run this command to download the CA certificate used by DTR: + +``` +curl -k https:///ca > dtr-ca.pem +``` + +Now that we've got the cache configuration file and TLS certificates, we can +deploy the cache by running: + +```none +docker run --detach --restart always \ + --name dtr-cache \ + --publish 5000:5000 \ + --volume $(pwd)/dtr-cache-ca.pem:/certs/dtr-cache-ca.pem \ + --volume $(pwd)/dtr-cache-key.pem:/certs/dtr-cache-key.pem \ + --volume $(pwd)/dtr-ca.pem:/certs/dtr-ca.pem \ + --volume $(pwd)/config.yml:/config.yml \ + docker/dtr-content-cache:{{ page.dtr_version }} /config.yml +``` + +## Use Let's Encrypt + +You can also use Let's Encrypt to automatically generate TLS certificates that +are trusted by most clients. + +Learn more [about Let's Encrypt](https://letsencrypt.org/how-it-works/), and +how to +[create a configuration file that leverages it](/registry/configuration.md#letsencrypt). + + +## Where to go next + +* [Chain multiple caches](chaining.md) diff --git a/datacenter/dtr/2.5/guides/admin/configure/enable-single-sign-on.md b/datacenter/dtr/2.5/guides/admin/configure/enable-single-sign-on.md new file mode 100644 index 0000000000..3d5ae48589 --- /dev/null +++ b/datacenter/dtr/2.5/guides/admin/configure/enable-single-sign-on.md @@ -0,0 +1,42 @@ +--- +title: Enable single sign-on +description: Learn how to set up single sign-on between UCP and DTR, so that your users only need to authenticate once +keywords: dtr, login, sso +--- + +By default, users are shared between UCP and DTR, but you need to authenticate +separately on the web UI of both applications. + +You can configure DTR to have single sign-on (SSO) with UCP, so that users only +need to authenticate once. + +## At installation time + +When installing DTR, use the `docker/dtr install --dtr-external-url ` +option to enable SSO. When accessing the DTR web UI, users are redirected to the +UCP login page, and once they are authenticated, they're redirected to the URL +you provided to `--dtr-external-url`. + +Use the domain name of DTR, or the domain name of a load balancer, if you're +using one, to load-balance requests across multiple DTR replicas. + +## After install + +In your browser, navigate to the DTR web UI, and choose **Settings**. In the +**General** tab, scroll to **Domain & proxies**. + +Update the **Load balancer / public address** field to the url where users +should be redirected once they are logged in. +Use the domain name of DTR, or the domain name of a load balancer, if you're +using one, to load-balance requests across multiple DTR replicas. + +Then enable **Use single sign-on**. + +![](../../images/enable-sso-1.png){: .with-border} + +Once you save, users are redirected to UCP for logging in, and redirected back to +DTR once they are authenticated. + +## Where to go next + +* [Use your own TLS certificates](use-your-own-tls-certificates.md) diff --git a/datacenter/dtr/2.5/guides/admin/configure/external-storage/index.md b/datacenter/dtr/2.5/guides/admin/configure/external-storage/index.md new file mode 100644 index 0000000000..e2735bb182 --- /dev/null +++ b/datacenter/dtr/2.5/guides/admin/configure/external-storage/index.md @@ -0,0 +1,76 @@ +--- +title: Configure DTR image storage +description: Storage configuration for Docker Trusted Registry +keywords: storage drivers, NFS, Azure, S3 +--- + +By default DTR uses the local filesystem of the node where it is running to +store your Docker images. You can configure DTR to use an external storage +backend, for improved performance or high availability. + +![architecture diagram](../../../images/configure-external-storage-1.svg) + +If your DTR deployment only has a single replica, you can continue using the +local filesystem to store your Docker images. If your DTR deployment has +multiple replicas, for high availability, you need to ensure all replicas are +using the same storage backend. When a user pulls an image, the node serving +the request needs to have access to that image. + +DTR supports these storage systems: + +* Local filesystem +* NFS +* Amazon S3 or compatible +* Google Cloud Storage +* Microsoft Azure Blob storage +* OpenStack Swift + +To configure the storage backend, you can log into the **DTR web UI** +as an administrator user, navigate to the **Settings** page, and choose +**Storage**. + +![dtr settings](../../../images/configure-external-storage-2.png){: .with-border} + +The storage configuration page in the DTR web UI has options for the most +common configuration options, but you can also upload a yaml configuration file. + +The format of this configuration file is similar to the one used by +[Docker Registry](/registry/configuration.md). + +## Local filesystem + +By default, DTR creates a volume named `dtr-registry-` to store +your images using the local filesystem. You can customize the name and path of +the volume used by DTR, using the `docker/dtr reconfigure --dtr-storage-volume` +option. + +If you're deploying DTR with high-availability, you need to use NFS or any other +centralized storage backend so that all your DTR replicas have access to the +same images. + +To check how much space your images are taking in the local filesystem, you +can ssh into the node where DTR is deployed and run: + +{% raw %} +``` +# Find the path to the volume +docker volume inspect dtr-registry- + +# Check the disk usage +sudo du -hs \ +$(dirname $(docker volume inspect --format '{{.Mountpoint}}' dtr-registry-)) +``` +{% endraw %} + +## NFS + +You can configure your DTR replicas to store images on an NFS partition, so that +all replicas can share the same storage backend. + +[Learn how to configure DTR with NFS](nfs.md). + + +## Amazon S3 + +DTR supports AWS3 or other storage systems that are S3-compatible like Minio. +[Learn how to configure DTR with Amazon S3](s3.md). diff --git a/datacenter/dtr/2.5/guides/admin/configure/external-storage/nfs.md b/datacenter/dtr/2.5/guides/admin/configure/external-storage/nfs.md new file mode 100644 index 0000000000..1a6c3172b9 --- /dev/null +++ b/datacenter/dtr/2.5/guides/admin/configure/external-storage/nfs.md @@ -0,0 +1,71 @@ +--- +title: Use NFS +description: Learn how to integrate Docker Trusted Registry with NFS +keywords: registry, dtr, storage, nfs +--- + +You can configure DTR to store Docker images in an NFS directory. + +Before installing or configuring DTR to use an NFS directory, make sure that: + +* The NFS server has been correctly configured +* The NFS server has a fixed IP address +* All hosts running DTR have the correct NFS libraries installed + + +To confirm that the hosts can connect to the NFS server, try to list the +directories exported by your NFS server: + +```bash +showmount -e +``` + +You should also try to mount one of the exported directories: + +```bash +mkdir /tmp/mydir && sudo mount -t nfs : +``` + +## Install DTR with NFS + +One way to configure DTR to use an NFS directory is at install time: + +```none +docker run -it --rm {{ page.dtr_org }}/{{ page.dtr_repo }}:{{ page.dtr_version }} install \ + --nfs-storage-url \ + +``` + +The NFS storage URL should be in the format `nfs:///`. + +When you join replicas to the DTR cluster, the replicas will pick up that +configuration, so you don't need to specify it again. + +### Reconfigure DTR to use NFS + +If you're upgrading from a previous version of DTR and are already using +NFS you can continue using the same configurations. + +If you want to start using the new DTR built-in support for NFS you can +reconfigure DTR: + +```none +docker run -it --rm {{ page.dtr_org }}/{{ page.dtr_repo }}:{{ page.dtr_version }} reconfigure \ + --nfs-storage-url +``` + +If you want to reconfigure DTR to stop using NFS storage, leave the option +in blank: + +```none +docker run -it --rm {{ page.dtr_org }}/{{ page.dtr_repo }}:{{ page.dtr_version}} reconfigure \ + --nfs-storage-url "" +``` + +If the IP address of your NFS server changes, even if the DNS address is kept +the same, you should reconfigure DTR to stop using NFS storage, and then +add it back again. + +## Where to go next + +* [Configure where images are stored](index.md) diff --git a/datacenter/dtr/2.5/guides/admin/configure/external-storage/s3.md b/datacenter/dtr/2.5/guides/admin/configure/external-storage/s3.md new file mode 100644 index 0000000000..d42e3b0bb0 --- /dev/null +++ b/datacenter/dtr/2.5/guides/admin/configure/external-storage/s3.md @@ -0,0 +1,111 @@ +--- +title: Store images on Amazon S3 +description: Learn how to configure Docker Trusted Registry to store Docker images on + Amazon S3 +keywords: dtr, storage driver, s3 +--- + +You can configure DTR to store Docker images on Amazon S3, or other file servers +with an S3-compatible API like Minio. + +Amazon S3 and compatible services store files in "buckets", and users have +permissions to read, write, and delete files from those buckets. When you +integrate DTR with Amazon S3, DTR sends all read and write operations to the +S3 bucket so that the images are persisted there. + +## Create a bucket on Amazon S3 + +Before configuring DTR you need to create a bucket on Amazon S3. +To get faster pulls and pushes, you should create the S3 bucket on a region +that's physically close to the servers where DTR is running. + +Start by +[creating a bucket](http://docs.aws.amazon.com/AmazonS3/latest/gsg/CreatingABucket.html). +Then, as a best practice you should +[create a new IAM user](http://docs.aws.amazon.com/IAM/latest/UserGuide/id_users_create.html) +just for the DTR +integration and apply an IAM policy that ensures the user has limited permissions. + +This user only needs permissions to access the bucket that you use to store +images, and the ability read, write, and delete files. + +Here's an example of a policy like that: + +```json +{ + "Version": "2012-10-17", + "Statement": [ + { + "Effect": "Allow", + "Action": "s3:ListAllMyBuckets", + "Resource": "arn:aws:s3:::*" + }, + { + "Effect": "Allow", + "Action": [ + "s3:ListBucket", + "s3:GetBucketLocation", + "s3:ListBucketMultipartUploads" + ], + "Resource": "arn:aws:s3:::" + }, + { + "Effect": "Allow", + "Action": [ + "s3:PutObject", + "s3:GetObject", + "s3:DeleteObject", + "s3:ListBucketMultipartUploads" + ], + "Resource": "arn:aws:s3:::/*" + } + ] +} + +``` + + + +## Configure DTR + +Once you've created a bucket and user, you can configure DTR to use it. +Navigate to the **DTR web UI**, go to **Settings**, and choose **Storage**. + +![](../../../images/s3-1.png){: .with-border} + +Select the **S3** option, and fill-in the information about the bucket and +user. + +| Field | Description | +|:----------------|:----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| +| Root directory | The path in the bucket where images are stored | +| AWS Region name | The region where the bucket is. [Learn more](http://docs.aws.amazon.com/general/latest/gr/rande.html#s3_region) | +| S3 bucket name | The name of the bucket to store the images | +| AWS access key | The access key to use to access the S3 bucket. This can be left empty if you're using an IAM policy. [Learn more](http://docs.aws.amazon.com/general/latest/gr/managing-aws-access-keys.html) | +| AWS secret key | The secret key to use to access the S3 bucket. This can be left empty if you're using an IAM policy | +| Region endpoint | The endpoint name for the region you're using. [Learn more](http://docs.aws.amazon.com/general/latest/gr/rande.html#s3_region) | + +There are also some advanced settings. + +| Field | Description | +|:-------------------------|:----------------------------------------------------------------------------------------------------------------------------------------------------------| +| Signature version 4 auth | Authenticate the requests using AWS signature version 4. [Learn more](http://docs.aws.amazon.com/AmazonS3/latest/API/sig-v4-authenticating-requests.html) | +| Use HTTPS | Secure all requests with HTTPS, or make requests in an insecure way | +| Skip TLS verification | Encrypt all traffic, but don't verify the TLS certificate used by the storage backend | +| Root CA certificate | The public key certificate of the root certificate authority that issued the storage backend certificate | + +Once you click **Save**, DTR validates the configurations and saves the changes. + +## Configure your clients + +If you use a TLS certificate in your storage backend that's not globally +trusted, you need to configure all Docker Engines that push or pull from DTR +to trust that certificate. When you push or pull an image DTR redirects the +requests to the storage backend, so if clients don't trust the TLS certificates +of both DTR and the storage backend, they can't push or pull images. +[Learn how to configure the Docker client](../../../user/access-dtr/index.md). + +And if you've configured DTR to skip TLS verification, you also need to +configure all Docker Engines that push or pull from DTR to skip TLS +verification. You do this by adding DTR to +the [list of insecure registries when starting Docker](/engine/reference/commandline/dockerd.md). diff --git a/datacenter/dtr/2.5/guides/admin/configure/garbage-collection.md b/datacenter/dtr/2.5/guides/admin/configure/garbage-collection.md new file mode 100644 index 0000000000..4c384d7d8c --- /dev/null +++ b/datacenter/dtr/2.5/guides/admin/configure/garbage-collection.md @@ -0,0 +1,85 @@ +--- +title: Garbage collection +description: Save disk space by configuring the garbage collection settings in + Docker Trusted Registry +keywords: registry, garbage collection, gc, space, disk space +--- + +You can configure Docker Trusted Registry to automatically delete unused image +layers, thus saving you disk space. This process is also known as garbage collection. + +## How DTR deletes unused layers + +First you configure DTR to run a garbage collection job on a fixed schedule. At +the scheduled time: + +1. DTR becomes read-only. Images can be pulled, but pushes are not allowed. +2. DTR identifies and marks all unused image layers. +3. DTR deletes the marked image layers. + +Since this process puts DTR in read-only mode and is CPU-intensive, you should +run garbage collection jobs outside business peak hours. + +## Schedule garbage collection + +Navigate to the **Settings** page, and choose **Garbage collection**. + +![](../../images/garbage-collection-1.png){: .with-border} + +Select for how long the garbage collection job should run: +* Until done: Run the job until all unused image layers are deleted. +* For x minutes: Only run the garbage collection job for a maximum of x minutes +at a time. +* Never: Never delete unused image layers. + +Once you select for how long to run the garbage collection job, you can +configure its schedule (in UTC time) using the cron format. + +![](../../images/garbage-collection-2.png){: .with-border} + +Once everything is configured you can chose to **Save & start** to immediately +run the garbage collection job, or just **Save** to run the job on the next +scheduled interval. + +## Stop the garbage collection job + +Once the garbage collection job starts running, a banner is displayed on the +web UI explaining that users can't push images. If you're an administrator, you can click the banner to stop the garbage +collection job. + +![](../../images/garbage-collection-3.png){: .with-border} + +## Under the hood + +Each image stored in DTR is made up of multiple files: + +* A list of image layers that represent the image filesystem. +* A configuration file that contains the architecture of the image and other +metadata. +* A manifest file containing the list of all layers and configuration file for +an image. + +All these files are stored in a content-addressable way in which the name of +the file is the result of hashing the file's content. This means that if two +image tags have exactly the same content, DTR only stores the image content +once, even if the tag name is different. + +As an example, if `wordpress:4.8` and `wordpress:latest` have the same content, +they will only be stored once. If you delete one of these tags, the other won't +be deleted. + +This means that when users delete an image tag, DTR can't delete the underlying +files of that image tag since it's possible that there are other tags that +also use the same files. + +To delete unused image layers, DTR: +1. Becomes read-only to make sure that no one can push an image, thus +changing the underlying files in the filesystem. +2. Check all the manifest files and keep a record of the files that are +referenced. +3. If a file is never referenced, that means that no image tag uses it, so it +can be safely deleted. + +## Where to go next + +* [Deploy DTR caches](deploy-caches/index.md) diff --git a/datacenter/dtr/2.5/guides/admin/configure/license-your-installation.md b/datacenter/dtr/2.5/guides/admin/configure/license-your-installation.md new file mode 100644 index 0000000000..3c14e283a5 --- /dev/null +++ b/datacenter/dtr/2.5/guides/admin/configure/license-your-installation.md @@ -0,0 +1,39 @@ +--- +title: License your installation +description: Learn how to license your Docker Trusted Registry installation. +keywords: dtr, install, license +--- + +By default, you don't need to license your Docker Trusted Registry. When +installing DTR, it automatically starts using the same license file used on +your Docker Universal Control Plane cluster. + +However, there are some situations when you need to manually license your +DTR installation: + +* When upgrading to a new major version, +* When your current license expires. + + +## Download your license + +Go to [Docker Store](https://store.docker.com/editions/enterprise/docker-ee-trial) +and download your license. + +![](../../images/license-1.png){: .with-border} + + +## License your installation + +Once you've downloaded the license file, you can apply it to your DTR +installation. Navigate to the **DTR web UI**, and then go to the **Settings +page**. + +![](../../images/license-2.png){: .with-border} + +Click the **Apply new license** button, and upload your new license file. + + +## Where to go next + +* [Enable single sign-on](enable-single-sign-on.md) diff --git a/datacenter/dtr/2.5/guides/admin/configure/set-up-high-availability.md b/datacenter/dtr/2.5/guides/admin/configure/set-up-high-availability.md new file mode 100644 index 0000000000..be21611565 --- /dev/null +++ b/datacenter/dtr/2.5/guides/admin/configure/set-up-high-availability.md @@ -0,0 +1,89 @@ +--- +title: Set up high availability +description: Lean how to scale Docker Trusted Registry by adding and removing replicas. +keywords: dtr, install, deploy +--- + +Docker Trusted Registry is designed to scale horizontally as your usage +increases. You can add more replicas to make DTR scale to your demand and for +high availability. + +All DTR replicas run the same set of services and changes to their configuration +are automatically propagated to other replicas. + +![](../../images/set-up-high-availability-1.svg) + +To make DTR tolerant to failures, add additional replicas to the DTR cluster. + +| DTR replicas | Failures tolerated | +|:------------:|:------------------:| +| 1 | 0 | +| 3 | 1 | +| 5 | 2 | +| 7 | 3 | + + +When sizing your DTR installation for high-availability, +follow these rules of thumb: + +* Don't create a DTR cluster with just two replicas. Your cluster +won't tolerate any failures, and it's possible that you experience performance +degradation. +* When a replica fails, the number of failures tolerated by your cluster +decreases. Don't leave that replica offline for long. +* Adding too many replicas to the cluster might also lead to performance +degradation, as data needs to be replicated across all replicas. + +To have high-availability on UCP and DTR, it is recommended to have a minimum of: + +* 3 dedicated nodes to install UCP with high availability, +* 3 dedicated nodes to install DTR with high availability, +* As many nodes as you want for running your containers and applications. + +## Join more DTR replicas + +To add replicas to an existing DTR deployment: + +1. Use ssh to log into any node that is already part of UCP. + +2. Run the DTR join command: + + ```none + docker run -it --rm \ + {{ page.dtr_org }}/{{ page.dtr_repo }}:{{ page.dtr_version }} join \ + --ucp-node \ + --ucp-insecure-tls + ``` + + Where the `--ucp-node` is the hostname of the UCP node where you want to + deploy the DTR replica. `--ucp-insecure-tls` tells the command to trust the + certificates used by UCP. + +3. If you have a load balancer, add this DTR replica to the load balancing pool. + +## Remove existing replicas + +To remove a DTR replica from your deployment: + +1. Use ssh to log into any node that is part of UCP. +2. Run the DTR remove command: + +```none +docker run -it --rm \ + {{ page.dtr_org }}/{{ page.dtr_repo }}:{{ page.dtr_version }} remove \ + --ucp-insecure-tls +``` + +You will be prompted for: + +* Existing replica id: the id of any healthy DTR replica of that cluster +* Replica id: the id of the DTR replica you want to remove. It can be the id of an +unhealthy replica +* UCP username and password: the administrator credentials for UCP + +If you're load-balancing user requests across multiple DTR replicas, don't +forget to remove this replica from the load balancing pool. + +## Where to go next + +* [Set up vulnerability scans](set-up-vulnerability-scans.md) diff --git a/datacenter/dtr/2.5/guides/admin/configure/set-up-vulnerability-scans.md b/datacenter/dtr/2.5/guides/admin/configure/set-up-vulnerability-scans.md new file mode 100644 index 0000000000..7f8c754b8f --- /dev/null +++ b/datacenter/dtr/2.5/guides/admin/configure/set-up-vulnerability-scans.md @@ -0,0 +1,188 @@ +--- +title: Set up Security Scanning in DTR +description: Enable and configure Docker Security Scanning for Docker Trusted Registry. +keywords: registry, scanning, security scan, vulnerability, CVE +redirect_from: +- /docker-cloud/builds/image-scan/ +--- + +This page explains how to set up and enable Docker Security Scanning on an existing installation of Docker Trusted Registry. + +## Prerequisites + +These instructions assume that you have already installed Docker Trusted +Registry, and have access to an account on the DTR instance with administrator +access. + +Before you begin, make sure that you or your organization has purchased a DTR +license that includes Docker Security Scanning, and that your Docker ID can +access and download this license from the Docker Store. + +If you are using a license associated with an individual account, no additional +action is needed. If you are using a license associated with an organization +account, you may need to make sure your Docker ID is a member of the `Owners` +team. Only `Owners` team members can download license files for an Organization. + +If you will be allowing the Security Scanning database to update itself +automatically, make sure that the server hosting your DTR instance can access +`https://dss-cve-updates.docker.com/` on the standard https port 443. + +## Get the security scanning license. + +If your DTR instance already has a license that includes Security Scanning, skip +this step and proceed to [enable DTR Security Scanning](#enable-dtr-security-scanning). + +> **Tip**: To check if your existing DTR license includes scanning, navigate to the DTR **Settings** page, and click **Security**. If an "Enable scanning" toggle appears, the license includes scanning. + +If your current DTR license doesn't include scanning, you must first download the new license. + +1. Log in to the Docker Store using a Docker ID with access to the license you need. +2. In the top right corner, click your user account icon, and select **My Content**. +3. Locate **Docker Enterprise Edition** in the content list, and click **Setup**. +4. Click **License Key** to download the license. + ![](../../images/security-scanning-setup-1.png){: .with-border} + +Next, install the new license on the DTR instance. + +7. Log in to your DTR instance using an administrator account. +8. Click **Settings** in the left navigation. +9. On the **General** tab click **Apply new license**. + + A file browser dialog appears. + +10. Navigate to where you saved the license key (`.lic`) file, select it, and click **Open**. + +![](../../images/security-scanning-setup-2.png){: .with-border} + +Proceed to [enable DTR Security Scanning](#enable-dtr-security-scanning). + +## Enable DTR security scanning + +To enable security scanning in DTR: + +1. Log in to your DTR instance with an administrator account. +2. Click **Settings** in the left navigation. +3. Click the **Security** tab. + + > **Note**: If you see a message on this tab telling you to contact your Docker sales representative, then the license installed on this DTR instance does not include Docker Security Scanning. Check that you have purchased Security Scanning, and that the DTR instance is using the latest license file. + +4. Click the **Enable scanning** toggle so that it turns blue and says "on". + ![](../../images/security-scanning-setup-3.png){: .with-border} +5. Next, provide a security database for the scanner. **Security scanning will not function until DTR has a security database to use.** + + By default, security scanning is enabled in **Online** mode. In this mode, + DTR attempts to download a security database from a Docker server. If your + installation cannot access `https://dss-cve-updates.docker.com/` you must + manually upload a `.tar` file containing the security database. + + - If you are using `Online` mode, the DTR instance will contact a Docker server, download the latest vulnerability database, and install it. Scanning can begin once this process completes. + - If you are using `Offline` mode, use the instructions in [Update scanning database - offline mode](#update-cve-database---offline-mode) to upload an initial security database. + +By default when Security Scanning is enabled, new repositories will automatically scan on `docker push`. If you had existing repositories before you enabled security scanning, you might want to [change repository scanning behavior](#set-repository-scanning-mode). + +## Set repository scanning mode + +Two modes are available when Security Scanning is enabled: + +- `Scan on push & Scan manually`: the image is re-scanned on each `docker push` to the repository, and whenever a user with `write` access clicks the **Start Scan** links or **Scan** button. +- `Scan manually`: the image is scanned only when a user with `write` access clicks the **Start Scan** links or **Scan** button. + +By default, _new_ repositories are set to `Scan on push & Scan manually`, but +you can change this setting during repository creation. + +![](../../images/security-scanning-setup-4.png){: .with-border} + +Any repositories that existed before scanning was enabled are set to `Scan manually` mode by default. If these repositories are still in use, you can change this setting from each repository's **Settings** page. + +> **Note**: To change an individual repository's scanning mode, you must have +`write` or `admin` access to the repo. + +To change an individual repository's scanning mode: + +1. Navigate to the repository, and click the **Settings** tab. +2. Scroll down to the **Image scanning** section. +3. Select the desired scanning mode. +![](../../images/security-scanning-setup-5.png){: .with-border} + +## Update the CVE scanning database + +Docker Security Scanning indexes the components in your DTR images and compares +them against a known CVE database. When new vulnerabilities are reported, Docker +Security Scanning matches the components in new CVE reports to the indexed +components in your images, and quickly generates an updated report. + +Users with administrator access to DTR can check when the CVE database was last updated from the **Security** tab in the DTR **Settings** pages. + +### Update CVE database - online mode + +By default Docker Security Scanning checks automatically for updates to the +vulnerability database, and downloads them when available. If your installation +does not have access to the public internet, use the [Offline mode instructions below](#update-cve-database-offline-mode). + +To ensure that DTR can access these updates, make sure that the host can reach +`https://dss-cve-updates.docker.com/` on port 443 using https. + +DTR checks for new CVE database updates at 3:00 AM UTC every day. If an update +is found it is downloaded and applied without interrupting any scans in +progress. Once the update is complete, the security scanning system looks for +new vulnerabilities in the indexed components. + +To set the update mode to Online: + +1. Log in to DTR as a user with administrator rights. +2. Click **Settings** in the left navigation and click **Security**. +3. Click **Online**. + +Your choice is saved automatically. + +> **Tip**: DTR also checks for CVE database updates when scanning is first enabled, and when you switch update modes. If you need to check for a CVE database update immediately, you can briefly switch modes from online to offline and back again. + +### Update CVE database - offline mode + +To update the CVE database for your DTR instance when it cannot contact the update server, you download and install a `.tar` file that contains the database updates. To download the file: + +1. Log in to the [Docker Store](https://store.docker.com/). + + If you are a member of an Organization managing licenses using Docker Store, + make sure your account is a member of the `Owners` team. Only Owners can + view and manage licenses and other entitlements for Organizations from the + Docker Store. + +2. In the top right corner, click your user account icon, and select **My Content**. +3. If necessary, select an organization account from the **Accounts** menu at the upper right. +4. Locate your Docker EE Advanced subscription or trial. +5. Click **Setup** button. + + ![](../../images/security-scanning-setup-6.png){: .with-border} + +6. Click **Download CVE Vulnerability Database** link to download the database file. + + ![](../../images/security-scanning-setup-7.png){: .with-border} + + If you run into problems, contact us at nautilus-feedback@docker.com for the file. + +To manually update the DTR CVE database from a `.tar` file: + +1. Log in to DTR as a user with administrator rights. +2. Click **Settings** in the left navigation and click **Security**. +4. Click **Upload .tar database file**. +5. Browse to the latest `.tar` file that you received, and click **Open**. + +DTR installs the new CVE database, and begins checking already indexed images +for components that match new or updated vulnerabilities. + +> **Tip**: The Upload button is unavailable while DTR applies CVE database updates. + +## Enable or disable automatic database updates + +To change the update mode: + +1. Log in to DTR as a user with administrator rights. +2. Click **Settings** in the left navigation and click **Security**. +3. Click **Online/Offline**. + +Your choice is saved automatically. + +## Where to go next + +* [Deploy DTR caches](deploy-caches/index.md) diff --git a/datacenter/dtr/2.5/guides/admin/configure/use-a-load-balancer.md b/datacenter/dtr/2.5/guides/admin/configure/use-a-load-balancer.md new file mode 100644 index 0000000000..826ccf5fc6 --- /dev/null +++ b/datacenter/dtr/2.5/guides/admin/configure/use-a-load-balancer.md @@ -0,0 +1,292 @@ +--- +title: Use a load balancer +description: Learn how to configure a load balancer to balance user requests across multiple Docker Trusted Registry replicas. +keywords: dtr, load balancer +--- + +Once you’ve joined multiple DTR replicas nodes for +[high-availability](set-up-high-availability.md), you can configure your own +load balancer to balance user requests across all replicas. + +![](../../images/use-a-load-balancer-1.svg) + + +This allows users to access DTR using a centralized domain name. If a replica +goes down, the load balancer can detect that and stop forwarding requests to +it, so that the failure goes unnoticed by users. + +## Load balancing DTR + +DTR does not provide a load balancing service. You can use an on-premises +or cloud-based load balancer to balance requests across multiple DTR replicas. + +Make sure you configure your load balancer to: + +* Load balance TCP traffic on ports 80 and 443 +* Make sure the load balancer is not buffering requests +* Make sure the load balancer is forwarding the `Host` HTTP header correctly +* Make sure there's no timeout for idle connections, or set it to more than 10 minutes +* Use the unauthenticated `/_ping` endpoint (note the lack of an `/api/v0/` in +the path) on each DTR replica, to check if the replica is healthy and if it +should remain in the load balancing pool or not + +## Health check endpoints + +The `/_ping` endpoint returns a JSON object for the replica being queried of +the form: + +```json +{ + "Error": "error message", + "Healthy": true +} +``` + +A response of `"Healthy": true` means the replica is suitable for taking +requests. It is also sufficient to check whether the HTTP status code is 200. + +An unhealthy replica will return 503 as the status code and populate `"Error"` +with more details on any one of these services: + +* Storage container (registry) +* Authorization (garant) +* Metadata persistence (rethinkdb) +* Content trust (notary) + +This endpoint is for checking the health of a *single* replica. To get +the health of every replica in a cluster, querying each replica individually is +the preferred way to do it in real time. + +The `/api/v0/meta/cluster_status` +[endpoint](../../../reference/api) +returns a JSON object for the entire cluster *as observed* by the replica being +queried, and it takes the form: + +```json +{ + "replica_health": { + "replica id": "OK", + "another replica id": "error message" + }, + "replica_timestamp": { + "replica id": "2006-01-02T15:04:05Z07:00", + "another replica id": "2006-01-02T15:04:05Z07:00" + }, + "(other fields go here)": "..." +} +``` + +Health statuses for the replicas is available in the `"replica_health"` object. +These statuses are taken from a cache which is last updated by each replica +individually at the time specified in the `"replica_timestamp"` object. + +The response also contains information about the internal DTR storage state, +which is around 45 KB of data. This, combined with the fact that the endpoint +requires admin credentials, means it is not particularly appropriate for load +balance checks. Use `/_ping` instead for those kinds of checks. + + +## Configuration examples + +Use the following examples to configure your load balancer for DTR. + + +
+
+```conf +user nginx; +worker_processes 1; + +error_log /var/log/nginx/error.log warn; +pid /var/run/nginx.pid; + +events { + worker_connections 1024; +} + +stream { + upstream dtr_80 { + server :80 max_fails=2 fail_timeout=30s; + server :80 max_fails=2 fail_timeout=30s; + server :80 max_fails=2 fail_timeout=30s; + } + upstream dtr_443 { + server :443 max_fails=2 fail_timeout=30s; + server :443 max_fails=2 fail_timeout=30s; + server :443 max_fails=2 fail_timeout=30s; + } + server { + listen 443; + proxy_pass dtr_443; + } + + server { + listen 80; + proxy_pass dtr_80; + } +} +``` +
+
+```conf +global + log /dev/log local0 + log /dev/log local1 notice + +defaults + mode tcp + option dontlognull + timeout connect 5s + timeout client 50s + timeout server 50s + timeout tunnel 1h + timeout client-fin 50s +### frontends +# Optional HAProxy Stats Page accessible at http://:8181/haproxy?stats +frontend dtr_stats + mode http + bind 0.0.0.0:8181 + default_backend dtr_stats +frontend dtr_80 + mode tcp + bind 0.0.0.0:80 + default_backend dtr_upstream_servers_80 +frontend dtr_443 + mode tcp + bind 0.0.0.0:443 + default_backend dtr_upstream_servers_443 +### backends +backend dtr_stats + mode http + option httplog + stats enable + stats admin if TRUE + stats refresh 5m +backend dtr_upstream_servers_80 + mode tcp + option httpchk GET /_ping HTTP/1.1\r\nHost:\ + server node01 :80 check weight 100 + server node02 :80 check weight 100 + server node03 :80 check weight 100 +backend dtr_upstream_servers_443 + mode tcp + option httpchk GET /_ping HTTP/1.1\r\nHost:\ + server node01 :443 weight 100 check check-ssl verify none + server node02 :443 weight 100 check check-ssl verify none + server node03 :443 weight 100 check check-ssl verify none +``` +
+
+```json +{ + "Subnets": [ + "subnet-XXXXXXXX", + "subnet-YYYYYYYY", + "subnet-ZZZZZZZZ" + ], + "CanonicalHostedZoneNameID": "XXXXXXXXXXX", + "CanonicalHostedZoneName": "XXXXXXXXX.us-west-XXX.elb.amazonaws.com", + "ListenerDescriptions": [ + { + "Listener": { + "InstancePort": 443, + "LoadBalancerPort": 443, + "Protocol": "TCP", + "InstanceProtocol": "TCP" + }, + "PolicyNames": [] + } + ], + "HealthCheck": { + "HealthyThreshold": 2, + "Interval": 10, + "Target": "HTTPS:443/_ping", + "Timeout": 2, + "UnhealthyThreshold": 4 + }, + "VPCId": "vpc-XXXXXX", + "BackendServerDescriptions": [], + "Instances": [ + { + "InstanceId": "i-XXXXXXXXX" + }, + { + "InstanceId": "i-XXXXXXXXX" + }, + { + "InstanceId": "i-XXXXXXXXX" + } + ], + "DNSName": "XXXXXXXXXXXX.us-west-2.elb.amazonaws.com", + "SecurityGroups": [ + "sg-XXXXXXXXX" + ], + "Policies": { + "LBCookieStickinessPolicies": [], + "AppCookieStickinessPolicies": [], + "OtherPolicies": [] + }, + "LoadBalancerName": "ELB-DTR", + "CreatedTime": "2017-02-13T21:40:15.400Z", + "AvailabilityZones": [ + "us-west-2c", + "us-west-2a", + "us-west-2b" + ], + "Scheme": "internet-facing", + "SourceSecurityGroup": { + "OwnerAlias": "XXXXXXXXXXXX", + "GroupName": "XXXXXXXXXXXX" + } +} +``` +
+
+ + +You can deploy your load balancer using: + + +
+
+```conf +# Create the nginx.conf file, then +# deploy the load balancer + +docker run --detach \ + --name dtr-lb \ + --restart=unless-stopped \ + --publish 80:80 \ + --publish 443:443 \ + --volume ${PWD}/nginx.conf:/etc/nginx/nginx.conf:ro \ + nginx:stable-alpine +``` +
+
+```conf +# Create the haproxy.cfg file, then +# deploy the load balancer + +docker run --detach \ + --name dtr-lb \ + --publish 443:443 \ + --publish 80:80 \ + --publish 8181:8181 \ + --restart=unless-stopped \ + --volume ${PWD}/haproxy.cfg:/usr/local/etc/haproxy/haproxy.cfg:ro \ + haproxy:1.7-alpine haproxy -d -f /usr/local/etc/haproxy/haproxy.cfg +``` +
+
+ +## Where to go next + +* [Backups and disaster recovery](../backups-and-disaster-recovery.md) +* [DTR architecture](../../architecture.md) diff --git a/datacenter/dtr/2.5/guides/admin/configure/use-a-web-proxy.md b/datacenter/dtr/2.5/guides/admin/configure/use-a-web-proxy.md new file mode 100644 index 0000000000..9490e5e2ad --- /dev/null +++ b/datacenter/dtr/2.5/guides/admin/configure/use-a-web-proxy.md @@ -0,0 +1,33 @@ +--- +title: Use a web proxy +description: Learn how to configure Docker Content Trust to use a web proxy to + reach external services. +keywords: dtr, configure, http, proxy +--- + +Docker Trusted Registry makes outgoing connections to check for new versions, +automatically renew its license, and update its vulnerability database. +If DTR can't access the internet, then you need to manually apply updates. + +One option to keep your environment secure while still allowing DTR access to +the internet is to use a web proxy. If you have an HTTP or HTTPS proxy, you +can configure DTR to use it. To avoid downtime you should do this configuration +outside business peak hours. + +As an administrator, log into a node where DTR is deployed, and run: + +``` +docker run -it --rm \ + {{ page.dtr_org }}/{{ page.dtr_repo }}:{{ page.dtr_version }} reconfigure \ + --http-proxy http://: \ + --https-proxy https://: \ + --ucp-insecure-tls +``` + +To confirm how DTR is configured, check the **Settings** page on the web UI. + +![DTR settings](../../images/use-a-web-proxy-1.png){: .with-border} + +## Where to go next + +* [Configure garbage collection](garbage-collection.md) diff --git a/datacenter/dtr/2.5/guides/admin/configure/use-your-own-tls-certificates.md b/datacenter/dtr/2.5/guides/admin/configure/use-your-own-tls-certificates.md new file mode 100644 index 0000000000..5ff5fe3031 --- /dev/null +++ b/datacenter/dtr/2.5/guides/admin/configure/use-your-own-tls-certificates.md @@ -0,0 +1,45 @@ +--- +title: Use your own TLS certificates +description: Learn how to configure Docker Trusted Registry with your own TLS certificates. +keywords: dtr, tls +--- + + +By default the DTR services are exposed using HTTPS, to ensure all +communications between clients and DTR is encrypted. Since DTR +replicas use self-signed certificates for this, when a client accesses +DTR, their browsers don't trust this certificate, so the browser displays a +warning message. + +You can configure DTR to use your own certificates, so that it is automatically +trusted by your users' browser and client tools. + +## Replace the server certificates + +To configure DTR to use your own certificates and keys, go to the +**DTR web UI**, navigate to the **Settings** page, and scroll down to the +**Domain** section. + +![](../../images/use-your-certificates-1.png){: .with-border} + + +Set the DTR domain name and upload the certificates and key: + +* Load balancer/public address, is the domain name clients will use to access DTR. +* TLS certificate, is the server certificate and any intermediate CA public +certificates. This certificate needs to be valid for the DTR public address, +and have SANs for all addresses used to reach the DTR replicas, including load +balancers. +* TLS private key is the server private key. +* TLS CA is the root CA public certificate. + +Finally, click **Save** for the changes to take effect. + +If you're using certificates issued by a globally trusted certificate authority, +any web browser or client tool should now trust DTR. If you're using an internal +certificate authority, configure your system to trust that +certificate authority. + +## Where to go next + +* [Set up external storage](external-storage/index.md) diff --git a/datacenter/dtr/2.5/guides/admin/install/index.md b/datacenter/dtr/2.5/guides/admin/install/index.md new file mode 100644 index 0000000000..c09d036e3f --- /dev/null +++ b/datacenter/dtr/2.5/guides/admin/install/index.md @@ -0,0 +1,131 @@ +--- +title: Install Docker Trusted Registry +description: Learn how to install Docker Trusted Registry for production. +keywords: dtr, registry, install +--- + +Docker Trusted Registry (DTR) is a containerized application that runs on a +swarm managed by Docker Universal Control Plane (UCP). It can be installed +on-premises or on a cloud infrastructure. + +Use these instructions to install DTR. + +## Step 1. Validate the system requirements + +The first step in installing DTR, is ensuring your +infrastructure has all the [requirements DTR needs to run](system-requirements.md). + +## Step 2. Install UCP + +Since DTR requires Docker Universal Control Plane (UCP) +to run, you need to install UCP on all the nodes where you plan to install DTR. +[Learn how to install UCP](/datacenter/ucp/2.2/guides/admin/install.md). + +DTR needs to be installed on a worker node that is being managed by UCP. +You can't install DTR on a standalone Docker Engine. + +![](../../images/install-dtr-1.svg) + + +## Step 3. Install DTR + +Once UCP is installed, navigate to the **UCP web UI**. In the **Admin Settings**, +choose **Docker Trusted Registry**. + +![](../../images/install-dtr-2.png){: .with-border} + +After you configure all the options, you have a snippet that you can use +to deploy DTR. It should look like this: + +```none +# Pull the latest version of DTR +$ docker pull {{ page.dtr_org }}/{{ page.dtr_repo }}:{{ page.dtr_version }} + +# Install DTR +$ docker run -it --rm \ + {{ page.dtr_org }}/{{ page.dtr_repo }}:{{ page.dtr_version }} install \ + --ucp-node \ + --ucp-insecure-tls +``` + +You can run that snippet on any node where Docker is installed. As an example +you can SSH into a UCP node and run the DTR installer from there. By default +the installer runs in interactive mode and prompts you for any additional +information that is necessary. +[Learn more about the installer](../../../reference/cli/install.md). + +## Step 4. Check that DTR is running + +In your browser, navigate to the Docker **Universal Control Plane** +web UI, and navigate to the **Applications** screen. DTR should be listed +as an application. + +![](../../images/install-dtr-3.png){: .with-border} + +You can also access the **DTR web UI**, to make sure it is working. In your +browser, navigate to the address where you installed DTR. + +![](../../images/install-dtr-4.png){: .with-border} + + +## Step 5. Configure DTR + +After installing DTR, you should configure: + + * The certificates used for TLS communication. [Learn more](../configure/use-your-own-tls-certificates.md). + * The storage backend to store the Docker images. [Lean more](../configure/external-storage/index.md). + + To perform these configurations, navigate to the **Settings** page of DTR. + + ![](../../images/install-dtr-5.png){: .with-border} + + +## Step 6. Test pushing and pulling + +Now that you have a working installation of DTR, you should test that you can +push and pull images to it. +[Learn how to push and pull images](../../user/manage-images/pull-and-push-images.md). + +## Step 7. Join replicas to the cluster + +This step is optional. + +To set up DTR for high availability, +you can add more replicas to your DTR cluster. Adding more replicas allows you +to load-balance requests across all replicas, and keep DTR working if a +replica fails. + +For high-availability you should set 3, 5, or 7 DTR replicas. The nodes where +you're going to install these replicas also need to be managed by UCP. + +To add replicas to a DTR cluster, use the `docker/dtr join` command: + +1. Load your UCP user bundle. + +2. Run the join command. + + When you join a replica to a DTR cluster, you need to specify the + ID of a replica that is already part of the cluster. You can find an + existing replica ID by going to the **Applications** page on UCP. + + Then run: + + ```none + docker run -it --rm \ + {{ page.dtr_org }}/{{ page.dtr_repo }}:{{ page.dtr_version }} join \ + --ucp-node \ + --ucp-insecure-tls + ``` + +3. Check that all replicas are running. + + In your browser, navigate to the Docker **Universal Control Plane** + web UI, and navigate to the **Applications** screen. All replicas should + be displayed. + + ![](../../images/install-dtr-6.png){: .with-border} + +## See also + +* [Install DTR offline](install-offline.md) +* [Upgrade DTR](../upgrade.md) diff --git a/datacenter/dtr/2.5/guides/admin/install/install-offline.md b/datacenter/dtr/2.5/guides/admin/install/install-offline.md new file mode 100644 index 0000000000..74250ed34f --- /dev/null +++ b/datacenter/dtr/2.5/guides/admin/install/install-offline.md @@ -0,0 +1,70 @@ +--- +title: Install Docker Trusted Registry offline +description: Learn how to install Docker Trusted Registry on a machine with no internet + access. +keywords: registry, install, offline +--- + +The procedure to install Docker Trusted Registry on a host is the same, +whether that host has access to the internet or not. + +The only difference when installing on an offline host, +is that instead of pulling the UCP images from Docker Hub, you use a +computer that is connected to the internet to download a single package with +all the images. Then you copy that package to the host where you’ll install DTR. + +## Versions available + +{% include components/ddc_url_list_2.html product="dtr" version="2.5" %} + +## Download the offline package + +Use a computer with internet access to download a package with all DTR images: + +```bash +$ wget -O dtr.tar.gz +``` + +Now that you have the package in your local machine, you can transfer it to +the machines where you want to install DTR. + +For each machine where you want to install DTR: + +1. Copy the DTR package to that machine. + + ```bash + $ scp dtr.tar.gz @ + ``` + +2. Use ssh to log into the hosts where you transferred the package. + +3. Load the DTR images. + + Once the package is transferred to the hosts, you can use the + `docker load` command to load the Docker images from the tar archive: + + ```bash + $ docker load < dtr.tar.gz + ``` + +## Install DTR + +Now that the offline hosts have all the images needed to install DTR, +you can [install DTR on that host](index.md). + +### Preventing outgoing connections + +DTR makes outgoing connections to: + +* report analytics, +* check for new versions, +* check online licenses, +* update the vulnerability scanning database + +All of these uses of online connections are optional. You can choose to +disable or not use any or all of these features on the admin settings page. + +## Where to go next + +* [DTR architecture](../../architecture.md) +* [Install DTR](index.md) diff --git a/datacenter/dtr/2.5/guides/admin/install/system-requirements.md b/datacenter/dtr/2.5/guides/admin/install/system-requirements.md new file mode 100644 index 0000000000..971c423f64 --- /dev/null +++ b/datacenter/dtr/2.5/guides/admin/install/system-requirements.md @@ -0,0 +1,46 @@ +--- +title: Docker Trusted Registry system requirements +description: Learn about the system requirements for installing Docker Trusted Registry. +keywords: DTR, architecture, requirements +--- + +Docker Trusted Registry can be installed on-premises or on the cloud. +Before installing, be sure your infrastructure has these requirements. + +## Software requirements + +You can install DTR on-premises or on a cloud provider. To install DTR, +all nodes must: +* Be a worker node managed by Universal Control Plane. +* Have a fixed hostname. + +## Ports used + +When installing DTR on a node, make sure the following ports are open on that +node: + +| Direction | Port | Purpose | +|:---------:|:--------|:--------------------------------------| +| in | 80/tcp | Web app and API client access to DTR. | +| in | 443/tcp | Web app and API client access to DTR. | + +These ports are configurable when installing DTR. + +## Compatibility and maintenance lifecycle + +Docker Enterprise Edition is a software subscription that includes three products: + +* Docker Engine EE, +* Docker Trusted Registry, +* Docker Universal Control Plane. + +[Learn more about the maintenance lifecycle for these products](https://success.docker.com/article/Compatibility_Matrix). + +## Hardware requirements + +Hardware requirements for DTR nodes are found at [UCP Hardware requirement](/datacenter/ucp/2.2/guides/admin/install/system-requirements.md) + +## Where to go next + +* [DTR architecture](../../architecture.md) +* [Install DTR](index.md) diff --git a/datacenter/dtr/2.5/guides/admin/install/uninstall.md b/datacenter/dtr/2.5/guides/admin/install/uninstall.md new file mode 100644 index 0000000000..26d8c28c43 --- /dev/null +++ b/datacenter/dtr/2.5/guides/admin/install/uninstall.md @@ -0,0 +1,31 @@ +--- +title: Uninstall Docker Trusted Registry +description: Learn how to uninstall your Docker Trusted Registry installation. +keywords: dtr, install, uninstall +--- + +Uninstalling DTR can be done by simply removing all data associated with each +replica. To do that, you just run the remove command once per replica and destroy the last one : + +```none +docker run -it --rm \ + docker/dtr:{{ page.dtr_version }} remove \ + --ucp-insecure-tls +``` + +```none +docker run -it --rm \ + docker/dtr:{{ page.dtr_version }} destroy \ + --ucp-insecure-tls +``` + +You will be prompted for the UCP URL, UCP credentials, and which replica to +remove/destroy. + +To see what options are available in the remove/destroy commands, check the +[remove command reference documentation](../../../reference/cli/remove.md) and [destroy command reference documentation](../../../reference/cli/destroy.md). + +## Where to go next + +* [Scale your deployment](../configure/set-up-high-availability.md) +* [Install DTR](index.md) diff --git a/datacenter/dtr/2.5/guides/admin/manage-users/create-and-manage-orgs.md b/datacenter/dtr/2.5/guides/admin/manage-users/create-and-manage-orgs.md new file mode 100644 index 0000000000..fd4ba27b52 --- /dev/null +++ b/datacenter/dtr/2.5/guides/admin/manage-users/create-and-manage-orgs.md @@ -0,0 +1,47 @@ +--- +title: Create and manage organizations +description: Learn how to set up organizations to enforce security in Docker Trusted + Registry. +keywords: registry, security, permissions, organizations +--- + +When a user creates a repository, only that user has permissions to make changes +to the repository. + +For team workflows, where multiple users have permissions to manage a set of +common repositories, create an organization. By default, DTR has one +organization called 'docker-datacenter', that is shared between DTR and UCP. + +To create a new organization, navigate to the **DTR web UI**, and go to the +**Organizations** page. + +![](../../images/create-and-manage-orgs-1.png){: .with-border} + +Click the **New organization** button, and choose a meaningful name for the +organization. + +![](../../images/create-and-manage-orgs-2.png){: .with-border} + +Repositories owned by this organization will contain the organization name, so +to pull an image from that repository, use: + +```bash +$ docker pull //: +``` + +Click **Save** to create the organization, and then **click the organization** +to define which users are allowed to manage this +organization. These users can edit the organization settings, edit +all repositories owned by the organization, and define the user permissions for +this organization. + +For this, click the **Add user** button, **select the users** that you want to +grant permissions to manage the organization, and click +**Save**. Then change their permissions from 'Member' to **Admin**. + +![](../../images/create-and-manage-orgs-3.png){: .with-border} + +## Where to go next + +* [Create and manage users](create-and-manage-users.md) +* [Create and manage teams](create-and-manage-teams.md) diff --git a/datacenter/dtr/2.5/guides/admin/manage-users/create-and-manage-teams.md b/datacenter/dtr/2.5/guides/admin/manage-users/create-and-manage-teams.md new file mode 100644 index 0000000000..435305d92e --- /dev/null +++ b/datacenter/dtr/2.5/guides/admin/manage-users/create-and-manage-teams.md @@ -0,0 +1,55 @@ +--- +title: Create and manage teams in DTR +description: Learn how to manage teams to enforce fine-grain access control in Docker + Trusted Registry. +keywords: registry, security, permissions, teams +--- + +You can extend a user's default permissions by granting them individual +permissions in other image repositories, by adding the user to a team. A team +defines the permissions a set of users have for a set of repositories. + +To create a new team, go to the **DTR web UI**, and navigate to the +**Organizations** page. +Then **click the organization** where you want to create the team. In this +example, we create the 'billing' team under the 'whale' organization. + +![](../../images/create-and-manage-teams-1.png){: .with-border} + +Click '**+**' to create a new team, and give it a name. + +![](../../images/create-and-manage-teams-2.png){: .with-border} + +## Add users to a team + +Once you have created a team, **click the team** name, to manage its settings. +The first thing we need to do is add users to the team. Click the **Add user** +button and add users to the team. + +![](../../images/create-and-manage-teams-3.png){: .with-border} + +## Manage team permissions + +The next step is to define the permissions this team has for a set of +repositories. Navigate to the **Repositories** tab, and click the +**Add repository** button. + +![](../../images/create-and-manage-teams-4.png){: .with-border} + +Choose the repositories this team has access to, and what permission levels the +team members have. + +![](../../images/create-and-manage-teams-5.png){: .with-border} + +There are three permission levels available: + +| Permission level | Description | +|:-----------------|:-----------------------------------------------------------------| +| Read only | View repository and pull images. | +| Read & Write | View repository, pull and push images. | +| Admin | Manage repository and change its settings, pull and push images. | + +## Where to go next + +* [Create and manage users](create-and-manage-users.md) +* [Permission levels](permission-levels.md) diff --git a/datacenter/dtr/2.5/guides/admin/manage-users/create-and-manage-users.md b/datacenter/dtr/2.5/guides/admin/manage-users/create-and-manage-users.md new file mode 100644 index 0000000000..34799b07fe --- /dev/null +++ b/datacenter/dtr/2.5/guides/admin/manage-users/create-and-manage-users.md @@ -0,0 +1,28 @@ +--- +title: Create and manage users in DTR +description: Learn how to manage user permissions in Docker Trusted Registry. +keywords: registry, security, permissions, users +--- + +When using the built-in authentication, you can create users +to grant them fine-grained permissions. +Users are shared across UCP and DTR. When you create a new user in +Docker Universal Control Plane, that user becomes available in DTR and vice +versa. + +To create a new user, go to the **DTR web UI**, and navigate to the **Users** +page. + +![](../../images/create-manage-users-1.png){: .with-border} + +Click the **New user** button, and fill-in the user information. + +![](../../images/create-manage-users-2.png){: .with-border} + +Check the **Trusted Registry admin** option, if you want to grant permissions +for the user to be a UCP and DTR administrator. + +## Where to go next + +* [Authentication and authorization](index.md) +* [Create and manage teams](create-and-manage-teams.md) diff --git a/datacenter/dtr/2.5/guides/admin/manage-users/index.md b/datacenter/dtr/2.5/guides/admin/manage-users/index.md new file mode 100644 index 0000000000..0d02ca49e2 --- /dev/null +++ b/datacenter/dtr/2.5/guides/admin/manage-users/index.md @@ -0,0 +1,56 @@ +--- +title: Authentication and authorization in DTR +description: Learn about the permission levels available on Docker Trusted Registry. +keywords: registry, security, permissions, users +--- + +With DTR you get to control which users have access to your image repositories. + +By default, anonymous users can only pull images from public repositories. +They can't create new repositories or push to existing ones. +You can then grant permissions to enforce fine-grained access control to image +repositories. For that: + +* Start by creating a user. + + Users are shared across UCP and DTR. When you create a new user in + Docker Universal Control Plane, that user becomes available in DTR and vice + versa. Registered users can create and manage their own repositories. + + You can also integrate with an LDAP service to manage users from a single + place. + +* Extend the permissions by adding the user to a team. + + To extend a user's permission and manage their permissions over repositories, + you add the user to a team. + A team defines the permissions users have for a set of repositories. + + +## Organizations and teams + +When a user creates a repository, only that user can make changes to the +repository settings, and push new images to it. + +Organizations take permission management one step further, since they allow +multiple users to own and manage a common set of repositories. This +is useful when implementing team workflows. With organizations you can +delegate the management of a set of repositories and user permissions to the +organization administrators. + +An organization owns a set of repositories, and defines a set of teams. With +teams you can define fine-grain permissions that a team of +user has for a set of repositories. + +![](../../images/authentication-authorization-1.svg) + +In this example, the 'Whale' organization has three repositories and two teams: + +* Members of the blog team can only see and pull images from the whale/java +repository, +* Members of the billing team can manage the whale/golang repository, and push +and pull images from the whale/java repository. + +## Where to go next + +* [Create and manage users](create-and-manage-users.md) diff --git a/datacenter/dtr/2.5/guides/admin/manage-users/permission-levels.md b/datacenter/dtr/2.5/guides/admin/manage-users/permission-levels.md new file mode 100644 index 0000000000..6ce70e8da3 --- /dev/null +++ b/datacenter/dtr/2.5/guides/admin/manage-users/permission-levels.md @@ -0,0 +1,54 @@ +--- +title: Permission levels in DTR +description: Learn about the permission levels available in Docker Trusted Registry. +keywords: registry, security, permissions +--- + +Docker Trusted Registry allows you to define fine-grain permissions over image +repositories. + +## Administrator users + +Users are shared across UCP and DTR. When you create a new user in Docker +Universal Control Plane, that user becomes available in DTR and vice versa. +When you create an administrator user in DTR, the user has permissions to: + +* Manage users across UCP and DTR, +* Manage DTR repositories and settings, +* Manage UCP resources and settings. + +## Team permission levels + +Teams allow you to define the permissions a set of user has for a set of +repositories. Three permission levels are available: + +| Repository operation | read | read-write | admin | +|:----------------------|:----:|:----------:|:-----:| +| View/ browse | x | x | x | +| Pull | x | x | x | +| Push | | x | x | +| Start a scan | | x | x | +| Delete tags | | x | x | +| Edit description | | | x | +| Set public or private | | | x | +| Manage user access | | | x | +| Delete repository | | | x | + +Team permissions are additive. When a user is a member of multiple teams, they +have the highest permission level defined by those teams. + +## Overall permissions + +Here's an overview of the permission levels available in DTR: + +* Anonymous users: Can search and pull public repositories. +* Users: Can search and pull public repos, and create and manage their own +repositories. +* Team member: Everything a user can do, plus the permissions granted by the teams the user is member of. +* Team admin: Everything a team member can do, and can also add members to the team. +* Organization admin: Everything a team admin can do, can create new teams, and add members to the organization. +* Admin: Can manage anything across UCP and DTR. + +## Where to go next + +* [Authentication and authorization](index.md) diff --git a/datacenter/dtr/2.5/guides/admin/monitor-and-troubleshoot/index.md b/datacenter/dtr/2.5/guides/admin/monitor-and-troubleshoot/index.md new file mode 100644 index 0000000000..f04826a346 --- /dev/null +++ b/datacenter/dtr/2.5/guides/admin/monitor-and-troubleshoot/index.md @@ -0,0 +1,44 @@ +--- +title: Monitor Docker Trusted Registry +description: Learn how to monitor your DTR installation. +keywords: registry, monitor, troubleshoot +--- + +Docker Trusted Registry is a Dockerized application. To monitor it, you can +use the same tools and techniques you're already using to monitor other +containerized applications running on your cluster. One way to monitor +DTR is using the monitoring capabilities of Docker Universal Control Plane. + +In your browser, log in to **Docker Universal Control Plane** (UCP), and +navigate to the **Stacks** page. +If you have DTR set up for high-availability, then all the DTR replicas are +displayed. + +![](../../images/monitor-1.png){: .with-border} + +To check the containers for the DTR replica, **click the replica** you want +to inspect, click **Inspect Resource**, and choose **Containers**. + +![](../../images/monitor-2.png){: .with-border} + +Now you can drill into each DTR container to see its logs and find the root +cause of the problem. + +![](../../images/monitor-3.png){: .with-border} + +## Health checks + +DTR also exposes several endpoints you can use to assess if a DTR replica +is healthy or not: + +* `/_ping`: Checks if the DTR replica is healthy, and +returns a simple json response. This is useful for load balancing or other +automated health check tasks. +* `/nginx_status`: Returns the number of connections being handled by the +NGINX front-end used by DTR. +* `/api/v0/meta/cluster_status`: Returns extensive information about all DTR +replicas. + +## Where to go next + +* [Troubleshoot with logs](troubleshoot-with-logs.md) diff --git a/datacenter/dtr/2.5/guides/admin/monitor-and-troubleshoot/notary-audit-logs.md b/datacenter/dtr/2.5/guides/admin/monitor-and-troubleshoot/notary-audit-logs.md new file mode 100644 index 0000000000..577821f6c0 --- /dev/null +++ b/datacenter/dtr/2.5/guides/admin/monitor-and-troubleshoot/notary-audit-logs.md @@ -0,0 +1,266 @@ +--- +title: Check Notary audit logs +description: When you push signed images, Docker Trusted Registry keeps audit + logs for the changes made to the image metadata. Learn how to view these logs. +keywords: registry, monitor, troubleshoot +--- + +Docker Content Trust (DCT) keeps audit logs of changes made to trusted repositories. +Every time you push a signed image to a repository, or delete trust data for a +repository, DCT logs that information. + +These logs are only available from the DTR API. + +## Get an authentication token + +To access the audit logs you need to authenticate your requests using an +authentication token. You can get an authentication token for all repositories, +or one that is specific to a single repository. + + +
+
+ +```bash +curl --insecure --silent \ +--user : \ +"https:///auth/token?realm=dtr&service=dtr&scope=registry:catalog:*" +``` + +
+
+ +```bash +curl --insecure --silent \ +--user : \ +"https:///auth/token?realm=dtr&service=dtr&scope=repository:/:pull" +``` + +
+
+ +DTR returns a JSON file with a token, even when the user doesn't have access +to the repository to which they requested the authentication token. This token +doesn't grant access to DTR repositories. + +The JSON file returned has the following structure: + + +```json +{ + "token": "", + "access_token": "", + "expires_in": "", + "issued_at": "