---
schema_version: "1"
id: a9dacf17b6ce4c6ddce460572a20c7faf1a15bf35ecda73de91b57c244931d86
title: Installing Runtime Fabric Using RTFCTL
collection: mulesoft
version: current
locale: en-us
portal_url: https://docs.salesforce.com/mulesoft/current/en-us/runtime-fabric/2.9/install-self-managed.md
canonical_url: https://docs.mulesoft.com/runtime-fabric/2.9/install-self-managed
source_site: docs.mulesoft.com
content_type: documentation
content_hash: 2f94e9511b98c3c2abca9ef4810b7ab3e9b25d9eb7cb0cb56ba15d80629d4d9c
description: MuleSoft Documentation Site
release: "2.9"
latest: false
---
---
product: Runtime Fabric
version: 2.9
---

# Installing Runtime Fabric Using RTFCTL

> For the full documentation index, see: https://docs.mulesoft.com/llms.txt

You can use the Runtime Fabric command line tool, `rtfctl`, to install Anypoint Runtime Fabric on an
Amazon Elastic Kubernetes Service (Amazon EKS), Amazon Elastic Kubernetes Service Anywhere (Amazon
EKS-A), Azure Kubernetes Service (AKS), Alibaba Cloud Container Service for Kubernetes (ACK), Google
Kubernetes Engine (GKE), Rancher Kubernetes Engine (RKE) installation that you manage.

> [!NOTE] Runtime Fabric versions 2.2.5 or later that support multiple instances require `rtfctl`
> version 0.4.1 or later.

> [!NOTE] `rtfctl` always installs the latest version of Runtime Fabric agent.

