Upgrading from 2.4 to 2.8

Adjust Solution Designer

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:

  • global.endpoints.localMarketplaceController.host

  • k5-local-marketplace-controller.marketplace.storage.secretName

Tip: You can probably use the default values for these parameters, see Installation Process.

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:

  • global.truststore.secretName

  • global.identity.url

  • global.identity.realm

  • global.identity.adminCredentialsSecretName

  • global.k5-designer-backend.mongoDb.secretName

  • global.k5-designer-backend.mongoDb.dbName

  • global.k5-designer-backend.migration.db.gic.mongoDb.secretName

  • global.k5-designer-backend.migration.db.gic.mongoDb.dbName

  • global.k5-git-integration-controller.mongoDb.secretName

  • global.k5-git-integration-controller.mongoDb.dbName

  • global.k5-git-integration-controller.tokenEncryptionMasterKey.secretName

  • global.k5-solution-controller.marketplace.storage.secretName

  • 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

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:

  • global.identity.url

  • global.identity.realm

  • 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 projects

All existing low-code projects 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 pro-code projects

Every existing pro-code project with implementation language Java needs to be updated in the Git repository. Please change the files listed below. The placeholders <PROJECT_ACRONYM> (project acronym in upper case) and <project_acronym> (project acronym in lower case) needs to be replaced:

Necessary File Changes

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

Note: 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.4 to 2.6. The following shows all secrets that have been changed:

Previous Secret NameNew Secret Name
k5-s3-storage-accessk5-s3-storage-credentials
iam-secretk5-iam-secret
k5-token-encryption-master-keyk5-encryption-master-key
cp-dt-backend-mongodb-secretk5-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 below. 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 secret value mentioned above 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 secret value mentioned above 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 secret value mentioned above 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 APIs shown in the previous sections to get all secrets and verify if all is set up properly. Once this is done, one can clean up 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

Upgrade Solution CLI

Upgrade the Solution CLI to the latest version (4.2.64).

fss upgrade-cli

Access deployed projects

After upgrading IBM Financial Services Workbench to version 2.8 already deployed projects will not be accessible 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 project with the existing CI/CD pipeline. All data will remain the same!