Contact Us 1-800-596-4880
  1. Homepage
  2. Runtime Fabric (1.13)
  3. Managing Runtime Fabric

  4. Using the Runtime Fabric Command Line Tool

Using the Runtime Fabric Command Line Tool

Install and use the rtfctl command line tool to locally manage Runtime Fabrics. The rtfctl tool supports the following actions:

  • Get the status of a Runtime Fabric.

  • Perform a heap dump or a thread dump of a running application.

  • Display memory usage of a running application.

  • Manage proxy settings.

  • Manage secure properties.

  • Manage a Mule license.

  • Manage the alert sender email address.

Install rtfctl

The tasks in the section must be performed by an IT administrator.

If you’re using Runtime Fabric on Self-Managed Kubernetes for AKS and have the AKS-managed Azure AD integration enabled, the following command returns the credentials needed to run rtfctl commands:

az aks get-credentials --name <NAME> --resource-group <RESOURCE_GROUP> --admin

For Runtime Fabric on Self-Managed Kubernetes:

  1. Download the rtfctl command-line tool:

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

    • Windows

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

    • MacOS (Darwin)

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

    • Linux

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

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

    sudo chmod +x rtfctl

For Runtime Fabric appliance:

  1. Download the rtfctl command-line tool:

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

    • Windows

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

    • MacOS (Darwin)

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

    • Linux

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

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

    sudo chmod +x rtfctl

Running Commands

