From 897ecb7f147f70062d4e3a43df363f88aa87ecd8 Mon Sep 17 00:00:00 2001 From: g-pan Date: Tue, 19 Mar 2024 19:39:17 -0400 Subject: [PATCH] HPCC-25660 Document LDAP Admin externalization Signed-off-by: g-pan --- .../ContainerizedMods/CustomConfig.xml | 124 ++++++++++-------- 1 file changed, 69 insertions(+), 55 deletions(-) diff --git a/docs/EN_US/ContainerizedHPCC/ContainerizedMods/CustomConfig.xml b/docs/EN_US/ContainerizedHPCC/ContainerizedMods/CustomConfig.xml index 0ad6b4e1330..d9673a3f156 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 will walk 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 @@ -996,34 +995,37 @@ eclagent: LDAP Security for Containers - Containerized LDAP support for HPCC Systems can be accomplished by - externalizing the LDAP Active Directory Security Manager administrator - account credentials using Kubernetes and Hashicorp Vault secrets. To use - these externalized credentials, as prerequisite should be familiar setting - up Kubernetes secrets and/or Hashicorp Vault secrets. + 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 LDAP Administrator account is the only HPCC user that must have - Active Directory administrator rights. This account should exist in the - configured "systemBasedn" branch of the Active Directory, typically set to - cn=Users. + The LDAP Administrator account is the only HPCC user account that + must have Active Directory administrator rights. This account should exist + in the configured "systemBasedn" branch of the Active Directory, typically + set to cn=Users. - Configuring LDAP for Kubernetes + Configuring LDAP in Kubernetes - To configure secrets in Kubernetes, from the Kubernetes CLI, - create the LDAP "secret" similar to the following example. Note the - secret name, "admincredssecretname" used in this example. The LDAP - Administrator "username" and "password" key/values are required; - additional properties are allowed but ignored. + To create a secret in Kubernetes for the HPCC Administrator + account from a command line intereface to the Kubernetes, execute a + command similar to the following example. Note the secret name, is + "admincredssecretname" used in this example. The LDAP Administrator + "username" and "password" key/values are required; and additional + properties are allowed but ignored. kubectl create secret generic admincredssecretname --from-literal=username=hpcc_admin \ --from-literal=password=t0pS3cr3tP@ssw0rd - -kubectl get secret admincredssecretname This effectively sets the values for the Administrator's username - and password in Kubernetes. + and password in Kubernetes. 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. @@ -1031,21 +1033,26 @@ kubectl get secret admincredssecretname Deploying the Kubernetes Secret - Override the "secrets:" section in - HPCC-Platform/helm/hpcc/values.yaml, or your own customization - chart. - - Create a unique key name used to reference the secret (this will - be the mounted file system name of the secret), and set it to the - secret value ("admincredssecretname") that you created in the - configuring section. In this example, the key named - "admincredsmountname," and optionally define an additional alternate - one "admincredsaltmountname" which could be used with another Active - Directory server, for instance. Note that the "admincredsmountname" - key/value pair already exists as a 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. + 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 (this will be the mounted file system name of that 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 could be used with another Active + Directory server. The alternate name is illustrated in the example + below and could also 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: @@ -1073,26 +1080,30 @@ kubectl get secret admincredssecretname ldapAdminSecretKey: "admincredsaltmountname" # use alternate secrets creds - + - Configuring LDAP for HashiCorp Vault + Configuring LDAP in HashiCorp Vault - To configure secrets for HashiCorp Vault, from it's command line - interface, create the LDAP "secret" similar to the following example. - Note the secret name, is "myvaultadmincreds" in this example. The LDAP - Administrator "username" and "password" key/values are required; - additional properties are allowed but ignored. The secret name must be - specified with the "secret/authn/" prefix. + To create and store secrets in the HashiCorp Vault, from the + command command line interface, execute the Vault commands similar to + the following example. Note the secret name, in this example is + "myvaultadmincreds" and must be specified with the "secret/authn/" + prefix, as illustrated below. The LDAP Administrator "username" and + "password" key/values are required; and additional properties are + allowed but ignored. - vault kv put secret/authn/myvaultadmincreds username=hpcc_admin password=t0pS3cr3tP@ssw0rd - vault kv get secret/authn/myvaultadmincreds - + vault kv put secret/authn/myvaultadmincreds username=hpcc_admin password=t0pS3cr3tP@ssw0rd + + This stores the values for the LDAP Administrator's username and + password into the HashiCorp Vault. + + To verify and confirm the secret values, execute the following + command: - This effectively sets the values for the LDAP Administrator's - username and password into the HashiCorp Vault. + vault kv get secret/authn/myvaultadmincreds For more information about creating secrets for HashiCorp Vault see the appropriate HashiCorp documentation for your @@ -1104,9 +1115,11 @@ kubectl get secret admincredssecretname 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. + customized configuration chart. For more information about customizing + your HPCC Systems containerized deployment see the above sections on + customization techniques. - The Vault name is defined for this example in a + The Vault name: value is defined for this example in a 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. @@ -1114,7 +1127,8 @@ kubectl get secret admincredssecretname vaults: authn: - name: my-authn-vault - #Note the data node in the URL is there for the REST APIs use. The path inside the vault starts after /data + #Note the data node in the URL is there for the REST APIs use. + #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