docker
/
docs
mirror of https://github.com/docker/docs.git
1
0
Fork 0
Code Issues Packages Projects Releases Wiki Activity

Merge pull request #792 from docker/ucp-config-729 

UCP config updates 729
This commit is contained in:
Justin I. Nevill 2018-10-18 13:41:33 -04:00 committed by GitHub
parent b6c1aec3a8 d5020cb468
commit 7c1e8c9231
No known key found for this signature in database
GPG Key ID: 4AEE18F83AFDEB23
5 changed files with 55 additions and 179 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

2
_data/toc.yaml
View File

@ -1572,8 +1572,6 @@ manuals:
title: Enable SAML authentication
- 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/

68
ee/ucp/admin/configure/external-auth/enable-ldap-config-file.md
View File

@ -1,68 +0,0 @@
---
title: Integrate with LDAP by using a configuration file
description: Set up LDAP authentication by using a configuration file.
keywords: UCP, LDAP, config
---
Docker UCP integrates with LDAP directory services, so that you can manage
users and groups from your organization's directory and automatically
propagate this information to UCP and DTR. You can set up your cluster's LDAP
configuration by using the UCP web UI, or you can use a
[UCP configuration file](../ucp-configuration-file.md).
To see an example TOML config file that shows how to configure UCP settings,
run UCP with the `example-config` option.
[Learn about UCP configuration files](../ucp-configuration-file.md).
```bash
docker container run --rm {{ page.ucp_org }}/{{ page.ucp_repo }}:{{ page.ucp_version }} example-config
```
## Set up LDAP by using a configuration file
1. Use the following command to extract the name of the currently active
configuration from the `ucp-agent` service.
```bash
{% raw %}
$ CURRENT_CONFIG_NAME=$(docker service inspect --format '{{ range $config := .Spec.TaskTemplate.ContainerSpec.Configs }}{{ $config.ConfigName }}{{ "\n" }}{{ end }}' ucp-agent | grep 'com.docker.ucp.config-')
{% endraw %}
```
2. Get the current configuration and save it to a TOML file.
```bash
{% raw %}
docker config inspect --format '{{ printf "%s" .Spec.Data }}' $CURRENT_CONFIG_NAME > config.toml
{% endraw %}
```
3. Use the output of the `example-config` command as a guide to edit your
`config.toml` file. Under the `[auth]` sections, set `backend = "ldap"`
and `[auth.ldap]` to configure LDAP integration the way you want.
4. Once you've finished editing your `config.toml` file, create a new Docker
Config object by using the following command.
```bash
NEW_CONFIG_NAME="com.docker.ucp.config-$(( $(cut -d '-' -f 2 <<< "$CURRENT_CONFIG_NAME") + 1 ))"
docker config create $NEW_CONFIG_NAME config.toml
```
5. Update the `ucp-agent` service to remove the reference to the old config
and add a reference to the new config.
```bash
docker service update --config-rm "$CURRENT_CONFIG_NAME" --config-add "source=${NEW_CONFIG_NAME},target=/etc/ucp/ucp.toml" ucp-agent
```
6. Wait a few moments for the `ucp-agent` service tasks to update across
your cluster. If you set `jit_user_provisioning = true` in the LDAP
configuration, users matching any of your specified search queries will
have their accounts created when they log in with their username and LDAP
password.
## Where to go next
- [Create users and teams manually](../../../authorization/create-users-and-teams-manually.md)
- [Create teams with LDAP](../../../authorization/create-teams-with-ldap.md)

8
ee/ucp/admin/configure/set-session-timeout.md
View File

