Installing Concert and Concert Workflows on a FIPS-enabled VM

Edit online

The following details and instructions outline the additional configuration steps required to enable FIPS 140-2 compliance when installing a unified instance of Concert and Concert Workflows on a VM.

Federal Information Processing Standards (FIPS) are standards and guidelines that are issued by the National Institute of Standards and Technology (NIST) for federal government computer systems. FIPS standards ensure that systems and software, especially those involving encryption, meet specific, high-security requirements.

When you install Concert and Concert Workflows on a FIPS-enabled system, all cryptographic operations performed by Concert and Concert Workflows use FIPS-approved algorithms and validated cryptographic modules.

Note:

When Concert and Concert Workflows are operating in a FIPS-compliant environment and use FIPS-validated modules, the products themselves have not yet undergone formal FIPS 140-2 or FIPS 140-3 certification.
Enabling FIPS changes the cryptographic policies on the VM. Ensure that all of its required components and images are compatible with FIPS before continuing your installation.

Before you begin

Ensure that your system meets all the installation specific requirements. For more information, see System requirements.
Ensure that you have obtained a valid IBM Entitlement Key. See Obtaining an IBM® entitlement API key.

Step 1: Verify FIPS mode

Ensure that your VM is running in FIPS mode.

If FIPS mode is not enabled, do the following to enable FIPS mode:
1. Enable FIPS mode by using the following command:
```
sudo fips-mode-setup --enable
```
2. Reboot the VM by using the following command:
```
sudo reboot
```
Verify if FIPS mode is enabled on your VM:
- Check the FIPS status by running the following command:
```
fips-mode-setup --check
```
- You can also verify by running the following command:
```
cat /proc/sys/crypto/fips_enabled
```
  If the command returns output as 1, FIPS mode is enabled on the VM.
  
  If the command returns output as 0, FIPS mode is not enabled on the VM.

Step 2: Download, extract, and export the latest software packages

Your software package for Concert and Concert Workflows includes scripts to install a FIPS-enabled version of Istio.

Download the latest software packages for Concert and Concert Workflows, or download directly from the public GitHub repository: https://github.com/IBM/Concert/releases
```
wget https://github.com/IBM/Concert/releases/download/v3.0.0/ibm-concert-x86.tar.gz
```
To set the default permissions for the package file, run the following command:
```
umask 0022
```
Extract the package.
```
tar xfz ibm-concert-x86.tar.gz
```

Export install directory.

export INSTALL_DIR=<install_directory>/ibm-concert

Navigate to the target installation directory.
```
cd $INSTALL_DIR
```

Step 3: Install Istio

Istio is an open-source service mesh platform that helps manage traffic between microservices within a VM. It ensures that all inter-pod communication is secured and observable without modifying application code.

To configure Istio on your VM, refer to the VM-specific procedure in Enhancing pod communication security by using Istio.

Step 4: Create a custom values file (Optional)

Note: This step only applies if Concert Workflows is included in your migration.

If you want to customize CPU and memory usage for certain Concert Workflows microservices, you can do so by creating a custom values YAML file that contains your preferred CPU and memory settings. For more information, refer to Customizing microservice resource usage.

Draft comment:
Removed "Use an external database or object storage service with Concert Workflows (Optional)", since testing is not completed.

Step 5: Configure which integrations are installed for Concert Workflows (Optional)

Note: This step only applies if Concert Workflows is included in your installation.

By default, when you install Concert Workflows on a VM, several hundred integrations are installed. To speed up the installation process, you can install a specific set of integrations. You can install a subset of commonly-used integrations or install your own customized set of integrations. For more information, see Configuring the installation of workflow integrations.

Step 6: Configure the params.ini file

The installation script requires a configuration file (params.ini) that defines environment-specific settings for Concert and Concert Workflows, located at $INSTALL_DIR/etc/params.ini.

For more information on params.ini file, list of sample params files as per the installation type, and list of required and optional parameters for installing on VM, see Configuring the params.ini file.

Copy the required parameters from the sample-params file as per your installation type:
```
cp $INSTALL_DIR/etc/sample-params/<sample-params-file-name> $INSTALL_DIR/etc/params.ini
```
Replace the <sample-params-file-name> with the sample params file name as per your installation type.
For example: If you want to install all three products (Concert and Concert Workflows), copy the concert-workflows-vm-quick-start-params.ini file:
```
cp $INSTALL_DIR/etc/sample-params/concert-workflows-vm-quick-start-params.ini $INSTALL_DIR/etc/params.ini
```
For more information on list of sample params.ini files as per the installation type, see Sample params.ini files.

Open and edit the $INSTALL_DIR/etc/params.ini file with required parameters:

vi $INSTALL_DIR/etc/params.ini

For more information on list of required and optional parameters for installing on VM, see Parameters for installing on VM.

Important: You must set the WORKFLOWS_ENABLE_FAAS and WORKFLOWS_ENABLE_ISTIO parameters as follows:

WORKFLOWS_ENABLE_FAAS: The FaaS integration in Concert Workflows is not supported for installations on FIPS-enabled VMs. This parameter must be set to false.
WORKFLOWS_ENABLE_ISTIO: For installations on FIPS-enabled VMs, this parameter must be set to true to enable Istio for mutual TLS communication between cluster pods.

Example:

