A MuleSoft license does not last forever. When it expires, our Runtime Fabric stops deploying and running applications. That is a production outage. We need to update the license before that happens — or fix it fast when it does.In this post, we walk through the full procedure.
What We Are Doing
Runtime Fabric stores the MuleSoft license as a Kubernetes Secret. That secret holds the license content encoded in Base64. When the license expires, we replace that secret with a new one.The steps are:
- Upload the new
.licfile to our K8s server. We’ll use Ubuntu server in this post. - Encode the file in Base64 on the server
- Delete the old license secret in Kubernetes
- Create a new license secret with the encoded value
- Restart the Runtime Fabric agent to pick up the change
Prerequisites
Before we start, we need:- A Kubernetes cluster with Runtime Fabric installed. For a quick test, check out our previous post on How to Install Mulesoft Runtime Fabric on K3s
- SSH access to that server
kubectlinstalled and configured on the server- A new
.licfile from the MuleSoft Support Portal - The namespace where Runtime Fabric is installed (commonly
rtf)
kubectl get namespaces
rtf in the list. If our namespace is different, we substitute it in every command below.We’ll also confirm Runtime Fabric is installed and check its current status:
kubectl get pods -n rtf
Step 1 — Upload the License File to the Server
We have three options to get the.lic file onto our Ubuntu server.Option A — Upload with scp (Secure Copy)
scp copies files over SSH. We run this from our laptop:
scp /path/to/muleSoft.lic ubuntu@<SERVER_IP>:/home/ubuntu/
<SERVER_IP> with our server's IP address. Replace /path/to/muleSoft.lic with the actual path to the file on our laptop.If your K8s server is on AWS you’d probably need to include the pem file for ssh connections. In that case use the following:
scp -i <your_pem_file> /path/to/muleSoft.lic ubuntu@<SERVER_IP>:/home/ubuntu/
We verify the file arrived:
ssh ubuntu@<SERVER_IP> "ls -lh /home/ubuntu/muleSoft.lic"
Option B — Upload with SFTP
Some teams prefer SFTP clients like FileZilla or WinSCP. We connect to our server using its IP, port22, and our SSH credentials. We drag the .lic file into the /home/ubuntu/ directory on the server.This option works well when our laptop is on Windows or when our team is not comfortable with command-line transfers.
Option C — Download Directly on the Server
If our server has outbound internet access, we can download the file directly from the MuleSoft Support Portal.We log into the portal and copy the download URL for our license file. Then on the server:
wget -O /home/ubuntu/muleSoft.lic "https://<DOWNLOAD_URL>"
curl:curl -L -o /home/ubuntu/muleSoft.lic "https://<DOWNLOAD_URL>"
ls -lh /home/ubuntu/muleSoft.lic
Step 2 — Encode the License in Base64 on the Server
Why Base64? Kubernetes Secrets store binary and text data as Base64 strings. We must encode our.lic file before we can create a secret from it.Why on the server? Encoding on our laptop and copying the string introduces formatting risks. Line breaks or encoding differences between operating systems corrupt the secret. We always encode on the server where we apply it.
We SSH into our server:
We encode the file and save the output to a variable:
The
We SSH into our server:
ssh ubuntu@<SERVER_IP>
We encode the file and save the output to a variable:
LICENSE_B64=$(base64 -w 0 /home/ubuntu/muleSoft.lic)
-w 0 flag disables line wrapping. Kubernetes requires the Base64 string on a single line. Without this flag, base64 wraps at 76 characters and breaks the secret.We confirm the variable is not empty:
We should see a long string of letters and numbers. If the output is blank, the file upload in Step 1 failed. We go back and repeat it.
We first confirm the secret exists:
Expected output:
If you don’t find it, check the name of the secrets in the rtf namespace to get the specific name of the secret
echo $LICENSE_B64 | head -c 100
Step 3 — Remove the Expired License Secret
Runtime Fabric stores the license in a Kubernetes Secret namedmule-license. We delete it before creating the replacement.We first confirm the secret exists:
kubectl get secret rtf-muleruntime-license -n rtf
NAME TYPE DATA AGE
mule-license Opaque 1 365d
kubectl get secrets -n rtf
We delete it:
Expected output:
Note: Deleting the secret does not immediately stop running applications. The pods that already loaded the license continue running. The new secret takes effect after we restart the agent in Step 5.
We verify the secret was created:
Expected output:
We also do a quick sanity check to confirm the secret contains data:
The output should be a number greater than zero.
We find the agent pod:
kubectl delete secret rtf-muleruntime-license -n rtf
secret "rtf-muleruntime-license" deleted
Step 4 — Create the New License Secret
We create a new Kubernetes Secret using our encoded license string:kubectl create secret generic rtf-muleruntime-license \
--from-literal=license="$LICENSE_B64" \
-n rtf
kubectl get secret rtf-muleruntime-license -n rtf
NAME. TYPE DATA AGE
rtf-muleruntime-license Opaque 1 5s
kubectl get secret rtf-muleruntime-license -n rtf -o jsonpath='{.data.license}' | wc -cStep 5 — Restart the Runtime Fabric Agent
The Runtime Fabric agent reads the license at startup. We must restart it to load the new secret.We find the agent pod:
kubectl get pods -n rtf
We look for a pod named something like
Expected output:
We watch the rollout complete:
Expected output:
All pods should show
rtf-agent-xxxxxxxxx-xxxxx. Then we restart the deployment:kubectl rollout restart deployment/agent -n rtf
deployment.apps/agent restarted
kubectl rollout status deployment/agent -n rtf
deployment "rtf-agent" successfully rolled out
Step 6 — Verify the License Is Active
We check that the new agent pod is running:kubectl get pods -n rtf
Running status. Check the AGE value for the rtf agent. You’ll see also that the name of the agent pod has changed
We also check the agent logs for license confirmation:
kubectl logs -n rtf agent-5dc78f9b4b-sjfhz -c rtfd | grep -i license
We look for lines that confirm the license loaded successfully. If we see error messages about an invalid or expired license, we go back to Step 2 and re-encode the file. The most common cause of failure is a corrupted Base64 string.
We can also verify from Anypoint Platform. We log into Runtime Manager, navigate to Runtime Fabric, and open our fabric instance. The status should show healthy.
Troubleshooting
The agent pod is in CrashLoopBackOff
We read the pod logs:
kubectl logs deployment/rtf-agent -n rtf --previous
-w 0 flag, and re-create the secret.The secret was created but the status in Anypoint shows expired
We confirm the secret key name is exactly license (lowercase):
kubectl get secret rtf-muleruntime-license -n rtf -o yaml
data:, we must see license: as the key. If the key name is wrong, we delete the secret and re-create it using the exact command in Step 4.We do not know the correct namespace
We search for the existing secret across all namespaces:
kubectl get secret mule-license --all-namespaces
Summary
| Step | Action |
|---|---|
| 1 | Upload .lic file to the Ubuntu server |
| 2 | Encode the file in Base64 on the server with -w 0 |
| 3 | Delete the old mule-license secret in Kubernetes |
| 4 | Create a new secret with the encoded value |
| 5 | Restart the rtf-agent deployment |
| 6 | Verify agent status and license in Anypoint |
The full process takes less than ten minutes. The critical rule to remember: always encode on the server, always use
In the next post, if you installed your RTF with Helm, we’ll see how to do it with Helm.
-w 0, and always verify the secret is non-empty before restarting the agent.In the next post, if you installed your RTF with Helm, we’ll see how to do it with Helm.