Register and View Edge Runtime Information

Why to register Edge Runtimes?

You are required to register your edge runtime with your tenant first in order for it to be able to connect with IBM webMethods Integration and make use of remote monitoring, control, and syncing capabilities.

However, if you do not want to register an edge runtime, you can use the default cloud runtime that is provided in your cloud tenant.

Register Edge Runtimes

The basic flow of edge runtime registration is as follows:

Before you Begin

• Ensure that your IBM webMethods Integration tenant has the Develop anywhere, Deploy anywhere capability enabled. The Integration Runtimes tab appears if the capability is enabled.

• Ensure that you have installed a container runtime such as Docker or Rancher on your machine.
  
  For local development, it is recommended that you use Docker instead of a container, to ensure compatibility with any docker commands provided here. However, for production-based deployment, any Open Container Initiative (OCI) compliant container engine is supported and there are no restrictions on which one you use.

Basic Flow

1. Click Integration Runtimes on the IBM webMethods Integration title bar.

   

2. Click the (Plus) icon. The Register Edge Runtime wizard appears.

3. Click Create new Edge Runtime.
   

   

   You are redirected to the Get Edge Runtime Image page. The page contains a Docker command that retrieves the edge runtime image from the container registry.

   Note

   • If you have already downloaded the image to your local system, you can:
     • Skip steps 4 and 5 and proceed directly to step 6 for pulling the latest image. Or,
     • Skip steps 4, 5, and 6 and proceed directly to step 7.
       However, it is recommended to follow step 6 to guarantee that you have the most up-to-date image version, complete with the latest features and fixes.
   • If you are registering for the first time, follow all steps. This is required as you need to log in to the webMethods package registry to retrieve the runtime image. Follow the instructions in:
     • Step 4 to retrieve the username and token details.
     • Step 5 for logging into the package registry using the retrieved credentials.
     • Step 6 for retrieving the most up-to-date image version.
     Steps 4 and 5 are a one-time activity that must be done when you are registering an edge runtime for the first time.

4. To obtain the user name and token details:

   a. Click the Container Registry link available under the Sign in to Container Registry section.

   

   You are directed to the login page.

   b. Enter your credentials.

   c. Click Next. After successful login, the container registry home page appears.

   d. Click User Profile > Settings.

   

   The User Profile page appears.

   

   e. Click Generate Password. The Container registry credentials confirmation message appears.

   

   f. Select the I agree to the IBM’s Terms and Conditions checkbox after going through the terms and conditions. The token name and password are generated.

   

   These details are required for logging into the container registry. You can copy the command listed under Docker login and save it for later reference.

   g. Close the Container registry credentials dialog box and go to the Register Edge Runtime wizard.

5. To login to the container registry:

   Tip

   You can paste the command copied in Step 4-f on the container terminal page and proceed to Step 5-c. Otherwise, follow Steps 5-a and 5-b.

   a. Copy the command from the first text box in the Sign in to Container Registry section using the (copy) icon and paste it on your terminal window or command prompt.

   

   b. Replace user name and user token with the values generated in the previous step.

   c. Press Enter to run the command. After successful validation, the Login Succeeded message appears.

   

   d. Go to the Register Edge Runtime wizard.

6. To pull the edge runtime image:

   a. Copy the command from the last text box in the Get Edge Runtime Image section using the (copy) icon and paste it on your terminal where you want to run the container.

   

   b. Press Enter to run the command. The latest edge runtime is downloaded.

   

   c. Go to the Register Edge Runtime wizard.

7. Click Next. The Configure page appears.

8. Enter a name and description for the new edge runtime, so that you can easily identify it later.

   

9. Set the button under Access with one of the following values:

   • Public: Select this option to make the Integration Runtime public so that all users can access the runtime irrespective of their access privileges.

   • Private: Select this option to make the Integration Runtime private. The user registering the runtime will become the owner of this runtime.

   Note

   The Access option is displayed for administrators only. By default, any runtime that is registered by a non-administrator user is marked as private. Once a runtime is made as private or public, administrators cannot modify it. For more information about access privileges related to public and private runtimes, see Integration Runtimes Access Privileges.

10. Click Next. The Connect page appears.

    

