Configuring IBM Transformation Advisor

CASE installer configuration

Options for install action:

oc ibm-pak launch \
    $CASE_NAME \
    --version $CASE_VERSION \
    --inventory v2InstallProduct \
    --namespace $TA_PROJECT \
    --action install \
    --args "[OPTIONS]"
 

--licenseType <true|false>          : REQUIRED: Must be used and set to a valid license type.
--acceptLicense <true|false>        : REQUIRED: Must be used and set to true to proceed with install.
--installIbmCatalog <true|false>    : OPTIONAL: If set to true, the IBM operator catalog will be installed if it is not already. Default is false.
--secret <secret>                   : OPTIONAL: Specify a secret to use to pull the Tranformation Advisor images from entitle registry.
--registry <registry>               : OPTIONAL: Specified entitled registry, e.g. cp.icr.io.
--user <user>                       : OPTIONAL: Specify user to access the entitled registry.
--pass <password>                   : OPTIONAL: Specify password for user to access entitled registry.
--persistence <true|false>          : OPTIONAL: If persistence is required for Transformation Advisor (Default is true).
--accessMode <accessMode>           : OPTIONAL: storage accessMode. Default is ReadWriteOnce.
--persistenceClaimCouchDB <claim>   : OPTIONAL: Use an existing persistence claim for CouchDB.
--persistenceClaimNeo4j <claim>     : OPTIONAL: Use an existing persistence claim for Neo4j.
--storageClass <storage class>      : OPTIONAL: Recommended way use persistence with Transformation Advisor. Specify a valid storage class to use.
--supplementalGroups [gid,...]      : OPTIONAL: May be used if using file system based storage to ensure database container has read/write permission for the storage.
--hostName <hostname>               : OPTIONAL: hostname to access cluster. Transformation Advisor will discover and set this value. It should not need to be changed for most environments.
--apiEndpoint <apiEndpoint>         : OPTIONAL: API url for the cluster. Transformation Advisor will discover and set this value. It should not need to be changed for most environments.
--authIssuerEndpoint <aiEndpoint>   : OPTIONAL: Auth issuer endpoint for the cluster. Transformation Advisor will discover and set this value. It should not need to be changed for most environments.
--publicUrlServer                   : OPTIONAL: See docs for more information. Transformation Advisor will discover and set this value. It should not need to be changed for most environments.
--publicUrlUI                       : OPTIONAL: See docs for more information. Transformation Advisor will discover and set this value. It should not need to be changed for most environments.
--customCACert <file path>          : OPTIONAL: Specify file to use as custom CA cert.
--authConfigFile <file path>        : OPTIONAL: Specify file to use to configure third party authentication.
--namespaceScoped <true|false>      : OPTIONAL: If ommitted, defaults to false. This will make the operator to be insalled into openshift-operators namespace and manage all the namespaces, operand will go into namespace specified by --namespace attribute. If set to true, operator and operand are installed into namespace specified by --namespace attribute.
--taHelp                            : OPTIONAL: Display options available
 

Options for uninstall action:

oc ibm-pak launch \
    $CASE_NAME \
    --version $CASE_VERSION \
    --case ibm-transadv \
    --inventory v2InstallProduct \
    --namespace $TA_PROJECT \
    --action uninstall \
    --args "[OPTIONS]"
 

--uninstallIbmCatalog <true|false>    : OPTIONAL: If set to true, the IBM operator catalog will be uninstalled. Default is false.
--uninstallTaCatalog <true|false>     : OPTIONAL: If set to true, the IBM operator catalog will be uninstalled. Default is false.
 

Configure third-party authentication

Update third-party OAuthClient or OAuthApp

You need to configure the redirection URL to allow the OAuthClient or OAuthApp redirect to Transformation Advisor UI route.

The redirection URL is your-ta-ui-route/auth/callback

For example, https://ta.apps.ken.cp.fyre.ibm.com/auth/callback, where https://ta.apps.ken.cp.fyre.ibm.com is the Transformation Advisor UI route.

You can get this route from the OCP UI in the navigation: Networking -> Routes -> ta-ui-route -> Location

Configuring MFA

Integrating Multi-Factor Authentication (MFA) with Red Hat OpenShift Container Platform strengthens security by requiring users to verify their identity through multiple methods, such as a password, a one-time passcode (OTP), or other supported verification factors. Red Hat OpenShift does not natively enforce MFA. For more information, see How to integrate Multi-Factor Authentication for authentication in OpenShift 4.

Client ID and secret

