Upgrade Notes

The upgrade to IBM Financial Services Workbench 2.8 is supported from the earlier versions 2.7, 2.6, 2.5, 2.4, 2.3 and 2.2.

Upgrading IBM Financial Services Workbench from version 2.6 to 2.8 or from version 2.7 to 2.8 only requires updating the Solution CLI to the latest version (4.2.28). Depending on the other versions already installed, the upgrade steps are described in the following sections 2.2, 2.3, 2.4 and 2.5.

Note: The upgrade of the Solution CLI (Run fss upgrade-cli) is necessary at all times!

For detailed information about upgrading IBM Financial Services Workbench, see Installing an Upgrade or Hotfix.

Deployment Versions

In the following table you will find the expected versions of Solution Designer and Solution Hub after the installation was performed:

Release Version Component
Deployment Name
 Deployment Version
2.8.0 Solution Designer release-ssob-solution-designer 3.7.55
2.8.0 Solution Hub release-ssob-solution-hub 2.8.3

Upgrading from 2.2 to 2.6

Adjust solution-designer-values.yaml

Two configuration parameters have been added to the solution-designer-values.yaml that affect the k5-local-marketplace-controller, which is responsible for providing the API endpoints to work with the local marketplace:

  1. global.endpoints.localMarketplaceController.host
  2. k5-local-marketplace-controller.marketplace.storage.secretName
You can probably use the default values for these parameters, see the Optional: YAML file solution-designer-values.yaml.

Since version 2.5, the following configuration parameters are now configured via the K5 Configurator API and are no longer specified in the solution-designer-values.yaml file and must be removed from it:

  1. global.truststore.secretName
  2. global.identity.url
  3. global.identity.realm
  4. global.identity.adminCredentialsSecretName
  5. global.k5-designer-backend.mongoDb.secretName
  6. global.k5-designer-backend.mongoDb.dbName
  7. global.k5-designer-backend.migration.db.gic.mongoDb.secretName
  8. global.k5-designer-backend.migration.db.gic.mongoDb.dbName
  9. global.k5-git-integration-controller.mongoDb.secretName
  10. global.k5-git-integration-controller.mongoDb.dbName
  11. global.k5-git-integration-controller.tokenEncryptionMasterKey.secretName
  12. global.k5-solution-controller.marketplace.storage.secretName
  13. global.k5-s3-storage.secretName
Note: Before you remove these values, save them and keep them available for the configuration of the installation.

Adjust solution-hub-values.yaml

Since version 2.5, the following configuration parameters are mostly configured via the K5 Configurator API and are no longer specified in the solution-hub-values.yaml file and must be removed from it:

  1. global.identity.url
  2. global.identity.realm
  3. global.truststore.trustMap.identity
Note: Before you remove these values, save them and keep them available for the configuration of the installation.

Migrate API Bindings

Every existing API-binding (DEV binding or stored in the Configuration Management) that is referring to API dependencies that have been developed also with Financial Services Workbench need to be adjusted if the JSON Web Token (JWT) used in your solution should be forwarded to call the API dependency. The option k5_propagate_security_token: true|false is introduced in version 2.3 and needs to be included in the existing API bindings (JSON format).

The second option is to use the Local Lookup property to enable dynamic dependency determination for API dependencies developed with Financial Services Workbench.

Migrate Java Low-Code Solutions

All existing low-code solutions with implementation language Java need to be updated in the Git repository due to a known issue. There is only the root level pom.xml file that has to be changed.

Search for the parent attribute and change it according to the following snippet:

<parent>
    <groupId>de.knowis.cp.sdk</groupId>
    <artifactId>cp-framework-managed-sdk-parent</artifactId>
    <version>2.1.5</version>
    <relativePath>./.framework/repo/de/knowis/cp/sdk/cp-framework-managed-sdk-parent/2.1.5/cp-framework-managed-sdk-parent-2.1.5.pom</relativePath>
</parent>

Migrate Java Custom-Code Solutions

Every existing Custom-Code-Solution (Java) needs to be updated in the Git repository. Please change the files listed below. The placeholders <SOLUTION_ACRONYM> (solution acronym in upper case) and<solution_acronym> (solution acronym in lower case) needs to be replaced:

