gluufederation/opendj

镜像概述与主要用途

该Docker镜像由Gluu Federation提供，是OpenDJ的Docker打包版本，用于便捷部署和运行OpenDJ LDAP服务器。OpenDJ是一款功能强大的目录服务器，广泛应用于身份管理、用户数据存储和目录服务场景。本镜像支持多种配置和密钥管理适配器、自动LDAP复制等特性，简化了OpenDJ在容器化环境中的部署与运维。

版本信息

• 稳定版本：请参考https://github.com/GluuFederation/docker-opendj/releases%E9%A1%B5%E9%9D%A2%E8%8E%B7%E5%8F%96%E7%A8%B3%E5%AE%9A%E7%89%88%E6%9C%AC%E3%80%82
• 开发/不稳定版本：使用标签 gluufederation/opendj:5.0.0_dev。

环境变量

容器支持以下环境变量，用于配置服务行为：

配置管理相关

• CN_CONFIG_ADAPTER：配置后端适配器，可选值为consul（默认）、kubernetes或google。
• CN_CONFIG_CONSUL_HOST：Consul的主机名或IP（默认值：localhost）。
• CN_CONFIG_CONSUL_PORT：Consul的端口（默认值：8500）。
• CN_CONFIG_CONSUL_CONSISTENCY：Consul一致性模式，可选default、consistent或stale（默认值：stale）。
• CN_CONFIG_CONSUL_SCHEME：Consul支持的协议（http或https）。
• CN_CONFIG_CONSUL_VERIFY：是否验证证书（默认值：false）。
• CN_CONFIG_CONSUL_CACERT_FILE：Consul CA证书文件路径（默认值：/etc/certs/consul_ca.crt）。当CN_CONFIG_CONSUL_VERIFY设为true且文件存在时使用。
• CN_CONFIG_CONSUL_CERT_FILE：Consul证书文件路径（默认值：/etc/certs/consul_client.crt）。
• CN_CONFIG_CONSUL_KEY_FILE：Consul密钥文件路径（默认值：/etc/certs/consul_client.key）。
• CN_CONFIG_CONSUL_TOKEN_FILE：包含ACL令牌的文件路径（默认值：/etc/certs/consul_token）。
• CN_CONFIG_KUBERNETES_NAMESPACE：Kubernetes命名空间（默认值：default）。
• CN_CONFIG_KUBERNETES_CONFIGMAP：Kubernetes配置映射名称（默认值：jans）。
• CN_CONFIG_KUBERNETES_USE_KUBE_CONFIG：是否从$HOME/.kube/config加载凭据（仅非容器环境有用，默认值：false）。
• GOOGLE_PROJECT_ID：Google项目ID（默认值：空字符串）。当CN_CONFIG_ADAPTER或CN_SECRET_ADAPTER设为google时使用。
• GOOGLE_APPLICATION_CREDENTIALS：包含Google凭据的JSON文件路径（可选）。参考Google云认证文档获取支持的凭据类型。

密钥管理相关

• CN_SECRET_ADAPTER：密钥适配器，可选值为vault（默认）、kubernetes或google。
• CN_SECRET_VAULT_VERIFY：是否验证Vault证书（默认值：false）。
• CN_SECRET_VAULT_ROLE_ID_FILE：包含Vault AppRole角色ID的文件路径（默认值：/etc/certs/vault_role_id）。
• CN_SECRET_VAULT_SECRET_ID_FILE：包含Vault AppRole密钥ID的文件路径（默认值：/etc/certs/vault_secret_id）。
• CN_SECRET_VAULT_CERT_FILE：Vault证书文件路径（默认值：/etc/certs/vault_client.crt）。
• CN_SECRET_VAULT_KEY_FILE：Vault密钥文件路径（默认值：/etc/certs/vault_client.key）。
• CN_SECRET_VAULT_CACERT_FILE：Vault CA证书文件路径（默认值：/etc/certs/vault_ca.crt）。当CN_SECRET_VAULT_VERIFY设为true且文件存在时使用。
• CN_SECRET_VAULT_ADDR：Vault的URL（默认值：http://localhost:8200）。
• CN_SECRET_VAULT_NAMESPACE：访问密钥时使用的命名空间（默认值：空字符串）。
• CN_SECRET_VAULT_KV_PATH：KV密钥引擎的路径（默认值：secret）。
• CN_SECRET_VAULT_PREFIX：构建密钥路径的基础前缀（默认值：jans）。
• CN_SECRET_VAULT_APPROLE_PATH：AppRole的路径（默认值：approle）。
• CN_SECRET_KUBERNETES_NAMESPACE：Kubernetes命名空间（默认值：default）。
• CN_SECRET_KUBERNETES_CONFIGMAP：Kubernetes密钥名称（默认值：jans）。
• CN_SECRET_KUBERNETES_USE_KUBE_CONFIG：是否从$HOME/.kube/config加载凭据（仅非容器环境有用，默认值：false）。
• CN_GOOGLE_SECRET_VERSION_ID：Google Secret Manager中Janssen密钥的版本ID（默认值：latest，推荐使用）。
• CN_GOOGLE_SECRET_MANAGER_PASSPHRASE：Google Secret Manager中Janssen密钥的密码（推荐修改，默认值：secret）。
• CN_GOOGLE_SECRET_NAME_PREFIX：Google Secret Manager中Janssen密钥的前缀（默认值：jans，若保留则创建jans-secret密钥）。

