App Connect

App Connect

Join this online user group to communicate across IBM product users and experts by sharing advice and best practices with peers and staying up to date regarding product enhancements.

 View Only

Creating ingress resources for your App Connect Designer Authoring and switch servers out of the box on IBM Cloud Kubernetes Service

By Shanna Xu posted Mon May 12, 2025 05:41 AM

  

Introduction

App Connect Designer Authoring and switch server resources now support ingress out of the box on IBM Cloud Kubernetes Service (IKS), with the releases of IBM® App Connect Operator 12.9.0 and 12.11.0, respectively.

Whilst you can continue to manually create, and subsequently manage the life cycle of ingress, this new feature allows the App Connect Designer Authoring and switch servers to manage the life cycle of their required ingress resources. It is worth noting that this new feature is available only with App Connect licenses.

This article contains a tutorial on how to enable your App Connect Designer Authoring and switch servers to manage ingress on IKS. Follow the related tutorial on App Connect Dashboard and integration runtimes to learn how to enable ingress for those resources on IKS.

Prerequisites

  • Install App Connect Operator 12.11.0 or later
  • Install App Connect Designer Authoring and switch server versions 13.0.3.0-r1 or later
  • Use App Connect licenses only (such as AppConnectEnterpriseProduction)
  • Use Kubernetes version 1.27, 1.28, or 1.29, 1.30 or 1.31
  • Configure a test cluster on IKS, either Classic or VPC

Article index

Note: In this article, resource names are highlighted in dark red.  Keywords that are displayed on a UI are highlighted in bold.

Overview

In the following, we describe two relevant scenarios: first we demonstrate how to create a switch server resource with ingress out of the box; second we show the equivalent with Designer Authoring.  Finally, we describe how to test the created resources. 

Scenario 1: Create a switch server resource with ingress enabled on IKS

  1. On the test cluster, create a namespace called ace-ingress with the following command:
    kubectl create namespace ace-ingress
  2. Set ace-ingress as your current namespace, so that the subsequent commands target it.
    kubectl config set-context --current --namespace ace-ingress
  3. To define the custom resource (CR) for a switch server instance, copy the following YAML template into a file, and save it as example-switch.yaml.
    apiVersion: appconnect.ibm.com/v1beta1
    kind: SwitchServer
    metadata:
      name: default
      labels:
        backup.appconnect.ibm.com/component: switchserver
      namespace: ace-ingress
    spec:
      ingress:
        enabled: true
      license:
        accept: true
        license: L-KPRV-AUG9NC
        use: AppConnectEnterpriseProduction
      version: '13.0.3.0-r1'
    1. Notice that metadata.name is set to default. As a result, the Designer Authoring instance, which you will create in scenario 2, is automatically configured to use this switch server instance. If you modified this value, you must set it as the value of spec.switchServer.name in the Designer Authoring CR.
    2. Ensure that spec.ingress.enabled is set to true. This setting enables the switch server resource to automatically manage the life cycle of its ingress resource. By default, this value is set to false, which requires you to manually set up ingress for the switch server resource.
    3. Notice that spec.license.use is set to AppConnectEnterpriseProduction because this new feature is available only with App Connect licenses.
    4. Notice that spec.version is set to 13.0.3.0-r1, which reconciles the switch server instance to the latest operand version for App Connect Operator 12.11.0.
  4. Now, create a switch server with the following command:
    kubectl apply -f example-switch.yaml
  5. Wait for the switch server to become ready, and then verify that the required ingress resource is created. You can carry out the following actions:
    1. Check the status of the switch server with the following command:
      kubectl get switchserver default
      The output provides details about the current status of the switch server. When the instance is ready, you can see that STATUS is set to Ready.
      Here is an example output:
      NAME      RESOLVEDVERSION   CUSTOMIMAGES   STATUS   AGENTCONFIGURATIONNAME   AGE
      default   13.0.3.0-r1       false          Ready    default-agentx           1m
    2. Verify that the required ingress resource is created with the following command:
      kubectl get ingress
      The switch server created an ingress resource as shown in the following example:
      NAME                  CLASS                  HOSTS                                                     ADDRESS         PORTS     AGE
      default-switch        public-iks-k8s-nginx   default-switch-ace-ingress.testcluster.cloud              x.x.x.x         80        1m
      Additional information:
      • The ingress name is in the format [switch_server_name]-switch.
      • The value of HOSTS is in the format [ingress_name]-[switch-server-namespace].[cluster_subdomain]
        • The value of cluster_subdomain is the default subdomain of your cluster. In your IKS cluster, this subdomain is exposed by the k8s-alb-health ingress in the kube-system namespace.
        • Instead of using the default cluster subdomain to construct the ingress host for your switch server, you can provide a customised subdomain by specifying a value for spec.ingress.domain.
          For example, with spec.ingress.domain set to mytest.domain, the ingress host of your switch server in this case becomes default-switch-ace-ingress.mytest.domain.
          You can provide the customised subdomain when you create the switch server, or you can modify an existing CR to automatically update the ingress host.
      • The ingress resource is created and owned by the switch server instance. As a result, when you delete the instance, the ingress resource is also deleted.

