Procedure

1. In the Red Hat OpenShift web console, click Operators.
2. Click OperatorHub.
3. Type MTA in the Filter by keyword field to search for the MTA Operator.
4. Click Migration toolkit for applications (MTA) Operator.
5. Click Install.
6. On the Install Operator page, click Install.

7. Optional: Review and edit the custom resource (CR) settings.

   A window for creating CR settings opens automatically after the installation of the MTA Operator is complete. The default settings are acceptable. However, make sure to check the system requirements for storage, memory, and cores.

   Alternatively, to work directly with the YAML file, click the YAML view and review the CR settings listed in the spec section of the YAML file.

   The spec section of the YAML file can have the following configuration:

   kind: Tackle
   apiVersion: tackle.konveyor.io/v1alpha1
   metadata:
     name: mta
     namespace: openshift-mta
   spec:
     hub_bucket_volume_size: "2.5Gi"
     maven_data_volume_size: "2.5Gi"
     rwx_supported: "false"

8. Verify that the MTA pods are running:

   1. In the Administration view, click Workloads.
   2. Click Pods.

Procedure

1. Click MTA Operator.
2. Under Provided APIs, search for Tackle.
3. Click Create Instance.
4. Access the user interface from your browser by using the route provided by the mta-ui application within Red Hat OpenShift.

5. Log in to the user interface instance by using the default credentials:

   • Username: admin
   • Password: Passw0rd!
6. When prompted, create a new password.

Procedure

1. Navigate to the MTA download page and download one of the following operating system-specific CLI files or the src file:

   • mta-8.1.2-cli-linux-amd64.zip
   • mta-8.1.2-cli-linux-arm64.zip
   • mta-8.1.2-cli-darwin-amd64.zip
   • mta-8.1.2-cli-darwin-arm64.zip
   • mta-8.1.2-cli-windows-amd64.zip
   • mta-8.1.2-cli-windows-arm64.zip
   • mta-8.1.2-cli-src.zip
2. Extract the .zip file to the .kantra directory inside your $HOME directory. The .zip file extracts the mta-cli binary, along with other required directories and files.

3. Move the mta-cli binary to your $PATH variable.

   Note

   You can place the mta-cli binary in any folder that is included in the $PATH variable. You can also add a folder that contains mta-cli to $PATH. This way, you do not need to specify a full path when using the CLI.

1. Download the required images by using an external computer.
2. Copy the downloaded images to the system you want to install the MTA CLI on.

Procedure

1. On a connected device, perform the following steps:

   1. Authenticate to registry.redhat.io:

      $ podman login registry.redhat.io

   2. Run the mta-cli binary file:

      $ mta-cli analyze

      Important

      The binary file pulls only the required provider images. For example, if you run a command that requires Java images, the command will not pull .NET images.

   3. Display the image list:

      $ podman images

      REPOSITORY                                                        TAG         IMAGE ID      CREATED       SIZE
      registry.redhat.io/mta/mta-generic-external-provider-rhel9        7.3.1       8b8d7fa14570  13 days ago   692 MB
      registry.redhat.io/mta/mta-cli-rhel9                              7.3.1       45422a12d936  13 days ago   1.6 GB
      registry.redhat.io/mta/mta-java-external-provider-rhel9           7.3.1       4d6d0912a38b  13 days ago   715 MB
      registry.redhat.io/mta/mta-dotnet-external-provider-rhel9         7.3.1       66ec9fc51408  13 days ago   1.27 GB

   4. Save the images:

      $ podman save <image_ID> -o <image_name>.image

   5. Copy the images onto a USB drive or directly to the file system of the disconnected device.

2. On the disconnected device, enter:

   $ podman load --input <image_name>.image

Procedure

1. Open a PowerShell with Administrator privileges.