File
./api.json Change the value of url to /<SOLUTION_ACRONYM>/v3/api-docs/<SOLUTION_ACRONYM>
./<solution_acronym>-application/pom.xml Change the value of version of the <parent> to 2.1.6
./<solution_acronym>-application/src/main/java/<solution_acronym>/ config/SecurityConfigurer.java Change line 25 from 
.antMatchers(appContextPath()+"/api-docs").permitAll()
to 
.antMatchers(appContextPath()+"/v3/api-docs/*").permitAll()
./<solution_acronym>-application/src/main/java/<solution_acronym>/ provider/HelloWorldController.java Change 
"/*/api/v1/hello"
in line 17 to 
"/${de.knowis.cp.solution.acronym:<SOLUTION_ACRONYM>}/api/v1/hello"
Please change your other controllers accordingly.

Migrate secrets

In version 2.5 there are a few secrets that have been changed. This needs to be adjusted to migrate from 2.2 to 2.6. The following shows all secrets that have been changed:
Previous secret name
New secret name
k5-s3-storage-access k5-s3-storage-credentials
iam-secret k5-iam-secret
k5-token-encryption-master-key k5-encryption-master-key
cp-dt-backend-mongodb-secret k5-designer-mongodb

There are two possibilities to properly migrate those secrets. Either by using the k5-configurator API as described in the following sections or by using the shell script bellow: Please replace values from the manual data definition with proper values. After doing so execute this script and all secrets should be set properly. 


# Manual data
export JWT={ENTER THE JWT} # Replace this value with a valid OpenShift token
export OC_NAMESPACE={ENTER THE HUB NAMESPACE} # Replace this value with a valid hub namespace
export IAM_USER_REALM={ENTER IAM REALM} # Replace this value with your iam realm
export IAM_HOSTNAME={ENTER IAM HOSTNAME} # Replace this value with your iam hostname

# Status definition
# Replace this only if you changed the old secret names before
export OLD_SECRET_NAME_S3_STORAGE=k5-s3-storage-access
export OLD_SECRET_NAME_IAM=iam-secret
export OLD_SECRET_NAME_ENCRYPTION_MASTER_KEY=k5-token-encryption-master-key
export OLD_SECRET_NAME_MONGO=cp-dt-backend-mongodb-secret


# Auto retrieved data
echo "Retrieving secret values from OpenShift"
export S3_STORAGE_ACCESS_KEY=$(oc get secret ${OLD_SECRET_NAME_S3_STORAGE} -n $OC_NAMESPACE -o jsonpath="{.data.accesskey}" | base64 -d)
export S3_STORAGE_SECRET_KEY=$(oc get secret ${OLD_SECRET_NAME_S3_STORAGE} -n $OC_NAMESPACE -o jsonpath="{.data.secretkey}" | base64 -d)

export IAM_USER_PW=$(oc get secret ${OLD_SECRET_NAME_IAM} -n $OC_NAMESPACE -o jsonpath="{.data.adminPassword}" | base64 -d)
export IAM_USER_NAME=$(oc get secret ${OLD_SECRET_NAME_IAM} -n $OC_NAMESPACE -o jsonpath="{.data.adminUser}" | base64 -d)

export ENCRYPTION_MASTER_KEY=$(oc get secret ${OLD_SECRET_NAME_ENCRYPTION_MASTER_KEY} -n $OC_NAMESPACE -o jsonpath="{.data.key}" | base64 -d)

export MONGO_CONNECTION_STRING=$(oc get secret ${OLD_SECRET_NAME_MONGO} -n $OC_NAMESPACE -o jsonpath="{.data.connectionString}" | base64 -d)

export BASE_URL=$(oc get route k5-configurator -n $OC_NAMESPACE | sed -n 2p | awk '{print $2}')

echo "Successfully retrieved secret values from OpenShift"

# Execute migration
echo "Calling k5-configurator to set s3 storage secret ..."
curl -X PUT "https://$BASE_URL/api/k5-configurator/v1/configs/s3storage" -H  "accept: application/json;charset=UTF-8" -H  "Authorization: Bearer $JWT" -H  "Content-Type: application/json" -d "{\"accesskey\":\"$S3_STORAGE_ACCESS_KEY\",\"secretkey\":\"$S3_STORAGE_SECRET_KEY\"}"

echo "Calling k5-configurator to set iam secrets ..."
curl -X PUT "https://$BASE_URL/api/k5-configurator/v1/configs/iam" -H  "accept: application/json;charset=UTF-8" -H  "Authorization: Bearer $JWT" -H  "Content-Type: application/json" -d "{\"adminUsername\":\"$IAM_USER_NAME\",\"adminPassword\":\"$IAM_USER_PW\",\"hostname\":\"$IAM_HOSTNAME\",\"realm\":\"$IAM_USER_REALM\"}"