@ -7,7 +7,7 @@ keywords: UCP, authorization, authentication, security, session, timeout
Docker Universal Control Plane enables setting properties of user sessions,
like session timeout and number of concurrent sessions.
To configure UCP login sessions, go to the UCP web UI, navigate to the
To configure UCP login sessions, go to the UCP web interface, navigate to the
**Admin Settings** page and click **Authentication & Authorization**.
![](../../images/authentication-authorization.png)
@ -16,6 +16,6 @@ To configure UCP login sessions, go to the UCP web UI, navigate to the
| Field | Description |
| :---------------------- | :-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Lifetime Minutes | The initial lifetime of a login session, from the time UCP generates it. When this time expires, UCP invalidates the session, and the user must authenticate again to establish a new session. The default is 4320 minutes, which is 72 hours. |
| Renewal Threshold Minutes | The time before session expiration when UCP extends an active session. UCP extends the session by the number of hours specified in **Lifetime Hours**. The threshold value can't be greater than **Lifetime Hours**. The default is 1440 minutes, which is 24 hours. To specify that sessions are extended with every use, set the threshold equal to the lifetime. To specify that sessions are never extended, set the threshold to zero. This may cause users to be logged out unexpectedly while using the UCP web UI. |
| Per User Limit | The maximum number of simultaneous logins for a user. If creating a new session exceeds this limit, UCP deletes the least recently used session. To disable the limit, set the value to zero. |
| Lifetime Minutes | The initial lifetime of a login session, starting from the time UCP generates the session. When this time expires, UCP invalidates the active session. To establish a new session, the user must authenticate again. The default is 60 minutes with a minimum of 10 minutes. |
| Renewal Threshold Minutes | The time by which UCP extends an active session before session expiration. UCP extends the session by the number of minutes specified in **Lifetime Minutes**. The threshold value can't be greater than **Lifetime Minutes**. The default extension is 20 minutes. To specify that no sessions are extended, set the threshold value to zero. This may cause users to be logged out unexpectedly while using the UCP web interface. The maximum threshold is 5 minutes less than **Lifetime Minutes**. |
| Per User Limit | The maximum number of simultaneous logins for a user. If creating a new session exceeds this limit, UCP deletes the least recently used session. Every time you use a session token, the server marks it with the current time (`lastUsed` metadata). When you create a new session that would put you over the per user limit, the session with the oldest `lastUsed` time is deleted. This is not necessarily the oldest session. To disable this limit, set the value to zero. The default limit is 10 sessions. |

153
ee/ucp/admin/configure/ucp-configuration-file.md
View File