INSTALL_VM=true
INSTALL_CONCERT=true
IMAGE_REGISTRY_PREFIX=cp.icr.io/cp
HUB_IMAGE_REGISTRY_SUFFIX=/solis-hub
CONCERT_IMAGE_REGISTRY_SUFFIX=/concert

INSTALL_WORKFLOWS=true
WORKFLOWS_IMAGE_REGISTRY_SUFFIX=/concert         
WORKFLOWS_INSTANCE_ADDRESS=hostname.domain.com <FQDN of your VM>
#namespace for Workflows(optional:default will be concert-workflows)
WORKFLOWS_NS=
#For enabling AI feature in workflow
WORKFLOWS_OVERRIDE_VALUES=
# The FaaS integration is not supported in FIPS-enabled environments.
WORKFLOWS_ENABLE_FAAS=false
# Enable Istio for mutual TLS communication between cluster pods.
WORKFLOWS_ENABLE_ISTIO=true
# Determines whether all integrations are installed. By default all are installed.
WORKFLOWS_INSTALL_ALL_INTEGRATIONS=

Save the $INSTALL_DIR/etc/params.ini file.

Step 7: Run the installation setup script

Run the installation setup script:

$INSTALL_DIR/bin/setup --license_acceptance=y --username=<user> --password=<password> --registry_password=<registry_entitlement_key>

Remember: The username and password that you specify when running the setup script will be used as the default values for the login, providing the initial credentials for access.

Parameter	Description
`--username`	Use the `--username` option to specify the default user for the installation. This option enables you to set a custom username value, which is used as the username for your product login.
`--password`	Use the `--password` option to specify the password for the default user for the installation. If you do not specify a value for this option, the tool prompts you to enter it.
`--registry_password`	Use the `--registry_password` option to specify the password required to access the source registry. If you are using `cp.icr.io/cp` as the source registry, then the password is the entitlement key.
`--license_acceptance`	License acceptance flag must be set to `y` to proceed with installation. Note: Concert is sold under multiple licenses. All licenses are available in IBM Terms. Prior to installing or upgrading Concert, ensure that you know the license associated with your product, read the license that applies to your purchase, and ensure that you agree to the terms and conditions of the license.

Note: The installation process may take 15 to 30 minutes depending on your system resources and network speed.

Verify installation:
- Upon successful installation completion, you will see:
```
INFO DEPLOYMENT SUCCESSFUL
```
- If you encounter any errors during installation, check the installation logs:
```
$INSTALL_DIR/localstorage/logs/prod_install_logs_<timestamp>.log
```

Step 8: Configure the Istio gateway and routes

Configure Istio to perform the following tasks:

Secure intra-pod communication by creating a gateway and virtual service mappings.
Observe intra-pod traffic by gathering pod logs, configuration, events, and state and installation diagnostics.

Complete the following steps:

Go to the folder that contains the configure-istio-gw-workflows-concert.sh and collect_logs_istio scripts.

Run the following commands:

If you are installing Concert and Concert Workflows, use the following command:

chmod +x cw-istio-configure-workflows-concert-std.sh
./cw-istio-configure-workflows-concert-std.sh \
--ns ${WORKFLOWS_NS} \ # e.g. concert-workflows
--host ${CW_ROUTE} # e.g <host>.com

If you are installing only Concert Workflows, use the following command:

chmod +x cw-istio-configure-workflows-std.sh
./cw-istio-configure-workflows-std.sh \
--ns ${WORKFLOWS_NS} \ # e.g. concert-workflows
--host ${CW_ROUTE} # e.g <host>.com

Verify that the Istio gateway and virtual service were created successfully by running the following command:
```
kubectl -n ${WORKFLOWS_NS} get gateway,virtualservice
```
Verify that both HTTPS ports are active by running this command:
```
kubectl -n istio-system get svc istio-ingressgateway -o wide
```

Confirm that TLS communication is in place by running these commands:

POD=$(kubectl -n ${WORKFLOWS_NS} get pod -l pliant.io/service=rna-core-pliant-front -o jsonpath='{.items[0].metadata.name}')
istioctl -n ${WORKFLOWS_NS} proxy-config clusters "$POD" | grep outbound | head

(Optional) Collect logs and diagnostics for Istio by running these commands:
```
chmod +x cw-istio-collect-logs
./cw-istio-collect-logs
```

Step 9: Access the UI

After successful installation, open your web browser and access the Concert product. To login to your required component, you can either login to the unified instance UI or use the component specific URL for login:

You can access the unified instance UI by navigating to the URL details provided in the output. Enter your login credentials (username and password provided in the setup script during installation), and click Login. After you log in to the unified UI, you can access and navigate to each component, allowing for easy navigation between them.

Access to the Concert products using the following URLs:

Table 1. Component specific access url
Components	URL	Default port
Concert	https://<VM_FQDN>:12443	12443
Concert Workflows	https://<VM_FQDN>:443	443

Replace <VM_FQDN> with your VM's fully qualified domain name (example, vm.example.com). For local access, you can use localhost instead of the FQDN.

Log in with your credentials. Use the username and password that you specified when running the installation setup script to log in to Concert.
Click Login to access the product.
Note: You might see a security warning about the SSL certificate. This is expected for self-signed certificates. Proceed to the site (the exact steps depend on your browser). To bring your own SSL certificate for Concert, see Bring your own SSL certificate.

Next steps

After accessing the product, manage user permissions through the Managing users and roles guide.

If you encounter issues during installation or operation, see Troubleshooting .