Congratulations! You have created a switch server instance with ingress enabled.  When you are ready, navigate to scenario 2to create a Designer Authoring resource with ingress enabled.

Scenario 2: Create and access the App Connect Designer Authoring with ingress enabled on IKS

  1. Follow the documentation on entitlement key to create a secret resource named ibm-entitlement-key. This key enables you to download the required images for the Designer Authoring resource.
  2. To define the CR for a Designer Authoring instance, copy the following YAML template into a file, and save it as example-designerauthoring.yaml:
    apiVersion: appconnect.ibm.com/v1beta1
    kind: Designer
    metadata:
      name: example-des
      labels:
        backup.appconnect.ibm.com/component: designerauthoring
      namespace: ace-ingress
    spec:
      ingress:
        enabled: true
      license:
        accept: true
        license: L-KPRV-AUG9NC
        use: AppConnectEnterpriseProduction
      couchdb:
        replicas: 1
        storage:
          class: ibmc-block-retain-gold
          size: 20Gi
          type: persistent-claim
      designerMappingAssist:
        enabled: false
      designerFlowsOperationMode: local
      replicas: 1
      version: '13.0.3.0-r1'
      authorization:
        integrationKeycloak:
          enabled: false
      authentication:
        integrationKeycloak:
          enabled: false
    1. Ensure that spec.ingress.enabled is set to true. This setting enables the Designer Authoring instance to automatically manage the life cycle of its required ingress resources. By default, this value is set to false, which requires you to manually set up ingress for the Designer Authoring resource.
    2. Notice that spec.license.use is set to AppConnectEnterpriseProduction because this new feature is available only with App Connect licenses.
    3. Notice that spec.version is set to 13.0.3.0-r1, which reconciles the Designer Authoring instance to the latest operand version for App Connect Operator 12.11.0.
    4. Follow the storage instructions for the App Connect Designer Authoring to set spec.couchdb.storage.
  3. Now, create a Designer Authoring instance with the following command:
    kubectl apply -f example-designerauthoring.yaml
  4. Wait for the Designer Authoring instance to become ready, and then verify that the required ingress resources are created. You can carry out the following actions:
    1. Check the status of the Designer Authoring instance with the following command:
      kubectl get designerauthoring example-des
      The output provides details on the current status of the Designer Authoring instance. When the instance is ready, you can see that STATUS is set to Ready, and URL is set to the Designer Authoring UI.
      Here is an example output:
      NAME          RESOLVEDVERSION   URL                                                    KEYCLOAKURL   CUSTOMIMAGES   STATUS   AGE
      example-des   13.0.3.0-r1       https://example-des-ui-ace-ingress.testcluster.cloud                 false          Ready    1m
      Additional information:
      • The Designer Authoring UI URL is in the format https://[host_prefix].[cluster_subdomain]
        • The value of host_prefix is immutable, and in the format [designerauthoring_name]-ui-[designerauthoring_namespace]
        • The value of cluster_subdomain is the default subdomain of your cluster. In your IKS cluster, it is exposed by the k8s-alb-health ingress in the kube-system namespace.
        • Instead of using the default cluster subdomain to construct your Designer Authoring UI URLs, you can provide a customised subdomain by providing a value for spec.ingress.domain.
          For example, with spec.ingress.domain set to mytest.domain, the Designer Authoring UI URL in this case becomes https://example-des-ui-ace-ingress.mytest.domain.
          You can provide the customised subdomain when you create the Designer Authoring resource, or you can modify an existing CR to automatically update the URL.

      • In this example, the KEYCLOAKURL is not set, because we disabled self-managed Keycloak by setting both spec.authentication.integrationKeycloak.enabled and spec.authorization.integrationKeycloak.enabled to false. To understand how to enable the Designer Authoring resource to manage ingress when a self-managed Keycloak is configured, see Introducing Self-Managed Keycloak for App Connect Dashboard and Designer Authoring.
    2. [Optional] Alternatively, locate the Designer Authoring UI URL in the YAML output of the Designer Authoring instance. The URL is shown in spec.status.endpoints.
      Run the following command:
      kubectl get designerauthoring example-des -o yaml 
      Here is an example output:
      status:
        endpoints:
        - name: ui
          type: UI 
          uri: https://example-des-ui-ace-ingress.testcluster.cloud
    3. Verify the required ingress resources are created with the following command:
      kubectl get ingress
      The Designer Authoring instance created four ingress resources as shown in the following example:
      NAME                           CLASS                  HOSTS                                                        ADDRESS   PORTS     AGE
      example-des-designer-http      public-iks-k8s-nginx   example-des-designer-http-ace-ingress.testcluster.cloud      x.x.x.x   80        1m
      example-des-designer-https     public-iks-k8s-nginx   example-des-designer-https-ace-ingress.testcluster.cloud     x.x.x.x   80, 443   1m
      example-des-designer-webhook   public-iks-k8s-nginx   example-des-designer-webhook-ace-ingress.testcluster.cloud   x.x.x.x   80        1m
      example-des-ui                 public-iks-k8s-nginx   example-des-ui-ace-ingress.testcluster.cloud                 x.x.x.x   80        1m
      Additional information:
      • The UI ingress name is in the format [designerauthoring_name]-ui. In this example, example-des-ui in the NAME column is the ingress for the UI of the Designer Authoring instance.
      • The other ingress names are in the format [designerauthoring_name]-designer-[ingress-type].
      • These ingress resources are created and owned by the Designer Authoring instance. As a result, when you delete the Designer Authoring instance, these ingress resources are also deleted.
  5. After the App Connect Designer Authoring deployment is ready, use the Designer Authoring URL to access the Designer Authoring UI.  Here is an example of the Designer Authoring UI:
  6. From the navigation pane in the Designer Authoring UI, click Connect, and then click Private networks.
  7. Notice a private network connection is available for this Designer Authoring instance, which is called Private network agent for default. This is the switch server instance that you created in scenario 1
