Issue 564: Refactor navigation on cluster installation pages

docs/installing/edge_cluster_agent.md

@@ -1,8 +1,8 @@
 ---
 
 copyright:
-years: 2022 - 2023
-lastupdated: "2023-03-18"
+years: 2022 - 2024
+lastupdated: "2024-07-15"
 title: "Installing the edge cluster agent"
 
 parent: Edge clusters
@@ -28,27 +28,19 @@ This content provides instructions on installing the cluster agent on common Kub
 ## Pre-requisites
 {: #reqs}
 
-* Architecture must be either x86_64 or arm64
+* Architecture must be either x86_64 (amd64) or arm64
 * Operating system must be modern Linux variant with 64-bit and systemd support
 
 **Note**: {{site.data.keyword.ieam}} cluster agent installation requires cluster admin access on the edge cluster.  Additionally, the "jq" command-line JSON processor must be installed prior to running the agent install script.
 
 ## Installing
 {: #steps}
 
-Begin by installing the {{site.data.keyword.edge_notm}} agent on one of these types of Kubernetes edge clusters:
+Install the {{site.data.keyword.edge_notm}} Cluster Agent on one of these types of Kubernetes edge clusters:
 
 * [Installing agent on {{site.data.keyword.ocp}} Kubernetes edge cluster](#install_kube)
 * [Installing agent on k3s and microk8s edge clusters](#install_lite)
 
-Then, deploy an edge service to your edge cluster:
-
-* [Deploying services to your edge cluster](#deploying_services)
-
-If you need to remove the agent:
-
-* [Removing agent from edge cluster](../using_edge_services/removing_agent_from_cluster.md)
-
 ## Installing agent on {{site.data.keyword.ocp}} Kubernetes edge cluster
 {: #install_kube}
 
@@ -318,100 +310,9 @@ This content describes how to install the {{site.data.keyword.ieam}} agent on [K
    ```
    {: codeblock}
 
-8. Usually, when an edge cluster is registered for policy, but does not have any user-specified node policy, none of the deployment policies deploy edge services to it. This is expected. Proceed to [Deploying services to your edge cluster](#deploying_services) to set node policy so that an edge service will be deployed to this edge cluster.
-
-## Deploying services to your edge cluster
-{: #deploying_services}
-
-Setting node policy on this edge cluster can cause deployment policies to deploy edge services here. This content shows an example of doing that.
-
-1. Set some aliases to make it more convenient to run the `hzn` command. (The `hzn` command is inside the agent container, but these aliases make it possible to run `hzn` from this host.)
-
-   ```bash
-   cat << 'END_ALIASES' >> ~/.bash_aliases
-   alias getagentpod='kubectl -n openhorizon-agent get pods --selector=app=agent -o jsonpath={.items[].metadata.name}'
-   alias hzn='kubectl -n openhorizon-agent exec -i $(getagentpod) -- hzn'
-   END_ALIASES
-   source ~/.bash_aliases
-   ```
-   {: codeblock}
-
-2. Verify that your edge node is configured (registered with the {{site.data.keyword.ieam}} management hub):
-
-   ```bash
-   hzn node list
-   ```
-   {: codeblock}
-
-3. To test your edge cluster agent, set your node policy with a property that deploys the example helloworld operator and service to this edge node:
-
-   ```bash
-   cat << 'EOF' > operator-example-node.policy.json
-   {
-     "properties": [
-       { "name": "openhorizon.example", "value": "nginx-operator" }
-     ]
-   }
-   EOF
-
-   cat operator-example-node.policy.json | hzn policy update -f-
-   hzn policy list
-   ```
-   {: codeblock}
-
-   **Note**:
-   * Because the real **hzn** command is running inside the agent container, for any `hzn` commands that require an input file, you need to pipe the file into the command so its content will be transferred into the container.
-
-4. After a minute, check for an agreement and the running edge operator and service containers:
-
-   ```bash
-   hzn agreement list
-   kubectl -n openhorizon-agent get pods
-   ```
-   {: codeblock}
-
-5. Using the pod IDs from the previous command, view the log of edge operator and service:
-
-   ```bash
-   kubectl -n openhorizon-agent logs -f <operator-pod-id>
-   # control-c to get out
-   kubectl -n openhorizon-agent logs -f <service-pod-id>
-   # control-c to get out
-   ```
-   {: codeblock}
-
-6. You can also view the environment variables that the agent passes to the edge service:
-
-   ```bash
-   kubectl -n openhorizon-agent exec -i <service-pod-id> -- env | grep HZN_
-   ```
-   {: codeblock}
-
-### Changing what services are deployed to your edge cluster
-{: #changing_services}
-
-* To change what services are deployed to your edge cluster, change the node policy:
-
-  ```bash
-  cat <new-node-policy>.json | hzn policy update -f-
-  hzn policy list
-  ```
-  {: codeblock}
-
-   After a minute or two the new services will be deployed to this edge cluster.
-
-* **Note**: On some VMs with microk8s, the service pods that are being stopped (replaced) might stall in the **Terminating** state. If that happens, run:
-
-  ```bash
-  kubectl delete pod <pod-id> -n openhorizon-agent --force --grace-period=0
-  pkill -fe <service-process>
-  ```
-  {: codeblock}
+8. Usually, when an edge cluster is registered for policy, but does not have any user-specified node policy, none of the deployment policies deploy edge services to it. This is expected. Proceed to [Deploying services to your edge cluster](../using_edge_services/deploying_services_cluster.md) to set node policy so that an edge service will be deployed to this edge cluster.
 
-* If you want to use a pattern instead of a policy to run services on your edge cluster:
+## What's next
 
-  ```bash
-  hzn unregister -f
-  hzn register -n $HZN_EXCHANGE_NODE_AUTH -p <pattern-name>
-  ```
-  {: codeblock}
+- [Deploying services to an edge cluster](../using_edge_services/deploying_services_cluster.md)
+- [Removing an agent from an edge cluster](../using_edge_services/removing_agent_from_cluster.md)

docs/installing/edge_clusters.md

@@ -1,8 +1,8 @@
 ---
 
 copyright:
-years: 2021 - 2023
-lastupdated: "2023-03-17"
+years: 2021 - 2024
+lastupdated: "2024-07-15"
 title: "Edge clusters"
 
 nav_order: 12
@@ -25,11 +25,13 @@ has_toc: false
 
 ![{{site.data.keyword.horizon_exchange}}, {{site.data.keyword.agbot}}s and agents](../../images/edge/05b_Installing_edge_agent_on_cluster.svg "{{site.data.keyword.horizon_exchange}}, {{site.data.keyword.agbot}}s and agents")
 
-The following sections describe how to install an edge cluster and install the {{site.data.keyword.ieam}} agent on it.
+The following sections describe how to install an edge cluster, then how to install the {{site.data.keyword.ieam}} agent on the cluster.  Then we provide documentation on how to deploy services to the cluster, followed up by how to remove an agent from a cluster.
 
 - [Preparing an edge cluster](preparing_edge_cluster.md)
    - [Installing an OCP cluster](./install_ocp_edge_cluster.md)
    - [Installing a K3s cluster](./install_k3s_edge_cluster.md)
    - [Installing a microk8s cluster](./install_microk8s_edge_cluster.md)
-- [Installing the agent](edge_cluster_agent.md)
+- [Installing the agent](./edge_cluster_agent.md)
+- [Deploying services to an edge cluster](../using_edge_services/deploying_services_cluster.md)
+- [Removing an agent from an edge cluster](../using_edge_services/removing_agent_from_cluster.md)
 {: childlinks}

docs/installing/install_k3s_edge_cluster.md

@@ -1,8 +1,8 @@
 ---
 
 copyright:
-years: 2020 - 2023
-lastupdated: "2023-03-17"
+years: 2020 - 2024
+lastupdated: "2024-07-15"
 title: "Installing a K3s edge cluster"
 
 parent: Preparing an edge cluster
@@ -26,12 +26,12 @@ has_toc: false
 ## Introduction
 {: #intro}
 
-This content provides a summary of how to install k3s (rancher), a lightweight and small Kubernetes cluster, on Ubuntu Linux AMD64. For more information, see the [k3s documentation ](https://rancher.com/docs/k3s/latest/en/){:target="_blank"}{: .externalLink}.
+This content provides a summary of how to install k3s (rancher), a lightweight and small Kubernetes cluster, on a recent Ubuntu LTS distribution. For more information, see the [k3s documentation ](https://rancher.com/docs/k3s/latest/en/){:target="_blank"}{: .externalLink}.
 
 ## Pre-requisites
 {: #reqs}
 
-* Architecture must be either x86_64 or arm64
+* Architecture must be either x86_64 (amd64) or arm64
 * Operating system must be modern Linux variant with 64-bit and systemd support
 
 **Note**: If installed, uninstall kubectl before completing the following steps.
@@ -187,4 +187,4 @@ This content provides a summary of how to install k3s (rancher), a lightweight a
 
 ## What's next
 
-* [Installing the Cluster Agent](edge_cluster_agent.md)
+* [Installing the Cluster Agent](./edge_cluster_agent.md)

docs/installing/install_microk8s_edge_cluster.md

@@ -1,8 +1,8 @@
 ---
 
 copyright:
-years: 2020 - 2023
-lastupdated: "2023-03-17"
+years: 2020 - 2024
+lastupdated: "2024-07-15"
 title: "Installing a microk8s edge cluster"
 
 parent: Preparing an edge cluster
@@ -130,4 +130,4 @@ This content provides a summary of how to install microk8s, a lightweight and sm
 
 ## What's next
 
-* [Installing the Cluster Agent](edge_cluster_agent.md)
+* [Installing the Cluster Agent](./edge_cluster_agent.md)

docs/installing/install_ocp_edge_cluster.md

@@ -1,8 +1,8 @@
 ---
 
 copyright:
-years: 2020 - 2023
-lastupdated: "2023-03-17"
+years: 2020 - 2024
+lastupdated: "2024-07-15"
 title: "Installing an OCP edge cluster"
 
 parent: Preparing an edge cluster
@@ -29,4 +29,4 @@ has_toc: false
 
 ## What's next
 
-* [Installing the Cluster Agent](edge_cluster_agent.md)
+* [Installing the Cluster Agent](./edge_cluster_agent.md)

docs/installing/preparing_edge_cluster.md

@@ -1,8 +1,8 @@
 ---
 
 copyright:
-years: 2020 - 2023
-lastupdated: "2023-03-17"
+years: 2020 - 2024
+lastupdated: "2024-07-15"
 title: "Preparing an edge cluster"
 
 parent: Edge clusters
@@ -26,7 +26,7 @@ has_toc: false
 Install one of these Kubernetes clusters and prepare it for installation of the {{site.data.keyword.edge_notm}} Cluster Agent:
 
 - Preparing an edge cluster
-  - [Install an OCP edge cluster](#install_ocp_edge_cluster)
-  - [Install and configure a k3s edge cluster](#install_k3s_edge_cluster)
-  - [Install and configure a microk8s edge cluster](#install_microk8s_edge_cluster) (for development and test, not recommended for production)
-- [Installing the Cluster Agent](edge_cluster_agent.md)
+   - [Installing an OCP cluster](./install_ocp_edge_cluster.md)
+   - [Installing a K3s cluster](./install_k3s_edge_cluster.md)
+   - [Installing a microk8s cluster](./install_microk8s_edge_cluster.md)
+- [Installing the Cluster Agent](./edge_cluster_agent.md)

docs/using_edge_services/deploying_services_cluster.md

@@ -0,0 +1,108 @@
+---
+
+copyright:
+years: 2022 - 2024
+lastupdated: "2024-06-07"
+title: "Deploying services to an edge cluster"
+
+parent: Edge clusters
+nav_order: 3
+---
+
+# Deploying services to an edge cluster
+
+## How to deploy services to an edge cluster
+{: #deploying_services}
+
+Setting node policy on this edge cluster can cause deployment policies to deploy edge services here. This content shows an example of doing that.
+
+1. Set some aliases to make it more convenient to run the `hzn` command. (The `hzn` command is inside the agent container, but these aliases make it possible to run `hzn` from this host.)
+
+   ```bash
+   cat << 'END_ALIASES' >> ~/.bash_aliases
+   alias getagentpod='kubectl -n openhorizon-agent get pods --selector=app=agent -o jsonpath={.items[].metadata.name}'
+   alias hzn='kubectl -n openhorizon-agent exec -i $(getagentpod) -- hzn'
+   END_ALIASES
+   source ~/.bash_aliases
+   ```
+   {: codeblock}
+
+2. Verify that your edge node is configured (registered with the {{site.data.keyword.ieam}} management hub):
+
+   ```bash
+   hzn node list
+   ```
+   {: codeblock}
+
+3. To test your edge cluster agent, set your node policy with a property that deploys the example helloworld operator and service to this edge node:
+
+   ```bash
+   cat << 'EOF' > operator-example-node.policy.json
+   {
+     "properties": [
+       { "name": "openhorizon.example", "value": "nginx-operator" }
+     ]
+   }
+   EOF
+
+   cat operator-example-node.policy.json | hzn policy update -f-
+   hzn policy list
+   ```
+   {: codeblock}
+
+   **Note**:
+   * Because the real **hzn** command is running inside the agent container, for any `hzn` commands that require an input file, you need to pipe the file into the command so its content will be transferred into the container.
+
+4. After a minute, check for an agreement and the running edge operator and service containers:
+
+   ```bash
+   hzn agreement list
+   kubectl -n openhorizon-agent get pods
+   ```
+   {: codeblock}
+
+5. Using the pod IDs from the previous command, view the log of edge operator and service:
+
+   ```bash
+   kubectl -n openhorizon-agent logs -f <operator-pod-id>
+   # control-c to get out
+   kubectl -n openhorizon-agent logs -f <service-pod-id>
+   # control-c to get out
+   ```
+   {: codeblock}
+
+6. You can also view the environment variables that the agent passes to the edge service:
+
+   ```bash
+   kubectl -n openhorizon-agent exec -i <service-pod-id> -- env | grep HZN_
+   ```
+   {: codeblock}
+
+### Changing what services are deployed to your edge cluster
+{: #changing_services}
+
+* To change what services are deployed to your edge cluster, change the node policy:
+
+  ```bash
+  cat <new-node-policy>.json | hzn policy update -f-
+  hzn policy list
+  ```
+  {: codeblock}
+
+   After a minute or two the new services will be deployed to this edge cluster.
+
+* **Note**: On some VMs with microk8s, the service pods that are being stopped (replaced) might stall in the **Terminating** state. If that happens, run:
+
+  ```bash
+  kubectl delete pod <pod-id> -n openhorizon-agent --force --grace-period=0
+  pkill -fe <service-process>
+  ```
+  {: codeblock}
+
+* If you want to use a pattern instead of a policy to run services on your edge cluster:
+
+  ```bash
+  hzn unregister -f
+  hzn register -n $HZN_EXCHANGE_NODE_AUTH -p <pattern-name>
+  ```
+  {: codeblock}

docs/using_edge_services/removing_agent_from_cluster.md

@@ -1,8 +1,12 @@
 ---
 
 copyright:
-years: 2020 - 2022
-lastupdated: "2022-03-17"
+years: 2022 - 2024
+lastupdated: "2024-06-07"
+title: "Removing the agent from an edge cluster"
+
+parent: Edge clusters
+nav_order: 4
 
 ---
 
@@ -14,7 +18,7 @@ lastupdated: "2022-03-17"
 {:child: .link .ulchildlink}
 {:childlinks: .ullinks}
 
-# Removing agent from edge cluster
+# Removing the agent from an edge cluster
 {: #remove_agent}
 
 To unregister an edge cluster and remove the {{site.data.keyword.ieam}} agent from that cluster, perform these steps: