Manually creating ingress definitions for IBM App Connect instances in an Azure Kubernetes Service (AKS) cluster

Kubernetes-only contentUse these instructions to expose your deployed App Connect Dashboard, App Connect Designer, integration server, and switch server instances in an Azure Kubernetes Service (AKS) environment to external traffic. If you have enabled the API for IBM® App Connect in containers to administer resources in the App Connect Dashboard, you also need to expose the API to external traffic.

Before you begin

An ingress controller must be installed and running in the AKS cluster.

You can install an ingress controller in various ways. The following steps describe how to install an NGINX ingress controller by using a Helm chart.

  1. Create a namespace called ingress in your cluster.
    kubectl create namespace ingress
  2. Add the NGINX ingress controller chart repository and then update all Helm repositories in your system by running the following commands.
    helm repo add ingress-nginx https://kubernetes.github.io/ingress-nginx
helm repo update
  3. Install the Helm chart in the ingress namespace by running either of the following helm commands. These commands install an NGINX ingress controller (nginx-ingress) for use with your App Connect Dashboard (and API if enabled), App Connect Designer, integration server, and switch server instances. The command varies slightly for a switch server, which is required to configure connectivity for hybrid integrations that interact with callable flows in IBM App Connect Enterprise or IBM Integration Bus, or with applications in a private network. (For more information about switch servers, see App Connect Switch Server reference.)
    Note: The helm commands provide a basic definition to get you started, and can be extended with additional settings if required for your environment.

    • If you do not intend to deploy hybrid integrations that require a switch server, run the following helm command. 
      helm install nginx-ingress ingress-nginx/ingress-nginx \
     --namespace ingress \
     --set controller.replicaCount=2 \
     --set controller.nodeSelector."beta\.kubernetes\.io/os"=linux \
     --set defaultBackend.nodeSelector."beta\.kubernetes\.io/os"=linux \
     --set controller.admissionWebhooks.patch.nodeSelector."beta\.kubernetes\.io/os"=linux
    • If you require a switch server for callable flow or private network connectivity, run the helm command with an additional --set flag:

      --set "controller.extraArgs.enable-ssl-passthrough="

      This setting needs to be applied to any NGINX ingress controller that allows external integration servers, which have been configured with an agentx.json, agenta.json, or switchclient.json file, to connect directly to the switch server. For information about working with the agentx.json or agenta.json files, see Configuring connectivity between a calling flow and a callable flow, Agentx type, and AgentA type. For information about connecting your flows or integrations to a private network, see Connecting to a private network from App Connect Designer, Connecting to a private network from the App Connect Dashboard, and Private Network Agent type.

      helm install nginx-ingress ingress-nginx/ingress-nginx \
     --namespace ingress \
     --set controller.replicaCount=2 \
     --set controller.nodeSelector."beta\.kubernetes\.io/os"=linux \
     --set defaultBackend.nodeSelector."beta\.kubernetes\.io/os"=linux \
     --set controller.admissionWebhooks.patch.nodeSelector."beta\.kubernetes\.io/os"=linux \
     --set "controller.extraArgs.enable-ssl-passthrough="

About this task

For each App Connect Dashboard (and API if enabled), App Connect Designer, integration server, or switch server instance that is created, you must create an ingress resource with rules that define an externally-reachable URL for accessing the running service in the cluster.

Work with a cluster administrator if necessary to create and apply the ingress resources.

Creating an ingress route for an App Connect Dashboard UI

Create an ingress resource that will be used to route external traffic to an App Connect Dashboard UI in your cluster.

Procedure