Congratulations! You have created a Designer Authoring instance with ingress enabled. When you are ready, navigate to the next sectionto use this instance to test your switch server.

Testing your creations

This section tests the Designer Authoring and switch server resources that you created in the previous scenarios. As a result, you gain a deeper understanding of how these resources can be configured and utilised.
There are four parts in this section. In part 1, you create an API flow from the Designer Authoring UI. With the use of your switch server, this flow will establish a HTTP connection to your computer on port 1234. In order to establish the connection, you follow part 2 to set up and start a secure agent on your computer. In addition, you use part 3 to create and start a HTTP server on port 1234 to receive HTTP requests. Finally, you can test the API flow from the Designer Authoring UI in part 4.


Part 1: Use the Designer Authoring UI to create an API flow

  1. Use the Designer Authoring URL (see scenario 2 step 4) to access the Designer Authoring UI. From the Designer Authoring UI, click Create flows for an API to create an API flow.
  2. From the top pane, rename the flow as testSwitchServer, and then specify the model name as invokeLocalApp.  Finally, click Create model to create a model for the API flow.
  3. Add a property named responseMsg, and then click Operations to add an operation for the API flow.
  4. Click Select an operation to add, and then select Create invokeLocalApp.
  5. Click Implement flow to implement the API flow.
  6. Note that the Response node has an error, because the responseMsg property requires a value. 
  7. Click the Response node to provide set a value, such as Hello!. When the flow is successfully invoked, this is be the response message that it issues.
  8. Click the blue circle between the Request and Response nodes to add an HTTP node to the flow. We will use the HTTP node to establish a connection to your computer. From the search pane under Applications & APIs, type http to locate the HTTP node, and then click Invoke method to configure it.
  9. Click Connect to create an account for the HTTP node.
  10. Click Maximize panel to show all configurable properties.
  11. Click to edit the Private network connection (optional) property, and set it to Private network agent for default.  This uses your switch server to establish the HTTP connection.
  12. Edit the Override the HTTP endpoint host name and port of the URL used in the flow (optional) property, and set it to http://localhost:1234. Finally, click Connect.
  13. Edit the property called HTTP method, and set it to GET. Edit the property called URL (fully qualified), and set it to http://localhost:1234. Finally, click Done to create the flow.
  14.  Click Start API to start the flow.
  15. The flow should be in the Running status.