2. Ensure Hyper-V is installed and enabled:

   PS C:\Users\<user_name>> Enable-WindowsOptionalFeature -Online ` -FeatureName Microsoft-Hyper-V-All

   PS C:\Users\<user_name>> Enable-WindowsOptionalFeature -Online ` -FeatureName Containers

   Note

   You might need to reboot Windows for the change to take effect.

3. Install Docker Desktop on Windows.

   1. Run the installation program by double-clicking the Docker_Desktop_Installer.exe file.

      By default, Docker Desktop is installed to the C:\Program Files\Docker\Docker path.

   2. Ensure that Docker runs Windows containers as the backend instead of Linux containers:

      1. In the Windows task bar, right-click the Docker icon.
      2. Click Switch to Windows containers.

4. In PowerShell, create a folder for MTA:

   PS C:\Users\<user_name>> mkdir C:\Users\<user_name>\MTA

5. Extract the mta-8.1.2-cli-windows.zip file to the MTA folder:

   PS C:\Users\<user_name>> cd C:\Users\<user_name>\Downloads

   PS C:\Users\<user_name>> Expand-Archive ` -Path "{ProductShortNameLower}-{ProductVersion}-cli-windows.zip" ` -DestinationPath "C:\Users\<user_name>\MTA"

6. Ensure that Docker is running Windows containers and that the OS/Arch is set to windows/amd64:

   PS C:\Users\<user_name>> docker version

   Client:
    Version:           27.0.3
    API version:       1.46
    Go version:        go1.21.11
    Git commit:        7d4bcd8
    Built:             Sat Jun 29 00:03:32 2024
    OS/Arch:           windows/amd64
    Context:           desktop-windows
   Server: Docker Desktop 4.32.0 (157355)
    Engine:
     Version:          27.0.3
     API version:      1.46 (minimum version 1.24)
     Go version:       go1.21.11
     Git commit:       662f78c
     Built:            Sat Jun 29 00:02:13 2024
     OS/Arch:          windows/amd64
     Experimental:     false

7. Set the CONTAINER_TOOL environment variable to use Docker:

   PS C:\Users\<user_name>> $env:CONTAINER_TOOL="C:\Windows\system32\docker.exe"

8. Set the DOTNET_PROVIDER_IMG environment variable to use the upstream dotnet-external-provider:

   PS C:\Users\<user_name>> $env:DOTNET_PROVIDER_IMG="quay.io/konveyor/dotnet-external-provider:v0.5.0"

9. Set the RUNNER_IMG environment variable to use the upstream image:

   PS C:\Users\<user_name>> $env:RUNNER_IMG="quay.io/konveyor/kantra:v0.5.0"

Procedure

1. Edit the tackle CR:

   $ oc edit tackle

2. Switch to the edit mode in the terminal text editor:

   i

3. Optionally, configure the authentication fields:

   spec:
     feature_auth_required:true
     idp_primary:true
     hub_oidc_token_lifespan:300
     hub_oidc_refresh_token_lifespan:172800
     hub_apikey_lifespan:87600
     hub_auth_cache_lifespan:5
     hub_ldap_auth_lifespan:5
     hub_oidc_key_rotation:90

   • feature_auth_required:: Enforces authentication to the Hub API and the web console. By default, the value is true.
   • idp_primary:: If you set this field true, MTA Hub automatically redirects authentication to the auto-discovered Keycloak Identity Provider in upgraded deployments where users authenticated using Keycloak. If the field value is false, users can authenticate on the MTA login page. If you configured an identity provider (IdP), then users can authenticate by using the IdP button on the login page.
   • hub_oidc_token_lifespan:: By default, the OAuth access token lifespan is 300 seconds.
   • hub_oidc_refresh_token_lifespan:: By default, the OAuth refresh token lifespan is 172800 seconds or 2 days.
   • hub_apikey_lifespan:: By default, the OAuth API key lifespan is 87600 hours.
   • hub_auth_cache_lifespan:: By default, the OAuth authentication cache lifespan is 5 minutes.
   • hub_ldap_auth_lifespan:: By default, the LDAP authentication lifespan is 5 minutes.
   • hub_oidc_key_rotation:: By default, the OIDC key rotation interval is 90 days.