For Runtime Fabric on VMs / Bare Metal, you must run rtfctl from a controller node. The rtfctl binary is in directory /opt/anypoint/runtimefabric/`. Confirm that the current working directory is also /opt/anypoint/runtimefabric/. The tool detects the required configuration to manage the cluster.

For Runtime Fabric on Self-Managed Kubernetes, rtfctl consumes kubeconfig files as described in Organizing Cluster Access Using kubeconfig Files. Use this method to configure which cluster you want to manage. Confirm that the rtfctl binary is present in the current working directory and in the user $PATH.

  • Run rtfctl commands as a privileged user.

  • To list all supported commands, run rtfctl -h.

  • For more information about a specific command, run rtfctl <command> -h.

Checking for Proxy Settings

When you run commands, rtfctl checks for any proxy settings in your environment. The tool looks for a NO_PROXY key (in upper case) and will accept a no_proxy key (in lower case) if NO_PROXY is not used. If both keys are present, rtfctl uses NO_PROXY. The rtfctl tool sets the key in your local Kubernetes context to honor your proxy settings.

Commands for Managing the Runtime Fabric Appliance

Use the following commands to manage the Runtime Fabric Appliance.

These commands are for Runtime Fabric on VMs / Bare Metal only.

appliance

Performs operations on the Runtime Fabric appliance

  • Applies alert sender email

    rtfctl appliance apply alert-smtp-from "<sender>@<domain>.com"

  • Renews an expired client certificate by downloading the certificate bundle

    rtfctl appliance renew-expired-client-cert --auth 'Bearer <YOUR ANYPOINT AUTHORIZATION TOKEN>' --url 'https://anypoint.mulesoft.com/runtimefabric/api/organizations/<org-id>/fabrics/<fabric-id>/certificate-bundle'

  • Renews an expired client certificate using a pre-downloaded package

    rtfctl appliance renew-expired-client-cert --file <cert-bundle-filename>

  • Reinstalls Runtime Fabric components using the latest scripts

    rtfctl appliance reinstall

  • Reinstalls Runtime Fabric components without downloading the latest scripts

    rtfctl appliance reinstall --skip-download

  • Generates an appliance diagnostics report

    rtfctl appliance report --file <filename>.tar.gz

  • Performs rollback to the existing version after a failed appliance upgrade

    rtfctl appliance rollback

  • Lists rollback steps without executing the rollback

    rtfctl appliance rollback --dry-run

  • Performs rollback to the existing version after a failed appliance upgrade without prompting for confirmation

    rtfctl appliance rollback --confirm

  • Upgrades the cluster using a pre-downloaded package

    rtfctl appliance upgrade --file runtimefabric-<VERSION>.tar.gz

  • Upgrades the cluster by downloading a package

    rtfctl appliance upgrade --url https://<host>/<path-to-installer-package>

Commands for Configuring Runtime Fabric

Use the following commands to configure Runtime Fabric.

Command Description

apply

Applies changes to a Runtime Fabric configuration

update

Updates rtfctl

wait

Waits for Runtime Fabric components to become ready

apply

Applies changes to a Runtime Fabric configuration.

  • Applies an HTTP proxy configuration

    rtfctl apply http-proxy http://<domain>:<port>

  • Applies an HTTP proxy configuration with hostnames bypassing the proxy

    rtfctl apply http-proxy http://<domain>:<port> --no-proxy "DOMAIN.com,DOMAIN2.com"

  • Applies an HTTP proxy configuration with authentication

    rtfctl apply http-proxy http://username:password@<domain>.com:<port>

  • Clears an HTTP proxy configuration

    rtfctl apply http-proxy "" --no-proxy ""

  • Applies an ingress configMap for a specific pod

    For Runtime Fabric on Self-Managed Kubernertes versions 1.8 and 1.9 only

    		 
    rtfctl apply ingress-configmap "/<pod>/<path-to-configMap.yaml>"`

  • Applies a secure property

    rtfctl apply secure-property --key <key> --value <value> -n <environment>

  • Applies a system configuration on a host node

    rtfctl apply system-configuration

  • Applies a system configuration on a host node without downloading the latest scripts

    rtfctl apply system-configuration --skip-download

  • Applies a Mule license

    rtfctl apply mule-license '<BASE64-encoded-license>'

  • Applies a monitoring proxy

    rtfctl apply monitoring-proxy "socks5://<username>:<password>@<monitoring-URL>:<PORT>"`

  • Clears a monitoring proxy configuration

    rtfctl apply monitoring-proxy ""

update

Updates rtfctl.

  • Updates from the US control plane

    rtfctl update

  • Updates rtfctl from the EU control plane

    rtfctl update --host eu1.anypoint.mulesoft.com

wait

Waits for Runtime Fabric components to become ready

  • Specifies the number of seconds to wait

rtfctl wait <value in seconds>

  • Specifies the number of seconds to pass before timing out the wait (Default is 600 seconds)

rtfctl wait --timeout <value in seconds>

Commands for Installing and Upgrading Runtime Fabric

Use the following commands when installing or upgrading Runtime Fabric, or when performing a back up or restore.

Command Description

install

Installs Runtime Fabric

backup

Performs a back up of the local Runtime Fabric state

restore

Restores local Runtime Fabric state from a backup

validate

Validates the cluster for Runtime Fabric installation

version

Displays the Runtime Fabric version information

install

  • Installs Runtime Fabric

rtfctl install <activation data>

  • Override the Docker image registry URL and secret

    rtfctl install <activation data> --image-pull-registry <string>  --image-pull-secret <string>

backup

Performs a back up of the local Runtime Fabric state.

rtfctl backup /var/backups/<backup-filename>.tar.gz

restore

Restores the local Runtime Fabric state from a backup

rtfctl restore /var/backups/<filename>.tar.gz

validate

Validates the cluster for a Runtime Fabric installation

  • Performs a validation check

    rtfctl validate <activation-data>

  • Performs a validation check and passes the fabric.tf configuration file that contains proxy settings

    rtfctl validate -f <path-to-settings-file>

    To validate installation with a proxy, you must specify proxy settings in your settings file:

MULE_LICENSE=<your-mule-license>
ACTIVATION_DATA=<activation-data>
HTTP_PROXY=http://proxy-domain.com:<port>

version

Displays the Runtime Fabric version information

rtfctl version

Commands for Managing Applications on Runtime Fabric

Use the following commands to manage applications deployed to Runtime Fabric.

Command Description

delete

Deletes a secure property

describe

Displays details for an application

disk

Displays disk usage for an application

memory

Displays the JVM memory usage in a pod

package

Creates a debugging information package for an application

restart

Restarts an application

heapdump

Captures a JVM heap dump

threaddump

Captures a JVM thread dump

delete

Deletes a secure property

rtfctl delete secure-property <sample-key> -n <sample-app-namespace>

describe

Displays details for an application in a specific namespace

rtfctl describe app <app-name> --namespace <namespace>

disk

Displays disk usage for an application

  • Displays the disk usage for an application, using the first replica by default

    rtfctl disk <app-name>

  • Displays the disk usage for an application, using a specific replica

    rtfctl disk <app-name> --details --pod <replica-name>

memory

Displays the JVM memory usage in a pod

  • Gets the JVM memory for each replica

    rtfctl memory <app-name>

  • Gets the JVM memory for a particular replica

    rtfctl memory <app-name> --pod <app-name>-pod-1

package

Creates a debugging information package for an application

  • Creates a package for an application using the first pod by default

    rtfctl package <app-name> <path-to-file>

  • Creates a package for an application containing the apps, policies, and .mule directories

    rtfctl package <app-name> <path-to-file> --apps --policies --dotmule

  • Creates a package for an application containing a heap dump

    rtfctl package <app-name> <path-to-file> --heap-dump

restart

Restarts an application

rtfctl restart my-app

heapdump

Triggers a JVM heap dump

  • Performs a JVM heap dump for an application, saving it as `/tmp/dump.hprof, using the first replica by default

    rtfctl heapdump <app-name> /tmp/dump.hprof

  • Performs a JVM heap dump for an application, saving it as /tmp/dump.hprof, using a specific replica

    rtfctl heapdump <app-name> /tmp/dump.hprof --pod <replica-name>

