From e53b19ee4ad870ddf510925b2f275e774fe43a9c Mon Sep 17 00:00:00 2001 From: g-pan Date: Thu, 14 Mar 2024 17:33:42 -0400 Subject: [PATCH] HPCC-25660 Document LDAP Admin externalization Signed-off-by: g-pan --- .../ContainerizedMods/CustomConfig.xml | 176 +++++++++++++++++- 1 file changed, 170 insertions(+), 6 deletions(-) diff --git a/docs/EN_US/ContainerizedHPCC/ContainerizedMods/CustomConfig.xml b/docs/EN_US/ContainerizedHPCC/ContainerizedMods/CustomConfig.xml index c01e7bfb060..f0303d3fd67 100644 --- a/docs/EN_US/ContainerizedHPCC/ContainerizedMods/CustomConfig.xml +++ b/docs/EN_US/ContainerizedHPCC/ContainerizedMods/CustomConfig.xml @@ -7,12 +7,11 @@ Customization Techniques - In this section, we will walk through creating a custom - configuration YAML file and deploying an HPCC - Systems® platform using the default - configuration plus the customizations. Once you understand the concepts in - this chapter, you can refer to the next chapter for a reference to all - configuration value settings. + This section walks through creating a customized configuration YAML + file and deploying an HPCC Systems® platform + using the default configuration plus the customizations. Once you + understand the concepts in this chapter, you can refer to the next chapter + for a reference to all configuration value settings. There are several ways to customize a platform deployment. We recommend using methods that allow you to best take advantage of the @@ -992,4 +991,169 @@ eclagent: + + + LDAP Security for Containers + + Containerized LDAP support for HPCC Systems is accomplished by + externalizing the LDAP Active Directory Security Manager administrators + account credentials using Kubernetes or Hashicorp Vault secrets. As a + prerequisite to use these externalized credentials, you should be familiar + with setting up Kubernetes and/or Hashicorp Vault secrets. + + The HPCC Administrator does not have Active Directory administrator + rights. Instead, it must have administrator rights to all of the Base DNs + used by the HPCC Systems platform. The credentials for that HPCC Systems + administrators account therefore must be secured either using Kubernetes + secrets or the Hashicorp Vault. + + + Securing Credentials in Kubernetes + + To create a secret in Kubernetes for the HPCC Administrators user + account from a command line interface to Kubernetes, execute a command + similar to the following example. Note the secret name, is + "admincredssecretname" in this example. The HPCC Administrators user + account "username" and "password" key/values are required, and + additional properties are ignored. + + kubectl create secret generic admincredssecretname --from-literal=username=hpcc_admin \ + --from-literal=password=t0pS3cr3tP@ssw0rd + + + This sets the values for the Administrator's username and password + in Kubernetes and sets them as secrets. At this point you can verify the + secret you just created by executing the following command on the + Kubernetes command line interface. + + kubectl get secret admincredssecretname + + For more information about Kubernetes see the appropriate + Kubernetes documentation for your implementation. + + + Deploying the Kubernetes Secret + + To deploy the Kubernetes secrets override the "secrets:" section + in HPCC-Platform/helm/hpcc/values.yaml, or deploy with your own + customized chart. For more information about customizing your HPCC + Systems containerized deployment see the above sections on + customization techniques. + + In your chart, create a unique key name used to reference the + secret, and set it to the secret value that you created in the + previous step. In the above example it was + "admincredssecretname". + + You can optionally define an additional alternate name, such as, + "admincredsaltmountname" which can be used with another Active + Directory server. The alternate name is illustrated in the example + below and should be added to your chart if necessary. + + The "admincredsmountname" key/value pair already exists by + default in the HPCC Systems delivered values.yaml file. The key is + referenced in the component's ldap.yaml file. You may override these + and add additional key/values as needed. + + secrets: + authn: + admincredsmountname: "admincredssecretname" #exernalize HPCC Admin creds + admincredsaltmountname: "admincredsaltsecretname" #exernalize alternate HPCC Admin creds + + + + + Enable LDAP Authentication + + In the delivered + HPCC-Platform/esp/applications/common/ldap/ldap.yaml file, the + "ldapAdminSecretKey" is already set to the key mount name illustrated + in the example above. To enable LDAP authentication and to modify this + value, override the ESP/ECLWatch helm component located in values.yaml + as illustrated in the following example: + + esp: +- name: eclwatch + application: eclwatch + auth: ldap + ldap: + ldapAddress: "myldapserver" + ldapAdminSecretKey: "admincredsaltmountname" # use alternate secrets creds + + + + + + + + Configuring LDAP in HashiCorp Vault + + To create and store secrets in the HashiCorp Vault, from the + command command line interface, execute the following Vault commands. + The secret name used in the example below is "myvaultadmincreds" and + must be prefixed with "secret/authn/" as illustrated. The HPCC Systems + administrator "username" and "password" key/values are required; and + additional properties are ignored. + + vault kv put secret/authn/myvaultadmincreds username=hpcc_admin password=t0pS3cr3tP@ssw0rd + + This stores the values for the HPCC Systems administrator username + and password into the HashiCorp Vault. + + To verify and confirm the secret values, execute the following + command: + + vault kv get secret/authn/myvaultadmincreds + + For more information about creating secrets for HashiCorp Vault + see the appropriate HashiCorp documentation for your + implementation. + + + Deploying the HashiCorp + Vault + + You can deploy the HashiCorp Vault secrets when you override the + "secrets:" section in HPCC-Platform/helm/hpcc/values.yaml, or in your + customized configuration chart. For more information about customizing + your HPCC Systems containerized deployment see the above sections on + customization techniques. + + The Vault name value is defined for this example in the + values-secrets.yaml configuration chart. You can find an example of + this chart in the HPCC-Platform repository under + /helm/examples/secrets/values-secrets.yaml. + + vaults: + authn: + - name: my-authn-vault + #The data node in the URL is there for use by the REST API + #The path inside the vault starts after /data + url: http://${env.VAULT_SERVICE_HOST}:${env.VAULT_SERVICE_PORT}/v1/secret/data/authn/${secret} + kind: kv-v2 + + + + + Referencing Vault Stored Authentication + + The key names "ldapAdminSecretKey" and "ldapAdminVaultId" are + used by the HPCC Systems security manager to resolve the secrets, and + must match exactly when using the Vault name set up in the previous + steps. + + esp: +- name: eclwatch + application: eclwatch + auth: ldap + ldap: + ldapAddress: "myldapserver" + ldapAdminSecretKey: "myvaultadmincreds" + ldapAdminVaultId: "my-authn-vault" + + + + + +