Before Transformation Advisor 3.4.0, you need to update the OAuthClient's or OAuthApp's client ID and secret in the Transformation Advisor instance configuration using the properties authentication.oidc.clientId and authentication.oidc.clientSecret.

Transformation Advisor 3.4.0 or after, you need to supply to the client Id and client secret in a secret transformation-advisor-secret before you install Transformation Advisor. Here is the command:

oc create secret generic transformation-advisor-secret \
--from-literal=clientId=your-clientId-value \
--from-literal=clientSecret=your-clientSecret-value
 

Alternatively, you can update your secret after the installation of Transformation Advisor. Here is the command:

oc patch secret transformation-advisor-secret \
-p '{"data":{"'"clientId"'": "'"your-clientId-value"'", "'"clientSecret"'": "'"your-clientSecret-value"'"}}' --type=merge
 

Then, you may need to delete the Server and UI pods, so the new secret values can be applied to the pods.

Update egress network policy

Configuring third-party authentication - UI install

IAM

Transformation Advisor can be configured to use IBM Identity and Access Management (IAM) as an authentication source.

1. Perform OpenID Connect (OIDC) registration as per instructions here: https://www.ibm.com/docs/en/cpfs?topic=sign-automated-client-registration-method-3

2. Following the process in step 1, a secret will be created that contains the clientId and clientSecret. Add the clientId and clientSecret to the Transformation Advisor secret ( as specified in property: authentication.ocp.secretName).

3. Update the Transformation Advisor configuration values as follows:

      description: "IAM"
      identityRequestEndpoint: "https://cp-console.<OCP domain>:443"
      identityRequestEndpointPath: "/idprovider/v1/auth/authorize"
      identityRequestEndpointScope: "openid+profile+email"
      identityRequestEndpointStatePrefix: ""
      tokenRequestEndpoint: "https://cp-console.<OCP domain>:443"
      tokenRequestEndpointPath: "/idprovider/v1/auth/token"
      tokenVerificationEndpoint: "https://cp-console.<OCP domain>:443"
      tokenVerificationEndpointPath: "/idprovider/v1/auth/userInfo"
 

Github OAuth

The following is an example of the configuration required in the thirdparty configuration object to use Github OAuth:

      description: "github"
      identityRequestEndpoint: "https://github.com"
      identityRequestEndpointPath: "/login/oauth/authorize"
      identityRequestEndpointScope: "openid+offline"
      identityRequestEndpointStatePrefix: ""
      tokenRequestEndpoint: "https://github.com"
      tokenRequestEndpointPath: "/login/oauth/access_token"
      tokenVerificationEndpoint: "https://api.github.com"
      tokenVerificationEndpointPath: "/user"
 

Box OAuth

The following is an example of the configuration required in the thirdparty configuration object to use Box OAuth:

      description: "box"
      identityRequestEndpoint: "https://account.box.com"
      identityRequestEndpointPath: "/api/oauth2/authorize"
      identityRequestEndpointScope: "root_readonly"
      identityRequestEndpointStatePrefix: ""
      tokenRequestEndpoint: "https://api.box.com"
      tokenRequestEndpointPath: "/oauth2/token"
      tokenVerificationEndpoint: "https://api.box.com"
      tokenVerificationEndpointPath: "/2.0/users/me"
 

Configuring third-party authentication - CASE install

Specify a third-party authentication configuration file using the --authConfigFile option with the CASE install action.

The following is an example of that file that uses GitHub OAuth:

Do not change the format of the file.

# set to true to disable authentication on UI server
TA_AUTH_UI_DISABLED=false
# set to true to disable authentication on Liberty server
TA_AUTH_LIBERTY_DISABLED=false

# OAuth2 Server client id
TA_AUTH_OIDC_CLIENT_ID=xxx
# OAuth2 Server client secret
TA_AUTH_OIDC_CLIENT_SECRET=xxx

# endpoint to request identity of the OAuth2 Server, no tailing /
TA_AUTH_IDENTITY_REQUEST_ENDPOINT=https://github.com
# path of the endpoint to request identity to OAuth2 Server, with heading /
TA_AUTH_IDENTITY_REQUEST_ENDPOINT_PATH=/login/oauth/authorize
# OAuth2 scope
TA_AUTH_IDENTITY_REQUEST_ENDPOINT_SCOPE=openid+offline
# some OAuth2 state requires minimum length, default to empty
TA_AUTH_CALLBACK_STATE_PREFIX_PADDING=

# endpoint to request token of the OAuth2 Server, no tailing /
TA_AUTH_TOKEN_REQUEST_ENDPOINT=https://github.com
# path of the endpoint to request token of the OAuth2 Server, with heading /
TA_AUTH_TOKEN_REQUEST_ENDPOINT_PATH=/login/oauth/access_token

