> ## Documentation Index
> Fetch the complete documentation index at: https://anaconda.com/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Migrating from Gravity to K3s

export const Danger = ({children}) => {
  return <div class="callout my-4 px-5 py-4 overflow-hidden rounded-2xl flex gap-3 border danger-admonition dark:danger-admonition" data-callout-type="danger">
      <div class="mt-0.5 w-4">
        <svg width="14" height="14" viewBox="0 0 14 14" fill="rgb(239, 68, 68)" xmlns="http://www.w3.org/2000/svg" class="w-4 h-4 text-sky-500" aria-label="Danger">
          <path fill-rule="evenodd" clip-rule="evenodd" d="M7 1.3C10.14 1.3 12.7 3.86 12.7 7C12.7 10.14 10.14 12.7 7 12.7C5.48908 12.6974 4.0408 12.096 2.97241 11.0276C1.90403 9.9592 1.30264 8.51092 1.3 7C1.3 3.86 3.86 1.3 7 1.3ZM7 0C3.14 0 0 3.14 0 7C0 10.86 3.14 14 7 14C10.86 14 14 10.86 14 7C14 3.14 10.86 0 7 0ZM8 3H6V8H8V3ZM8 9H6V11H8V9Z"></path>
        </svg>
      </div>
      <div class="text-sm prose min-w-0 w-full">
        {children}
      </div>
    </div>;
};

noindex: true

Due to the suspension of support for Gravity by Teleport, Anaconda highly recommends that Gravity users migrate to a fully supported, up-to-date Kubernetes implementation. To aid you in the process and make it as painless as possible, Anaconda has developed a migration process that allows you to leave your data in place, meaning your cluster will retain its configurations, projects, deployments, and scheduled jobs.

<Danger>
  Do not uninstall Gravity until you are instructed to do so in the process described below.
</Danger>

## Prerequisites

Before starting the Gravity to K3s migration process, ensure your system meets the following requirements:

* Verify that you have a functioning Gravity cluster running Workbench.
* Verify that you have 300GB disk space available in `var/lib/rancher`.
* Verify that you have SSH access from the control plane node to all agent nodes.

<Tip>
  Anaconda recommends generating a dedicated SSH key distributed across the nodes of the cluster—separate from the one you may use to access the cluster itself—to facilitate passwordless node-to-node access.
</Tip>

