Deploying a development Vault for HCL Commerce on Kubernetes

Vault is used to store HCL Commerce environment configurations and secrets. It is also used as a Certification Authority (CA), to issue certificates to HCL Commerce servers and allow them communicate securely over SSL. Consul is used in conjunction with Vault for its name-value pair storage capabilities.

The hcl-commerce-vaultconsul-helmchart Helm Chart deploys Vault and Consul for use as a remote configuration center, storing HCL Commerce Version 9.1 environment data, and acting as the certification agent to issue certificates to each HCL Commerce application server based on their unique service names. If you plan to use the Vault configuration mode, both Vault and Consul are required to be configured before you can deploy the HCL Commerce Version 9.1 application. Once Vault and Consul are deployed, they can be used to deploy and control multiple Commerce environments. After Vault is started, it can run scripts to load HCL Commerce environment configuration data as specified in values.yaml, and can also configure a Public Key Infrastructure (PKI) back-end to issue certificates, if enabled via the vaultConsul.vaultLoadData configuration.

HCL Commerce Version 9.1.9.0 or laterNote: Consul and all related configurations were removed from HCL Commerce 9.1.9.0 and greater. The filename of the provided Vault Helm Chart, however, remains the same.

Before you begin

  • Obtain the hcl-commerce-helmchart and hcl-commerce-vaultconsul-helmchart from the HCL License and Delivery portal. For up-to-date release information, see HCL Commerce eAssemblies.
  • The provided Helm Chart attempts to pull Vault and Consul Docker images from DockerHub. If you use the default settings, ensure that your environment can connect to the Internet. Otherwise, you can download the Docker images and place them into a private Docker Image Repository.

    The relevant configuration is defined as follows:

    Attribute name Value Usage
    vaultConsul.imageRepo
    • x86-64docker.io
    • Power
      • HCL Commerce Version 9.1.7.0 or laterdocker.io/ibmcom/
      • HCL Commerce Version 9.1.12.0 or latericr.io/ppc64le-oss/
    Defines the Docker image repository for Vault and Consul Docker images.
    HCL Commerce Version 9.1.7.0 or latervaultConsul.vaultImageName
    • x86-64vault
    • Powervault-ppc64le
    The Vault Docker image name.
    vaultConsul.vaultImageTag
    • x86-64
      • HCL Commerce Version 9.1.15.0 or later1.14.4
      • HCL Commerce Version 9.1.14.01.13.4
      • HCL Commerce Version 9.1.13.01.13.1
      • HCL Commerce Version 9.1.12.01.9.9
      • HCL Commerce Version 9.1.10.01.9.1
      • HCL Commerce Version 9.1.9.01.8.5
      • HCL Commerce Version 9.1.7.01.7.0
      • Prior releases: 1.3.3
    • Power
      • HCL Commerce Version 9.1.15.0 or later1.14.4
      • HCL Commerce Version 9.1.12.01.9.9
      • HCL Commerce Version 9.1.7.01.5.3-ubi8
    The Vault Docker image tag.
    HCL Commerce Version 9.1.7.0 or latervaultConsul.consulImageName
    • x86-64consul
    • Powerconsul-ppc64le
    The Consul Docker image name.
    HCL Commerce Version 9.1.9.0 or laterNote: Removed in HCL Commerce 9.1.9.0 and greater.
    vaultConsul.consulImageTag
    • HCL Commerce Version 9.1.7.0 or laterx86-641.9.4
    • HCL Commerce Version 9.1.7.0 or laterPower1.8.3-ubi8
    • x86-64For releases prior to 9.1.7.0: 1.7.1
    The Consul Docker image tag.
    HCL Commerce Version 9.1.9.0 or laterNote: Removed in HCL Commerce 9.1.9.0 and greater.
    test.image docker.io/centos:latest The Helm Test command uses the Centos Docker image. This is used for sanity testing purposes.
  • As part of the Vault deployment, Vault will create a Vault token secret within the  commerce  namespace. It will be created within this namespace so that the HCL Commerce application can obtain the Vault token from that secret. This requires that the commerce namespace exists before you can deploy Vault.

    If  the commerce  namespace has not been created, you can create it with the following Kubernetes command:  kubectl create ns commerce. If you plan to deploy HCL Commerce in other namespaces, then you must also create those namespaces at this point, and list all of the namespaces in the commerceNameSpaces section of your configuration file.

    It is also recommended to deploy Vault in a separate namespace, such as  vault, to serve for all HCL Commerce environments. If you do not  have a dedicated Vault  namespace, then you can create it now with the same command: kubectl create ns vault.

  • Before deploying Vault, you must plan how you are going to deploy HCL Commerce, and then modify the data accordingly within your values.yaml file that will be loaded to the Vault as a postStart action. In Vault, a tenant name will be used as a secret mount path. This secret path will contain one or more environments, and each environment contains the key-value (KV) pairs for that environment. The environment level KV pairs will be under environment path directly, while auth and live instance specific KV pairs are under auth or live.
    For example:
    /Demo                                                        # tenant path 
    /qa                                                      # env path 
    internalDomainName: commerce.svc.cluster.local       # environment level properties 
    … 
    /auth                                                # auth instance path 
    dbHost: myDb.com                                 # auth instance level properties 
    … 
    /live                                                # live instance path 
    dbHost: myLiveDb.com                             # live instance level properties 
     
  • Create a copy of the Vault configuration file, values.yaml for use in your custom Vault deployment.

    It is strongly recommended to not modify the default  values.yaml  file for your deployment. Instead, make a copy of the file for customization, for example, my-values.yaml.