服务配置相关

• CN_WAIT_MAX_TIME：启动时“健康检查”的最长运行时间（默认值：300秒）。
• CN_WAIT_SLEEP_DURATION：启动“健康检查”之间的延迟时间（默认值：10秒）。
• CN_CERT_ALT_NAME：证书中作为Subject Alt Name的额外DNS名称。若值非空且与现有证书中的Subject Alt Name不匹配（或不存在），则会重新生成新证书并覆盖配置后端中保存的证书。仅当部署oxShibboleth时需要，用于解决连接OpenDJ时CN与目标主机名不匹配的问题。注意：任何连接到OpenDJ的现有容器都必须重新部署以下载新证书。
• CN_MAX_RAM_PERCENTAGE：传递给Java选项-XX:MaxRAMPercentage的值。
• CN_JAVA_OPTIONS：传递给入口点的Java选项，如-Xmx1024m（默认值：空字符串）。

LDAP复制相关

• CN_LDAP_AUTO_REPLICATE：是否自动启用复制（默认值：true）。
• CN_LDAP_REPL_CHECK_INTERVAL：复制检查的间隔时间（秒，默认值：10）。
• CN_LDAP_REPL_MAX_RETRIES：自动复制初始化的最大重试次数（默认值：10）。达到最大重试次数后，无论复制状态如何，进程都会停止（可能需要手动运行进程）。
• CN_LDAP_REPL_SOURCE：作为复制源的地址（例如：ldap，默认值：空字符串）。
• CN_LDAP_REPL_DISABLE_ON_EXIT：退出时是否自动禁用复制（默认值：true）。
• CN_LDAP_USE_SSL：是否使用SSL连接到LDAP服务器（默认值：true）。

部署要求

全新部署

1. 生成包含cn=Directory Manager密码的ldap_password密钥，例如：Test1234#。

2. 生成包含信任库密码的ldap_truststore_password密钥，例如：

   sh
   tr -dc 'a-zA-Z0-9' < /dev/urandom | fold -w 12 | head -n 1
   

3. 创建opendj.crt和opendj.key文件，例如：

   sh
   openssl req \
       -x509 \
       -newkey rsa:2048 \
       -sha256 \
       -days 365 \
       -nodes \
       -keyout opendj.key \
       -out opendj.crt \
       -subj '/CN=demoexample.jans.io' \
       -addext 'subjectAltName=DNS:ldap,DNS:opendj'
   

   注意：需添加额外的DNS:<opendj-service-name>以匹配OpenDJ的Kubernetes服务名称。

   使用以下命令准备ldap_ssl_cert密钥：

   sh
   cat opendj.crt | base64 -w0
   

   使用以下命令准备ldap_ssl_key密钥：

   sh
   cat opendj.key | base64 -w0
   

