Renew Self-Managed Flex Gateway Registration | MuleSoft Documentation
# Renew Self-Managed Flex Gateway Registration
Anypoint Flex Gateway uses a managed PKI certificate to communicate with Anypoint Platform. This certificate is generated when you register Flex Gateway in either Connected Mode or Local Mode. Updating the certificate ensures the continued operation of your applications.
You update a certificate by renewing registration via the `flexctl registration renew` command.
  * The `renew` command renews an existing Flex Gateway registration with Runtime Manager.
  * For authentication, you run the `renew` command with either user credentials or with connected app credentials. Authentication with user credentials requires the `--username` and `--password` flags. Authentication with connected app credentials requires the `--client-id` and `--client-secret` flags.


You verify the renewal process via the `flexctl registration inspect` command.
  * The `inspect` command extracts registration information you can use to verify whether the `renew` command was successful.
  * You can also use the `inspect` command to first determine if renewing registration is actually required. The `inspect` command returns the certificate expiration date.
  * You can verify (inspect) renewal by using the default method, or you can specify your existing registration file. If you run the `inspect` command without flags, the command inspects registration status by using the default method.


To avoid disruptions:
  1. Download the latest version of Flex Gateway.
  2. Renew your Flex Gateway registration.
Choose one of two methods:
     * Anypoint Platform User Credentials
     * Connected App Credentials
  3. Verify the success of the renewal process.
Choose one of two methods:
     *      * Registration File


## Before You Begin
To invoke the registration renewal `flexctl` command, download the latest version of Flex Gateway. You don’t need to register and run this version of the gateway.
  * Downloading Flex Gateway


## Renew Registration with Anypoint Platform User Credentials
  1. Create a new directory called `flex-renew-registration` (or similar). You run the `renew` command in this new directory. The command creates a new registration file.
Registration renewal fails if the `renew` command is run in a directory containing an existing registration file.  
---  
  2. Use the following command:
     * Linux
     * Docker
     * Podman
```
flexctl registration renew --username=<your-username> --password=<your-password> \
 <path-to-registration-file>
```

Replace `<your-username>` and `<your-password>` with Anypoint Platform user credentials.
Replace `<path-to-registration-file>` with the path and filename of the existing `registration.yaml` file.
Use `sudo` if you encounter file permission issues when running this command.
For Flex Gateway running in a container, invoke `renew` as part of the container `run` command.
```
docker run --entrypoint flexctl \
-v "$(pwd)":/renew \
-v <path-to-registration-directory>:/registration \
-u $UID mulesoft/flex-gateway \
registration renew \
--username=<your-username> \
--password=<your-password> \
--output-directory=/renew \
<path-to-registration-file-in-container>
```

Replace `<your-username>` and `<your-password>` with Anypoint Platform user credentials.
Replace `<path-to-registration-file-in-container>` with the path and filename of the existing `registration.yaml` file. You must specify the file in the container file system, which in this case is `/registration/registration.yaml`.
As an example, if `/home/user/flex/registration.yaml` contains your current registration file, navigate to `/home/user/flex/` and run the following command with your Anypoint Platform credentials:
```
docker run --entrypoint flexctl \
-u $UID -v "$(pwd)":/registration \
mulesoft/flex-gateway \
registration renew \
--username=<your-username> \
--password=<your-password> \
--output-directory=/registration/new \
/registration/registration.yaml
```

The command creates a new registration file: `/home/user/flex/new/registration.yaml`.
For Flex Gateway running in a container, invoke `renew` as part of the container `run` command.
```
podman run --entrypoint flexctl --userns=keep-id \
-v "$(pwd)":/renew:Z \
-v <path-to-registration-directory>:/registration:Z \
-u $UID docker.io/mulesoft/flex-gateway \
registration renew \
--username=<your-username> \
--password=<your-password> \
--output-directory=/renew \
<path-to-registration-file-in-container>
```

Replace `<your-username>` and `<your-password>` with Anypoint Platform user credentials.
Replace `<path-to-registration-file-in-container>` with the path and filename of the existing `registration.yaml` file. You must specify the file in the container file system, which in this case is `/registration/registration.yaml`.
Disable MFA for your Anypoint Platform account prior to running the `renew` command with user credentials.  
---  
  3. Run the command.
The output should include the message:
```
Registration renewal completed
```

  4. Copy the newly created registration file to the runtime registration file location. For example:
`/usr/local/share/mulesoft/flex-gateway/conf.d/registration.yaml`
  5. Restart the Flex Gateway replica if one is already running.


