Sample Kubernetes Deployment for WSO2 Integrator: MI and Integration Control Plane (ICP)¶ This guide walks you through setting up a basic deployment of WSO2 Integrator: MI and Integration Control Plane (ICP) on a local Kubernetes cluster. The deployment includes: Two MI replicas for high availability. One ICP pod to monitor and manage your integration services. Instructions on how to provide configurable values through Helm. While this guide uses a local Kubernetes setup (e.g., Minikube or Kind) for simplicity, you can also deploy the same configuration on any cloud platform (such as AWS, GCP, or Azure) by adjusting the relevant settings. Before you begin¶ Ensure you have an active WSO2 Subscription. If you don't have a subscription, sign up for a WSO2 Free Trial Subscription. Note You need an active subscription to use the updated Docker images of the WSO2 Integrator: MI with your Helm resources. Otherwise, you can use the community version of the Docker images, which do not include product updates. Install Git, Docker, Helm, and the Kubernetes client. Set up a Kubernetes cluster. You can also try deploying WSO2 Integrator: MI locally with a local Kubernetes cluster. Install the NGINX Ingress Controller. Note Helm resources for WSO2 product deployment patterns are compatible with the ingress-nginx controller-v1.12.0 release. Step 1 - Get the Helm resources¶ You can find the official WSO2 Integrator: MI Helm charts repository at: https://github.com/wso2/helm-mi Open a terminal and navigate to the location where you want to save the local copy. Clone the WSO2 Integrator: MI Git repository that contains the Helm resources: git clone https://github.com/wso2-enterprise/helm-mi.git cd helm-mi git checkout 4.5.x Note The 4.5.x branch includes Helm resources that are compatible with WSO2 Integrator: MI version 4.5.0. Let's refer to the root folder of the cloned repository as <HELM_HOME> throughout this guide. Step 2 - Build the Docker Image¶ For the MI deployment, you will use a pre-developed integration project that includes the following artifacts: An API that calls a backend service to retrieve the currency rate. A configurable to externalize the backend URL, whose value will be injected as an environment variable in later steps. Download the Currency converter project and extract the contents. We'll refer to the root directory of the project as <PROJECT_HOME>. Run the following command inside the <PROJECT_HOME> directory to build the project and create the Docker image: mvn clean install -Pdocker Note This command runs the docker Maven profile defined in the integration project. It builds the Docker image and stores it in your local Docker daemon. If you need to deploy the image from a remote registry (e.g., in a cloud environment), use the docker push command to push the image to your container registry. By default, the resulting Docker image name will be in the format <project_artifactId>:<project_version>. For this project, the image will be named currencyconverter:1.0.0. You can customize the image name and other settings via the VS Code MI project settings or by editing the pom.xml file located at <PROJECT_HOME>/pom.xml. You can also use the MI for VS Code extension to build the Docker image. For more details, see Build Docker Image. For the ICP deployment, the official WSO2 ICP Docker image will be used. Step 3 - Deploy MI and ICP¶ In this step, you will deploy both the WSO2 Integrator: MI and the Integration Control Plane (ICP) using Helm. The deployment will be configured using two values files: mi-values.yaml – Contains the deployment-specific configurations for the WSO2 Integrator: MI. icp-values.yaml – Contains the configurations for the Integration Control Plane. You may expand each file section below to review the configuration content and understand the purpose of each setting. mi-values.yaml 1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59# -- Container registry (When running on a local Kubernetes cluster using local image, make this empty) containerRegistry: "" wso2: ingress: enabled: true ingressClassName: "nginx" annotations: nginx.ingress.kubernetes.io/backend-protocol: "HTTPS" config: keyStore: primary: # -- Primary keystore file name fileName: "wso2carbon.jks" # -- Primary keystore alias alias: "wso2carbon" # -- Primary keystore password password: "wso2carbon" # -- Primary keystore key password keyPassword: "wso2carbon" internal: # -- Internal keystore file name fileName: "wso2carbon.jks" # -- Internal keystore alias alias: "wso2carbon" # -- Internal keystore password password: "wso2carbon" # -- Internal keystore key password keyPassword: "wso2carbon" trustStore: primary: # -- Primary truststore file name fileName: "client-truststore.jks" # -- Primary truststore password password: "wso2carbon" icp: # -- ICP URL url: "https://cloud-icp:9743/dashboard/api/" deployment: securityContext: # -- Enable/Disable AppArmor (https://kubernetes.io/docs/tutorials/security/apparmor/) apparmor: false # -- Enable/Disable seccomp profile (https://kubernetes.io/docs/tutorials/security/seccomp/) seccompProfile: false runAsUser: "10802" # -- Hostname of the WSO2 Integrator: MI deployment hostname: "mi.wso2.com" # -- Build version of the WSO2 Integrator: MI BuildVersion: "4.5.0" image: # -- Container image repository name repository: "currencyconverter" # -- Container image tag tag: "1.0.0" # -- Number of deployment replicas replicas: 2 # -- (list) Environment variables for the WSO2 Integrator: MI deployment envs: currency_service_url: "https://dev-tools.wso2.com/gs/helpers/v1.0" Line 7 – This configuration uses the NGINX Ingress Controller for ingress traffic. If you're using a different ingress controller, update the ingressClassName and relevant annotations accordingly. Line 36 – This defines the URL for the Integration Control Plane (ICP) so that MI can communicate with it. Since both MI and ICP are deployed in the same Kubernetes cluster, the internal service name of the ICP is used. By default: Group ID is set to the Helm release name. Node ID is derived from the MI pod name. You can override these values using the groupId and nodeId parameters as needed. Line 40 – In this guide, AppArmor and seccomp are disabled (apparmor: false, seccompProfile: false) because we are using a local Kubernetes cluster where these security features may not be fully supported or configured. For production environments, it is strongly recommended to enable and configure both AppArmor and seccomp to enforce container-level security and minimize the attack surface. For more details, refer to the Kubernetes AppArmor documentation and Seccomp documentation. Line 45 – Specifies the user ID (UID) that the container process runs as. This UID should match the one used when creating the Docker image. By default, the MI Docker image uses 10802. Line 50 – This section configures the Docker image used for the MI deployment. The image version is specified using the tag. Alternatively, you can specify the image using its digest via the digest parameter under image. Line 58 – Use the env section to pass environment variables required by your integration. These environment variables should match the configurables declared in your integration artifacts. For example, the currency_service_url variable is used by the API in this tutorial to dynamically resolve the backend service URL. For a complete list of available configuration options and usage examples, refer to the MI Helm Chart Configuration Guide. icp-values.yaml 1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42containerRegistry: "wso2" wso2: ingress: # -- Enable Ingress for ICP enabled: true # -- Ingress class name ingressClassName: "nginx" # -- (list) Ingress annotations annotations: nginx.ingress.kubernetes.io/backend-protocol: "HTTPS" config: miUserstore: # -- The user name for signing in to the WSO2 Integrator: MI runtimes username: "admin" # -- The user password for signing in to the WSO2 Integrator: MI runtimes. password: "admin" keyStore: # -- The keystore file name fileName: "dashboard.jks" # -- The keystore alias alias: "wso2carbon" # -- The keystore password password: "wso2carbon" # -- The keystore key password keyPassword: "wso2carbon" deployment: securityContext: # -- Enable/Disable AppArmor (https://kubernetes.io/docs/tutorials/security/apparmor/) apparmor: false # -- Enable/Disable seccomp profile (https://kubernetes.io/docs/tutorials/security/seccomp/) seccompProfile: false # -- The UID to run the entrypoint of the container process runAsUser: "802" # -- Hostname of the ICP deployment hostname: "icp.wso2.com" # -- Build version of the ICP BuildVersion: "1.2.0" image: # -- Container image repository name repository: "wso2-integration-control-plane" # -- Container image tag tag: "1.2.0" Line 1 – Since the WSO2 official ICP Docker image is used, the containerRegistry is set to wso2. Line 17 – This defines the user credentials the ICP uses to connect to MI nodes. In this example, the default super admin credentials are used. Line 33 – Specifies the user ID (UID) for running the container entry point. Ensure this value matches the UID used when building the Docker image. By default, the ICP Docker image uses UID 802. Line 38 – This section configures the Docker image for the ICP deployment. The image version is specified using the tag. Alternatively, you can specify the image using the digest parameter under image. For a complete list of configuration options and their usage, refer to the ICP Helm Chart Configuration Guide. Download the configuration files: mi-values.yaml and icp-values.yaml. Copy the mi-values.yaml file to the <HELM_HOME>/mi directory. Copy the icp-values.yaml file to the <HELM_HOME>/icp directory. Navigate to the <HELM_HOME>/mi directory and execute the following Helm command: CommandExample helm install <RELEASE_NAME> . -f mi-values.yaml -n <NAMESPACE> --create-namespace helm install apis-intg . -f mi-values.yaml -n dev --create-namespace The above command will create a Kubernetes namespace called dev and deploy the WSO2 Integrator: MI with the release name apis-intg. Next, you will deploy the Integration Control Plane (ICP). Navigate to the <HELM_HOME>/icp directory and execute the following Helm command: CommandExample helm install <RELEASE_NAME> . -f icp-values.yaml -n <NAMESPACE> helm install icp . -f icp-values.yaml -n dev The above command will deploy the Integration Control Plane (ICP) with the release name icp in the dev namespace. Step 4 - Verify and test the deployment¶ Once the deployment is successful, the following resources will be created in your Kubernetes cluster. You can use the commands below to verify them. Note It may take around 1 minute for all the pods to be fully up and running. The following commands use the namespace dev and reflect the release names and chart configurations used in the previous steps. If you have modified these values, update the commands accordingly. Verify that the WSO2 Integrator: MI and Integration Control Plane (ICP) pods are running successfully: kubectl get pods -n dev You should see output similar to: NAME READY STATUS RESTARTS AGE cloud-icp-d5575fb-x6gnw 1/1 Running 0 5m32s cloud-apis-intg-7486b48657-tdcww 1/1 Running 0 108s cloud-apis-intg-7486b48657-2gf5c 1/1 Running 0 108s Ensure the status of the pods is Ready before proceeding to the next step. If you encounter any issues, refer to the Troubleshooting section for guidance. Access the Integrations and Integration Control Plane¶ Follow these steps from your terminal to invoke the integration and access the Integration Control Plane (ICP). Note After deploying your integrations in the Kubernetes cluster, you can also test them without using the Ingress controller by forwarding a service port. This is useful for quick testing and debugging. See the Invoke without Ingress Controller section for more details. Get the external IP of the Ingress resources. Run the following command to list the Ingress resources in the dev namespace. kubectl get ingress -n dev You should see output similar to: NAME CLASS HOSTS ADDRESS PORTS AGE cloud-apis-intg nginx mi.wso2.com 192.168.5.15 80, 443 145m cloud-icp nginx icp.wso2.com 192.168.5.15 80, 443 145m Add host entries to /etc/hosts. To access the deployed services using domain names (mi.wso2.com and icp.wso2.com), you need to add entries to your local /etc/hosts file. This maps the domain names to the external IP of your Kubernetes Ingress. For example, if your ingress IP is 192.168.5.15, add the following lines. 192.168.5.15 mi.wso2.com 192.168.5.15 icp.wso2.com Invoke the integration. Run the following command to invoke the sample integration. curl -X POST https://mi.wso2.com/currencyapi -d '{"fromCurrency": "AUD", "toCurrency": "USD"}' -H "Content-Type: application/json" -k You should see a response like: {"fromCurrency":"AUD", "toCurrency":"USD", "rate":0.67} Access the Integration Control Plane. Open https://icp.wso2.com/login in your browser and sign in using admin for both the username and password. Verify MI nodes. In the Nodes view of the Integration Control Plane (ICP), you should see both MI pods grouped under the configured release name, each identified by its respective pod name. Invoke without Ingress controller¶ You can access the deployed WSO2 Integrator: MI and Integration Control Plane (ICP) without using an Ingress controller by forwarding service ports locally. This is useful for testing or when Ingress is not set up. Port-forward the WSO2 Integrator: MI service: kubectl port-forward service/cloud-apis-intg -n dev 8253:8253 Invoke the deployed API: curl -X POST https://localhost:8253/currencyapi -d '{"fromCurrency": "AUD", "toCurrency": "USD"}' -H "Content-Type: application/json" -k You should see a response like: {"fromCurrency":"AUD", "toCurrency":"USD", "rate":0.67} Port-forward the Integration Control Plane service: kubectl port-forward service/cloud-icp -n dev 9743:9743 Access the Integration Control Plane by opening https://localhost:9743/login in your browser. Troubleshooting¶ If you face issues during or after the deployment, here are some common troubleshooting tips: 1. Pods are stuck in Pending or CrashLoopBackOff state. Run kubectl describe pod <POD_NAME> -n dev to view detailed logs and events. Check if your Kubernetes cluster has sufficient CPU and memory resources. Ensure that the Docker image and tag are correctly defined 2. Ingress IP is <pending>. Verify that the NGINX Ingress Controller is installed and running: kubectl get pods -n ingress-nginx 3.Unable to invoke API or access ICP. Make sure /etc/hosts entries (mi.wso2.com, icp.wso2.com) point to the correct ingress IP. Check that the relevant services and ingresses are correctly created: kubectl get svc,ingress -n dev 4. Check pod logs to verify runtime or product-level issues. Use the following command to inspect logs for the MI or ICP pods: kubectl logs <POD_NAME> -n dev Look for any configuration errors, port binding issues, or missing dependencies in the startup logs. For container crashes, check if the log contains stack traces or error messages related to deployment or connectivity. 5. MI nodes not visible in Integration Control Plane (ICP). Confirm that group_id and node_id are correctly configured in the MI deployment.toml. Ensure the dashboard_url is properly set to point to ICP.