feat(instances): understanding qga

compute/instances/reference-content/understanding-qemu-guest-agent.mdx

@@ -0,0 +1,112 @@
+---
+meta:
+  title: Understanding the QEMU Guest Agent in Scaleway Instances
+  description: Discover how the QEMU Guest Agent in Scaleway Instances works.
+content:
+  h1: Understanding the QEMU Guest Agent in Scaleway Instances
+  paragraph: Discover how the QEMU Guest Agent in Scaleway Instances works.
+tags: instance qga guemu guest agent
+dates:
+  validation: 2024-10-28
+categories:
+  - compute
+---
+
+Some features of the Instances product require Scaleway's infrastructure to query or exchange information with your Instance. To enable this communication, a software component must run on the guest operating system: the QEMU Guest Agent (QGA).
+
+This document provides essential insights into this mechanism.
+
+<Message type="note">
+  This document does not apply to Instances running the Microsoft Windows operating system.
+</Message>
+
+## What are the features provided by QGA?
+
+Running the QEMU Guest Agent (QGA) on your Instance currently enables the following feature:
+
+- **Automatic network reconfiguration** upon flexible IP attachment or detachment.
+
+Additional features may be added in the future.
+
+## Checking the status of QGA
+
+Since March 1, 2024, all Scaleway-provided GNU/Linux and InstantApp images for Instances come with QGA pre-installed and enabled by default.
+
+To verify that QGA is running on your Instance, use the following command:
+
+```bash
+# systemctl is-active qemu-guest-agent.service
+```
+
+If the output is `active`, QGA is running, and you are ready to benefit from the associated features. If the output is `inactive`, you may need to install and/or activate QGA.
+
+## Opting In
+
+Follow these steps to enable QGA on an Instance where it is currently inactive.
+
+### Installation
+
+Instances created from images older than March 1, 2024, may require manual installation of the `qemu-guest-agent` package:
+
+- **Fedora / AlmaLinux / RockyLinux / CentOS**
+
+  ```bash
+  # yum -y install qemu-guest-agent
+  ```
+
+- **Debian / Ubuntu**
+
+  ```bash
+  # apt-get update
+  # apt-get -y install qemu-guest-agent
+  ```
+
+### Activation
+
+After installing the package, start the `qemu-guest-agent.service` by either:
+
+- Rebooting your instance, or
+- Running the following command:
+
+  ```bash
+  # systemctl start qemu-guest-agent.service
+  ```
+
+## Opting Out
+
+Follow these steps to disable QGA and the associated Scaleway features.
+
+### Deactivation
+
+<Message type="important">
+  Disabling QGA is not recommended, as doing so also disables all [Scaleway features](#what-are-the-features-provided-by-qga) it provides.
+</Message>
+
+To stop and disable QGA, run:
+
+```bash
+# systemctl stop qemu-guest-agent.service
+# systemctl mask qemu-guest-agent.service
+```
+
+This stops the service and prevents it from starting on subsequent reboots.
+
+### Deinstallation (Optional)
+
+<Message type="note">
+  Deinstalling QGA is not strictly necessary to opt out. [Deactivating the service](#deactivation) is sufficient.
+</Message>
+
+If you prefer to completely remove QGA, ensure the service is stopped first, then run:
+
+- **Fedora / AlmaLinux / RockyLinux / CentOS**
+
+  ```bash
+  # yum -y remove qemu-guest-agent
+  ```
+
+- **Debian / Ubuntu**
+
+  ```bash
+  # apt-get -y purge qemu-guest-agent
+  ```

menu/navigation.json

@@ -1353,6 +1353,10 @@
                     "label": "Understanding the differences between ARM and x86 Instances",
                     "slug": "understanding-differences-x86-arm"
                   },
+                  {
+                    "label": "Understanding QEMU Guest Agent",
+                    "slug": "understanding-qemu-guest-agent"
+                  },
                   {
                     "label": "Understanding Instance pricing",
                     "slug": "understanding-instance-pricing"