# endpoint to verify tokens of the OAuth2 Server, no tailing /
TA_AUTH_TOKEN_VERIFICATION_ENDPOINT=https://api.github.com
# path to the endpoint to verify tokens of the OAuth2 Server, with heading /
TA_AUTH_TOKEN_VERIFICATION_ENDPOINT_PATH=/user
 

Enable Bring Your Own Key (BYOK)

You can bring your own certificate (referred to as cert in the rest of the section) and key used for internal TLS.

Assuming:

1. The public cert is public.crt, and the private key is private.pem.
2. Transformation Advisor is or to be installed in the ta namespace.

Here is an example of how to get a cert and key pair, and your own cert and key shall be in the same format:

openssl req -newkey rsa:2048 -nodes -keyout private.pem -x509 -days 730 -out public.crt -subj "/C=IE/ST=Cork/L=Cork/O=IBM/CN=internal.ta.ibm.com" -addext "subjectAltName=DNS:ta-couchdb.<namespace>.svc,DNS:*.ta-couchdb.<namespace>.svc,DNS:*.ta-couchdb.<namespace>.svc.cluster.local,DNS:ta-couchdb.<namespace>.svc.cluster.local
 

After you obtain your own cert and key pair, follow the steps to enable your own cert and key:

1. Switch to ta namespace, or create one if you haven't installed Transformation Advisor.

      # switch the project
      oc project ta
    

   or

      # create ta ns if it's not already there
      oc create ns ta
    

2. Delete the Transformation Advisor secret transformation-advisor-secret, if it exists.

   oc delete secret transformation-advisor-secret
    

3. If installing via the CASE installer, pass the --customCACert <public.crt> where <public.crt> is the full path to the public.crt file.

   If installing via the OpenShift UI, update the caCert property in the custom resource YAML. See Installing for more details on accessing the custom resource YAML from the UI.

   Here is an example of caCert in the custom resource YAML:

         tls:
           enabled: true
           caCert: |
             -----BEGIN CERTIFICATE-----
             MIIDKjCCAhICCQCjbqTC95dw+jANBgkqhkiG9w0BAQsFADBXMQswCQYDVQQGEwJJ
             RTENMAsGA1UECAwEQ29yazENMAsGA1UEBwwEQ29yazEMMAoGA1UECgwDSUJNMRww
             GgYDVQQDDBNpbnRlcm5hbC50YS5pYm0uY29tMB4XDTIwMDEyMDEzMjkxMVoXDTIy
             MDExOTEzMjkxMVowVzELMAkGA1UEBhMCSUUxDTALBgNVBAgMBENvcmsxDTALBgNV
             BAcMBENvcmsxDDAKBgNVBAoMA0lCTTEcMBoGA1UEAwwTaW50ZXJuYWwudGEuaWJt
             LmNvbTCCASIwDQYJKoZIhvcNAQEBBQADggEPADCCAQoCggEBAKMIGfSptUnimmxZ
             IdVK6uLscJQetel+MX7u4viIaBwdd/IGDE7GHDHEYYFmEfv+gYbVT1+EAkdiLtHG
             SutUMPxpbUyv1xCW+9z3nDInHKzZxHMJJwB5j4+oVq+XkdXzZu2hwuoc0aA7Ek3r
             L6FFPIQi9bcmayuOa7HRpH43+86JuJF8tcx1MrDxWzBJraZNuvDVLs574qr/eM2d
             x5N+qkJqwOy94k0eH+x7kAKRp6vBEcVR+I/HHYDZSnC4UNEX8I/NbCS3wMUXysC9
             lcC2vsIKrCRSn9Fu/ixWwlGy6QV1my4H6ZPtvJV56fcS42523KTDbT628Xa9B3/p
             cX0WZWMCAwEAATANBgkqhkiG9w0BAQsFAAOCAQEADIyp9A4p46DZ6brEbL0e+wWf
             bnnymf1QZWcz4xrrMW2CcKBmRqFIPFPBpSEbCKlsFaZex5863z7dsa5SU7fHRdHF
             Yk9t8mGu2B+yZF6nW4biPmezaDLPi9VUomxcd+/rxWKhZJIufWXxs22AOhNQHeeK
             PSjP8RPCh1Gny7kC3jUz1Q/wd4QF/OGeu+Xf5jhERpJPfjKMtPMPJPGiPYSqhYQM
             VA6G83nZVlPDtnFJ28AzZU2/YtvCzhU66Ua5PjbSG1w6QsXZt/lE3E9utcJ+MNQi
             3JwrLp4/97cupXsGmPPmkvH50LB8ex/N/ra6QOLGLm0gU218yXu7KezOfZNkTw==
             -----END CERTIFICATE-----
    

   You can manually copy and paste to the location. Remember, the indentation is important. There are 2 extra spaces for each line of the cert than the line of caCert.