11. Click Start Pairing. A pairing code including the cloud URL, and a registration token is generated.

    

    Note

    If you click the Previous button after clicking the Start Pairing button, and then again click Start Pairing, the edge runtime registration does not happen. This is because the edge runtime is already created. You must register with a new edge runtime name or delete the existing client registration details from the OAuth 2.0 page and reuse the name to register the edge runtime.

12. Copy the pairing code using the (copy) icon and paste it on your terminal where you want to run the container.

    

    Note

    • The Docker command uses a temporary pairing code to connect the runtime to your IBM webMethods Integration tenant securely without exposing your credentials.
    • Ensure that the port number on which the edge runtime communicates is unique.
      
    • It is recommended to verify the platform architecture of your system and the platform architecture of the container image before running the command. If the architecture does not match, you must set the –platform flag to specify the platform architecture. For example,
      
      

13. Press Enter to run the command. Upon successful pairing, the edge runtime is registered, and the success message appears.

    

    Note

    If the pairing process is not completed within the designated time, the following error message appears:

14. Click Done and try to register again.

    The newly registered edge runtime is displayed on the Integration Runtimes page. The runtimes you have registered or have access to appears in the Integration Runtimes page. Only administrators can see all runtimes. For more information about access privileges, see Integration Runtimes Access Privileges.

    

    Once the edge runtime transitions into the Running state, you can use the newly registered edge runtime to deploy and run services from your tenant. The runtime card displays the following details:

    

    If the runtime is private, then the icon appears on the runtime card instead of the icon.

Edge Runtime Multiple Instances

You can create multiple instances for an edge runtime.

An instance is a runtime engine that is associated with the logical runtime that you have registered with the control plane. It allows you to spin up more than one runtime instance with the same logical identity. This means that any invocations from your IBM webMethods Integration tenant will be distributed across these instances, giving you both high availability and the ability to scale as throughput requires. If an instance crashes or is shutdown, then another instance can take over the workload. It is important to remember that starting or stopping instances is controlled by you and not by the control plane and that you must use a long-term pairing token in the runtime startup command. The runtimes must be identically setup and the best way to do that is create a prebuilt image for the runtime.

Having instances provide several benefits, including:

• Scalability: You can easily create, clone, or terminate instances to scale your infrastructure up or down based on demand.

• High availability: You can ensure the reliable operation of your applications on server instances because of capabilities such as load balancing, auto-scaling, and fault tolerance to guarantee the high availability of your applications hosted.

By leveraging instances, you can rapidly deploy and scale your applications, avoid upfront infrastructure costs, and focus on your core business objectives.

Each instance is a separate runtime that could be running in different data centers or private clouds. However, they represent the same logical runtime and you cannot reference an instance individually, all invocations are distributed across the available instances.

An edge runtime having one or more instances is displayed as a stack of cards on the Integration Runtimes home page.

You can add instances to an edge runtime in one of the following methods:

• Manual: In this method, you can add a single instance by either using the Start command or Add Instance option in the Instance Listing page. Upon the instance’s creation, you can subsequently add another instance. However, you need to wait until the instance is created and displayed in the Instance Listing page.

• Auomatic: In this method, you can add one or more instances programmatically by running the Docker command from your container terminal. You need not wait until the instance is created. For this method, you must have a valid long-term access token.

Manual Runtime Instance Startup

Starting instances manually from the control plane is not recommended. Instead, you must leverage the auto-creation of instances through a container management system such as Kubernetes, where you configure a deployment set that allows you to programmatically define the number of instances and even implement auto-scaling. In which case, the number of instances are entirely automated based on load. Refer to the section on automating runtime startup.

1. Click the vertical ellipsis icon on the edge runtime card for which you want to add instances on the Integration Runtimes page. A menu appears.

2. Click Add Instance from the displayed menu.

   Note

   For an edge runtime that has more than one instance, another way of creating an instance is by clicking the Add Instance button in the Instance Listing page.

   The Add Instance dialog appears.

   

3. Copy the pairing code using the (copy) icon and paste the command in a text editor.

4. Update the port number on which the instance must communicate. The port number must be unique.

   

5. Copy the updated command and paste it on the terminal where you want to run the container.

6. Press Enter to run the command. Upon successful pairing, the edge runtime is registered, and the success message appears.

7. Click Done. A new instance is created, and the edge runtime card appears as a stack of cards. You can click the edge runtime card to view the details of an instance. For more information about instance details, see View Edge Runtime Information.

Automate Runtime Instance Startup

