diff --git a/_data/toc.yaml b/_data/toc.yaml index ef0739e115..626927284d 100644 --- a/_data/toc.yaml +++ b/_data/toc.yaml @@ -1638,6 +1638,8 @@ manuals: title: Integrate with Docker Trusted Registry - path: /datacenter/ucp/2.2/guides/admin/configure/external-auth/ title: Integrate with LDAP + - path: /datacenter/ucp/2.2/guides/admin/configure/external-auth/enable-ldap-config-file + title: Integrate with LDAP by using a configuration file - sectiontitle: Manage users section: - path: /datacenter/ucp/2.2/guides/admin/manage-users/ diff --git a/datacenter/ucp/2.2/guides/admin/configure/external-auth/enable-ldap-config-file.md b/datacenter/ucp/2.2/guides/admin/configure/external-auth/enable-ldap-config-file.md new file mode 100644 index 0000000000..f39e1b891d --- /dev/null +++ b/datacenter/ucp/2.2/guides/admin/configure/external-auth/enable-ldap-config-file.md @@ -0,0 +1,64 @@ +--- +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 swarm'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 + $ CURRENT_CONFIG_NAME=$(docker service inspect --format '{{ range $config := .Spec.TaskTemplate.ContainerSpec.Configs }}{{ $config.ConfigName }}{{ "\n" }}{{ end }}' ucp-agent | grep 'com.docker.ucp.config-') + ``` + +2. Get the current configuration and save it to a TOML file. + + ```bash + $ docker config inspect --format '{{ printf "%s" .Spec.Data }}' $CURRENT_CONFIG_NAME > config.toml + ``` + +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 swarm. 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 and manage users](../../manage-users/create-and-manage-users.md) +- [Create and manage teams](../../manage-users/create-and-manage-teams.md) \ No newline at end of file diff --git a/datacenter/ucp/2.2/guides/admin/configure/external-auth/index.md b/datacenter/ucp/2.2/guides/admin/configure/external-auth/index.md index e3a432837a..d7ad765bde 100644 --- a/datacenter/ucp/2.2/guides/admin/configure/external-auth/index.md +++ b/datacenter/ucp/2.2/guides/admin/configure/external-auth/index.md @@ -134,3 +134,4 @@ LDAP directory. - [Create and manage users](../../manage-users/create-and-manage-users.md) - [Create and manage teams](../../manage-users/create-and-manage-teams.md) - [UCP permission levels](../../permission-levels.md) +- [Enable LDAP integration by using a configuration file](enable-ldap-config-file.md) diff --git a/datacenter/ucp/2.2/guides/admin/configure/ucp-configuration-file.md b/datacenter/ucp/2.2/guides/admin/configure/ucp-configuration-file.md index d03a44c1fc..b59b8a955e 100644 --- a/datacenter/ucp/2.2/guides/admin/configure/ucp-configuration-file.md +++ b/datacenter/ucp/2.2/guides/admin/configure/ucp-configuration-file.md @@ -1,18 +1,32 @@ --- title: UCP configuration file description: Configure UCP deployments. -keywords: docker enterprise edition, ucp, universal control plane, swarm, cluster configuration, deploy +keywords: docker enterprise edition, ucp, universal control plane, swarm, configuration, deploy --- -Override the default UCP settings by providing a configuration file when you create -UCP manager nodes. This is useful for scripted installations. +Override the default UCP settings by providing a configuration file when you +create UCP manager nodes. This is useful for scripted installations. -```bash -$ docker config create --name ... -``` +## UCP configuration file -Specify your configuration settings in a TOML file. For more info, see -[Tom's Obvious, Minimal Language](https://github.com/toml-lang/toml/blob/master/README.md). +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 +swarms. + +- Install one swarm 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 swarms. +- Install a UCP swarm, extract and edit the configuration file, and use the + CLI to apply the new configuration to the same swarm. +- Run the `example-config` command, edit the example configuration file, and + apply the file at install time or 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`. ## Example configuration file @@ -20,7 +34,23 @@ You can see an example TOML config file that shows how to configure UCP settings. From the command line, run UCP with the `example-config` option: ```bash -$ docker container run --rm docker/ucp:2.2.0-latest example-config +$ docker container run --rm {{ page.ucp_org }}/{{ page.ucp_repo }}:{{ page.ucp_version }} example-config +``` + +## Inspect and create configurations + +Use the `docker config inspect` command to view the current settings and emit +them to a file. + +```bash +$ docker config inspect --format '{{ printf "%s" .Spec.Data }}' $CURRENT_CONFIG_NAME > ucp-config.toml +``` + +Use the `docker config create` command to read the settings that are specified +in a TOML file and create a new configuration. + +```bash +$ docker config create --name ... ``` ## Configuration file and web UI