## Renew Registration with Connected App Credentials
  1. If you don’t have a username or password for Anypoint Platform, you can configure a connected app via Anypoint Access Management.
    1. Include the following scopes:
       * Read Servers
       * Manage Servers
       * View Organization
    2. Save the **Id** and **Secret** of the connected app you configure, then use these credentials in the `renew` command.
  2. Create a new directory called `flex-renew-registration` (or similar). You run the `renew` command in this new directory. The command creates a new registration file.
Registration renewal fails if the `renew` command is run in a directory containing an existing registration file.  
---  
  3. Use the following command:
     * Linux
     * Docker
     * Podman
```
flexctl registration renew --client-id=<your-client-id> --client-secret=<your-client-secret> \
 <path-to-registration-file>
```

Replace `<your-client-id>` and `<your-client-secret>` with the connected app credentials.
Replace `<path-to-registration-file>` with the path and filename of the existing `registration.yaml` file.
Use `sudo` if you encounter file permission issues when running this command.
For Flex Gateway running in a container, invoke `renew` as part of the container `run` command.
```
docker run --entrypoint flexctl \
-v "$(pwd)":/renew \
-v <path-to-registration-directory>:/registration \
-u $UID mulesoft/flex-gateway \
registration renew \
--client-id=<your-client-id> \
--client-secret=<your-client-secret> \
--output-directory=/renew \
<path-to-registration-file-in-container>
```

Replace `<your-client-id>` and `<your-client-secret>` with the connected app credentials.
Replace `<path-to-registration-file-in-container>` with the path and filename of the existing `registration.yaml` file. You must specify the file in the container file system, which in this case is `/registration/registration.yaml`.
As an example, if `/home/user/flex/registration.yaml` contains your current registration file, navigate to `/home/user/flex/` and run the following command with your connected app credentials:
```
docker run --entrypoint flexctl \
-u $UID -v "$(pwd)":/registration \
mulesoft/flex-gateway \
registration renew \
--client-id=<your-client-id> \
--client-secret=<your-client-secret> \
--output-directory=/registration/new \
/registration/registration.yaml
```

The command creates a new registration file: `/home/user/flex/new/registration.yaml`.
For Flex Gateway running in a container, invoke `renew` as part of the container `run` command.
```
podman run --entrypoint flexctl --userns=keep-id \
-v "$(pwd)":/renew:Z \
-v <path-to-registration-directory>:/registration:Z \
-u $UID docker.io/mulesoft/flex-gateway \
registration renew \
--client-id=<your-client-id> \
--client-secret=<your-client-secret> \
--output-directory=/renew \
<path-to-registration-file-in-container>
```

Replace `<your-client-id>` and `<your-client-secret>` with the connected app credentials.
Replace `<path-to-registration-file-in-container>` with the path and filename of the existing `registration.yaml` file. You must specify the file in the container file system, which in this case is `/registration/registration.yaml`.
  4. Run the command.
The output should include the message:
```
Registration renewal completed
```

  5. Copy the newly created registration file to the runtime registration file location. For example:
`/usr/local/share/mulesoft/flex-gateway/conf.d/registration.yaml`
  6. Restart the Flex Gateway replica if one is already running.


## Verify Registration Status with the Default Method
To inspect a registration, run the following command:
  * Linux
  * Docker
  * Podman


```
flexctl registration inspect
```

Use `sudo` if you encounter file permission issues when running this command.
For Flex Gateway running in a container, run `inspect` as part of the container `exec` command. Replace `<container-name-or-id>` with the running container reference.
```
docker exec -u $UID <container-name-or-id> flexctl registration inspect
```
Replace `<your-client-id>` and `<your-client-secret>` with the connected app credentials.
Replace `<path-to-registration-file-in-container>` with the path and filename of the existing `registration.yaml` file. You must specify the file in the container file system, which in this case is `/registration/registration.yaml`.
  4. Run the command.
The output should include the message:
```
Registration renewal completed
```

  5. Copy the newly created registration file to the runtime registration file location. For example:
`/usr/local/share/mulesoft/flex-gateway/conf.d/registration.yaml`
  6. Restart the Flex Gateway replica if one is already running.


## Verify Registration Status with the Default Method
To inspect a registration, run the following command:
  * Linux
  * Docker
  * Podman


```
flexctl registration inspect
```

Use `sudo` if you encounter file permission issues when running this command.
For Flex Gateway running in a container, run `inspect` as part of the container `exec` command. Replace `<container-name-or-id>` with the running container reference.
```
docker exec -u $UID <container-name-or-id> flexctl registration inspect
```