To create an ingress route for a running Dashboard UI, complete the following steps:

  1. From your local computer, create a YAML file (for example, appconn-ingress-dashboard.yaml) with the following content, where:
    • <dashboardIngressName> is a unique short name by which the ingress can be identified.
    • <namespaceName> is the namespace where the Dashboard instance is deployed.
    • <dashboardHostPrefix> is a valid DNS subdomain name that is prefixed to your domain name (.mydomain.com) to form a host name for the Dashboard UI. Only one host name can be specified for a Dashboard UI.
    • <dashboardCRName> is the metadata.name value in the Dashboard instance custom resource.
    Note: The <dashboardIngressName> and <dashboardHostPrefix> values for the Dashboard UI must be different from the <dashboardIngressName> and <dashboardHostPrefix> values for the API.
    kind: Ingress
apiVersion: networking.k8s.io/v1
metadata:
  name: <dashboardIngressName>
  namespace: <namespaceName>
  annotations:
    kubernetes.io/ingress.class: "nginx"
    nginx.ingress.kubernetes.io/backend-protocol: HTTPS
spec:
  tls:
    - hosts:
      - <dashboardHostPrefix>.mydomain.com
  rules:
    - host: <dashboardHostPrefix>.mydomain.com
      http:
        paths:
        - path: /
          pathType: Prefix
          backend:
            service:
              name: <dashboardCRname>-dash
              port:
                number: 8300
  2. Run the following command to create the ingress: 
    kubectl apply -f appconn-ingress-dashboard.yaml

    You can now access the App Connect Dashboard UI instance to deploy and manage your integrations by providing the following URL in a browser:

    https://<dashboardHostPrefix>.mydomain.com

    Traffic to this URL will be routed to the <dashboardCRName>-dash service.

Creating an ingress route for an API that is enabled for the App Connect Dashboard

Create an ingress resource that will be used to route external traffic to an API for IBM App Connect in containers, which is enabled for an App Connect Dashboard instance in your cluster. This API provides REST API facilities for administering resources that the App Connect Dashboard manages.

For more information about the API, see API for IBM App Connect in containers.

Procedure

To create an ingress route for an API that is enabled for the Dashboard, complete the following steps:

  1. From your local computer, create a YAML file (for example, appconn-ingress-dashboardapi.yaml) with the following content, where:
    • <dashboardIngressName> is a unique short name by which the ingress can be identified.
    • <namespaceName> is the namespace where the Dashboard instance is deployed.
    • <dashboardHostPrefix> is a valid DNS subdomain name that is prefixed to your domain name (.mydomain.com) to form a host name for the Dashboard's API. Only one host name can be specified for an API.
    • <dashboardCRName> is the metadata.name value in the Dashboard instance custom resource.
    Note: The <dashboardIngressName> and <dashboardHostPrefix> values for the API must be different from the <dashboardIngressName> and <dashboardHostPrefix> values for the Dashboard UI.
    kind: Ingress
apiVersion: networking.k8s.io/v1
metadata:
  name: <dashboardIngressName>
  namespace: <namespaceName>
  annotations:
    kubernetes.io/ingress.class: "nginx"
    nginx.ingress.kubernetes.io/backend-protocol: HTTPS
spec:
  tls:
    - hosts:
      - <dashboardHostPrefix>.mydomain.com
  rules:
    - host: <dashboardHostPrefix>.mydomain.com
      http:
        paths:
        - path: /
          pathType: Prefix
          backend:
            service:
              name: <dashboardCRname>-dash
              port:
                number: 8400
  2. Run the following command to create the ingress: 
    kubectl apply -f appconn-ingress-dashboardapi.yaml

    If you have the correct permission, you can now make API calls to administer resources in the App Connect Dashboard instance by providing the following URL as the base URL (and appending an operation path):

    https://<dashboardHostPrefix>.mydomain.com

    Traffic to this URL will be routed to the <dashboardCRName>-dash service.

Creating an ingress route for a switch server

To expose a switch server to external traffic, you must create an ingress route immediately after you create the switch server because during its initialization, the switch server will need to provide a TLS host name (defined in an ingress resource) in order to request a certificate for this host. To prevent certificate-related errors from the ingress controller, the host name in the generated certificate and the TLS host name that is defined in your ingress resource must match.

Procedure

