Skip to content

Commit

Permalink
HPCC-25660 Document LDAP Admin externalization
Browse files Browse the repository at this point in the history 
Signed-off-by: g-pan <[email protected]>
  • Loading branch information
@g-pan
g-pan committed Mar 19, 2024
1 parent 4f3af9d commit 897ecb7
Showing 1 changed file with 69 additions and 55 deletions.
124 changes: 69 additions & 55 deletions docs/EN_US/ContainerizedHPCC/ContainerizedMods/CustomConfig.xml
View file
Original file line number Diff line number Diff line change
Expand Up @@ -7,12 +7,11 @@
<sect1 id="CustTechniques" role="nobrk">
<title>Customization Techniques</title>

<para>In this section, we will walk through creating a custom
configuration YAML file and deploying an HPCC
Systems<superscript>®</superscript> 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.</para>
<para>This section will walk through creating a customized configuration
YAML file and deploying an HPCC Systems<superscript>®</superscript>
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.</para>

<para>There are several ways to customize a platform deployment. We
recommend using methods that allow you to best take advantage of the
Expand Down Expand Up @@ -996,56 +995,64 @@ eclagent:
<sect1 id="LDAPSecurity_forConatiners">
<title>LDAP Security for Containers</title>

<para>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.</para>
<para>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.</para>

<para>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.</para>
<para>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.</para>

<sect2 id="Configuring_For_KubernetesSecrets">
<title>Configuring LDAP for Kubernetes</title>
<title>Configuring LDAP in Kubernetes</title>

<para>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.</para>
<para>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.</para>

<programlisting>kubectl create secret generic admincredssecretname --from-literal=username=hpcc_admin \
--from-literal=password=t0pS3cr3tP@ssw0rd

kubectl get secret admincredssecretname
</programlisting>

<para>This effectively sets the values for the Administrator's username
and password in Kubernetes.</para>
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. </para>

<programlisting>kubectl get secret admincredssecretname</programlisting>

<para>For more information about Kubernetes see the appropriate
Kubernetes documentation for your implementation.</para>

<sect3 id="Deploying_TheKubernetesSecret">
<title>Deploying the Kubernetes Secret</title>

<para>Override the "secrets:" section in
HPCC-Platform/helm/hpcc/values.yaml, or your own customization
chart.</para>

<para>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.</para>
<para>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.</para>

<para>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". </para>

<para>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. </para>

<para>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. </para>

<programlisting> secrets:
authn:
Expand Down Expand Up @@ -1073,26 +1080,30 @@ kubectl get secret admincredssecretname
ldapAdminSecretKey: "admincredsaltmountname" # use alternate secrets creds
</programlisting>

<para> </para>
<para></para>
</sect3>
</sect2>

<sect2 id="Configuring_For_HashoCorpVault">
<title>Configuring LDAP for HashiCorp Vault</title>
<title>Configuring LDAP in HashiCorp Vault</title>

<para>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.</para>
<para>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. </para>

<programlisting> vault kv put secret/authn/myvaultadmincreds username=hpcc_admin password=t0pS3cr3tP@ssw0rd
vault kv get secret/authn/myvaultadmincreds
</programlisting>
<programlisting>vault kv put secret/authn/myvaultadmincreds username=hpcc_admin password=t0pS3cr3tP@ssw0rd </programlisting>

<para>This stores the values for the LDAP Administrator's username and
password into the HashiCorp Vault.</para>

<para>To verify and confirm the secret values, execute the following
command: </para>

<para>This effectively sets the values for the LDAP Administrator's
username and password into the HashiCorp Vault.</para>
<programlisting> vault kv get secret/authn/myvaultadmincreds</programlisting>

<para>For more information about creating secrets for HashiCorp Vault
see the appropriate HashiCorp documentation for your
Expand All @@ -1104,17 +1115,20 @@ kubectl get secret admincredssecretname

<para>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.</para>
customized configuration chart. For more information about customizing
your HPCC Systems containerized deployment see the above sections on
customization techniques.</para>

<para>The Vault name is defined for this example in a
<para>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.</para>

<programlisting> 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
</programlisting>
Expand Down

0 comments on commit 897ecb7

Please sign in to comment.