echo "Calling k5-configurator to set masterkey secret ..."
curl -X PUT "https://$BASE_URL/api/k5-configurator/v1/configs/masterkey" -H  "accept: application/json;charset=UTF-8" -H  "Authorization: Bearer $JWT" -H  "Content-Type: application/json" -d "{\"key\":\"$ENCRYPTION_MASTER_KEY\"}"

echo "Calling k5-configurator to set mongodb secret ..."
curl -X PUT "https://$BASE_URL/api/k5-configurator/v1/configs/mongodb" -H  "accept: application/json;charset=UTF-8" -H  "Authorization: Bearer $JWT" -H  "Content-Type: application/json" -d "{\"connectionString\":\"$MONGO_CONNECTION_STRING\"}"
echo "Successfully set all secrets"

k5-s3-storage-access

1. Use the values from k5-s3-storage-access of your old 2.2 installation to configure the new secret. Those secret values are relevant to do so:
  • accesskey
  • secretkey
2. Use the provided API {BASE_URL}/api/k5-configurator/v1/configs/s3storage with your secretkey and accesskey in the request body to update the new secret value with the old one.
Note: This configures the new secret k5-s3-storage-credentials

iam-secret

1. Use the values from iam-secret of your old 2.2 installation to configure the new secret. Those secret values are relevant to do so:
  • adminPassword
  • adminUsername
  • realm
  • hostname
2. Use the provided API {BASE_URL}/api/k5-configurator/v1/configs/iam and the above mentioned secret values in the request body.
Note: This configures two new secrets: k5-iam-settings and k5-iam-secret

k5-token-encryption-master-key

1. Use the values from k5-token-encryption-master-key of your old 2.2 installation to configure the new secret. This secret value is relevant to do so:
  • key
2. Use the provided API {BASE_URL}/api/k5-configurator/v1/configs/masterkey and the above mentioned secret value in the request body.
Note: This configures the new secret k5-encryption-master-key

cp-dt-backend-mongodb-secret

1. Use the values from cp-dt-backend-mongodb-secret of your old 2.2 installation to configure the new secret. This secret value is relevant to do so:
  • connectionString
2. Use the provided API {BASE_URL}/api/k5-configurator/v1/configs/mongodb and the above mentioned secret value in the request body.
Note: This configures the new secret k5-designer-mongodb

Cleanup secrets

After successfully migrating all secrets, please verify your installation and check if all is working smoothly. Use the API's shown in the previous sections to get all secrets and verify if all is set up properly. Once this is done, one can cleanup the old unused secrets.
Warning: Please be aware that after cleaning-up, those secrets cannot be restored and the data is lost. Make sure that everything is up and running before cleaning secrets.

# Manual data
export OC_NAMESPACE={ENTER THE HUB NAMESPACE} # Replace this value with a valid hub namespace

# Status definition
# Replace this only if you changed the old secret names before
export OLD_SECRET_NAME_S3_STORAGE=k5-s3-storage-access
export OLD_SECRET_NAME_IAM=iam-secret
export OLD_SECRET_NAME_ENCRYPTION_MASTER_KEY=k5-token-encryption-master-key
export OLD_SECRET_NAME_MONGO=cp-dt-backend-mongodb-secret

oc delete secret $OLD_SECRET_NAME_S3_STORAGE -n $OC_NAMESPACE
oc delete secret $OLD_SECRET_NAME_IAM -n $OC_NAMESPACE
oc delete secret $OLD_SECRET_NAME_ENCRYPTION_MASTER_KEY -n $OC_NAMESPACE
oc delete secret $OLD_SECRET_NAME_MONGO -n $OC_NAMESPACE

Solution CLI Setup

Upgrade your CLI:
  • Run fss upgrade-cli

Deployed solutions

After upgrading FSW to version 2.6 the already deployed solutions will not be accessable via the provided Swagger UI linked in the Solution Envoy dashboard due to changed URLs. To fix that, please delete the deployment of these solutions with the Delete row capability in Solution Hub's Deployments view. You can then re-deploy the solution with the existing CI/CD pipeline. All data will remain the same!

Upgrading from 2.3 to 2.6

Adjust solution-designer-values.yaml