To create an ingress route for a newly deployed switch server, complete the following steps:

  1. From your local computer, create a YAML file (for example, appconn-ingress-switch.yaml) with the following content, where:
    • <switchServerIngressName> is a unique short name by which the ingress can be identified.
    • <namespaceName> is the namespace where the switch server is deployed.
    • <switchServerCRName> is the metadata.name value in the switch server custom resource.
    • <switchServerHostPrefix> is a valid DNS subdomain name that is prefixed to your domain name (.mydomain.com) to form a host name for the switch server. Only one host name can be specified for a switch server.
    Note: In the YAML definition, the supplied label appconnect.ibm.com/switch: <switchServerCRName> denotes which switch server this ingress applies to. The IBM App Connect Operator will try to find this ingress definition for 10 minutes from when it started trying to create the switch server. If the Operator cannot find the ingress definition after this time, the switch server deployment moves to a FAILED state.

    kind: Ingress
apiVersion: networking.k8s.io/v1
metadata:
  name: <switchServerIngressName>
  namespace: <namespaceName>
  labels:
    appconnect.ibm.com/switch: <switchServerCRName>
  annotations:
    kubernetes.io/ingress.class: "nginx"
    nginx.ingress.kubernetes.io/backend-protocol: "HTTPS"
    nginx.ingress.kubernetes.io/ssl-redirect: "true"
    nginx.ingress.kubernetes.io/ssl-passthrough: "true"
spec:
  tls:
    - hosts:
      - <switchServerHostPrefix>.mydomain.com
  rules:
    - host: <switchServerHostPrefix>.mydomain.com
      http:
        paths:
        - path: /
          pathType: Prefix
          backend:
            service:
              name: <switchServerCRName>-switch
              port:
                number: 4443
  2. Run the following command to create the ingress: 
    kubectl apply -f appconn-ingress-switch.yaml

    To help you resolve any network connectivity or certificate errors when using a switch server, see Troubleshooting ingress issues on Kubernetes.

Creating an ingress route for an App Connect Designer instance

Create an ingress resource that will be used to route external traffic to an App Connect Designer instance in your cluster.

About this task

When a Designer instance at version 13.0.1.0-r2 or later is deployed, an integration runtime is automatically deployed to provide support for the built-in test facility for flows. After you create an ingress route for a Designer instance, you will also be required to create an ingress route for this integration runtime as described in Creating an ingress route for the internal integration runtime that is deployed for App Connect Designer 13.0.1.0-r2 or later. If you are using a Designer instance at version 13.0.1.0-r1 or earlier, an integration server is deployed to provide support for the built-in test facility for flows. After you create an ingress route for the Designer instance, you similarly need to create an ingress route for the integration server as described in Creating an ingress route for the internal integration server that is deployed for App Connect Designer 13.0.1.0-r1 or earlier.

Procedure

To create an ingress route for a running Designer instance, complete the following steps:

  1. From your local computer, create a YAML file (for example, appconn-ingress-desauth.yaml) with the following content, where:
    • <designerAuthoringUIIngressName> is a unique short name by which the ingress can be identified.
    • <namespaceName> is the namespace where the Designer instance is deployed.
    • <designerAuthoringUIHostPrefix> is a valid DNS subdomain name that is prefixed to your domain name (.mydomain.com) to form a host name for the Designer instance. Only one host name can be specified for a Designer instance.
    • <designerAuthoringCRName> is the metadata.name value in the Designer instance custom resource.
    apiVersion: networking.k8s.io/v1
kind: Ingress
metadata:
  name: <designerAuthoringUIIngressName>
  namespace: <namespaceName>
  annotations:
    kubernetes.io/ingress.class: "nginx"
    nginx.ingress.kubernetes.io/backend-protocol: HTTPS
