From be513e9f8a8a73c43f64d9e067ab76b586d3068b Mon Sep 17 00:00:00 2001
From: Ruth Fuchss <ruth.fuchss@canonical.com>
Date: Wed, 7 Feb 2024 15:47:51 +0100
Subject: [PATCH] doc: add some API instructions for cloud-init

Signed-off-by: Ruth Fuchss <ruth.fuchss@canonical.com>
---
 doc/cloud-init.md | 31 ++++++++++++++++++++++++++++++-
 1 file changed, 30 insertions(+), 1 deletion(-)

diff --git a/doc/cloud-init.md b/doc/cloud-init.md
index 69c78b6424e4..61fa906b4ce4 100644
--- a/doc/cloud-init.md
+++ b/doc/cloud-init.md
@@ -67,7 +67,7 @@ To configure `cloud-init` for an instance, add the corresponding configuration o
 
 When configuring `cloud-init` directly for an instance, keep in mind that `cloud-init` runs only on the first start of the instance.
 That means that you must configure `cloud-init` before you start the instance.
-To do so, create the instance with [`lxc init`](lxc_init.md) instead of [`lxc launch`](lxc_launch.md), and then start it after completing the configuration.
+If you are using the CLI client, create the instance with [`lxc init`](lxc_init.md) instead of [`lxc launch`](lxc_launch.md), and then start it after completing the configuration.
 
 ### YAML format for `cloud-init` configuration
 
@@ -92,6 +92,35 @@ config:
 See {ref}`How to validate user data <cloud-init:check_user_data_cloud_config>` for information on how to check whether the syntax is correct.
 ```
 
+### Configure `cloud-init` through the API
+
+If you are using the API to configure your instance, provide the `cloud-init` configuration as a string with escaped newline characters.
+
+For example:
+
+    lxc query --request PATCH /1.0/instances/<instance_name> --data '{
+      "config": {
+        "cloud-init.user-data": "#cloud-config\npackage_upgrade: true\npackages:\n  - package1\n  - package2"
+      }
+    }'
+
+Alternatively, to avoid mistakes, write the configuration to a file and include that in your request.
+For example, create `cloud-init.txt` with the following content:
+
+    #cloud-config
+    package_upgrade: true
+    packages:
+      - package1
+      - package2
+
+Then send the following request:
+
+    lxc query --request PATCH /1.0/instances/<instance_name> --data '{
+    "config": {
+      "cloud-init.user-data": "'"$(awk -v ORS='\\n' '1' cloud-init.txt)"'"
+      }
+    }'
+
 ## How to check the `cloud-init` status
 
 `cloud-init` runs automatically on the first start of an instance.