Refer to [scalability benchmarking](https://docs.mulesoft.com/runtime-fabric/2.9/rtf-scale) to review the limits for `rtfctl`\-based deployments.
For larger deployments, use Helm-based Runtime Fabric deployments so you can allocate additional
resources to the agent for optimal performance.

## Before you Begin

Before installing Anypoint Runtime Fabric in a Kubernetes environment, ensure:

- You have reviewed the architecture and requirements outlined in [Runtime Fabric](https://docs.mulesoft.com/runtime-fabric/2.9/)

- You have
  [configured your network to support Runtime Fabric](https://docs.mulesoft.com/runtime-fabric/2.9/install-self-managed-network-configuration)

- You have installed and configured your Kubernetes environment with:

  - An ACK, AKS, EKS, EKS-A, GKE, or RKE Kubernetes environment. Other Kubernetes environments are
    not supported.

  - A supported Kubernetes version.

  - An ingress controller to send external requests to applications.

- You create your clusters using the latest Runtime Fabric agent version available. If you can’t do
  so, refer to
  [How to Specify the RTF Agent Version in Upgrades](https://help.salesforce.com/s/articleView?id=001117134&type=1).

> [!IMPORTANT]
>
> - If you want to use a local registry with Runtime Fabric, follow the installation instructions in
>   [Using a Local Registry with Runtime Fabric](https://docs.mulesoft.com/runtime-fabric/2.9/configure-local-registry). You must set up the
>   local registry during installation.

## RTFCTL Versions Compatibility

The following tables list the `rtfctl` versions compatibility with Runtime Fabric appliance 1.x.x
agent versions and Runtime Fabric self-managed 2.x.x agent versions.

### Runtime Fabric Appliance 1.x.x

The following `rtfctl` versions are compatible with all supported Runtime Fabric agents on appliance
clusters:

<table><colgroup><col> <col></colgroup><thead><tr><th>RTF appliance 1.x.x agent version</th><th><code>rtfctl</code> version</th></tr></thead><tbody><tr><td><p>All versions</p></td><td><p>0.6.0-2.release-gravity</p></td></tr><tr><td><p>All versions</p></td><td><p>0.5.2-4.release-gravity</p></td></tr><tr><td><p>All versions</p></td><td><p>0.3.87 to 0.4.22</p></td></tr></tbody></table>

### Runtime Fabric Self-Managed (BYOK) 2.x.x

The following `rtfctl` versions are compatible with Runtime Fabric agents in self-managed Kubernetes
clusters:

<table><colgroup><col> <col></colgroup><thead><tr><th>RTF self-managed 2.x.x agent version</th><th><code>rtfctl</code> version</th></tr></thead><tbody><tr><td><p>2.7.0</p></td><td><p>1.0.79 or later</p></td></tr><tr><td><p>2.6.52</p></td><td><p>0.4.1 or later</p></td></tr><tr><td><p>2.6.42</p></td><td><p>0.4.1 or later</p></td></tr><tr><td><p>2.6.23</p></td><td><p>0.4.1 or later</p></td></tr><tr><td><p>2.6.22</p></td><td><p>0.4.1 or later</p></td></tr><tr><td><p>2.6.2</p></td><td><p>0.4.1 or later</p></td></tr><tr><td><p>2.5.0</p></td><td><p>0.4.1 or later</p></td></tr><tr><td><p>2.4.45</p></td><td><p>0.4.1 or later</p></td></tr><tr><td><p>2.4.0</p></td><td><p>0.4.1 or later</p></td></tr><tr><td><p>2.3.34</p></td><td><p>0.4.1 or later</p></td></tr><tr><td><p>2.3.1</p></td><td><p>0.4.1 or later</p></td></tr><tr><td><p>2.2.5</p></td><td><p>0.4.1 or later</p></td></tr><tr><td><p>2.1.30</p></td><td><p>0.3.87 to 1.0.12</p></td></tr><tr><td><p>2.1.0</p></td><td><p>0.3.87 to 1.0.12</p></td></tr><tr><td><p>2.0.0</p></td><td><p>0.3.87 to 1.0.12</p></td></tr></tbody></table>

## Create a Runtime Fabric using Runtime Manager

To install Runtime Fabric, first create a Runtime Fabric using Runtime Manager. This is required to
obtain the activation data which is needed during installation.

1.  From Anypoint Platform, select Runtime Manager.

2.  Click **Runtime Fabrics**.

3.  Click **Create Runtime Fabric**.

4.  Enter the name of the new Runtime Fabric, then select one of the following options:

    - Amazon Elastic Kubernetes Service

    - Azure Kubernetes Service

    - Google Kubernetes Engine

5.  Click **Next**.

6.  Click **rtfctl**.

7.  Review the **Support responsibility** disclaimer, then if you agree click **Accept**.

    Runtime Manager creates the Runtime Fabric and displays the Activation State page. This page
    displays the activation data used to install Runtime Fabric on a Kubernetes service. Copy this
    data to the clipboard for use in the next section.

When creating the Runtime Fabric, the business unit you choose is set as the owner business unit.
This business unit is referenced in usage reports for reporting allocated cluster capacity. Ensure
that you select the correct business unit during installation.

## Download the rtfctl Utility

Runtime Fabric uses the `rtfctl` command-line utility for installation and management tasks. See
[Install the Runtime Fabric Command Line Tool](https://docs.mulesoft.com/runtime-fabric/2.9/install-rtfctl).

1.  Download the `rtfctl` command-line utility:

    `rtfctl` is supported on Windows, MacOS (Darwin), and Linux. Choose the appropriate method:

    - Windows

      ```copy
      curl -L https://anypoint.mulesoft.com/runtimefabric/api/download/rtfctl-windows/latest -o rtfctl.exe
      ```

    - MacOS (Darwin)

      ```copy
      curl -L https://anypoint.mulesoft.com/runtimefabric/api/download/rtfctl-darwin/latest -o rtfctl
      ```

    - Linux

      ```copy
      curl -L https://anypoint.mulesoft.com/runtimefabric/api/download/rtfctl/latest -o rtfctl
      ```

2.  Change file permissions for the `rtfctl` command-line utility:

    ```copy
    chmod +x rtfctl
    ```

## Install Runtime Fabric

After creating a Runtime Fabric in Runtime Manager and obtaining the activation data, install
Runtime Fabric into your Kubernetes service using the `rtfctl` command-line utility.

If your Kubernetes configuration is not located in the `\~/.kube/config` directory, set the
`KUBECONFIG` environment variable before running `rtfctl`:

```copy
export KUBECONFIG=<path-to-kubeconfig>
```

1.  Validate that your Kubernetes environment is ready for installation:

    ```copy
    rtfctl validate <activation_data>
    ```

    The `validate` option verifies that:

    - The Kubernetes environment is running.

    - All required components exist.

    - All required services are available.

      The `rtfctl` command-line utility outputs any incompatibilities with the Kubernetes
      environment.

2.  Install Runtime Fabric:

    ```copy
    rtfctl install <activation_data>
    ```

    `<activation_data>` is the activation data obtained after creating the Runtime Fabric using
    Runtime Manager. During installation, the `rtfctl` utility displays any errors encountered.

For private registry installations, add the `--cluster-ops-image` flag and select the image version
as per the release notes of the agent version to install:

```copy
rtfctl install <ACTIVATION_DATA> --cluster-ops-image <local-reg-host>/mulesoft/rtf-cluster-ops:<version-here>
```

## Insert the Mule License Key

If you didn’t add the Mule license key during install, you can add it using the `rtfctl` command
line utility or Helm.

Before you install the license key, encode it to Base64 format.

### Encode the License Key

- On MacOS, run the following command:

  ```copy
  base64 -b 0 -i <license-file>
  ```

- On Unix, run the following command:

  ```copy
  base64 -w0 <license-file>
  ```

- On Windows, choose one of the following:

  - Use a WSL or Cygwin shell that includes the base64 tool and use the above Unix command.

  - Use the base64.exe program included with Windows git (C:\\Program Files\\Git\\usr\\bin).

  - Use the following Powershell command:

    ```copy
    $BASE64_ENCODED_LICENSE=[convert]::ToBase64String((Get-Content -path "license.lic" -Encoding byte))
    ```

### Apply the License Key Using rtfctl

1.  On the controller node acting as the leader during installation (the installer node), run the
    following command:

    ```copy
    rtfctl apply mule-license $BASE64_ENCODED_LICENSE
    ```

    You can also apply the Mule license providing the file path directly:

    ```copy
    rtfctl apply mule-license --file /path/to/license.lic
    ```

    > [!NOTE] Any value used with `rtfcl apply` updates does not work for OpenShift. You have to
    > update the values in the OpenShift console.

2.  To verify the Mule license key has applied correctly, run:

    ```copy
    rtfctl get mule-license
    ```

### Apply the License Key Using Helm

To apply the license using Helm, run the following command:

```copy
helm upgrade runtime-fabric rtf/rtf-agent --set muleLicense=$BASE64_ENCODED_LICENSE -n rtf --reuse-values --version <current-version>
```

## Configure the Ingress Resource Template

If your ingress controller requires custom annotations and ingress class definition, follow the
instructions in [Defining a Custom Ingress Configuration](https://docs.mulesoft.com/runtime-fabric/2.9/custom-ingress-configuration).

> [!NOTE] For GKE customers, the ingress controller included with GKE will provision a separate HTTP
> load balancer per application by default. Please read this link:
> [KB article](https://help.salesforce.com/s/articleView?id=001116839&type=1) for more details.

## Validate Your Runtime Fabric

After completing the installation, your Runtime Fabric should be activated within your Anypoint
organization. To validate your installation, go to Anypoint Runtime Manager and confirm that the
status of the Runtime Fabric is `Active`.

Before deploying an application to your Runtime Fabric:

1.  Associate the Runtime Fabric with at least one Anypoint environment.

2.  Review and update the Inbound Traffic settings based upon your Kubernetes environment.

3.  Deploy an application to verify that Runtime Fabric is installed and configured correctly.

## Perform a Rollback

To roll back to a previous version of Runtime Fabric trigerred automatically on failed upgrade,
refer to the
[How to Specify the RTF Agent Version in Upgrades](https://help.salesforce.com/s/articleView?id=001117134&type=1)
Knowledge base article for details.

## See Also

- [Runtime Fabric Overview](https://docs.mulesoft.com/runtime-fabric/2.9/)

- [Configure Ingress for Runtime Fabric](https://docs.mulesoft.com/runtime-fabric/2.9/custom-ingress-configuration)

- [Deploy a Mule Application to Runtime Fabric](https://docs.mulesoft.com/runtime-fabric/2.9/deploy-to-runtime-fabric)