spec:
  tls:
    - hosts:
      - <designerAuthoringUIHostPrefix>.mydomain.com
  rules:
    - host: <designerAuthoringUIHostPrefix>.mydomain.com
      http:
        paths:
        - path: /
          pathType: Prefix
          backend:
            service:
              name: <designerAuthoringCRName>-ui
              port:
                number: 3001
  2. Run the following command to create the ingress: 
    kubectl apply -f appconn-ingress-desauth.yaml

    You can now access the App Connect Designer instance to create and manage flows by providing the following URL in a browser:

    https://<designerAuthoringUIHostPrefix>.mydomain.com

    Traffic to this URL will be routed to the <designerAuthoringCRName>-ui service.

What to do next

Create an ingress route that will be used by the built-in test facility for API flows in your App Connect Designer instance. For more information, see the relevant details for your Designer version:

Creating an ingress route for the internal integration runtime that is deployed for App Connect Designer 13.0.1.0-r2 or later

When you create an App Connect Designer instance with a spec.version value that resolves to 13.0.1.0-r2 or later, the IBM App Connect Operator (version 12.5.0 or later) automatically deploys an internal integration runtime for that Designer instance. This integration runtime supports your Designer flows and enables you to verify the behavior of a running API flow by using the built-in test facility to call the endpoints for the implemented API operations. The internal integration runtime is named <designerAuthoringCRName>-designer by default.


You must create an ingress resource that will be used to route external traffic to this integration runtime in the cluster, and then configure the correct endpoints for calling the API operations. (For information about creating API flows, see Creating and managing flows in App Connect Designer.)

Procedure

To create an ingress route for the internal integration runtime that is deployed for a Designer instance, complete the following steps:

  1. From your local computer, create a YAML file (for example, appconn-ingress-desauthruntime.yaml) with the following content, where:
    • <designerAuthoringIRIngressName> is a unique short name by which the ingress can be identified.
    • <namespaceName> is the namespace where the Designer instance is deployed.
    • <designerAuthoringIRHostPrefix> is a valid DNS subdomain name that is prefixed to your domain name (.mydomain.com) to denote the internal integration runtime's endpoint (host name). Only one host name can be specified for this instance.
    • <designerAuthoringCRName> is the metadata.name value in the Designer instance custom resource.
    apiVersion: networking.k8s.io/v1
kind: Ingress
metadata:
  name: <designerAuthoringIRIngressName>
  namespace: <namespaceName>
  annotations:
    kubernetes.io/ingress.class: "nginx"
    nginx.ingress.kubernetes.io/backend-protocol: HTTPS
spec:
  tls:
    - hosts:
      - <designerAuthoringIRHostPrefix>.mydomain.com
  rules:
    - host: <designerAuthoringIRHostPrefix>.mydomain.com
      http:
        paths:
        - path: /
          pathType: Prefix
          backend:
            service:
              name: <designerAuthoringCRName>-designer-ir
              port:
                number: 7843
  2. Run the following command to create the ingress: 
    kubectl apply -f appconn-ingress-desauthruntime.yaml
  3. To ensure that the API flow displays the correct endpoints for the running API while within the Test tab for the flow, run the following command to set the ingress external address, which you created earlier, on the deployment: 
    kubectl set env deployment/<designerAuthoringCRName>-ui SINGLE_TENANT_API_BASE_URL=https://<designerAuthoringIRHostPrefix>.mydomain.com

    For example:

    kubectl set env deployment/des-01-quickstart-ui SINGLE_TENANT_API_BASE_URL=https://mydesauthis.acmeair.com

    The correct endpoints will be shown when you open the Test tab for the running API in App Connect Designer. For each operation, you can then use the Try it tab to test that calls can be successfully made to the external endpoint.

    Ingress endpoint for an integration runtime in the App Connect Designer

Creating an ingress route for the internal integration server that is deployed for App Connect Designer 13.0.1.0-r1 or earlier

When you create an App Connect Designer instance with a spec.version value that resolves to 13.0.1.0-r1 or earlier, the IBM App Connect Operator (version 12.4.0 or earlier) automatically deploys an internal integration server for that Designer instance. This integration server supports your Designer flows and enables you to verify the behavior of a running API flow by using the built-in test facility to call the endpoints for the implemented API operations. The internal integration server is named <designerAuthoringCRName>-designer by default.


