From 06613d4d29838eaeb808832717d9f8ee6319139d Mon Sep 17 00:00:00 2001 From: Alexandra Molnar Date: Wed, 19 Feb 2025 14:12:46 +0000 Subject: [PATCH] https://issues.redhat.com/browse/ACM-17505--Add Manage and Configure OS to Edge Manager --- .../edge_mgr_manage_config_git_repo.adoc | 64 +++++++++ edge_manager/edge_mgr_manage_devices.adoc | 25 ++++ edge_manager/edge_mgr_manage_os_devices.adoc | 136 ++++++++++++++++++ edge_manager/edge_mgr_update_os_devices.adoc | 62 ++++++++ edge_manager/main.adoc | 5 + 5 files changed, 292 insertions(+) create mode 100644 edge_manager/edge_mgr_manage_config_git_repo.adoc create mode 100644 edge_manager/edge_mgr_manage_devices.adoc create mode 100644 edge_manager/edge_mgr_manage_os_devices.adoc create mode 100644 edge_manager/edge_mgr_update_os_devices.adoc diff --git a/edge_manager/edge_mgr_manage_config_git_repo.adoc b/edge_manager/edge_mgr_manage_config_git_repo.adoc new file mode 100644 index 0000000000..2fac232759 --- /dev/null +++ b/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//.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//.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: +spec: +[...] + config: + - name: example-site + configType: GitConfigProviderSpec + gitRef: + repository: site-settings + targetRevision: production + path: /example-site +[...] +---- \ No newline at end of file diff --git a/edge_manager/edge_mgr_manage_devices.adoc b/edge_manager/edge_mgr_manage_devices.adoc new file mode 100644 index 0000000000..461c5364fe --- /dev/null +++ b/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 \ No newline at end of file diff --git a/edge_manager/edge_mgr_manage_os_devices.adoc b/edge_manager/edge_mgr_manage_os_devices.adoc new file mode 100644 index 0000000000..59fb2b38f9 --- /dev/null +++ b/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 + +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. +|=== \ No newline at end of file diff --git a/edge_manager/edge_mgr_update_os_devices.adoc b/edge_manager/edge_mgr_update_os_devices.adoc new file mode 100644 index 0000000000..121274c59f --- /dev/null +++ b/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/ -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? \ No newline at end of file diff --git a/edge_manager/main.adoc b/edge_manager/main.adoc index 8d51756c06..1adf434ac3 100644 --- a/edge_manager/main.adoc +++ b/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] \ No newline at end of file