Congratulations! You have created an API flow that will use the switch server resource to establish an HTTP connection to a local application. When you are ready, navigate to part 2 to start a secure agent locally.


Part 2: Start a secure agent locally

  1. From the navigation pane in the Designer Authoring UI, click Connect, and then click Private networks.
  2. Click the options menu (⋮) for the Private network agent for defaults connection, and then click View setup instructions. This shows a set of instructions on how to configure a secure agent on your local computer.
    1. Expand 1. Download the secure agent, and then select an operating system under Select your operating system. This should be the operation system of your local computer. Finally, click Download the secure agent.
    2. Click Accept to download the agent.
    3. Expand 2. Download the secure agent configuration, and then click Download the configuration to download a configuration file for a switch client.
    4. From your local computer, carry out the following actions to start a secure agent:
      1. Copy both downloaded files into a folder named switchServer as shown in the following example:
      2. In a terminal, inside the switchServer folder, extract the secure agent file with the following command (substitute secureagent-x.tgz with your file name):
        tar xvf secureagent-x.tgz
      3. Inside the switchServer folder, create a new folder named config with the following command:
        mkdir config
      4. Move the switchclient.json file to the config folder with the following command:
        mv switchclient.json config/
      5. The switchServer folder now contains files as shown in the following example:
      6. Open the switchclient.json file, and then set the value of endpoints.hostname to localhost. Finally, set the value of endpoints.port to 1234. Here is an example edited file:
        Additional information:
        • Notice that the JSON file contains a switch object (from line 21 in the example file), which contains information on the switch server instance that you created in scenario 1.
            • The value of switch.url is the host of your switch server ingress.
            • The value of switch.certs is the certificates of your cluster, where the Designer Authoring and switch server instances are created.
      7. Start the secure agent with the following command:
        ./secureagent -c config/switchclient.json -l . -d
        Additional information:
        • The command is also provided in 4. Start the secure agent in the Designer Authoring UI (see step 2i).
        • If you are on MacOS, you might see a "secureagent" Not Opened error as a result of running the command. To remove the error, you need to assign permission to run the application in the Privacy & Security section of your System settings.
        • When you start the agent for the first time, type yes to accept license.
        • Once the agent has started, inspect the log messages to ensure the internal agents are connected successfully to the switch server resource. Here is an example output:
          [INFO] SysLogger AgentP - startInner - BIP6469 - AgentP successfully connected to switch(es)
          [INFO] SysLogger AgentX - startInner - BIP6450 - AgentX successfully connected to switch(es)
          [INFO] SysLogger AgentA - startInner - BIP6485 - AgentA successfully connected to switch(es)