The Manual Runtime Instance Startup section demonstrated how to use a generated Docker command to initiate multiple instances of the same runtime. While this approach involves manual steps and is not practical for production environments, you can instead use a script or Kubernetes auto-scaling (DeploymentSet) to dynamically manage instances or pods as needed. However, note that the pairing token generated by the register and start commands is valid for one-time use only and is time-limited, making it unsuitable for this purpose. You need to generate a long-term pairing token for this purpose.

Before you Begin

You need the following details:

• Long-term access token. For more information about long term access tokens, see Generating Pairing Tokens.

• Edge runtime pairing command. The command is available on the Add Instance dialog box. For more information about getting the pairing command, see Manual Runtime Instance Startup.

Basic Flow

1. Open a text editor and paste the Docker command that you copied from the Add Instance dialog box.

2. Update the following values:

   • p: Port number on which the runtime instance must communicate. Ensure that each instance port number is unique on the system you are running. Otherwise, docker command fails with port conflict errors.

   • SAG_IS_CLOUD_REGISTER_TOKEN: Replace with a valid long-term access token.

   • name: Name of the runtime instance. Ensure that each runtime instance name is unique.

   For example, the following sample image contains four commands to create four new instances.

   

3. Open a container runtime such as Docker or Rancher on your machine.

4. Copy an instance command from the text editor and paste the command on the container terminal.

5. Press Enter to run the command. After the command runs successfully, an ID appears.

   

6. Repeat steps 4 and 5 to create other instances.

7. Close the container terminal and go to Integration Runtimes page. The new instances are created, and the edge runtime card appears as a stack of cards.

   

   You can click the edge runtime card to view the details of an instance. For more information about instance details, see View Edge Runtime Information.

   

Generating Pairing Tokens

The pairing tokens are used during edge registration, especially when you want to register multiple instances for an edge runtime using the automatic approach. For more information about automatic approach, see Automate Runtime Instance Startup.

You can generate pairing tokens using the Add New Token option in OAuth 2.0. The Add New Token option is visible in tenants with Develop Anywhere, Deploy Anywhere enabled. You cannot use the Add New Token option for generating tokens for other clients communicating with IBM webMethods Integration, for that, see Generating Tokens.

1. Go to User Profile > Settings > OAuth 2.0 > Token Management. All available tokens are listed.

2. Click Add New Token. The Add New Token dialog box appears.

3. Select the client for which the token must be generated from the Client drop-down list.

4. Specify the number of days for which the token is valid from the Expiry Time drop-down list. The default value is 30 days.

5. Click Generate Token. The token is generated and listed.

   

6. Copy the access token and save it in your local system for future reference.

7. Click Close to exit the Add New Token dialog box. The Token Management page appears and the newly added access token is listed in the Tokens table.

   

Edge Runtime Lifecycle States

An edge runtime and its instances transition through different states from the moment you launch it until they are terminated. The various transition states of an edge runtime instance are as follows:

View Edge Runtime Information

You can view the details of an edge runtime instance by clicking the corresponding edge runtime card in the Integration Runtimes page. The runtimes are displayed based on your access privileges. For more information about access privileges, see Integration Runtimes Access Privileges.

Single Instance Edge Runtime

You can view the details of an edge runtime having a single instance in the Dashboard. For more information about runtime details, see Dashboard.

Multiple Instances Edge Runtime

You can view the details of an edge runtime having multiple instances in the Instance Listing page.

1. Click an edge runtime card that has more than one instance on the Integration Runtimes page. The Instance Listing page appears listing all instances created for that edge runtime.

   

The following details are listed for each instance:

• Container ID: Unique identification number of the Docker container created during an edge runtime registration. Use this ID to identify an edge runtime instance from the running Docker containers on your local system.

• Status: Status of an edge runtime instance. For more information about the complete list of edge runtime instance statuses, see Edge Runtime Lifecycle States.

• Actions: Lists the various tasks you can perform on an edge runtime instance. You can either stop or restart a specific instance using the options in the Actions column.

Key Points to Consider for Integration Runtimes

• The Ellipsis icon on the edge runtime card is visible to all and the actions listed in the ellipsis menu can be performed by all.

• Edge runtime exclusively functions in a stateless manner without local data persistence. Furthermore, it does not support features reliant on an internal database, including cross-referencing, service auditing, business processing management, document history, central user management, and guaranteed inbound adapter notifications.