@ -4,62 +4,52 @@ description: Set up UCP deployments by using a configuration file.
keywords: Docker EE, UCP, configuration, config
---
You have two options to configure UCP: through the web UI, or using a Docker
config object. In most cases, the web UI is a front-end for changing the
configuration file.
There are two ways to configure UCP:
- through the web interface, or
- by importing and exporting the UCP config in a TOML file. For more information about TOML, see the [TOML README on GitHub](https://github.com/toml-lang/toml/blob/master/README.md).
You can customize how UCP is installed by creating a configuration file upfront.
During the installation UCP detects and starts using the configuration.
You can customize the UCP installation by creating a configuration file at the
time of installation. During the installation, UCP detects and starts using the
configuration specified in this file.
## UCP configuration file
## The UCP configuration file
The `ucp-agent` service uses a configuration file to set up UCP.
You can use the configuration file in different ways to set up your UCP
cluster.
- Install one cluster and use the UCP web UI to configure it as desired,
extract the configuration file, edit it as needed, and use the edited
config file to make copies to multiple other cluster.
- Install a UCP cluster, extract and edit the configuration file, and use the
CLI to apply the new configuration to the same cluster.
- Install one cluster and use the UCP web interface to configure it as desired,
export the configuration file, edit it as needed, and then import the edited
configuration file into multiple other clusters.
- Install a UCP cluster, export and edit the configuration file, and then use the
API to import the new configuration into the same cluster.
- Run the `example-config` command, edit the example configuration file, and
apply the file at install time or after installation.
set the configuration at install time or import after installation.
Specify your configuration settings in a TOML file.
[Learn about Tom's Obvious, Minimal Language](https://github.com/toml-lang/toml/blob/master/README.md).
The configuration has a versioned naming convention, with a trailing decimal
number that increases with each version, like `com.docker.ucp.config-1`. The
`ucp-agent` service maps the configuration to the file at `/etc/ucp/ucp.toml`.
## Export and modify an existing configuration
## Inspect and modify existing configuration
Use the `docker config inspect` command to view the current settings and emit
them to a file.
Use the `config-toml` API to export the current settings and write them to a file. Within the directory of a UCP admin user's [client certificate bundle](../../user-access/cli.md), the following command exports the current configuration for the UCP hostname `UCP_HOST` to a file named `ucp-config.toml`:
```bash
{% raw %}
# CURRENT_CONFIG_NAME will be the name of the currently active UCP configuration
CURRENT_CONFIG_NAME=$(docker service inspect ucp-agent --format '{{range .Spec.TaskTemplate.ContainerSpec.Configs}}{{if eq "/etc/ucp/ucp.toml" .File.Name}}{{.ConfigName}}{{end}}{{end}}')
# Collect the current config with `docker config inspect`
docker config inspect --format '{{ printf "%s" .Spec.Data }}' $CURRENT_CONFIG_NAME > ucp-config.toml
{% endraw %}
curl --cacert ca.pem --cert cert.pem --key key.pem https://UCP_HOST/api/ucp/config-toml > ucp-config.toml
```
Edit the file, then use the `docker config create` and `docker service update`
commands to create and apply the configuration from the file.
Edit `ucp-config.toml`, then use the following `curl` command to import it back into
UCP and apply your configuration changes:
```bash
# NEXT_CONFIG_NAME will be the name of the new UCP configuration
NEXT_CONFIG_NAME=${CURRENT_CONFIG_NAME%%-*}-$((${CURRENT_CONFIG_NAME##*-}+1))
# Create the new cluster configuration from the file ucp-config.toml
docker config create $NEXT_CONFIG_NAME ucp-config.toml
# Use the `docker service update` command to remove the current configuration
# and apply the new configuration to the `ucp-agent` service.
docker service update --config-rm $CURRENT_CONFIG_NAME --config-add source=$NEXT_CONFIG_NAME,target=/etc/ucp/ucp.toml ucp-agent
curl --cacert ca.pem --cert cert.pem --key key.pem --upload-file ucp-config.toml https://UCP_HOST/api/ucp/config-toml
```
## Apply an existing configuration file at install time
You can configure UCP to import an existing configuration file at install time. To do this using the **Configs** feature of Docker Swarm, follow these steps.
1. Create a **Docker Swarm Config** object with a name of `com.docker.ucp.config` and the TOML value of your UCP configuration file contents.
2. When installing UCP on that cluster, specify the `--existing-config` flag to have the installer use that object for its initial configuration.
3. After installation, delete the `com.docker.ucp.config` object.
## Example configuration file
You can see an example TOML config file that shows how to configure UCP
@ -87,70 +77,6 @@ docker container run --rm {{ page.ucp_org }}/{{ page.ucp_repo }}:{{ page.ucp_ver
| `renewal_threshold_minutes` | no | The length of time, in minutes, before the expiration of a session where, if used, a session will be extended by the current configured lifetime from then. A zero value disables session extension. The default is 1440, which is 24 hours. |
| `per_user_limit` | no | The maximum number of sessions that a user can have active simultaneously. If creating a new session would put a user over this limit, the least recently used session will be deleted. A value of zero disables limiting the number of sessions that users may have. The default is 5. |
### auth.ldap (optional)
| Parameter | Required | Description |
|:------------------------|:---------|:---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
| `server_url` | no | The URL of the LDAP server. |
| `no_simple_pagination` | no | Set to `true` if the LDAP server doesn't support the Simple Paged Results control extension (RFC 2696). The default is `false`. |
| `start_tls` | no | Set to `true` to use StartTLS to secure the connection to the server, ignored if the server URL scheme is 'ldaps://'. The default is `false`. |
| `root_certs` | no | A root certificate PEM bundle to use when establishing a TLS connection to the server. |
| `tls_skip_verify` | no | Set to `true` to skip verifying the server's certificate when establishing a TLS connection, which isn't recommended unless testing on a secure network. The default is `false`. |
| `reader_dn` | no | The distinguished name the system uses to bind to the LDAP server when performing searches. |
| `reader_password` | no | The password that the system uses to bind to the LDAP server when performing searches. |
| `sync_schedule` | no | The scheduled time for automatic LDAP sync jobs, in CRON format. Needs to have the seconds field set to zero. The default is @hourly if empty or omitted. |
| `jit_user_provisioning` | no | Whether to only create user accounts upon first login (recommended). The default is `true`. |
### auth.ldap.additional_domains array (optional)
A list of additional LDAP domains and corresponding server configs from which
to sync users and team members. This is an advanced feature which most
environments don't need.
| Parameter | Required | Description |
|:-----------------------|:---------|:----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
| `domain` | no | The root domain component of this server, for example, `dc=example,dc=com`. A longest-suffix match of the base DN for LDAP searches is used to select which LDAP server to use for search requests. If no matching domain is found, the default LDAP server config is used. |
| `server_url` | no | The URL of the LDAP server for the current additional domain. |
| `no_simple_pagination` | no | Set to true if the LDAP server for this additional domain does not support the Simple Paged Results control extension (RFC 2696). The default is `false`. |
| `server_url` | no | The URL of the LDAP server. |
| `start_tls` | no | Whether to use StartTLS to secure the connection to the server, ignored if the server URL scheme is 'ldaps://'. |
| `root_certs` | no | A root certificate PEM bundle to use when establishing a TLS connection to the server for the current additional domain. |
| `tls_skip_verify` | no | Whether to skip verifying the additional domain server's certificate when establishing a TLS connection, not recommended unless testing on a secure network. The default is `true`. |
| `reader_dn` | no | The distinguished name the system uses to bind to the LDAP server when performing searches under the additional domain. |
| `reader_password` | no | The password that the system uses to bind to the LDAP server when performing searches under the additional domain. |
### auth.ldap.user_search_configs array (optional)
Settings for syncing users.
| Parameter | Required | Description |
|:--------------------------|:---------|:-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
| `base_dn` | no | The distinguished name of the element from which the LDAP server will search for users, for example, `ou=people,dc=example,dc=com`. |
| `scope_subtree` | no | Set to `true` to search for users in the entire subtree of the base DN. Set to `false` to search only one level under the base DN. The default is `false`. |
| `username_attr` | no | The name of the attribute of the LDAP user element which should be selected as the username. The default is `uid`. |
| `full_name_attr` | no | The name of the attribute of the LDAP user element which should be selected as the full name of the user. The default is `cn`. |
| `filter` | no | The LDAP search filter used to select user elements, for example, `(&(objectClass=person)(objectClass=user))`. May be left blank. |
| `match_group` | no | Whether to additionally filter users to those who are direct members of a group. The default is `true`. |
| `match_group_dn` | no | The distinguished name of the LDAP group, for example, `cn=ddc-users,ou=groups,dc=example,dc=com`. Required if `matchGroup` is `true`. |
| `match_group_member_attr` | no | The name of the LDAP group entry attribute which corresponds to distinguished names of members. Required if `matchGroup` is `true`. The default is `member`. |
| `match_group_iterate` | no | Set to `true` to get all of the user attributes by iterating through the group members and performing a lookup for each one separately. Use this instead of searching users first, then applying the group selection filter. Ignored if `matchGroup` is `false`. The default is `false`. |
### auth.ldap.admin_sync_opts (optional)
Settings for syncing system admininistrator users.
| Parameter | Required | Description |
|:-----------------------|:---------|:----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
| `enable_sync` | no | Set to `true` to enable syncing admins. If `false`, all other fields in this table are ignored. The default is `true`. |
| `select_group_members` | no | Set to `true` to sync using a group DN and member attribute selection. Set to `false` to use a search filter. The default is `true`. |
| `group_dn` | no | The distinguished name of the LDAP group, for example, `cn=ddc-admins,ou=groups,dc=example,dc=com`. Required if `select_group_members` is `true`. |
| `group_member_attr` | no | The name of the LDAP group entry attribute which corresponds to distinguished names of members. Required if `select_group_members` is `true`. The default is `member`. |
| `search_base_dn` | no | The distinguished name of the element from which the LDAP server will search for users, for example, `ou=people,dc=example,dc=com`. Required if `select_group_members` is `false`. |
| `search_scope_subtree` | no | Set to `true` to search for users in the entire subtree of the base DN. Set to `false` to search only one level under the base DN. The default is `false`. Required if `select_group_members` is `false`. |
| `search_filter` | no | The LDAP search filter used to select users if `select_group_members` is `false`, for example, `(memberOf=cn=ddc-admins,ou=groups,dc=example,dc=com)`. May be left blank. |
### registries array (optional)
An array of tables that specifies the DTR instances that the current UCP instance manages.
@ -159,7 +85,28 @@ An array of tables that specifies the DTR instances that the current UCP instanc
|:---------------|:---------|:--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
| `host_address` | yes | The address for connecting to the DTR instance tied to this UCP cluster. |
| `service_id` | yes | The DTR instance's OpenID Connect Client ID, as registered with the Docker authentication provider. |
| `ca_bundle` | no | If you're using a custom certificate authority (CA), the `ca_bundle` setting specifies the root CA bundle for the DTR instance. The value is a string with the contents of a `ca.pem` file. |
| `ca_bundle` | no | If you're using a custom certificate authority (CA), `ca_bundle` specifies the root CA bundle for the DTR instance. The value is a string with the contents of a `ca.pem` file. |
### custom headers (optional)
Included when you need to set custom API headers. You can repeat this section multiple times to specify multiple separate headers. If you include custom headers, you must specify both `name` and `value`.
[custom_api_server_headers]
| Item | Description |
| ----------- | ----------- |
| `name` | Set to specify the name of the custom header with `name` = "*X-Custom-Header-Name*". |
| `value` | Set to specify the value of the custom header with `value` = "*Custom Header Value*". |
### audit_log_configuration table (optional)
Configures audit logging options for UCP components.
| Parameter | Required | Description |
|:---------------|:---------|:--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
| `level` | no | Specify the audit logging level. Leave empty for disabling audit logs (default). Other legal values are `metadata` and `request`. |
| `support_dump_include_audit_logs` | no | When set to true, support dumps will include audit logs in the logs of the `ucp-controller` container of each manager node. The default is `false`. |
### scheduling_configuration table (optional)
@ -202,7 +149,7 @@ Configures the logging options for UCP components.
### license_configuration table (optional)
Specifies whether the your UCP license is automatically renewed.
Specifies whether the your UCP license is automatically renewed.
| Parameter | Required | Description |
|:---------------|:---------|:----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
@ -229,7 +176,7 @@ components. Assigning these values overrides the settings in a container's
| `profiling_enabled` | no | Set to `true` to enable specialized debugging endpoints for profiling UCP performance. The default is `false`. |
| `kv_timeout` | no | Sets the key-value store timeout setting, in milliseconds. The default is `5000`. |
| `kv_snapshot_count` | no | Sets the key-value store snapshot count setting. The default is `20000`. |
| `external_service_lb` | no | Specifies an optional external load balancer for default links to services with exposed ports in the web UI. |
| `external_service_lb` | no | Specifies an optional external load balancer for default links to services with exposed ports in the web interface. |
| `cni_installer_url` | no | Specifies the URL of a Kubernetes YAML file to be used for installing a CNI plugin. Applies only during initial installation. If empty, the default CNI plugin is used. |
| `metrics_retention_time` | no | Adjusts the metrics retention time. |
| `metrics_scrape_interval` | no | Sets the interval for how frequently managers gather metrics from nodes in the cluster. |

3
ee/ucp/ucp-architecture.md
View File

@ -180,14 +180,13 @@ driver.
By default, the data for these volumes can be found at
`/var/lib/docker/volumes/<volume-name>/_data`.
## Configurations use by UCP
## Configurations used by UCP
| Configuration name | Description |
|:-------------------------------|:-------------------------------------------------------------------------------------------------|
| com.docker.interlock.extension | Configuration for the Interlock extension service that monitors and configures the proxy service |
| com.docker.interlock.proxy | Configuration for the service responsible for handling user requests and routing them |
| com.docker.license | The Docker EE license |
| com.docker.ucp.config | The UCP controller configuration. Most of the settings available on the UCP UI are stored here |
| com.docker.ucp.interlock.conf | Configuration for the core Interlock service |
## How you interact with UCP