You must create an ingress resource that will be used to route external traffic to this integration server in the cluster, and then configure the correct endpoints for calling the API operations. (For information about creating API flows, see Creating and managing flows in App Connect Designer.)

Procedure

To create an ingress route for the internal integration server that is deployed for a Designer instance, complete the following steps:

  1. From your local computer, create a YAML file (for example, appconn-ingress-desauthserver.yaml) with the following content, where:
    • <designerAuthoringISIngressName> is a unique short name by which the ingress can be identified.
    • <namespaceName> is the namespace where the Designer instance is deployed.
    • <designerAuthoringISHostPrefix> is a valid DNS subdomain name that is prefixed to your domain name (.mydomain.com) to denote the internal integration server's endpoint (host name). Only one host name can be specified for this instance.
    • <designerAuthoringCRName> is the metadata.name value in the Designer instance custom resource.
    apiVersion: networking.k8s.io/v1
kind: Ingress
metadata:
  name: <designerAuthoringISIngressName>
  namespace: <namespaceName>
  annotations:
    kubernetes.io/ingress.class: "nginx"
    nginx.ingress.kubernetes.io/backend-protocol: HTTPS
spec:
  tls:
    - hosts:
      - <designerAuthoringISHostPrefix>.mydomain.com
  rules:
    - host: <designerAuthoringISHostPrefix>.mydomain.com
      http:
        paths:
        - path: /
          pathType: Prefix
          backend:
            service:
              name: <designerAuthoringCRName>-designer-is
              port:
                number: 7843
  2. Run the following command to create the ingress: 
    kubectl apply -f appconn-ingress-desauthserver.yaml
  3. To ensure that the API flow displays the correct endpoints for the running API while within the Test tab for the flow, run the following command to set the ingress external address, which you created earlier, on the deployment: 
    kubectl set env deployment/<designerAuthoringCRName>-ui SINGLE_TENANT_API_BASE_URL=https://<designerAuthoringISHostPrefix>.mydomain.com

    For example:

    kubectl set env deployment/des-01-quickstart-ui SINGLE_TENANT_API_BASE_URL=https://mydesauthis.acmeair.com

    The correct endpoints will be shown when you open the Test tab for the running API in App Connect Designer. For each operation, you can then use the Try it tab to test that calls can be successfully made to the external endpoint.

    Ingress endpoint for an integration server in the App Connect Designer

Creating an ingress route for an integration server in the App Connect Dashboard

When you deploy one or more BAR files to an integration server, you can indicate whether an HTTP or HTTPS route should be used to externally expose the service that identifies the set of pods where the integration runs. You must manually create this external route for the selected HTTP or HTTPS protocol. These instructions describe how to create an ingress resource for an integration server and configure the endpoints in your cluster.

Note: To use an HTTPS route, ensure that TLS is enabled for the integration server. Include the following custom resource (CR) settings in the integration server's CR before you deploy it or update the CR settings after deployment.
  • Set spec.forceFlowHTTPS.enabled to true to force all HTTP Input nodes and SOAP Input nodes in all deployed flows in the integration server to use TLS.
  • Set spec.forceFlowHTTPS.secretName to the name of a secret that stores a user-supplied public certificate/private key pair to use for enforcing TLS.
  • Set spec.service.endpointType to https.

Procedure

To create an ingress route for a running integration server, complete either of the following steps:

  • If you want to specify https as the type of transport to be used by the integration endpoint, complete the following steps:
    1. From your local computer, create a YAML file (for example, appconn-ingress-intserverhttps.yaml) with the following content.
      • Set <integrationServerIngressName> to a unique short name by which the ingress can be identified.
      • Set <namespaceName> to the namespace where the integration server is deployed.
      • For a secured HTTPS endpoint, set <integrationServerHostPrefix> to a valid DNS subdomain name that is prefixed to your domain name (.mydomain.com) to denote an external (TLS) endpoint. Also include the annotation nginx.ingress.kubernetes.io/backend-protocol: HTTPS, and use 7843 as the service port.
      • Set <integrationServerCRName> to the metadata.name value in the integration server custom resource.
      apiVersion: networking.k8s.io/v1