threaddump

Triggers a JVM threaddump

  • Performs a JVM thread dump for an application using the first replica by default

    rtfctl threaddump <app-name>

  • Performs a JVM thread dump for an application using a specific replica

    rtfctl threaddump <app-name>p --pod <replica-name>

Commands for Troubleshooting Runtime Fabric

Use the following commands to troubleshoot Runtime Fabric.

Command Description

get

Displays one or more resources

ping

Tests network connectivity

report

Generates a diagnostics report

status

Displays the status of Runtime Fabric

test

Verifies outbound network connectivity to the Runtime Fabric control plane

get

Displays one or more resources

  • Prints a list of all applications in all environments

    rtfctl get apps

  • Prints a list of all applications in a specific environment

    rtfctl get apps --namespace <environment>

  • Displays an HTTP proxy configurations

    rtfctl get http-proxy

  • Displays a monitoring proxy configuration

    rtfctl get monitoring-proxy

  • Displays secure properties

    rtfctl get secure-properties

  • Displays the Mule license

    rtfctl get mule-license

  • Displays Runtime Fabric registry credentials

    rtfctl get registry-credentials <activation data>

ping

Tests network connectivity

  • Pings example.com from inside an application, using the first replica by default

    rtfctl ping <app-name> example.com

  • Attempts to connect to example.com on port 12345 from inside an application, using the first replica by default

    rtfctl ping <app-name> --port 12345

report

Generates a diagnostics report at rtf-report.tar.gz

rtfctl report --file <filename>.tar.gz

status

Displays the status of Runtime Fabric

  • Displays status output in JSON

    rtfctl status --output json

  • Checks Kubernetes DNS health

    rtfctl status dns-check --<node-label> "<k>:<v>"

test

Verifies outbound network connectivity to the Runtime Fabric control plane.

  • Schedules a check on any nodes

    rtfctl test outbound-network

  • Schedules a check the nodes satisfying the node-label parameter

    rtfctl test outbound-network --<node-label> "<k>:<v>"

  • Schedules a check on all nodes

    rtfctl test outbound-network --all

Usage

Install a Mule license

  1. Make sure to base64 encode the license, following the instructions in Base64 Encode your Mule License Key.

  2. Run the following command:

    $ sudo ./rtfctl apply mule-license '<license-key-information>'
Updating rtf namespace... OK

Capture a Heap Dump

$ sudo /usr/local/bin/rtfctl heapdump hello-world /tmp/dump.hprof
Dumping heap for hello-world-f76484d8-l44qv...
Heap dump written to /tmp/dump.hprof

For additional information, run the rtfctl heapdump -h command.

Working with Multiple Replicas

For application management commands that accept a --pod flag, you can obtain the list of replicas using the describe command:

$ sudo ./rtfctl describe apps hello-world --namespace bed42b62-XXXX
Name:              hello-world
Namespace:         bed42b62-XXXX
Status:            PROGRESSING
Runtime:           2
ID:
Version:
Organization ID:   d30f74c0-XXXX
Replicas:          1 desired | 1 updated | 1 total | 0 available | 1 unavailable

  Name                             Status
  ----                             ------
  hello-world-77f5897949-z54gb   Pending

Understanding rtfctl Output

The rtfctl command line tool commonly calls other applications and system tools, and the output of those calls is sent to standard output and standard error output. This output is written in the context of each operation performed.

The rtfctl command line tool includes a last output line on the most verbose commands to make it clear whether the operation succeed or failed. Normal operation may include some intermediate failure messages, such as when a stopped system unit is attempted to be stopped again.

If you are in doubt about whether a message represents a problem or not, discuss it with your system administrator or contact MuleSoft support.

See Also