Since version 2.5, the following configuration parameters are now configured via the K5 Configurator API and are no longer specified in the solution-designer-values.yaml file and must be removed from it:

  1. global.truststore.secretName
  2. global.identity.url
  3. global.identity.realm
  4. global.identity.adminCredentialsSecretName
  5. global.k5-designer-backend.mongoDb.secretName
  6. global.k5-designer-backend.mongoDb.dbName
  7. global.k5-designer-backend.migration.db.gic.mongoDb.secretName
  8. global.k5-designer-backend.migration.db.gic.mongoDb.dbName
  9. global.k5-git-integration-controller.mongoDb.secretName
  10. global.k5-git-integration-controller.mongoDb.dbName
  11. global.k5-git-integration-controller.tokenEncryptionMasterKey.secretName
  12. global.k5-solution-controller.marketplace.storage.secretName
  13. global.k5-s3-storage.secretName
Note: Before you remove these values, save them and keep them available for the configuration of the installation.

Adjust solution-hub-values.yaml

Since version 2.5, the following configuration parameters are mostly configured via the K5 Configurator API and are no longer specified in the solution-hub-values.yaml file and must be removed from it:

  1. global.identity.url
  2. global.identity.realm
  3. global.truststore.trustMap.identity
Note: Before you remove these values, save them and keep them available for the configuration of the installation.

Migrate Java Low-Code Solutions

All existing low-code solutions with implementation language Java need to be updated in the Git repository due to a known issue. There is only the root level pom.xml file that has to be changed.

Search for the parent attribute and change it according to the following snippet:

<parent>
    <groupId>de.knowis.cp.sdk</groupId>
    <artifactId>cp-framework-managed-sdk-parent</artifactId>
    <version>2.1.5</version>
    <relativePath>./.framework/repo/de/knowis/cp/sdk/cp-framework-managed-sdk-parent/2.1.5/cp-framework-managed-sdk-parent-2.1.5.pom</relativePath>
</parent>

Migrate Java Custom-Code Solutions

Any existing Custom-Code-Solution (Java) needs to be updated in the Git repository. Please change the files listed below. The placeholders <SOLUTION_ACRONYM> (solution acronym in upper case) and <solution_acronym> (solution acronym in lower case) needs to be replaced:

File
./api.json Change the value of url to /<SOLUTION_ACRONYM>/v3/api-docs/<SOLUTION_ACRONYM>
./<solution_acronym>-application/pom.xml Change the value of version of the <parent> to 2.1.6
./<solution_acronym>-application/src/main/java/<solution_acronym>/ config/SecurityConfigurer.java Change line 25 from 
.antMatchers(appContextPath()+"/api-docs").permitAll()
to 
.antMatchers(appContextPath()+"/v3/api-docs/*").permitAll()
./<solution_acronym>-application/src/main/java/<solution_acronym>/ provider/HelloWorldController.java Change 
"/*/api/v1/hello"
in line 17 to 
"/${de.knowis.cp.solution.acronym:<SOLUTION_ACRONYM>}/api/v1/hello"
Please change your other controllers accordingly.

Migrate secrets

In version 2.5 there are a few secrets that have been changed. This needs to be adjusted to migrate from 2.3 to 2.6. The following shows all secrets that have been changed:
Previous secret name
New secret name
k5-s3-storage-access k5-s3-storage-credentials
iam-secret k5-iam-secret
k5-token-encryption-master-key k5-encryption-master-key
cp-dt-backend-mongodb-secret k5-designer-mongodb

There are two possibilities to properly migrate those secrets. Either by using the k5-configurator API as described in the following sections or by using the shell script bellow: Please replace values from the manual data definition with proper values. After doing so execute this script and all secrets should be set properly. 


# Manual data
export JWT={ENTER THE JWT} # Replace this value with a valid OpenShift token
export OC_NAMESPACE={ENTER THE HUB NAMESPACE} # Replace this value with a valid hub namespace
export IAM_USER_REALM={ENTER IAM REALM} # Replace this value with your iam realm
export IAM_HOSTNAME={ENTER IAM HOSTNAME} # Replace this value with your iam hostname

# Status definition
# Replace this only if you changed the old secret names before
export OLD_SECRET_NAME_S3_STORAGE=k5-s3-storage-access
export OLD_SECRET_NAME_IAM=iam-secret
export OLD_SECRET_NAME_ENCRYPTION_MASTER_KEY=k5-token-encryption-master-key
export OLD_SECRET_NAME_MONGO=cp-dt-backend-mongodb-secret


