https://issues.redhat.com/browse/ACM-17505--Add Manage and Configure …

…OS to Edge Manager

edge_manager/edge_mgr_manage_config_git_repo.adoc

@@ -0,0 +1,64 @@
+[#device-config-git-cli]
+= Managing the device configuration from a Git repository on the CLI
+
+Create and apply a device configuration in a Git repository.
+Complete the following steps:
+
+. Create a file, named `site-settings-repo.yaml`, that contains the following definition for a `Repository` resource, named `site-settings`:
+
++
+[source,yaml]
+----
+apiVersion: flightctl.io/v1alpha1
+kind: Repository
+metadata:
+  name: site-settings
+spec:
+  type: git
+  url: https://github.com/<your_org>/<your_repo>.git
+----
+
+. Create the `Repository` resource by running the following command:
+
++
+[source,bash]
+----
+flightctl apply -f site-settings-repo.yaml
+----
+
+. Verify that the resource has been correctly created and is accessible by {rhem} by running the following command:
+
++
+[source,bash]
+----
+flightctl get repository/site-settings
+----
++
+See the following example output:
++
+[source,bash]
+----
+NAME           TYPE  REPOSITORY URL                                 ACCESSIBLE
+site-settings  git   https://github.com/<your_org>/<your_repo>.git  True
+----
+
+. To apply the `example-site` configuration to a device, update the device specification as follows:
+
++
+[source,yaml]
+----
+apiVersion: flightctl.io/v1alpha1
+kind: Device
+metadata:
+  name: <device_name>
+spec:
+[...]
+  config:
+  - name: example-site
+    configType: GitConfigProviderSpec
+    gitRef:
+      repository: site-settings
+      targetRevision: production
+      path: /example-site
+[...]
+----

edge_manager/edge_mgr_manage_devices.adoc

@@ -0,0 +1,25 @@
+[#manage-devices]
+= Device management
+
+After provisioning, you need to enroll your devices to manage them with the {rhem}.
+Device management includes organizing, monitoring, and updating your devices with the {rhem}.
+You can manage your devices individually or in a fleet.
+Managing your devices individually is advantageous in the following scenarios:
+
+* If a few devices have different configuration.
+* If you use external automation for updating the device.
+//For managing your devices in a fleet, see xref:../[]
+
+For more information, read the following sections:
+
+////
+* xref:../edge_manager/edge_mgr_enroll_devices#enroll[Enrolling devices]
+* xref:../edge_manager/edge_mgr_view_devices#view-device[Viewing device inventory and device details]
+* xref:../edge_manager/edge_mgr_label_devices#labels[Labels and label selectors]
+* xref:../edge_manager/edge_mgr_update_labels_on_devices#update-labels-cli[Updating labels using the CLI]
+////
+
+* xref:../edge_manager/edge_mgr_manage_os_devices#manage-os-config[The operating system configuration]
+* xref:../edge_manager/edge_mgr_update_os_devices#update-os[Updating the operating system]
+
+*Required access:* Cluster administrator

edge_manager/edge_mgr_manage_os_devices.adoc

@@ -0,0 +1,136 @@
+[#manage-os-config]
+= Operating system configuration
+
+You can include an operating system-level host configuration in the image to provide maximum consistency and repeatability.
+To update a configuration, you create a new operating system image and update devices with the new image.
+
+However, updating devices with a new image can be impractical in the following cases:
+
+* The configuration is missing in the image.
+* The configuration needs to be specific to a device.
+* The configuration needs to be updateable at runtime without updating the operating system image and rebooting.
+
+For these cases, you can declare a set of configuration files that can be present on the file system of the device.
+The {rhem} agent applies updates to the configuration files while ensuring that either all files are successfully updated in the file system, or rolled back to their pre-update state.
+If the user updates both an operating system and configuration set of a device at the same time, the {rhem} agent updates the operating system first, then applies the specified set of configuration files.
+
+You can also specify a list of configurations sets that the {rhem} agent applies in sequence.
+In case of a conflict, the last applied configuration set is valid.
+
+*Important:* After the {rhem} agent updates the configuration on the disk, the configuration must be activated.
+Running applications need to reload the new configuration into memory for the configuration to become effective.
+If the update involves a reboot, `systemd` automatically restarts the applications with the new configuration and in the correct order.
+If the update does not involve a reboot, many application can detect changes to their configuration files and automatically reload the files.
+When an application does not support change detection, you can use device lifecycle hooks to run scripts or commands if certain conditions are met.
+//TODO Add link: For more information on device lifecycle hooks and the default rules used by the {rhem} agent, see xref:../[Device lifecycle hooks].
+
+[#config-providers]
+== Configuration providers
+
+You can provide configuration from multiple sources, called configuration providers, in {rhem}.
+The {rhem} currently supports the following configuration providers:
+
+Git Config Provider:: Fetches device configuration files from a Git repository.
+Kubernetes Secret Provider:: Fetches a secret from a Kubernetes cluster and writes the content to the file system of the device.
+HTTP Config Provider:: Fetches device configuration files from an HTTP(S) endpoint.
+Inline Config Provider:: Allows specifying device configuration files inline in the device manifest without querying external systems.
+
+Read more about the configuration providers in the following sections:
+
+* <<config-git,Configuration from a Git repository>>
+* <<config-k8s-secret,Secrets from a Kubernetes cluster>>
+* <<config-http,Configuration from an HTTP server>>
+* <<config-inline,Configuration inline in the device specification>>
+
+[#config-git]
+=== Configuration from a Git repository
+
+You can store device configuration in a Git repository such as GitHub or GitLab.
+The {rhem} synchronizes the configuration from the repository to the file system of the device by adding a Git Config Provider.
+
+The Git Config Provider takes the following parameters:
+
+[%header,cols="1,3"]
+|===
+|Parameter|Description
+|`Repository`|The name of a `Repository` resource defined in the {rhem}.
+
+|`TargetRevision`|The branch, tag, or commit of the repository to checkout.
+
+|`Path`|The subdirectory of the repository that contains the configuration.
+
+|`MountPath`|Optional. The directory in the file system of the device to which the configuration is written. By default, the value is the file system root `/`.
+|===
+
+The `Repository` resource defines the Git repository, the protocol and access credentials that the {rhem} must use.
+The repository needs to be set up only once.
+After setting up, the repository can be used to configure individual devices or device fleets.
+
+[#config-k8s-secret]
+=== Secrets from a Kubernetes cluster
+
+The {rhem} can query the Kubernetes cluster that it is running on for a Kubernetes secret.
+The content of that secret can be written to a path on the device file system.
+
+The Kubernetes Secret Provider takes the following parameters:
+
+[%header,cols="1,3"]
+|===
+|Parameter|Description
+|`Name`|The name of the secret.
+
+|`NameSpace`|The namespace of the secret.
+
+|`MountPath`|The directory in the file system of the device to write the secret contents to.
+|===
+
+*Note:* The {rhem} needs permission to access secrets in the defined namespace.
+For example, creating a `ClusterRole` and `ClusterRoleBinding` allows the `flightctl-worker` service account to get and list secrets in that namespace.
+
+//TODO add link: For more information about granting {rhem} permissions, see xref:..[RBAC].
+
+[#config-http]
+=== Configuration from an HTTP server
+
+The {rhem} can query an HTTP server for configuration.
+The HTTP server can serve static or dynamically generated configuration for a device.
+
+The HTTP Config Provider takes the following parameters:
+
+[%header,cols="1,3"]
+|===
+|Parameter|Description
+|`Repository`|The name of a `Repository` resource defined in the {rhem}.
+
+|`Suffix`|The suffix to append to the base URL defined in the `Repository` resource. The suffix can include path and query parameters, for example `/path/to/endpoint?query=param`.
+
+|`FilePath`|The path to the file on the device file system that stores the returned value of the HTTP Server.
+|===
+
+The `Repository` resource specifies the HTTP server for the {rhem} to connect to, and the protocol and access credentials to use.
+The repository needs to be set up once and then, the repository can be used to configure multiple devices or device fleets.
+
+[#config-inline]
+=== Configuration inline in the device specification
+
+You can specify configuration inline in a device specification.
+When using the inline device specification, the {rhem} does not need to connect to external systems to fetch the configuration.
+
+The Inline Config Provider takes a list of file specifications, where each file specification takes the following parameters:
+
+[%header,cols="1,3"]
+|===
+|Parameter|Description
+|`Path`|The absolute path to the file on the device.
+If a file already exists in the specified path, the file is overwritten.
+
+|`Content`|The UTF-8 or base64-encoded content of the file.
+
+|`ContentEncoding`|Defines how the contents are encoded. Must be either `plain` or `base64`. Default value is set to `plain`.
+
+|`Mode`|Optional. The permission mode of the file. You can specify the octal with a leading zero, for example `0644`, or as a decimal without a leading zero, for example `420`. The `setuid`, `setgid`, and `sticky` bits are supported. If not specified, the permission mode for files defaults to `0644`.
+
+|`User`|Optional. The owner of the file. Specified either as a name or numeric ID. Default value is set to `root`.
+
+|`Group`|Optional. The group of the file. Specified either as a name or numeric ID.
+|===

edge_manager/edge_mgr_update_os_devices.adoc

@@ -0,0 +1,62 @@
+[#update-os]
+= Updating the operating system
+
+You can update the operating system of a device by updating the target operating system image name or version in the device specification.
+When the {rhem} agent communicates with the service, the agent detects the requested update.
+Then, the agent automatically starts downloading and verifying the new operating system version in the background.
+The {rhem} agent schedules the actual system update according to the update policy.
+At the scheduled update time, the agent installs the new version without disrupting the currently running operating system.
+Finally, the device reboots into the new version.
+
+The {rhem} currently supports the following image type and image reference format:
+
+[%header,cols="1,3"]
+|===
+|Image Type |Image Reference
+|bootc|An OCI image reference to a container registry. Example: `quay.io/flightctl-example/rhel:9.5`
+|===
+//TODO update upstream path
+
+During the process, the agent sends status updates to the service.
+You can monitor the update process by viewing the device status.
+For more information, see xref:../edge_manager/edge_mgmt_manage_organize#view-devices[Viewing devices].
+
+[#update-os-cli]
+== Updating the operating system on the CLI
+
+Update a device using the CLI.
+Complete the following steps:
+
+. Get the current resource manifest of the device by running the following command:
+
++
+[source,bash]
+----
+flightctl get device/<device_name> -o yaml > my_device.yaml
+----
+
+. Edit the `Device` resource to specify the new operating system name and version target.
+
++
+[source,yaml]
+----
+apiVersion: flightctl.io/v1alpha1
+kind: Device
+metadata:
+  name: some_device_name
+spec:
+[...]
+  os:
+    image: quay.io/flightctl/rhel:9.5
+[...]
+----
+
+. Apply the updated `Device` resource by running the following command:
+
++
+[source,bash]
+----
+flightctl apply -f some_device_name.yaml
+----
+
+//Verify? Or monitor status?

edge_manager/main.adoc

@@ -5,3 +5,8 @@ include::modules/common-attributes.adoc[]
 include::edge_mgr_intro.adoc[leveloffset=+1]
 include::edge_mgr_enable.adoc[leveloffset=+2]
 include::edge_mgr_arch.adoc[leveloffset=+2]
+//Managing devices will have more subsections
+include::edge_mgr_manage_devices.adoc[leveloffset=+2]
+include::edge_mgr_manage_os_devices.adoc[leveloffset=+3]
+include::edge_mgr_manage_config_git_repo.adoc[leveloffset=+4]
+include::edge_mgr_update_os_devices.adoc[leveloffset=+3]