* Verify that you have the K3s directory bundle and the image tarball for the latest version of Workbench.
* Verify that Docker or Podman is removed from any VMs where K3s will be installed.
* Verify that your cluster’s SSL certificates are up to date.
* If you have created an `anaconda-persistence` volume, you need the `.yaml` file you wrote containing the `PersistentVolume` and `PersistentVolumeClaim` values. If you don’t have it anymore, [recreate the file before you begin the migration process](../../admin/advanced/nfs#creating-the-volume-list).
* Review the [K3s installation requirements](https://docs.k3s.io/installation/requirements) for your operating system and verify that your virtual machines are prepared to receive K3s:

  * SELinux must be disabled.
  * Anaconda strongly recommends that built-in firewall software is fully disabled during migration. If this is not possible, ensure that [you open the ports listed here](https://docs.k3s.io/installation/requirements#networking).
  * On RHEL/CentOS, the `NetworkManager` service must be disabled:

    ```
    systemctl disable nm-cloud-setup.service nm-cloud-setup.timer
    ```

  <Note>
    If Gravity is already successfully running, it is likely that your system already meets these requirements. Even so, Anaconda strongly encourages you to verify the requirements anyway, *especially* on RHEL.
  </Note>

## Pre-installation

Perform all actions from an administrative account that has `sudo` access on all nodes and a non-zero UID:

1. SSH onto the primary node.

2. Deliver the latest Workbench image tarball and K3s bundle to the primary node.

3. Unpack the K3s bundle and `cd` into the directory that it creates.

4. Remove old installations of conda by running the following command:

   ```sh theme={null}
   rm -rf ~/ae5-conda ~/miniconda3
   ```

5. Install and activate the `ae5_conda` environment by running the following commands:

   ```sh theme={null}
   bash ae5-conda-latest-Linux-x86_64.sh
   source ~/ae5-conda/bin/activate
   ```

   This environment contains all the tools you need to manage Workbench; for more information, see [Administration server](../../environment-prep/byok8s-prep#administration-server).

6. Obtain your current cluster configurations by running the following command:

   ```
   ./extract_config.sh
   ```

   The `extract_config.sh` script produces two files: `helm_values.yaml` and `anaconda-enterprise-certs.json`.

7. Back up your current instance by running the following command:

   ```
   ae_backup.sh
   ```

   The `ae_backup.sh` script produces two timestamped files: `ae5_config_db_<YYYYMMDDHHMM>.tar.gz` and `ae5_data_<YYYYMMDDHHMM>.tar.gz`.

8. Stage the K3s assets by running the following command:

   ```
   ./k3s_preinstall.sh
   ```

   The `k3s_preinstall.sh` script produces two files: `k3s_values.yaml` and `NEXT_STEPS.txt`.

   The preinstallation script is designed to coach you on the necessary actions you need to take to install if your system is not ready. For example, if you do not have your instance backed up, the `k3s_preinstall.sh` script will inform you that the backups are missing and tell you to perform a backup before proceeding. Once the script has completed, it saves the output to the `NEXT_STEPS.txt` file.

   <Note>
     * If you have made an error during the pre-installation process, perform the [pre-installation cleanup commands](./k3s-uninstall#cleaning-up-after-pre-installation). and start over.
     * It is safe to run the `./k3s_preinstall.sh` command as many times as is necessary. No destructive actions are performed on your cluster by running the pre-install script.
   </Note>

9. Verify that all of the files produced by running the pre-installation scripts were successfully generated. If you cannot locate all of the files, stop here and consult your Workbench support team to diagnose the failures and complete pre-installation successfully.

## Installation

The following steps detail the conventional output of what the `k3s_preinstall.sh` script will tell you to do. However, the script makes adjustments to these steps based on your local environment and outputs them to the `NEXT_STEPS.txt` file. *Review the file and, if the output diverges from these instructions, follow the instructions in the file instead.*

1. Log out of the server node, then log back in to pick up the environment changes that were made during the pre-installation process.

2. Pause the application by running the following command:

   ```
   ae_pause.sh
   ```

3. Uninstall Gravity and Workbench by running the following commands on each node, starting with the worker nodes and ending with the control plane node:

   ```sh theme={null}
   sudo gravity system uninstall
   sudo reboot
   ```

   This removes Gravity and the Workbench application from the cluster, but leaves the Workbench data in place!

   <Warning>
     Reboot each time you uninstall a node!
   </Warning>

4. Navigate to the `anaconda-enterprise-k3s-*` directory and install K3s by running the following command:

   ```
   ./k3s_install.sh
   ```

   <Note>
     This script installs and starts K3s, then uploads the Workbench images. The image upload process can take up to 30 minutes to complete, depending on your setup.
   </Note>

5. *Once the image uploads begin*, you can continue with installation by opening a second terminal and navigating back to the `anaconda-enterprise-k3s-*` directory, or you can wait until the images are fully uploaded to continue.

6. If your cluster has multiple nodes, add them now by running the following command for each node:

   ```sh theme={null}
   # Replace <PRIVATE_IP> with the nodes private network IP address
   ./k3s_addnode.sh <PRIVATE_IP>
   ```

7. Install the SSL certificates saved by the `extract_config.sh` script by running the following command:

   ```sh theme={null}
   kubectl create -f anaconda-enterprise-certs.json
   ```

8. Verify that the `k3s_values.yaml` contains the expected Workbench configuration values.

   <Tip>
     Take your time and verify *everything* is correct!
   </Tip>

9. If necessary, restore your instance’s manually created `anaconda-persistence` volume at this time by running the following command:

   ```sh theme={null}
   # Replace <FILE> with the anaconda-persistence volume file name
   kubectl create -f <FILE>.yaml
   ```

   <Note>
     If you have any other volumes, provision them now as well.
   </Note>

10. *Once the Workbench images are fully loaded*, install the Workbench application in paused mode by running the following command:

    ```sh theme={null}
    helm install -f k3s_values.yaml --set global.paused=true anaconda-enterprise Anaconda-Enterprise/
    ```

11. Restore the system configurations from the backup you took earlier by running the following command:

    ```sh theme={null}
    ae_restore.sh ae5_config_db_<YYYYMMDDHHMM>.tar.gz
    ```

12. Unpause the backed up deployments and scheduled jobs by running the following command:

    ```
    ae_unpause.sh
    ```

13. Monitor your cluster’s resources while they stabilize to ensure there are no unexpected issues by running the following command:

    ```sh theme={null}
    watch kubectl get pods
    ```

    Allow time to pass for the pods to appear and move to the `Ready` and `Running` states.

14. If you are upgrading from `5.5.x` or older, you must [complete the manual Keycloak upgrade process at this time](./keycloak-upgrade).

15. Open a browser and navigate to your instance of Workbench.

16. Log in to Workbench and explore the platform to verify that all of your projects, deployments, and scheduled jobs are present.