# Auto retrieved data
echo "Retrieving secret values from OpenShift"
export S3_STORAGE_ACCESS_KEY=$(oc get secret ${OLD_SECRET_NAME_S3_STORAGE} -n $OC_NAMESPACE -o jsonpath="{.data.accesskey}" | base64 -d)
export S3_STORAGE_SECRET_KEY=$(oc get secret ${OLD_SECRET_NAME_S3_STORAGE} -n $OC_NAMESPACE -o jsonpath="{.data.secretkey}" | base64 -d)

export IAM_USER_PW=$(oc get secret ${OLD_SECRET_NAME_IAM} -n $OC_NAMESPACE -o jsonpath="{.data.adminPassword}" | base64 -d)
export IAM_USER_NAME=$(oc get secret ${OLD_SECRET_NAME_IAM} -n $OC_NAMESPACE -o jsonpath="{.data.adminUser}" | base64 -d)

export ENCRYPTION_MASTER_KEY=$(oc get secret ${OLD_SECRET_NAME_ENCRYPTION_MASTER_KEY} -n $OC_NAMESPACE -o jsonpath="{.data.key}" | base64 -d)

export MONGO_CONNECTION_STRING=$(oc get secret ${OLD_SECRET_NAME_MONGO} -n $OC_NAMESPACE -o jsonpath="{.data.connectionString}" | base64 -d)

export BASE_URL=$(oc get route k5-configurator -n $OC_NAMESPACE | sed -n 2p | awk '{print $2}')

echo "Successfully retrieved secret values from OpenShift"

# Execute migration
echo "Calling k5-configurator to set s3 storage secret ..."
curl -X PUT "https://$BASE_URL/api/k5-configurator/v1/configs/s3storage" -H  "accept: application/json;charset=UTF-8" -H  "Authorization: Bearer $JWT" -H  "Content-Type: application/json" -d "{\"accesskey\":\"$S3_STORAGE_ACCESS_KEY\",\"secretkey\":\"$S3_STORAGE_SECRET_KEY\"}"

echo "Calling k5-configurator to set iam secrets ..."
curl -X PUT "https://$BASE_URL/api/k5-configurator/v1/configs/iam" -H  "accept: application/json;charset=UTF-8" -H  "Authorization: Bearer $JWT" -H  "Content-Type: application/json" -d "{\"adminUsername\":\"$IAM_USER_NAME\",\"adminPassword\":\"$IAM_USER_PW\",\"hostname\":\"$IAM_HOSTNAME\",\"realm\":\"$IAM_USER_REALM\"}"

echo "Calling k5-configurator to set masterkey secret ..."
curl -X PUT "https://$BASE_URL/api/k5-configurator/v1/configs/masterkey" -H  "accept: application/json;charset=UTF-8" -H  "Authorization: Bearer $JWT" -H  "Content-Type: application/json" -d "{\"key\":\"$ENCRYPTION_MASTER_KEY\"}"

echo "Calling k5-configurator to set mongodb secret ..."
curl -X PUT "https://$BASE_URL/api/k5-configurator/v1/configs/mongodb" -H  "accept: application/json;charset=UTF-8" -H  "Authorization: Bearer $JWT" -H  "Content-Type: application/json" -d "{\"connectionString\":\"$MONGO_CONNECTION_STRING\"}"
echo "Successfully set all secrets"

k5-s3-storage-access

1. Use the values from k5-s3-storage-access of your old 2.3 installation to configure the new secret. Those secret values are relevant to do so:
  • accesskey
  • secretkey
2. Use the provided API {BASE_URL}/api/k5-configurator/v1/configs/s3storage with your secretkey and accesskey in the request body to update the new secret value with the old one.
Note: This configures the new secret k5-s3-storage-credentials

iam-secret

1. Use the values from iam-secret of your old 2.3 installation to configure the new secret. Those secret values are relevant to do so:
  • adminPassword
  • adminUsername
  • realm
  • hostname
2. Use the provided API {BASE_URL}/api/k5-configurator/v1/configs/iam and the above mentioned secret values in the request body.
Note: This configures two new secrets: k5-iam-settings and k5-iam-secret

k5-token-encryption-master-key

1. Use the values from k5-token-encryption-master-key of your old 2.3 installation to configure the new secret. This secret value is relevant to do so:
  • key
2. Use the provided API {BASE_URL}/api/k5-configurator/v1/configs/masterkey and the above mentioned secret value in the request body.
Note: This configures the new secret k5-encryption-master-key

cp-dt-backend-mongodb-secret

1. Use the values from cp-dt-backend-mongodb-secret of your old 2.3 installation to configure the new secret. This secret value is relevant to do so:
  • connectionString
2. Use the provided API {BASE_URL}/api/k5-configurator/v1/configs/mongodb and the above mentioned secret value in the request body.
Note: This configures the new secret k5-designer-mongodb

Cleanup secrets

After successfully migrating all secrets, please verify your installation and check if all is working smoothly. Use the API's shown in the previous sections to get all secrets and verify if all is set up properly. Once this is done, one can cleanup the old unused secrets.
Warning: Please be aware that after cleaning-up, those secrets cannot be restored and the data is lost. Make sure that everything is up and running before cleaning secrets.

# Manual data
export OC_NAMESPACE={ENTER THE HUB NAMESPACE} # Replace this value with a valid hub namespace

# Status definition
# Replace this only if you changed the old secret names before
export OLD_SECRET_NAME_S3_STORAGE=k5-s3-storage-access
export OLD_SECRET_NAME_IAM=iam-secret
export OLD_SECRET_NAME_ENCRYPTION_MASTER_KEY=k5-token-encryption-master-key
export OLD_SECRET_NAME_MONGO=cp-dt-backend-mongodb-secret

oc delete secret $OLD_SECRET_NAME_S3_STORAGE -n $OC_NAMESPACE
oc delete secret $OLD_SECRET_NAME_IAM -n $OC_NAMESPACE
oc delete secret $OLD_SECRET_NAME_ENCRYPTION_MASTER_KEY -n $OC_NAMESPACE
oc delete secret $OLD_SECRET_NAME_MONGO -n $OC_NAMESPACE

Solution CLI Setup

Upgrade your CLI:
  • Run fss upgrade-cli

Deployed solutions

After upgrading FSW to version 2.6 the already deployed solutions will not be accessable via the provided Swagger UI linked in the Solution Envoy dashboard due to changed URLs. To fix that, please delete the deployment of these solutions with the Delete row capability in Solution Hub's Deployments view. You can then re-deploy the solution with the existing CI/CD pipeline. All data will remain the same!

Upgrading from 2.4 to 2.6

Adjust solution-designer-values.yaml

Since version 2.6, the following configuration parameters are now configured via the K5 Configurator API and are no longer specified in the solution-designer-values.yaml file and must be removed from it:

  1. global.truststore.secretName
  2. global.identity.url
  3. global.identity.realm
  4. global.identity.adminCredentialsSecretName
  5. global.k5-designer-backend.mongoDb.secretName
  6. global.k5-designer-backend.mongoDb.dbName
  7. global.k5-designer-backend.migration.db.gic.mongoDb.secretName
  8. global.k5-designer-backend.migration.db.gic.mongoDb.dbName
  9. global.k5-git-integration-controller.mongoDb.secretName
  10. global.k5-git-integration-controller.mongoDb.dbName
  11. global.k5-git-integration-controller.tokenEncryptionMasterKey.secretName
  12. global.k5-solution-controller.marketplace.storage.secretName
  13. global.k5-s3-storage.secretName
Note: Before you remove these values, save them and keep them available for the configuration of the installation.

Adjust solution-hub-values.yaml

Since version 2.5, the following configuration parameters are now configured via the K5 Configurator API and are no longer specified in the solution-hub-values.yaml file and must be removed from it:

  1. global.identity.url
  2. global.identity.realm
  3. global.truststore.trustMap.identity
Note: Before you remove these values, save them and keep them available for the configuration of the installation.

Migrate Java Low-Code Solutions

All existing low-code solutions with implementation language Java need to be updated in the Git repository due to a known issue. There is only the root level pom.xmlfile that has to be changed.

Search for the parent attribute and change it according to the following snippet:

<parent>
    <groupId>de.knowis.cp.sdk</groupId>
    <artifactId>cp-framework-managed-sdk-parent</artifactId>
    <version>2.1.5</version>
    <relativePath>./.framework/repo/de/knowis/cp/sdk/cp-framework-managed-sdk-parent/2.1.5/cp-framework-managed-sdk-parent-2.1.5.pom</relativePath>
</parent>

