<commit_before>---
title: UCP release notes
description: Release notes for Docker Universal Control Plane. Learn more about the
  changes introduced in the latest versions.
keywords: UCP, release notes
toc_min: 1
toc_max: 2
redirect_from:
  - /datacenter/ucp/2.2/guides/release-notes/
  - /datacenter/ucp/3.0/guides/release-notes/
---

Here you can learn about new features, bug fixes, breaking changes, and
known issues for the latest UCP version.
You can then use [the upgrade instructions](admin/install/upgrade.md) to
upgrade your installation to the latest release.

* [Version 3.1](#version-31)
* [Version 3.0](#version-30)
* [Version 2.2](#version-22)

# Version 3.1

## 3.1.3

2019-01-29

### New platforms
 * Added support for Windows Server 2019 and Windows Server 1809. (docker/orca#15810)
 * Added support for RHEL 7.6 with Devicemapper and Overlay2 storage drivers. (docker/orca#15535)
 * Added support for Oracle Enterprise Linux 7.6 with Overlay2 storage driver. (docker/orca#15791)

### Networking
 * Upgraded Calico to version 3.5. (#15884)

### Bug Fixes
 * Fixed system hang following UCP backup and docker daemon shutdown. (docker/escalation#841)
 * Non-admin users can no longer create `PersistentVolumes` that mount host directories. (docker/orca#15936)
 * Added support for the limit arg in `docker ps`. (docker/orca#15812)
 * Fixed an issue with ucp-proxy health check. (docker/orca#15814, docker/orca#15813, docker/orca#16021, docker/orca#15811)
 
### Known issue
 * By default, Kubelet begins deleting images, starting with the oldest unused images, after exceeding 85% disk space utilization. This causes an issue in an air-gapped environment.

## 3.1.2

2019-01-09

### Authentication and Authorization
* SAML Single Logout is now supported in UCP.
* Identity Provider initiated SAML Single Sign-on is now supported in UCP.  The admin can 
enable this feature in Admin Settings -> SAML Settings.

### Bug Fixes
* Core
  * Significantly reduced database load in environments with a lot of concurrent 
  and repeated API requests by the same user. (docker/escalation#911)
  * UCP backend will now complain when a service is created/updated if the
   `com.docker.lb.network` label is not correctly specified. (docker/orca#15015) 
  * LDAP group member attribute is now case insensitive. (docker/escalation#917)
* Interlock
  * Interlock headers can now be hidden. (escalation#833)
  * Now upgrading Interlock will also upgrade interlock proxy and interlock extension as well (escalation/871)
  * Added support for 'VIP' backend mode, in which the Interlock proxy connects to the backend service's Virtual IP instead of load-balancing directly to each task IP. (docker/interlock#206) (escalation/920)

## 3.1.1 

(2018-12-04)

* To address CVE-2018-1002105, a critical security issue in the Kubernetes API Server, Docker is using Kubernetes 1.11.5 for UCP 3.1.1.

## 3.1.0 

2018-11-08

## Bug Fixes

* Swarm placement constraint warning banner no longer shows up for `ucp-auth` services (#14539)
* "update out of sequence" error messages no longer appear when changing admin settings (#7093)
* Kubernetes namespace status appears in the web interface (#14526)
* UCP Kubernetes compose components always run on managers (#14208)
* `docker network ls --filter id=<id>` now works with a UCP client bundle (#14840)
* Collection deletes are correctly blocked if there is a node in the collection (#13704)

## New Features

### Kubernetes

* Kubernetes is updated to version 1.11.2.
* Kubernetes native RBAC feature manages access control for Kubernetes resources. Users can now create roles for Kubernetes APIs using Kubernetes `Role` and `ClusterRole` objects in the Kubernetes API. They can also grant permissions to users and service accounts with the `RoleBinding` and `ClusterRoleBinding` objects. The web interface for Kubernetes RBAC reflects these changes. Your old Kubernetes grants and roles will be automatically migrated during the UCP upgrade.

### Logging

Admins can now enable audit logging in the UCP config. This logs all incoming user-initiated requests in the `ucp-controller` logs. Admins can choose whether to log only metadata for incoming requests or the full request body as well. For more information, see [Create UCP audit logs](https://docs.docker.com/ee/ucp/admin/configure/create-audit-logs/).

### Authentication

Admins can configure UCP to use a SAML-enabled identity provider for user authentication. If enabled, users who log into the UCP web interface are redirected to the identity provider's website to log in. Upon log in, users are redirected back to the UCP web interface, authenticated as the user chosen. For more information, see [Enable SAML authentication](https://docs.docker.com/ee/ucp/admin/configure/enable-saml-authentication/).

### Metrics

* The `ucp-metrics` Prometheus server (used to render charts in the UCP interface) was engineered from a container on manager nodes to a Kubernetes daemonset. This lets admins change the daemonset's scheduling rules so that it runs on a set of worker nodes instead of manager nodes. Admins can designate certain UCP nodes to be metrics server nodes, freeing up resources on manager nodes. For more information, see [Collect UCP cluster metrics with Prometheus](https://docs.docker.com/ee/ucp/admin/configure/collect-cluster-metrics/).
* The UCP controller has a `/metricsdiscovery` endpoint so users can connect their own Prometheus instances to scrape UCP metrics data.

### UCP web interface

* If you enable single sign-on for a DTR instance with UCP, the UCP web interface shows image vulnerability data for images in that DTR instance. Containers and services that use images from that DTR instance show any vulnerabilities DTR detects.
* The UCP web interface is redesigned to offer larger views for viewing individual resources, with more information for Kubernetes resources.

### Configs

* UCP now stores its configurations in its internal key-value store instead of in a Swarm configuration so changes can propagate across the cluster more quickly.
* You can now use the `custom_api_server_headers` field in the UCP configuration to set arbitrary headers that are included with every UCP response.

## API updates

There are several backward-incompatible changes in the Kubernetes API that may affect user workloads. They are:

  * A compatibility issue with the `allowPrivilegeEscalation` field that caused policies to start denying pods they previously allowed was fixed. If you defined `PodSecurityPolicy` objects using a 1.8.0 client or server and set `allowPrivilegeEscalation` to false, these objects must be reapplied after you upgrade.
  * These changes are automatically updated for taints. Tolerations for these taints must be updated manually. Specifically, you must:
    * Change `node.alpha.kubernetes.io/notReady` to `node.kubernetes.io/not-ready`
    * Change `node.alpha.kubernetes.io/unreachable` to `node.kubernetes.io/unreachable`
    For more information about taints and tolerations, see [Taints and Tolerations](https://kubernetes.io/docs/concepts/configuration/taint-and-toleration/).

* JSON configuration used with `kubectl create -f pod.json` containing fields with incorrect casing are no longer valid. You must correct these files before upgrading. When specifying keys in JSON resource definitions during direct API server communication, the keys are case-sensitive. A bug introduced in Kubernetes 1.8 caused the API server to accept a request with incorrect case and coerce it to correct case, but this behaviour has been fixed in 1.11 so the API server will again enforce correct casing. During this time, the `kubectl` tool continued to enforce case-sensitive keys, so users that strictly manage resources with `kubectl` will be unaffected by this change.
* If you have a pod with a subpath volume PVC, there’s a chance that after the upgrade, it will conflict with some other pod; see [this pull request](https://github.com/kubernetes/kubernetes/pull/61373). It’s not clear if this issue will just prevent those pods from starting or if the whole cluster will fail.

## Known issues
* There are important changes to the upgrade process that, if not correctly followed, can impact the availability of applications running on the Swarm during uprades. These constraints impact any upgrades coming from any Docker Engine version before 18.09 to version 18.09 or greater. For more information about about upgrading Docker Enterprise to version 2.1, see [Upgrade Docker](../upgrade)

* In the UCP web interface, LDAP settings disappear after submitting them. However, the settings are properly saved. (#15503)

* You must use the ID of the user, organization, or team if you manually create a **ClusterRoleBinding** or **RoleBinding** for `User` or `Group` subjects. (#14935)
    * For the `User` subject Kind, the `Name` field contains the ID of the user.
    * For the `Group` subject Kind, the format depends on whether you are create a Binding for a team or an organization:
        * For an organization, the format is `org:{org-id}`
        * For a team, the format is `team:{org-id}:{team-id}`

* To deploy Pods with containers using Restricted Parameters, the user must be an admin and a service account must explicitly have a **ClusterRoleBinding** with `cluster-admin` as the  **ClusterRole**. Restricted Parameters on Containers include:
    * Host Bind Mounts
    * Privileged Mode
    * Extra Capabilities
    * Host Networking
    * Host IPC
    * Host PID

* If you delete the built-in **ClusterRole** or **ClusterRoleBinding** for `cluster-admin`, restart the `ucp-kube-apiserver` container on any manager node to recreate them. (#14483)

* Pod Security Policies are not supported in this release. (#15105)

* The default Kubelet configuration for UCP Manager nodes is expecting 4GB of free disk space in the `/var` partition. See [System Requirements](/ee/ucp/admin/install/system-requirements) for details.

## Deprecated features

The following features are deprecated in UCP 3.1.

* Collections
    *  User-created nested collections more than 2 layers deep within the root `/Swarm/` collection are deprecated and will be removed in future versions of the product. In the future, we recommend that at most only two levels of collections be created within UCP under the shared Cluster collection designated as `/Swarm/`. For example, if a production collection is created as a collection under the cluster collection `/Swarm/` as `/Swarm/production/` then at most one level of nestedness should be created, as in `/Swarm/production/app/`.

* Kubernetes
    * **PersistentVolumeLabel** admission controller is deprecated in Kubernetes 1.11. This functionality will be migrated to [Cloud Controller Manager](https://kubernetes.io/docs/tasks/administer-cluster/running-cloud-controller/](https://kubernetes.io/docs/tasks/administer-cluster/running-cloud-controller/)
    * `--cni-install-url` is deprecated in favor of `--unmanaged-cni`

# Version 3.0

## 3.0.9

2018-01-29

### New platforms
 * Added support for RHEL 7.6 with Devicemapper and Overlay2 storage drivers. (docker/orca#15996)

### Bug fixes
  * Upgrading Interlock now also upgrades interlock proxy and interlock extension. (docker/escalation/871)
  * Non-admin users can no longer create `PersistentVolumes` that mount host directories. (#15936)
  * Added support for the limit arg in `docker ps`. (#15812)
  
### Known issue
  * By default, Kubelet begins deleting images, starting with the oldest unused images, after exceeding 85% disk space utilization. This causes an issue in an air-gapped environment.

## 3.0.8

2019-01-09

### Bug fixes
* Core
  * Significantly reduced database load in environments with a lot of concurrent 
  and repeated API requests by the same user. (docker/escalation#911)
  * Added the ability to set custom HTTP response headers to be returned by the
   UCP Controller API Server. (docker/orca#10733)
  * UCP backend will now complain when a service is created/updated if the
   `com.docker.lb.network` label is not correctly specified. (docker/orca#15015) 
  * LDAP group member attribute is now case insensitive. (docker/escalation#917)
  * Fixed an issue that caused a system hang after the attempted shutdown of the Docker daemon to perform a swarm backup.  /dev/shm is now unmounted when starting the kubelet container. (docker/orca#15672)
  * Fixed system hang issue following UCP backup and docker daemon shutdown. (docker/escalation#841)
  
* Interlock
  * Interlock headers can now be hidden. (docker/escalation#833)
  * Respect `com.docker.lb.network` labels and only attach the specified networks
    to the Interlock proxy. (docker/interlock#169)
  * Add support for 'VIP' backend mode, in which the Interlock proxy connects to the 
     backend service's Virtual IP instead of load-balancing directly to each task IP. 
     (docker/interlock#206, escalation/920)<commit_msg>Fixed 3.0.8 duplicate info<commit_after>---
title: UCP release notes
description: Release notes for Docker Universal Control Plane. Learn more about the
  changes introduced in the latest versions.
keywords: UCP, release notes
toc_min: 1
toc_max: 2
redirect_from:
  - /datacenter/ucp/2.2/guides/release-notes/
  - /datacenter/ucp/3.0/guides/release-notes/
---

Here you can learn about new features, bug fixes, breaking changes, and
known issues for the latest UCP version.
You can then use [the upgrade instructions](admin/install/upgrade.md) to
upgrade your installation to the latest release.

* [Version 3.1](#version-31)
* [Version 3.0](#version-30)
* [Version 2.2](#version-22)

# Version 3.1

## 3.1.3

2019-01-29

### New platforms
 * Added support for Windows Server 2019 and Windows Server 1809. (docker/orca#15810)
 * Added support for RHEL 7.6 with Devicemapper and Overlay2 storage drivers. (docker/orca#15535)
 * Added support for Oracle Enterprise Linux 7.6 with Overlay2 storage driver. (docker/orca#15791)

### Networking
 * Upgraded Calico to version 3.5. (#15884)

### Bug Fixes
 * Fixed system hang following UCP backup and docker daemon shutdown. (docker/escalation#841)
 * Non-admin users can no longer create `PersistentVolumes` that mount host directories. (docker/orca#15936)
 * Added support for the limit arg in `docker ps`. (docker/orca#15812)
 * Fixed an issue with ucp-proxy health check. (docker/orca#15814, docker/orca#15813, docker/orca#16021, docker/orca#15811)
 
### Known issue
 * By default, Kubelet begins deleting images, starting with the oldest unused images, after exceeding 85% disk space utilization. This causes an issue in an air-gapped environment.

## 3.1.2

2019-01-09

### Authentication and Authorization
* SAML Single Logout is now supported in UCP.
* Identity Provider initiated SAML Single Sign-on is now supported in UCP.  The admin can 
enable this feature in Admin Settings -> SAML Settings.

### Bug Fixes
* Core
  * Significantly reduced database load in environments with a lot of concurrent 
  and repeated API requests by the same user. (docker/escalation#911)
  * UCP backend will now complain when a service is created/updated if the
   `com.docker.lb.network` label is not correctly specified. (docker/orca#15015) 
  * LDAP group member attribute is now case insensitive. (docker/escalation#917)
* Interlock
  * Interlock headers can now be hidden. (escalation#833)
  * Now upgrading Interlock will also upgrade interlock proxy and interlock extension as well (escalation/871)
  * Added support for 'VIP' backend mode, in which the Interlock proxy connects to the backend service's Virtual IP instead of load-balancing directly to each task IP. (docker/interlock#206) (escalation/920)

## 3.1.1 

(2018-12-04)

* To address CVE-2018-1002105, a critical security issue in the Kubernetes API Server, Docker is using Kubernetes 1.11.5 for UCP 3.1.1.

## 3.1.0 

2018-11-08

## Bug Fixes

* Swarm placement constraint warning banner no longer shows up for `ucp-auth` services (#14539)
* "update out of sequence" error messages no longer appear when changing admin settings (#7093)
* Kubernetes namespace status appears in the web interface (#14526)
* UCP Kubernetes compose components always run on managers (#14208)
* `docker network ls --filter id=<id>` now works with a UCP client bundle (#14840)
* Collection deletes are correctly blocked if there is a node in the collection (#13704)

## New Features

### Kubernetes

* Kubernetes is updated to version 1.11.2.
* Kubernetes native RBAC feature manages access control for Kubernetes resources. Users can now create roles for Kubernetes APIs using Kubernetes `Role` and `ClusterRole` objects in the Kubernetes API. They can also grant permissions to users and service accounts with the `RoleBinding` and `ClusterRoleBinding` objects. The web interface for Kubernetes RBAC reflects these changes. Your old Kubernetes grants and roles will be automatically migrated during the UCP upgrade.

### Logging

Admins can now enable audit logging in the UCP config. This logs all incoming user-initiated requests in the `ucp-controller` logs. Admins can choose whether to log only metadata for incoming requests or the full request body as well. For more information, see [Create UCP audit logs](https://docs.docker.com/ee/ucp/admin/configure/create-audit-logs/).

### Authentication

Admins can configure UCP to use a SAML-enabled identity provider for user authentication. If enabled, users who log into the UCP web interface are redirected to the identity provider's website to log in. Upon log in, users are redirected back to the UCP web interface, authenticated as the user chosen. For more information, see [Enable SAML authentication](https://docs.docker.com/ee/ucp/admin/configure/enable-saml-authentication/).

### Metrics

* The `ucp-metrics` Prometheus server (used to render charts in the UCP interface) was engineered from a container on manager nodes to a Kubernetes daemonset. This lets admins change the daemonset's scheduling rules so that it runs on a set of worker nodes instead of manager nodes. Admins can designate certain UCP nodes to be metrics server nodes, freeing up resources on manager nodes. For more information, see [Collect UCP cluster metrics with Prometheus](https://docs.docker.com/ee/ucp/admin/configure/collect-cluster-metrics/).
* The UCP controller has a `/metricsdiscovery` endpoint so users can connect their own Prometheus instances to scrape UCP metrics data.

### UCP web interface

* If you enable single sign-on for a DTR instance with UCP, the UCP web interface shows image vulnerability data for images in that DTR instance. Containers and services that use images from that DTR instance show any vulnerabilities DTR detects.
* The UCP web interface is redesigned to offer larger views for viewing individual resources, with more information for Kubernetes resources.

### Configs

* UCP now stores its configurations in its internal key-value store instead of in a Swarm configuration so changes can propagate across the cluster more quickly.
* You can now use the `custom_api_server_headers` field in the UCP configuration to set arbitrary headers that are included with every UCP response.

## API updates

There are several backward-incompatible changes in the Kubernetes API that may affect user workloads. They are:

  * A compatibility issue with the `allowPrivilegeEscalation` field that caused policies to start denying pods they previously allowed was fixed. If you defined `PodSecurityPolicy` objects using a 1.8.0 client or server and set `allowPrivilegeEscalation` to false, these objects must be reapplied after you upgrade.
  * These changes are automatically updated for taints. Tolerations for these taints must be updated manually. Specifically, you must:
    * Change `node.alpha.kubernetes.io/notReady` to `node.kubernetes.io/not-ready`
    * Change `node.alpha.kubernetes.io/unreachable` to `node.kubernetes.io/unreachable`
    For more information about taints and tolerations, see [Taints and Tolerations](https://kubernetes.io/docs/concepts/configuration/taint-and-toleration/).

* JSON configuration used with `kubectl create -f pod.json` containing fields with incorrect casing are no longer valid. You must correct these files before upgrading. When specifying keys in JSON resource definitions during direct API server communication, the keys are case-sensitive. A bug introduced in Kubernetes 1.8 caused the API server to accept a request with incorrect case and coerce it to correct case, but this behaviour has been fixed in 1.11 so the API server will again enforce correct casing. During this time, the `kubectl` tool continued to enforce case-sensitive keys, so users that strictly manage resources with `kubectl` will be unaffected by this change.
* If you have a pod with a subpath volume PVC, there’s a chance that after the upgrade, it will conflict with some other pod; see [this pull request](https://github.com/kubernetes/kubernetes/pull/61373). It’s not clear if this issue will just prevent those pods from starting or if the whole cluster will fail.

## Known issues
* There are important changes to the upgrade process that, if not correctly followed, can impact the availability of applications running on the Swarm during uprades. These constraints impact any upgrades coming from any Docker Engine version before 18.09 to version 18.09 or greater. For more information about about upgrading Docker Enterprise to version 2.1, see [Upgrade Docker](../upgrade)

* In the UCP web interface, LDAP settings disappear after submitting them. However, the settings are properly saved. (#15503)

* You must use the ID of the user, organization, or team if you manually create a **ClusterRoleBinding** or **RoleBinding** for `User` or `Group` subjects. (#14935)
    * For the `User` subject Kind, the `Name` field contains the ID of the user.
    * For the `Group` subject Kind, the format depends on whether you are create a Binding for a team or an organization:
        * For an organization, the format is `org:{org-id}`
        * For a team, the format is `team:{org-id}:{team-id}`

* To deploy Pods with containers using Restricted Parameters, the user must be an admin and a service account must explicitly have a **ClusterRoleBinding** with `cluster-admin` as the  **ClusterRole**. Restricted Parameters on Containers include:
    * Host Bind Mounts
    * Privileged Mode
    * Extra Capabilities
    * Host Networking
    * Host IPC
    * Host PID

* If you delete the built-in **ClusterRole** or **ClusterRoleBinding** for `cluster-admin`, restart the `ucp-kube-apiserver` container on any manager node to recreate them. (#14483)

* Pod Security Policies are not supported in this release. (#15105)

* The default Kubelet configuration for UCP Manager nodes is expecting 4GB of free disk space in the `/var` partition. See [System Requirements](/ee/ucp/admin/install/system-requirements) for details.

## Deprecated features

The following features are deprecated in UCP 3.1.

* Collections
    *  User-created nested collections more than 2 layers deep within the root `/Swarm/` collection are deprecated and will be removed in future versions of the product. In the future, we recommend that at most only two levels of collections be created within UCP under the shared Cluster collection designated as `/Swarm/`. For example, if a production collection is created as a collection under the cluster collection `/Swarm/` as `/Swarm/production/` then at most one level of nestedness should be created, as in `/Swarm/production/app/`.

* Kubernetes
    * **PersistentVolumeLabel** admission controller is deprecated in Kubernetes 1.11. This functionality will be migrated to [Cloud Controller Manager](https://kubernetes.io/docs/tasks/administer-cluster/running-cloud-controller/](https://kubernetes.io/docs/tasks/administer-cluster/running-cloud-controller/)
    * `--cni-install-url` is deprecated in favor of `--unmanaged-cni`

# Version 3.0

## 3.0.9

2018-01-29

### New platforms
 * Added support for RHEL 7.6 with Devicemapper and Overlay2 storage drivers. (docker/orca#15996)

### Bug fixes
  * Upgrading Interlock now also upgrades interlock proxy and interlock extension. (docker/escalation/871)
  * Non-admin users can no longer create `PersistentVolumes` that mount host directories. (#15936)
  * Added support for the limit arg in `docker ps`. (#15812)
  
### Known issue
  * By default, Kubelet begins deleting images, starting with the oldest unused images, after exceeding 85% disk space utilization. This causes an issue in an air-gapped environment.

## 3.0.8

2019-01-09

### Bug fixes
* Core
  * Significantly reduced database load in environments with a lot of concurrent 
  and repeated API requests by the same user. (docker/escalation#911)
  * Added the ability to set custom HTTP response headers to be returned by the
   UCP Controller API Server. (docker/orca#10733)
  * UCP backend will now complain when a service is created/updated if the
   `com.docker.lb.network` label is not correctly specified. (docker/orca#15015) 
  * LDAP group member attribute is now case insensitive. (docker/escalation#917)
  * Fixed an issue that caused a system hang after UCP backup and the attempted shutdown of the Docker daemon to perform a swarm backup. /dev/shm is now unmounted when starting the kubelet container. (docker/orca#15672, docker/escalation#841)
  
* Interlock
  * Interlock headers can now be hidden. (docker/escalation#833)
  * Respect `com.docker.lb.network` labels and only attach the specified networks
    to the Interlock proxy. (docker/interlock#169)
  * Add support for 'VIP' backend mode, in which the Interlock proxy connects to the 
     backend service's Virtual IP instead of load-balancing directly to each task IP. 
     (docker/interlock#206, escalation/920)
{'fraction_non_alphanumeric': 0.07026023742314683, 'fraction_numerical': 0.026565098024051662, 'mean_word_length': 4.4048066875653085, 'pattern_counts': {'":': 0, '<': 5, '<?xml version=': 0, '>': 7, 'https://': 14, 'lorem ipsum': 0, 'www.': 0, 'xml': 0}, 'pii_count': 0, 'substrings_counts': 0, 'word_list_counts': {'cursed_substrings.json': 0, 'profanity_word_list.json': 0, 'sexual_word_list.json': 0, 'zh_pornsignals.json': 0}}
{'dir': 'git-commits-cleaned', 'id': '3183520', 'n_tokens_mistral': 7499, 'n_tokens_neox': 6679, 'n_words': 3360}