4. Re-create the Transformation Advisor secret.

       # create key.p12
       openssl pkcs12 -export -inkey private.pem -in public.crt -name default -out key.p12 -passout pass:plain-text-password
   
       # base64 encode private.pem and public.crt
       base64 -w 0 ./private.pem > private-base64
       base64 -w 0 ./public.crt > public-base64
       # on Mac
       # base64 ./private.pem > private-base64
       # base64 ./public.crt > public-base64
   
       # create key and initial vector for AES-CBC-256 (P)
       # key length for aes256 is 256 bits around 32 characters
       TA_TEMP_KEY=`LC_CTYPE=C tr -dc A-Za-z0-9_ < /dev/urandom | head -c 32 | xargs`
       # key length for aes256 is 128 bits around 16 characters
       TA_TEMP_IV=`LC_CTYPE=C tr -dc A-Za-z0-9_ < /dev/urandom | head -c 16 | xargs`
   
       # create transformation-advisor-secret
       oc create secret generic transformation-advisor-secret \
       --from-literal=db_username='plain-text-username' --from-literal=secret='plain-text-password' \
       --from-file=ta_public_key=./public-base64 --from-file=ta_private_key=./private-base64 \
       --from-literal=ta_aes_key=$TA_TEMP_KEY --from-literal=ta_aes_iv=$TA_TEMP_IV \
       --from-file=key.p12=key.p12
    

You can now proceed with your installation.

Create an image pull secret to pull the entitled registry images

To avail of support for Transformation Advisor, one needs to provide access permissions to the Entitled Registry - this is done via creation of an Image Pull Secret and pointing to it on install. The name of the secret must be ibm-entitlement-key. A secret needs to be created in the same namespace where the product instance is installed or globally.

Please refer to the Image Registry Images Access document for more details on that. Here is how to point to the secret from Transformation Advisor instance configuration page:

couchdb:
  imagePullSecret: ibm-entitlement-key

neo4j:
  imagePullSecret: ibm-entitlement-key
  
transadv:
  imagePullSecret: ibm-entitlement-key

transadvui:
  imagePullSecret: ibm-entitlement-key
 

Provide your own credentials to access Transformation Advisor's internal DB's

Transformation Advisor creates random credentials to communicate with internal DB's (CouchDB and Neo4j) when it gets installed first time.

However, it is possible to provide your own credentials for this purpose.

The credentials are kept in a Kubernetes secret (called transformation-advisor-secret by default) object, which can be created as follows:

TA_TEMP_KEY=`LC_CTYPE=C tr -dc A-Za-z0-9_ < /dev/urandom | head -c 32 | xargs`
TA_TEMP_IV=`LC_CTYPE=C tr -dc A-Za-z0-9_ < /dev/urandom | head -c 16 | xargs`

oc -n <YOUR_TA_INSTANCE_NAMESPACE> create secret generic <YOUR_SECRET_NAME> \
  --from-literal=db_username=<YOUR_COUCHDB_USERNAME> \
  --from-literal=secret=<YOUR_COUCHDB_PASSWORD> \
  --from-literal=db_nonadmin_user=<YOUR_COUCHDB_NONADMIN_USERNAME> \
  --from-literal=db_nonadmin_secret=<YOUR_COUCHDB_NONADMIN_PASSWORD> \
  --from-literal=neo4j_username=<YOUR_NEO4J_USERNAME> \
  --from-literal=neo4j_secret=<YOUR_NEO4J_PASSWORD> \
  --from-literal=neo4j_auth=neo4j/<YOUR_NEO4J_PASSWORD>
 

Read the Re-create the TA secret section of this document to see how to create the public-base64 and private-base64 files.

You can provide your secret name at the time of installation of a Transformation Advisor instance in: .authentication.ocp.secretName

Edit cipher suites and TLS versions

Cipher suites are set automatically for Neo4j and the UI container.

For the Server and CouchDB container, you can set them manually by modifying those variables at installation time: couchdb.security.cipherSuites and transadv.security.cipherSuites.

Look up the default values in the previous table. Add your own as a whitespace-separated string.

Similarly, TLS versions can be set manually for the CouchDB container. The variable for that is couchdb.security.tlsVersions. See the previous table for default values.