Note:
  • HCL Commerce Version 9.1.7.0 or laterPowerBy default, the provided Helm Charts are enabled for x86-64 deployments. Full Power Linux (ppc64le) support was added to the Helm Charts in HCL Commerce 9.1.7.0. To enable the Power deployment, open the values.yaml configuration file within the hcl-commerce-vaultconsul-helmchart to disable the provided x86-64 values, and enable the respective Power ones.
  • Ensure that you use the versions specified in the table above. These versions are tested and are certified to work with HCL Commerce. There are no guarantees that other tagged versions will function with HCL Commerce as expected.
  • Resource limitations are not defined for Vault-Consul usage with HCL Commerce. Their use with HCL Commerce in this provided configuration is simply to support deployment of a non-production environment, and are not designed or intended for use in any performance application. This must be considered when planning and configuring your production environment with high availability and more strict application security in mind.

Procedure

  1. HCL Commerce Version 9.1.7.0 or later Define a Certificate Authority (CA) certificate, and configure how it is to be used by Vault.
    The provided Helm Chart deploys vault in development mode to bypass the unseal process. In this mode all data will be stored in memory only. Configuration data is defined in the Helm values file, so it is loaded every time Vault is redeployed or restarted. However, the root CA certificate can not be persisted unless it is defined and persisted in a secret. Therefore, the Helm Chart allows either specifying, or automatically generating a CA certificate, and then persisting it within a TLS secret.
    Choose from one of the following options:
    • Allow the Vault Helm Chart to automatically generate and persist the CA certificate.
      To allow the Vault Helm Chart to automatically create a CA certificate and create a TLS secret, set the following configuration parameters:
      • externalCA.enabled to true
      • externalCA.autoCreate to true
      This automatic creation logic also requires the Support container image. Ensure that it is configured using the supportC.imageRepo, supportC.image and  supportC.tag parameters.
      Note: Automatic CA certificate generation is only implemented during the Helm Chart installation (that is, using helm install). Therefore, if you have deployed the Vault using the previous version of the Helm Chart, or if you want to modify your CA certificate after deployment, you must delete and install the Helm Chart again in order to implement this method of CA certificate generation.
    • Generate and specify your CA certificate manually.
      Create a self-signed CA certificate and configure it for use in the Vault deployment.
      1. Generate the self-signed CA certificate.
        1. Create a private key, private.key.
          openssl genrsa -out private.key 2048
        2. Create a CA certificate based on the private key.
          openssl req -x509 -new -nodes -key private.key -days 730 -out ca.pem -config req.conf
          Where the req.conf configuration file contains the following specification.
          [ req ] 
          prompt=no 
          distinguished_name=dn 
          x509_extensions=ext 
          
          [ dn ] 
          CN=My Company CA
          
          [ ext ] 
          basicConstraints=CA:TRUE
        3. create a TLS certificate in the vault namespace for use with Vault, using kubectl.
          kubectl create secret tls my-vault-ca --cert=ca.pem --key=private.key -n vault
        4. Update your Vault deployment configuration file (based on the provided values.yaml)
          externalCA: 
              enabled: true 
              existingSecretName: 'my-vault-ca' 
              autoCreate: false
  2. Modify the deployment configuration values, based on the provided values.yaml file.
    1. Change the tenant name if you want to name it differently. If you change the tenant name here, you must also change the tenant name in the provided HCL Commerce Helm Chart values to match.
    2. By default, ingress for the Vault service is not enabled. If you want to create an ingress to access the Vault user interface, set  enableIngress  to  true.
      HCL Commerce Version 9.1.7.0 or laterPowerRestriction: The Vault user interface is not available for deployments on Power Linux.
    3. Populate the commerceNameSpaces section with your HCL Commerce namespaces.
      For example, if you want to deploy two HCL Commerce environments dev and qa in the commerce-dev and commerce-qa namespaces, you must run the following commands:
      kubectl create ns commerce-dev 
      kubectl create ns commerce-qa
      And add the following to your commerceNameSpaces section:
      commerceNameSpaces:  
      - commerce-dev 
      - commerce-qa
    4. Update the following vaultConsul deployment configuration values.
      • Update  the imageRepo, consulImageName, consulImageTag, vaultImageName,  and  vaultImageTag  values if you want to test different Consul or Vault images.

        This is not recommended.

      • Update  vaultToken  to the one that you want to use.

        If modified from the default value, you must encode your token in Base64 by running echo -n newToken | base64, and use it to update the vaultTokenBase64  value.

      • HCL Commerce Version 9.1.10.0 or laterEnable and update the vaultLoadDataWithSecret section to improve the security of your vault data. Also ensure that vaultLoadData is enabled in order to load data.

        With this option enabled, you can ignore the vaultData section of the Helm Chart. Any sensitive key value pairs are now shielded from being exposed in the deployment configuration files.

        If you choose this method then you must manually create a secret, and put the secret name in the secretName field.

        A sample yaml configuration file with this configuration is located in the sample_secret directory. Use this sample to ensure that your configuration is made correctly.

      • Update the values under  vaultData to reflect your environment.

        For example, update your database information.

  3. Install the Helm Chart.
    Run the following command:
    helm install vault-consul ./hcl-commerce-vaultconsul -f my-values.yaml -n vault
    Where:
    vault-consul
    The release name.
    ./hcl-commerce-vaultconsul
    The path to the Helm Chart.
    my-values.yaml
    Your custom configuration file based on the provided values.yaml.
    vault
    The separate namespace you created for Vault.
  4. Verify the deployment of Vault and Consul, and verify the Chart.
    • Run kubectl get pods -n vault to ensure that vault-consul-xxxx displays 2/2 in the READY column.

      NAME                            READY   STATUS    RESTARTS   AGE
      vault-consul-676d9c5485-hc44b   2/2     Running   0          20d
    • Run kubectl get secret vault-token-secret -n commerce to list the secret in your commerce namespace, to ensure that the secret has been created.
      For example:
      kubectl get secret vault-token-secret -n commerce 
      NAME                 TYPE     DATA   AGE 
      vault-token-secret   Opaque   1      7m44s
    • Run helm test vault-consul -n vault to verify the Chart. You should see an output similar to the following.
      helm test vault-consul -n vault
      Pod vault-consul-health-test pending
      Pod vault-consul-health-test pending
      Pod vault-consul-health-test pending
      Pod vault-consul-health-test running
      Pod vault-consul-health-test succeeded
      NAME: vault-consul
      LAST DEPLOYED: Tue May 12 00:44:29 2020
      NAMESPACE: vault
      STATUS: deployed
      REVISION: 1
      TEST SUITE:     vault-consul-health-test
      Last Started:   Thu Jun 25 16:06:27 2020
      Last Completed: Thu Jun 25 16:06:35 2020
      Phase:          Succeeded

Results

Vault is configured and deployed.
You can update their configuration at any time by updating your vaultData configuration and running the following command:
helm upgrade vault-consul ./hcl-commerce-vaultconsul -f my-values.yaml -n vault
HCL Commerce Version 9.1.10.0 or laterNote:
  • If you use vaultLoadDataWithSecret to load data, you can only update vault values by updating the data secret and then delete the existing vault pod to force a restart.
  • To upgrade your Vault deployment from HCL Commerce Version 9.0 to HCL Commerce Version 9.1, you must create a service account release-name-commerce-vault before running the helm upgrade command.

You can uninstall the Helm Chart at any time by running helm delete vault-consul -n vault.