4. 将上述密钥放入configuration.json（部分键省略）：

   json
   {
       "_secret": {
           "ldap_password": "<ldap_password>",
           "ldap_truststore_pass": "<ldap_truststore_password>",
           "ldap_ssl_cert": "<ldap_ssl_cert>",
           "ldap_ssl_key": "<ldap_ssl_key>"
       },
       "_configmap": {
           "optional_scopes": "[\"couchbase\", \"ldap\", \"redis\", \"sql\"]",
           "admin_email": "support@demoexample.jans.io",
           "hostname": "demoexample.jans.io",
           "city": "Austin",
           "country_code": "US",
           "orgName": "Gluu",
           "state": "TX"
       }
   }
   

   若使用charts的values.yaml，按以下示例放置相关密钥：

   yaml
   config:
     ldapPassword: "<ldap_password>"
     ldapTruststorePassword: "<ldap_truststore_password>"
     configmap:
       cnLdapCrt: "<ldap_ssl_cert>"
       cnLdapKey: "<ldap_ssl_key>"
   

从现有设置迁移

1. 在主机创建opendj_configuration_export.py：

   py
   import os
   
   from jans.pycloudlib import get_manager
   
   manager = get_manager()
   
   # 拉取密钥供后续使用
   manager.secret.to_file("ldap_ssl_cert", "/tmp/opendj.crt", decode=True)
   manager.secret.to_file("ldap_ssl_key", "/tmp/opendj.key", decode=True)
   manager.secret.to_file("ldap_truststore_pass", "/tmp/ldap_truststore_password")
   manager.secret.to_file("encoded_ox_ldap_pw", "/tmp/ldap_password", decode=True)
   
   # 转换并推送密钥
   manager.secret.from_file("ldap_ssl_cert", "/tmp/opendj.crt")
   manager.secret.from_file("ldap_ssl_key", "/tmp/opendj.key")
   manager.secret.from_file("ldap_password", "/tmp/ldap_password")
   

2. 将脚本复制到现有Pod并运行，例如：

   sh
   kubectl -n jans cp opendj_configuration_export.py jans-auth-xzddfi:/tmp/opendj_configuration_export.py
   
   # 此脚本将创建所需文件
   kubectl -n jans exec jans-auth-xzddfi -- python3 /tmp/opendj_configuration_export.py
   

3. 下载脚本生成的文件，例如：

   sh
   kubectl -n jans cp jans-auth-xzddfi:/tmp/ldap_password ldap_password
   kubectl -n jans cp jans-auth-xzddfi:/tmp/ldap_truststore_password ldap_truststore_password
   kubectl -n jans cp jans-auth-xzddfi:/tmp/opendj.crt opendj.crt
   kubectl -n jans cp jans-auth-xzddfi:/tmp/opendj.key opendj.key
   

4. 使用以下命令准备ldap_ssl_cert密钥：

   sh
   cat opendj.crt | base64 -w0
   

   使用以下命令准备ldap_ssl_key密钥：

   sh
   cat opendj.key | base64 -w0
   

5. 将上述密钥放入configuration.json（部分键省略）：

   json
   {
       "_secret": {
           "ldap_password": "<ldap_password>",
           "ldap_truststore_pass": "<ldap_truststore_password>",
           "ldap_ssl_cert": "<ldap_ssl_cert>",
           "ldap_ssl_key": "<ldap_ssl_key>"
       },
       "_configmap": {
           "optional_scopes": "[\"couchbase\", \"ldap\", \"redis\", \"sql\"]",
           "admin_email": "support@demoexample.jans.io",
           "hostname": "demoexample.jans.io",
           "city": "Austin",
           "country_code": "US",
           "orgName": "Gluu",
           "state": "TX"
       }
   }
   

   若使用charts的values.yaml，按以下示例放置相关密钥：

   yaml
   config:
     ldapPassword: "<ldap_password>"
     ldapTruststorePassword: "<ldap_truststore_password>"
     configmap:
       cnLdapCrt: "<ldap_ssl_cert>"
       cnLdapKey: "<ldap_ssl_key>"
   

部署策略

1. 部署单个OpenDJ实例
2. 扩展OpenDJ实例，默认会自动进行复制（另见LDAP复制）
3. 移除任何OpenDJ实例前，在容器内运行python3 /app/scripts/deregister_peer.py（在Kubernetes中，可使用preStop钩子替代）

LDAP复制

当容器运行时，满足以下条件会自动触发复制过程：

1. 集群中运行多个LDAP容器
2. o=jans、o=site、o=metric后端尚未复制且无条目

查看LDAP容器日志可了解结果，也可在容器内运行/opt/opendj/bin/dsreplication status检查复制状态。