kind: Ingress
metadata:
  name: <integrationServerIngressName>
  namespace: <namespaceName>
  annotations:
    kubernetes.io/ingress.class: "nginx"
    nginx.ingress.kubernetes.io/backend-protocol: HTTPS
spec:
  tls:
    - hosts:
      - <integrationServerHostPrefix>.mydomain.com
  rules:
    - host: <integrationServerHostPrefix>.mydomain.com
      http:
        paths:
        - path: /
          pathType: Prefix
          backend:
            service:
              name: <integrationServerCRName>-is
              port:
                number: 7843
    2. Run the following command to create the ingress: 
      kubectl apply -f appconn-ingress-intserverhttps.yaml
    3. To ensure that the integration server displays the correct endpoints for the deployed integration within the App Connect Dashboard, run the following command to set the ingress external address on the deployment: 
      kubectl set env deployment/<integrationServerCRName>-is MQSI_OVERRIDE_HOSTNAME=<integrationServerHostPrefix>.mydomain.com MQSI_OVERRIDE_HTTPS_PORT=443

      For example:

      kubectl set env deployment/myis-toolkit-is MQSI_OVERRIDE_HOSTNAME=myintserver.acmeair.com MQSI_OVERRIDE_HTTPS_PORT=443

      The correct endpoints will be shown when you click the tile for the relevant integration.

      Ingress endpoint for an integration server in the App Connect Dashboard
  • If you want to specify http as the type of transport to be used by the integration endpoint, complete the following steps:
    1. From your local computer, create a YAML file (for example, appconn-ingress-intserverhttp.yaml) with the following content.
      • Set <integrationServerIngressName> to a unique short name by which the ingress can be identified.
      • Set <namespaceName> to the namespace where the integration server is deployed.
      • For an unsecured HTTP endpoint, set <integrationServerHostPrefix> to a valid DNS subdomain name that is prefixed to your domain name (.mydomain.com) to denote an external endpoint. Also include the annotation nginx.ingress.kubernetes.io/backend-protocol: HTTP, and use 7800 as the service port.
      • Set <integrationServerCRName> to the metadata.name value in the integration server custom resource.
      apiVersion: networking.k8s.io/v1
kind: Ingress
metadata:
  name: <integrationServerIngressName>
  namespace: <namespaceName>
  annotations:
    kubernetes.io/ingress.class: "nginx"
    nginx.ingress.kubernetes.io/backend-protocol: HTTP
spec:
  tls:
    - hosts:
      - <integrationServerHostPrefix>.mydomain.com
  rules:
    - host: <integrationServerHostPrefix>.mydomain.com
      http:
        paths:
        - path: /
          pathType: Prefix
          backend:
            service:
              name: <integrationServerCRName>-is
              port:
                number: 7800
    2. Run the following command to create the ingress: 
      kubectl apply -f appconn-ingress-intserverhttp.yaml
    3. To ensure that the integration server displays the correct endpoints for the deployed integration within the App Connect Dashboard, run the following command to set the ingress external address on the deployment: 
      kubectl set env deployment/<integrationServerCRName>-is MQSI_OVERRIDE_HOSTNAME=<integrationServerHostPrefix>.mydomain.com MQSI_OVERRIDE_HTTP_PORT=80

      For example:

      kubectl set env deployment/myis-toolkit-is MQSI_OVERRIDE_HOSTNAME=myintserver.acmeair.com MQSI_OVERRIDE_HTTP_PORT=80

      The correct endpoints will be shown when you click the tile for the relevant integration.