4. Save the changes and exit the text editor to apply the changes:

   :wq!

Procedure

1. Log in to the MTA web console.
2. In the Administration mode, go to User Management.
3. Click Users.

4. Enter the following on the Create user page:

   • Username in the Login field.
   • Name of the user.
   • Email address of the user.
   • A new password in the Password field.
   • The same password in the Confirm Password field.
   • Select one or more roles from the Roles list.
5. Click Create.

Procedure

1. Log in to the MTA application with admin as your password.
2. Click your role dropdown at the top right corner.
3. Select User account.

4. Enter the following on the Edit user page:

   • Name
   • Email address
   • A new password in the Password field.
   • The same password in the Confirm Password field.
5. Click Save.

Procedure

1. Log in to the MTA web console.
2. In the Administration mode, go to User Management.
3. Click Roles.
4. Click the number of permissions scoped to the admin role to explore the resources and scoped permissions.
5. On the Roles page, click Create.
6. Enter a unique name for the new role in the Name field.
7. Type the name of a resource to see the list of permissions.

8. Add one or more permissions:

   • Select a permission from the Permissions list and click the Add selected icon.
   • Click the Add all icon to select all the permissions for that resource.
9. Click Create.

Procedure

1. Create an ldap-secret.yaml file:

   apiVersion: v1
   kind: Secret
   metadata:
     name: ldap-service-account
     namespace: openshift-mta
   type: Opaque
   stringData:
     password: "<service-account-password>"

2. Apply the ldap-secret file in the cluster:

   $ oc apply -f ldap-secret.yaml

3. Create an ldap.yaml file for the custom resource (CR):

   apiVersion: tackle.konveyor.io/v1alpha1
   kind: LdapProvider
   metadata:
     name: corporate-ldap
     namespace: openshift-mta
   spec:
     name: "Corporate LDAP"
     kind: "ActiveDirectory"
     url: "ldaps://ldap.example.com:636"
     baseDN: "dc=example,dc=com"
     bindDN: "cn=service,dc=example,dc=com"
     password:
       name: ldap-service-account
       namespace: openshift-mta
     userFilter: "(sAMAccountName=${login})"
     groupFilter: "(&(objectClass=group)(member=${dn}))"
     hasMemberOf: true
     roleMappings:
       - and:
           - Developers
         roles:
           - architect
       - any:
           - "**Administrator**"
         roles:
           - admin

   • kind:: Server type is "ACTIVEDIRECTORY", "AD", or blank for other LDAP implementations such as OpenLDAP.
   • url:: LDAP server URL
   • baseDN:: Base Distinguished Name to narrow the scope for LDAP searches
   • bindDN:: unique identifier of the service account used to authenticate against the LDAP directory
   • password:: Reference to Secret containing service account password

   • userFilter:: User search filter. The default value for the user filter in AD is (sAMAccountName=%s) and (uid=%s) for other LDAP implementations when you do not configure a value in the CR.

     To override the default, configure userFilter: "(sAMAccountName=${login})" for AD or userFilter: "(uid=${uid})" for other LDAP implementations.

   • groupFilter:: Group search filter. The default value for the group filter in AD is groupFilter: "(&(objectClass=group)(member=%s))" and (&(objectClass=*)(member=%s)) for other LDAP implementations when you do not configure a group in the CR.

     To override the default, configure groupFilter: "(&(objectClass=group)(member=${dn}))" for distinguished name. You can replace {dn} with {uid} for a unique identifier or {cn} for a common name.

   • hasMemberOf:: Use memberOf attribute for group membership in AD.
   • roleMappings:: Map LDAP groups to Hub roles. The MTA roles can be a list of default or custom roles. When you use global patterns to match the LDAP roles, you must use the DoubleStar pattern or double asterisk to match the complete role name.