Migrate secrets

In version 2.5 there are a few secrets that have been changed. This needs to be adjusted to migrate from 2.4 to 2.6. The following shows all secrets that have been changed:
Previous secret name
New secret name
k5-s3-storage-access k5-s3-storage-credentials
iam-secret k5-iam-secret
k5-token-encryption-master-key k5-encryption-master-key
cp-dt-backend-mongodb-secret k5-designer-mongodb

There are two possibilities to properly migrate those secrets. Either by using the k5-configurator API as described in the following sections or by using the shell script bellow: Please replace values from the manual data definition with proper values. After doing so execute this script and all secrets should be set properly. 


# Manual data
export JWT={ENTER THE JWT} # Replace this value with a valid OpenShift token
export OC_NAMESPACE={ENTER THE HUB NAMESPACE} # Replace this value with a valid hub namespace
export IAM_USER_REALM={ENTER IAM REALM} # Replace this value with your iam realm
export IAM_HOSTNAME={ENTER IAM HOSTNAME} # Replace this value with your iam hostname

# Status definition
# Replace this only if you changed the old secret names before
export OLD_SECRET_NAME_S3_STORAGE=k5-s3-storage-access
export OLD_SECRET_NAME_IAM=iam-secret
export OLD_SECRET_NAME_ENCRYPTION_MASTER_KEY=k5-token-encryption-master-key
export OLD_SECRET_NAME_MONGO=cp-dt-backend-mongodb-secret


# Auto retrieved data
echo "Retrieving secret values from OpenShift"
export S3_STORAGE_ACCESS_KEY=$(oc get secret ${OLD_SECRET_NAME_S3_STORAGE} -n $OC_NAMESPACE -o jsonpath="{.data.accesskey}" | base64 -d)
export S3_STORAGE_SECRET_KEY=$(oc get secret ${OLD_SECRET_NAME_S3_STORAGE} -n $OC_NAMESPACE -o jsonpath="{.data.secretkey}" | base64 -d)

export IAM_USER_PW=$(oc get secret ${OLD_SECRET_NAME_IAM} -n $OC_NAMESPACE -o jsonpath="{.data.adminPassword}" | base64 -d)
export IAM_USER_NAME=$(oc get secret ${OLD_SECRET_NAME_IAM} -n $OC_NAMESPACE -o jsonpath="{.data.adminUser}" | base64 -d)

export ENCRYPTION_MASTER_KEY=$(oc get secret ${OLD_SECRET_NAME_ENCRYPTION_MASTER_KEY} -n $OC_NAMESPACE -o jsonpath="{.data.key}" | base64 -d)

export MONGO_CONNECTION_STRING=$(oc get secret ${OLD_SECRET_NAME_MONGO} -n $OC_NAMESPACE -o jsonpath="{.data.connectionString}" | base64 -d)

export BASE_URL=$(oc get route k5-configurator -n $OC_NAMESPACE | sed -n 2p | awk '{print $2}')

echo "Successfully retrieved secret values from OpenShift"

# Execute migration
echo "Calling k5-configurator to set s3 storage secret ..."
curl -X PUT "https://$BASE_URL/api/k5-configurator/v1/configs/s3storage" -H  "accept: application/json;charset=UTF-8" -H  "Authorization: Bearer $JWT" -H  "Content-Type: application/json" -d "{\"accesskey\":\"$S3_STORAGE_ACCESS_KEY\",\"secretkey\":\"$S3_STORAGE_SECRET_KEY\"}"

echo "Calling k5-configurator to set iam secrets ..."
curl -X PUT "https://$BASE_URL/api/k5-configurator/v1/configs/iam" -H  "accept: application/json;charset=UTF-8" -H  "Authorization: Bearer $JWT" -H  "Content-Type: application/json" -d "{\"adminUsername\":\"$IAM_USER_NAME\",\"adminPassword\":\"$IAM_USER_PW\",\"hostname\":\"$IAM_HOSTNAME\",\"realm\":\"$IAM_USER_REALM\"}"

echo "Calling k5-configurator to set masterkey secret ..."
curl -X PUT "https://$BASE_URL/api/k5-configurator/v1/configs/masterkey" -H  "accept: application/json;charset=UTF-8" -H  "Authorization: Bearer $JWT" -H  "Content-Type: application/json" -d "{\"key\":\"$ENCRYPTION_MASTER_KEY\"}"

