--- schema_version: "1" id: 0af9e47d603ad57ccf9bd7ba517fb6059bc6e17f202f4479aac4945574c91190 title: Configuring Ingress Resource Template in Runtime Fabric collection: mulesoft version: current locale: en-us portal_url: https://docs.salesforce.com/mulesoft/current/en-us/runtime-fabric/2.11/custom-ingress-configuration.md canonical_url: https://docs.mulesoft.com/runtime-fabric/2.11/custom-ingress-configuration source_site: docs.mulesoft.com content_type: documentation content_hash: 6428301b0a40b035ff39286f1632b6fb9211a3dd2a135ab2d3cde3269787d410 description: MuleSoft Documentation Site release: "2.11" latest: false --- --- product: Runtime Fabric version: 2.11 --- # Configuring Ingress Resource Template in Runtime Fabric > For the full documentation index, see: https://docs.mulesoft.com/llms.txt > [!IMPORTANT] This content refers to configuring ingress on Runtime Fabric for versions 1.10 and > later. Refer to the documentation for versions 1.8 or 1.9 for previous ingress configuration > instructions. Anypoint Runtime Fabric enables you to specify custom Ingress configurations using an ingress resource template. In a template, similar to a [Kubernetes ingress spec](https://kubernetes.io/docs/concepts/services-networking/ingress/), you can specify annotations, ingress class name, and HTTP and HTTPS rules. If you do not apply an ingress resource template for an application, you can’t add ingress endpoints when you deploy it. > [!IMPORTANT] The ingress controller included with Google Kubernetes Engine (GKE) provisions a > separate HTTP load balancer per application by default. > > AWS Application Load Balancers have similar behavior unless you use the `group.name` annotation. > Refer to > [Application load balancing on Amazon EKS](https://docs.aws.amazon.com/eks/latest/userguide/alb-ingress.html) > for details. ## Benefits of Custom Ingress Resource Templates Using custom ingress resource templates in Runtime Fabric enables you to take advantage of native Kubernetes ingress configuration functionality, including support for: - Multiple ingress configurations per application - Multiple ingress controllers within the same Runtime Fabric instance - TLS and HTTPS configuration - Custom URL naming - URL parameter placeholders ## How Ingress Resources Templates Work in Runtime Fabric This diagram provides an overview of how to use ingress resource templates in Runtime Fabric: ![Diagram shows the ingress template workflow in Runtime Fabric](/mulesoft/current/en-us/runtime-fabric/2.11/_images/ingress-diagram.png) 1. An IT admin configures an ingress controller. 2. An IT admin creates or modifies an ingress resource template using the necessary parameters. Various ingress controllers operate differently. Review your ingress controller documentation and adjust your annotations accordingly. 3. An IT admin applies the template using `kubectl apply` commands. 4. From the applied template, Runtime Fabric creates placeholder URI domains and propagates the ingress configuration in Anypoint Runtime Manager as a template for all application deployments. 5. A Mule application developer uses Runtime Manager to configure an application for deployment by selecting an available host, an optional subdomain, and a path combination, as specified in the ingress template. 6. Runtime Fabric receives the application deployment request and uses the ingress configurations from the template to create a corresponding ingress object in the cluster. ## Example Ingress Resource Templates These examples illustrate how to modify a Kubernetes ingress spec to create a Runtime Fabric ingress-resource template. ### networking.k8s.io/v1 > [!NOTE] This template is a simplified version of the configuration. The final configuration of the > template can vary depending on the controller and ingress routing rules you use. Review the > documentation for your ingress controller carefully. ```yaml apiVersion: networking.k8s.io/v1 kind: Ingress metadata: name: example-rtf-ingress namespace: rtf (1) labels: spec: ingressClassName: rtf-nginx (2) tls: (3) - hosts: - app-name.example.com secretName: example-tls rules: - host: app-name.example.com (4) http: paths: (5) - pathType: Prefix path: / (6) backend: (7) service: name: service-name port: name: service-port ``` Note this about this example:
1The template must be placed in the rtf namespace.
2ingressClassName must be prefixed with rtf-, for example, rtf-nginx.

Runtime Fabric uses the rtf- prefix to recognize the object as a template. Templates with rtf- prefix in the spec.ingressClassName field are consumed by the Runtime Fabric agent only and not by the actual ingress controller. Ingress controllers discover only those resources with a spec.ingressClassName value that use the vendor-specific name, for example, nginx or haproxy.

kubernetes.io/ingress.class is deprecated by K8s > 1.18, for details refer to Improvements to the Ingress API in Kubernetes 1.18
3TLS is optional.

If you add the TLS section with a secretName attribute, you must ensure that you also create the referred TLS secret in the rtf namespace.

4The app-name placeholder parameter is replaced with the actual app name when you deploy the application. It helps to ensure that each endpoint name is unique if there is not a wildcard in the subdomain.
5A template can include multiple paths for a host, but Runtime Manager displays only the first path rule for the host.
6The path parameter value is replaced by the value you add in the Path field when you configure ingress for a Mule application. Note that path is not a placeholder.
7These placeholder values are required for Kubernetes validation, but the actual values are not used by Runtime Fabric.
For a path-based routing ingress template, consult your ingress controller documentation and configure it accordingly. For an example using Nginx, see [Path-based Nginx Ingress Routing Example for Runtime Fabric on Self-Managed Kubernetes](https://help.salesforce.com/s/articleView?id=001116839&type=1). ### Template Placeholders These placeholders are optional. If you use a placeholder, replace it in the appropriate location in the template. Placeholders must be lowercase.
Name of PlaceholderLocationExample Value

business-group-id

path, host, annotation, labels

labels:
  business:
  business-group-id

environment-id

path, host, annotation, labels

labels:
  environment:
  environment-id

unique-id

path, annotation, labels

path: /app-name-unique-id.com
Use the `unique-id` placeholder to create a unique application URL. This is useful if you want to deploy two applications with same name from different business groups. For example, if you use `app-name-unique-id.com` in the `path` section of the ingress template, the resulting endpoint will be similar to `app-name-7jkbic.com`. > [!NOTE] The `unique-id` placeholder is available in Runtime Fabric version 1.12.28 and later. ## Using TLS in the Ingress Template To use TLS in the ingress template, you must create a TLS secret. See the [Kubernetes TLS documentation](https://kubernetes.io/docs/concepts/services-networking/ingress/#tls) for details. You can use the `rtf.mulesoft.com/synchronized: "true"` label to configure Runtime Fabric to synchronize any TLS secret updates to all application namespaces, for example: ```none apiVersion: v1 kind: Secret metadata: name: testsecret-tls namespace: labels: rtf.mulesoft.com/synchronized: "true" data: tls.crt: base64 encoded cert tls.key: base64 encoded key type: kubernetes.io/tls ``` Applying this label to your secret enables your ingress controller to immediately apply the updated TLS material into application namespaces. If you don’t add this label, you must manually update the secret in each namespace. > [!NOTE] You can use the synchronization mechanism to replicate any secret from the Runtime Fabric > agent namespace into the application namespace upon deployment. ## Modify an Existing Ingress Template You can modify existing ingress templates even if they were already used for application deployments. Note that already created ingress objects based on this template are not updated if you modify the template. To update existing ingresses with the template changes, you have to perform a redeployment of the Mule application. For example, if you update the base domain which requires to change the endpoint for the ingress template, you must remove the old endpoint and add the new one as part of the application redeployment. ## Existing Ingress Configurations Translated Post-Upgrade When upgrading to Runtime Fabric version 1.10, the upgrade process automatically translates any existing ingress ConfigMaps to the ingress resource template format, including annotations, path, namespace, and host parameters. Review this table to determine if any action is required after upgrading.
Runtime Fabric Pre-upgradeRuntime Fabric UpgradedAction RequiredTLS Support

No domains configured and no ingress-ConfigMap applied

No template is generated automatically after the upgrade

Create a template. See Create an Ingress Resource Template and Apply it in the Cluster.

-

No domains configured, but a valid ingress-ConfigMap applied

Generated template will contain * for hosts and will contain the path and annotations from the previous ingress-ConfigMap

Edit the host field in the generated template to provide a valid host/domain for deploying applications in Runtime Manager

No TLS section added by default

Valid domains configured, but no ingress-ConfigMap applied

Generated templates will contain one host per domain per template and will include /app-name in the path for each template

No immediate action is required unless the domains use https://; in this case, configure a TLS secret in the template corresponding to the HTTPS domain

For domains that have https://, the template corresponding to that domain will have a TLS section without a secret attribute

Valid domains configured and a valid ingress-ConfigMap applied

Generated templates will contain one host per domain per template and will include all the paths and annotations from the previous ingress-ConfigMap

No immediate action required, unless the domains use https://; in this case, configure a TLS secret in the template corresponding to the HTTPS domain

For domains that have https://, the template corresponding to that domain will have a TLS section without a secret attribute

## Troubleshooting Ingress Issues If you encounter errors when attempting to use ingress for Runtime Fabric, troubleshoot them as follows. ### Mule App Deployed But Cannot Access Its Endpoint Scenario: You successfully deploy a Mule application in Runtime Manager, but you cannot access the application’s endpoint. To troubleshoot this issue: 1. Verify that the application is listening on port 8081: ```copy kubectl port-forward -n [NAMESPACE] svc/ 8081:8081 ``` 2. Verify that the application is running and responding to HTTP requests: ```copy curl -v \http://127.0.0.1:8081/ ``` This helps determine if the API access issue is on the Mule app itself. 3. Validate that an ingress resource exists for that application service: ```copy kubectl get ingress -n [NAMESPACE] ``` 4. Validate that the service was created: ```copy kubectl get svc -n [NAMESPACE] ``` If not, check the Runtime Fabric agent logs: ```copy kubectl logs -n rtf [AGENT_POD_NAME] -f ``` If the service and ingress object look healthy, see additional troubleshooting tasks. ### Ingress Resource Created in Cluster But Cannot Access Its Endpoint Scenario: Runtime Fabric successfully creates an ingress resource in the cluster but you cannot access the application’s endpoint due to a 404 error. To troubleshoot this issue: 1. Verify the ingress and service resources: ```copy kubectl get ingress -n kubectl get svc -n ``` The results should be similar to: \# kubectl get ingress -n NAME CLASS HOSTS ADDRESS PORTS AGE .com 80, 443 7m3s # kubectl get svc -n NAME TYPE CLUSTER-IP EXTERNAL-IP PORT(S) AGE ClusterIP 8081/TCP,8082/TCP,5701/TCP 8m5s 2. Check the ingress resource for your app to ensure that the HTTP path in the resource, annotations, and host are correctly rendered: ```copy kubectl get ing -n -oyaml ``` The results should be similar to: ```yaml # kubectl get ing -n -oyaml apiVersion: extensions/v1beta1 kind: Ingress metadata: labels: ingress.rtf.mulesoft.com/svcName: ingress.rtf.mulesoft.com/svcVersion: … … spec: ingressClassName: rules: - host: myapp.example.com http: paths: - backend: serviceName: myapp servicePort: 8081 path: / pathType: Prefix tls: - hosts: myapp.example.com secretName: example-tls status: loadBalancer: ingress: - hostname: ``` 3. Check the application pod logs to ensure that you’ve configured the correct listening port: ```copy kubectl logs -f -n -c app ``` The results should be similar to: \# kubectl logs -f -n< -c app ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ - Starting app '' + ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ \[2021-07-29 21:22:37.842\] INFO QueueXaResourceManager \[ArtifactDeployer.start.01\] \[event: \]: Starting ResourceManager \[2021-07-29 21:22:37.842\] INFO QueueXaResourceManager \[ArtifactDeployer.start.01\] \[event: \]: Started ResourceManager \[2021-07-29 21:22:37.846\] INFO AbstractLifecycleManager \[ArtifactDeployer.start.01\] \[event: \]: Starting Bean: org.mule.runtime.module.extension.internal.runtime.config.ConfigurationProviderToolingAdapter-HTTP\_Listener\_config \[2021-07-29 21:22:37.859\] INFO GrizzlyHttpServer \[ArtifactDeployer.start.01\] \[event: \]: Listening for connections on 'http://0.0.0.0:8081' \[2021-07-29 21:22:37.874\] INFO FlowConstructLifecycleManager \[ArtifactDeployer.start.01\] \[event: \]: Starting flow: sample-json-backendFlow \[2021-07-29 21:22:38.171\] INFO AbstractLifecycleManager \[ArtifactDeployer.start.01\] \[event: \]: Starting Bean: listener \[2021-07-29 21:22:38.178\] INFO LogUtil \[ArtifactDeployer.start.01\]: 4. In the logs, verify that the listener port matches the service port discovered in Step 1. 5. If the port is correct, check the application logs to verify that the application is receiving requests from the ingress controller. ### Ingress Resource Not Recognized by AWS Application Load Balancer Scenario: When using an AWS ALB, you can’t access an application’s endpoint, even though you successfully deployed the application and endpoint. If you’re using AWS Load Balancer Controller for ingress, you must specify the `spec.ingressClassName: rtf-alb` in the template. AWS Load Balancer Controller requires the `spec.ingressClassName` to discover and create L7 load balancers for deployed ingress resources for those annotations.