4. Apply the LDAP CR in the cluster:

   $ oc apply -f ldap.yaml

5. Restart the Hub to load the new client and the secret:

   $ oc rollout restart deployment/tackle-hub -n openshift-mta

Procedure

1. Retrieve your admin credentials:

   $ oc get secret mta-keycloak-rhbk -n openshift-mta -o json| jq -r '.data.password | @base64d'

   The admin credentials for RHBK are stored in the mta-keycloak-rhbk secret file in the namespace where you installed MTA.

2. Enter the following URL in your browser:

   https://<web_console_address>/auth/admin

3. Access the RHBK Admin Console by entering your credentials.

Procedure

1. Create a secret such as <idp-client-secret>.yaml:

   apiVersion: v1
   kind: Secret
   metadata:
     name: idp-client-secret
     namespace: <mta-namespace>
   type: Opaque
   stringData:
     clientSecret: "<secret>"

   • <mta-namespace>:: The namespace where you deployed MTA.
   • <secret>:: The secret that you configured in the identity provider configuration.

2. Apply the <idp-client-secret>.yaml file in the cluster:

   $ oc apply -f <idp-client-secret>.yaml

3. Restart the Hub to load the secret:

   $ oc rollout restart deployment/tackle-hub -n openshift-mta

Procedure

1. Create an <my-idp>.yaml custom resource:

   apiVersion: tackle.konveyor.io/v1alpha1
   kind: IdentityProvider
   metadata:
     name: corporate-sso
     namespace: openshift-mta
   spec:
     name: "Corporate SSO"
     issuer: "https://idp.example.com/realms/tackle"
     clientId: "tackle-hub"
     clientSecret:
       name: idp-client-secret
       namespace: openshift-mta
     redirectURI: "https://hub.example.com/oidc/idp/callback"
     primary:
       description: IdP is the primary authentication method. When true, users are automatically redirected to this IdP for authentication.
       type: true
     scopes:
       - openid
       - profile
       - email

   • name:: A display name for the IdP button in the UI.
   • issuer:: IdP issuer URL for OIDC discovery. You can use template variables in the issuer field. For example, "${issuer.proto}://${issuer.host}/auth/realms/tackle".
   • clientId:: OAuth client ID registered with the IdP.
   • clientSecret:: Optional Kubernetes secret for the MTA Hub to securely connect to the IdP. Omit this configuration if you did not create a secret for the IdP.
   • redirectURI:: Callback URI to the MTA Hub after the IdP authentication completes. You must add the /oidc/idp/callback path to the Hub URI. You can use template variables in the redirect URI field. For example, "${issuer.proto}://${issuer.host}/oidc/idp/callback".
   • primary:: IdP is the primary authentication method. When true, the Hub redirects users automatically to this IdP for authentication. If you configured the field in the Tackle CR, the MTA Hub resolves the configuration for this field from the Tackle CR value.
   • scopes:: OAuth scopes used by an OpenID Connect client to request the access privileges for the access token.

2. Apply the `<my-idp>.yaml file in the cluster:

   $ oc apply -f <my-idp>.yaml

3. Restart the Hub to load the configuration:

   $ oc rollout restart deployment/tackle-hub -n openshift-mta

Procedure

1. Log in to the MTA application.
2. In the Administration mode, go to User Management.
3. Select Tokens.
4. Click Create API Key.
5. Optionally enter the lifespan of the token.
6. Click Create.

7. Copy the displayed token.

   You can use the API key for the Red Hat Developer Lightspeed for migration toolkit for applications agent.

Procedure

1. Log in to the MTA web console.
2. In the Administration mode, go to User Management.
3. Select Tokens.
4. On the Tokens page, click the options icon.
5. Click Revoke.

Procedure

1. Log in to the MTA web console.
2. In the Migration mode, click your username at the top right corner.
3. Select Tokens.
4. On the Tokens page, click the options icon.
5. Click Revoke.