echo "Calling k5-configurator to set mongodb secret ..."
curl -X PUT "https://$BASE_URL/api/k5-configurator/v1/configs/mongodb" -H  "accept: application/json;charset=UTF-8" -H  "Authorization: Bearer $JWT" -H  "Content-Type: application/json" -d "{\"connectionString\":\"$MONGO_CONNECTION_STRING\"}"
echo "Successfully set all secrets"

k5-s3-storage-access

1. Use the values from k5-s3-storage-access of your old 2.4 installation to configure the new secret. Those secret values are relevant to do so:
  • accesskey
  • secretkey
2. Use the provided API {BASE_URL}/api/k5-configurator/v1/configs/s3storage with your secretkey and accesskey in the request body to update the new secret value with the old one.
Note: This configures the new secret k5-s3-storage-credentials

iam-secret

1. Use the values from iam-secret of your old 2.4 installation to configure the new secret. Those secret values are relevant to do so:
  • adminPassword
  • adminUsername
  • realm
  • hostname
2. Use the provided API {BASE_URL}/api/k5-configurator/v1/configs/iam and the above mentioned secret values in the request body.
Note: This configures two new secrets: k5-iam-settings and k5-iam-secret

k5-token-encryption-master-key

1. Use the values from k5-token-encryption-master-key of your old 2.4 installation to configure the new secret. This secret value is relevant to do so:
  • key
2. Use the provided API {BASE_URL}/api/k5-configurator/v1/configs/masterkey and the above mentioned secret value in the request body.
Note: This configures the new secret k5-encryption-master-key

cp-dt-backend-mongodb-secret

1. Use the values from cp-dt-backend-mongodb-secret of your old 2.4 installation to configure the new secret. This secret value is relevant to do so:
  • connectionString
2. Use the provided API {BASE_URL}/api/k5-configurator/v1/configs/mongodb and the above mentioned secret value in the request body.
Note: This configures the new secret k5-designer-mongodb

Cleanup secrets

After successfully migrating all secrets, please verify your installation and check if all is working smoothly. Use the API's shown in the previous sections to get all secrets and verify if all is set up properly. Once this is done, one can cleanup the old unused secrets.
Warning: Please be aware that after cleaning-up, those secrets cannot be restored and the data is lost. Make sure that everything is up and running before cleaning secrets.

# Manual data
export OC_NAMESPACE={ENTER THE HUB NAMESPACE} # Replace this value with a valid hub namespace

# Status definition
# Replace this only if you changed the old secret names before
export OLD_SECRET_NAME_S3_STORAGE=k5-s3-storage-access
export OLD_SECRET_NAME_IAM=iam-secret
export OLD_SECRET_NAME_ENCRYPTION_MASTER_KEY=k5-token-encryption-master-key
export OLD_SECRET_NAME_MONGO=cp-dt-backend-mongodb-secret

oc delete secret $OLD_SECRET_NAME_S3_STORAGE -n $OC_NAMESPACE
oc delete secret $OLD_SECRET_NAME_IAM -n $OC_NAMESPACE
oc delete secret $OLD_SECRET_NAME_ENCRYPTION_MASTER_KEY -n $OC_NAMESPACE
oc delete secret $OLD_SECRET_NAME_MONGO -n $OC_NAMESPACE

Solution CLI Setup

Upgrade your CLI:
  • Run fss upgrade-cli

Deployed solutions

After upgrading FSW to version 2.6 the already deployed solutions will not be accessable via the provided Swagger UI linked in the Solution Envoy dashboard due to changed URLs. To fix that, please delete the deployment of these solutions with the Delete row capability in Solution Hub's Deployments view. You can then re-deploy the solution with the existing CI/CD pipeline. All data will remain the same!

Upgrading from 2.5 to 2.6

There is currently only one manual upgrade step necessary.

Migrate Java Low-Code Solutions

All existing low-code solutions with implementation language Java need to be updated in the Git repository due to a known issue. There is only the root level pom.xml file that has to be changed.

Search for the parent attribute and change it according to the following snippet:

<parent>
    <groupId>de.knowis.cp.sdk</groupId>
    <artifactId>cp-framework-managed-sdk-parent</artifactId>
    <version>2.1.5</version>
    <relativePath>./.framework/repo/de/knowis/cp/sdk/cp-framework-managed-sdk-parent/2.1.5/cp-framework-managed-sdk-parent-2.1.5.pom</relativePath>
</parent>