For Flex Gateway running in a container, run `inspect` as part of the container `exec` command. Replace `<container-name-or-id>` with the running container reference.
```
podman exec -u $UID <container-name-or-id> flexctl registration inspect
```

The output should include the date of certificate expiration. For example:
```
{“expiration_date”: “2025-09-25 19:27:32 +0000 UTC”}
```

## Verify Registration Status with a Registration File
You can inspect a registration by extracting the information from your `registration.yaml` file. Specify the path and filename.
To inspect a registration, run the following command:
  * Linux
  * Docker
  * Podman


```
flexctl registration inspect --file=<path-to-registration-file>
```

Use `sudo` if you encounter file permission issues when running this command.
For Flex Gateway running in a container, invoke `inspect` as part of the container `run` command.
```
docker run --entrypoint flexctl \
-v <path-to-registration-directory>:/registration \
-u $UID mulesoft/flex-gateway \
registration inspect --file=<path-to-registration-file>
```

For Flex Gateway running in a container, invoke `inspect` as part of the container `run` command.
```
podman run --entrypoint flexctl --userns=keep-id \
-v <path-to-registration-directory>:/registration:Z \
-u $UID docker.io/mulesoft/flex-gateway \
registration inspect --file=<path-to-registration-file>
```

The output should include the date of certificate expiration:
```
{“expiration_date”: “2025-09-25 19:27:32 +0000 UTC”}
```

As an example, if your current directory contains the registration file, run the following command:
```
docker run --entrypoint flexctl \
-v "$(pwd)":/registration \
-u $UID mulesoft/flex-gateway \
registration inspect --file=/registration/registration.yaml
```

## Renew Registration for Flex Gateway Running in Kubernetes
The following example describes a scenario where Flex Gateway is installed in a `gateway` namespace with an `ingress` release name, and where registration is stored in the Kubernetes database.
  1. Recover the `registration.yaml` file with the following `kubectl` command:
```
kubectl -n gateway get secret "$(kubectl -n gateway get deployment ingress -o=jsonpath='{.spec.template.spec.volumes[?(@.name=="registration")].secret.secretName}')" -o=jsonpath='{.data.registration\.yaml}' | base64 --decode > registration.yaml
```

The command stores the registration file in `./registration.yaml`.
  2. Run the `flexctl registration renew` command, as described for Docker in previous sections:
     * Renew with Anypoint Platform User Credentials
     * Renew with Connected App Credentials
  3. Upgrade Flex Gateway with the following `helm` command:
```
helm get values -n gateway ingress > values.yaml \
&& helm upgrade -n gateway ingress flex-gateway/flex-gateway --wait -f values.yaml --set-file registration.content=new/registration.yaml
```



## Get Help with the Renewal and Verification Commands
You can run the following `help` commands for information about usage:
  * Renewal
    * Linux
    * Docker
    * Podman
```
flexctl registration renew --help
```

Use `sudo` if you encounter file permission issues when running this command.
For Flex Gateway running in a container, invoke `help` as part of the container `run` command.
```
docker run --entrypoint flexctl mulesoft/flex-gateway registration renew --help
```

For Flex Gateway running in a container, invoke `help` as part of the container `run` command.
```
podman run --entrypoint flexctl docker.io/mulesoft/flex-gateway registration renew --help
```

  * Verification
    * Linux
    * Docker
    * Podman
```
flexctl registration inspect --help
```

Use `sudo` if you encounter file permission issues when running this command.
For Flex Gateway running in a container, invoke `help` as part of the container `run` command.
```
docker run --entrypoint flexctl mulesoft/flex-gateway registration inspect --help
```

For Flex Gateway running in a container, invoke `help` as part of the container `run` command.
```
podman run --entrypoint flexctl docker.io/mulesoft/flex-gateway registration inspect --help
```



## Renew an Expired Registration
Attempting to run Flex Gateway with an expired certificate in Connected Mode results in the following:
  * New replicas fail to download API configurations from Anypoint Platform, thereby becoming unusable. Existing clusters fail to reload.
  * Logs and metrics fail to upload to Anypoint Platform. Troubleshooting using Anypoint Platform is not possible.
  * Metering information fails to upload to Anypoint Platform. MuleSoft is unable to collect or report usage metrics.


Attempting to run Flex Gateway with an expired certificate in Local Mode results in the following:
  * Metering information fails to upload to Anypoint Platform. MuleSoft is unable to collect or report usage metrics.


If a certificate expires, you can still invoke `flexctl registration renew`, which updates the expired certificate.
## See Also
  * Downloading Flex Gateway
  * Registering and Running Flex Gateway in Connected Mode
  * Registering and Running Flex Gateway in Local Mode