Congratulations! You have started a secure agent locally. When you are ready, navigate to part 3 to start an HTTP server locally.


Part 3: Start an HTTP server locally

The final component of your test setup is an HTTP server, which should run on your computer and listens on port 1234 to accept incoming HTTP requests. Such server can be established in many ways. Follow this tutorial to create a server written in the Go programming language.

  1. Copy the following Go template into a file, and save it as exampleApp.go
    package main
    
    import (
    	"log"
    	"net/http"
    )
    
    func main() {
    	helloHandler := func(w http.ResponseWriter, req *http.Request) {
    		log.Print("Hello world!")
    	}
    
    	http.HandleFunc("/", helloHandler)
    	log.Fatal(http.ListenAndServe(":1234", nil))
    }
  2. In a new terminal, start the HTTP server with the following command:
    go run sampleApp.go
Congratulations! You have started an HTTP server locally, listening on port 1234. When you are ready, navigate to part 4 to test the API flow.


Part 4: Test the API flow from the Designer Authoring UI

  1. From the Designer Authoring UI, click the testSwitchServer tile.
  2. Click Test to invoke the flow.
  3. From the side pane, click POST/invokeLocalApp, and then click Try it.
  4. Click Generate to create test data for the request body, and then click Send to invoke the flow.
  5. You should receive a response code of 201, indicating a success. The response body should contain "responseMsg": "Hello!".
  6. From your local computer, inspect the terminal that hosts the HTTP server. You should see a message that contains Hello world!. Here is an example output:
    2025/04/29 18:23:04 Hello world!
  7. From your local computer, inspect the terminal that hosts the secure agent. You should see a number of debug messages showing the agent has operated successfully.  Here is an example output:
    [2025-04-29T18:23:04.086+01:00] [DEBUG] AceWebSocket Received OP_ENDPOINT_OPEN header
    [2025-04-29T18:23:04.089+01:00] [DEBUG] AceWebSocket Received OP_ENDPOINT_OPEN body
    [2025-04-29T18:23:04.090+01:00] [DEBUG] AgentPReceiver OP_ENDPOINT_OPEN
    [2025-04-29T18:23:04.092+01:00] [DEBUG] AgentPReceiver Endpoint found: {"name":"","hostname":"localhost","port":1234,"useTLS":false,"certs":{"key":"","cert":"","ca":[""],"rejectUnauthorized":true}}
    [2025-04-29T18:23:04.094+01:00] [DEBUG] AgentPReceiver OP_ENDPOINT_SEND
    [2025-04-29T18:23:04.100+01:00] [DEBUG] AgentPReceiver Connected to endpoint: {"name":"","hostname":"localhost","port":1234,"useTLS":false,"certs":{"key":"","cert":"","ca":[""],"rejectUnauthorized":true}}
    [2025-04-29T18:23:04.101+01:00] [DEBUG] AceWebSocket Sending OP_ENDPOINT_CLOSE header. Endpoint ID: 1
    [2025-04-29T18:23:04.102+01:00] [DEBUG] AceWebSocket Sending OP_ENDPOINT_CLOSE body. Length: 0 bytes
        

Conclusion

The IBM® App Connect Operator (version 12.11.0 or later) handles ingress for App Connect Designer Authoring and switch server instances on IKS. This means that you can access the App Connect Designer Authoring UI as soon as a Designer Authoring instance becomes ready. In addition, you can test switch servers out of box from such Designer Authoring instances.

If you want to upgrade your existing Designer Authoring and switch server instances to exploit this new feature, see the documentation on creating ingress for App Connect resources.

0 comments
23 views

Permalink