Merge pull request #577 from joewxboy/issue-576

Issue 576: updated from API key to authentication string and other en…

docs/hub/prepare_for_edge_nodes.md

@@ -1,8 +1,8 @@
 ---
 
 copyright:
-years: 2020 - 2022
-lastupdated: "2022-06-24"
+years: 2020 - 2024
+lastupdated: "2024-07-29"
 
 ---
 
@@ -17,34 +17,26 @@ lastupdated: "2022-06-24"
 # Prepare for setting up edge nodes
 {: #prepare_for_edge_nodes}
 
-This content explains how to create an API key and gather some files and environment variable values that are needed when you set up edge nodes. Perform these steps on an admin host that can connect to your {{site.data.keyword.ieam}} management hub cluster.
+This content explains how to use your issued authentication credentials and related environment variable values to install the anax Agent on edge nodes. Perform these steps on an edge host that can connect to your {{site.data.keyword.ieam}} management hub cluster.
 
 ## Before you begin
 
-- If you have not already installed **cloudctl**, see [Installing cloudctl, oc, and kubectl](../cli/cloudctl_oc_cli.md) to do that.
-- Contact your {{site.data.keyword.ieam}} administrator for the information that you need to log in to the management hub via **cloudctl**.
+- Contact your {{site.data.keyword.ieam}} administrator for the information that you need to log in to the desired management hub instance.  If you do not have one, you may choose to install an [all-in-one instance](https://open-horizon.github.io/docs/mgmt-hub/docs/) locally on an x86 machine, or you can request an account on [the LF Edge Community Lab developer instances](https://wiki.lfedge.org/display/LE/Open+Horizon+Management+Hub+Developer+Instance).
 
 ## Procedure
 
-1. Use `cloudctl` to log in to the {{site.data.keyword.ieam}} management hub. Specify the user that you want to create an API key for:
+1. Each user who is setting up edge nodes must have an authentication string. You can use the same authentication string to set up all of your edge nodes (it is not saved on the edge nodes). An administrator can create a new user from the CLI:
 
    ```bash
-   cloudctl login -a <cluster-url> -u <user> -p <password> --skip-ssl-validation
+   hzn exchange user create -o <existing organization ID> [-A] <desired username> <desired password> <user email address>
    ```
    {: codeblock}
 
-2. Each user who is setting up edge nodes must have an API key. You can use the same API key to set up all of your edge nodes (it is not saved on the edge nodes). Create an API key:
+   Note the optional `-A` flag which grants organization admin privileges.  The authentication string will be a combination of `username` and `password` separated by a colon.  Both values should begin with an alpha character, not a number.  Neither should contain spaces.
 
-   ```bash
-   cloudctl iam api-key-create "<choose-an-api-key-name>" -d "<choose-an-api-key-description>"
-   ```
-   {: codeblock}
-
-   Find the key value in the command output; this is the line that starts with **API Key**. Save the key value for future use because you cannot query it from the system later.
-
-3. If you have not already installed the **horizon-cli** package on this host, do that now. See [Post installation configuration](post_install.md#postconfig) for an example of this process.
+2. If you have not already installed the **horizon-cli** package on this host, do that now. See [Post installation configuration](post_install.md#postconfig) for an example of this process.
 
-4. Locate the **agent-install.sh** and **agent-uninstall.sh** scripts that were installed as part of the **horizon-cli** package. These scripts are required on each edge node during setup (currently **agent-uninstall.sh** only supports edge clusters):
+3. Locate the **agent-install.sh** and **agent-uninstall.sh** scripts that were installed as part of the **horizon-cli** package. These scripts are required on each edge node during setup (currently **agent-uninstall.sh** only supports edge clusters):
 
    - {{site.data.keyword.linux_notm}} example:
 
@@ -60,14 +52,15 @@ This content explains how to create an API key and gather some files and environ
      ```
      {: codeblock}
 
-5. Contact your {{site.data.keyword.ieam}} administrator for help in setting these environment variables:
+4. Contact your {{site.data.keyword.ieam}} administrator for help in setting these environment variables:
 
    ```bash
-   export HZN_EXCHANGE_USER_AUTH=iamapikey:<api-key>
    export HZN_ORG_ID=<your-exchange-organization>
-   mgmtHubIngress=$(oc get cm management-ingress-ibmcloud-cluster-info -o jsonpath='{.data.cluster_ca_domain}')
-   export HZN_FSS_CSSURL=https://$mgmtHubIngress/edge-css/
-   echo "export HZN_FSS_CSSURL=$HZN_FSS_CSSURL"
+   export HZN_EXCHANGE_USER_AUTH=<authentication string>
+   export HZN_EXCHANGE_URL= # example http://open-horizon.lfedge.iol.unh.edu:3090/v1
+   export HZN_FSS_CSSURL= # example http://open-horizon.lfedge.iol.unh.edu:9443/
+   export HZN_AGBOT_URL= # example http://open-horizon.lfedge.iol.unh.edu:3111
+   export HZN_FDO_SVC_URL= # example http://open-horizon.lfedge.iol.unh.edu:9008/api
    ```
    {: codeblock}
 

docs/installing/advanced_man_install.md

@@ -1,8 +1,8 @@
 ---
 
 copyright:
-years: 2021 - 2023
-lastupdated: "2023-02-25"
+years: 2021 - 2024
+lastupdated: "2024-07-29"
 title: "Manual agent install"
 
 parent: Edge devices info
@@ -311,7 +311,15 @@ Follow these steps:
 
    ```bash
    eval export $(cat agent-install.cfg)
-   export HZN_EXCHANGE_USER_AUTH=iamapikey:<api-key>
+
+   # or 
+
+   export HZN_ORG_ID=<your-exchange-organization>
+   export HZN_EXCHANGE_USER_AUTH=<authentication string>
+   export HZN_EXCHANGE_URL= # example http://open-horizon.lfedge.iol.unh.edu:3090/v1
+   export HZN_FSS_CSSURL= # example http://open-horizon.lfedge.iol.unh.edu:9443/
+   export HZN_AGBOT_URL= # example http://open-horizon.lfedge.iol.unh.edu:3111
+   export HZN_FDO_SVC_URL= # example http://open-horizon.lfedge.iol.unh.edu:9008/api
    ```
    {: codeblock}
 

docs/installing/automated_install.md

@@ -1,8 +1,8 @@
 ---
 
 copyright:
-years: 2020 - 2023
-lastupdated: "2023-01-23"
+years: 2020 - 2024
+lastupdated: "2024-07-29"
 
 ---
 
@@ -24,10 +24,12 @@ Note: These steps are the same for all edge device types (architectures).
 2. Log in to your edge device and set the same environment variables that you obtained in step 1:
 
    ```bash
-   export HZN_EXCHANGE_USER_AUTH=iamapikey:<api-key>
    export HZN_ORG_ID=<your-exchange-organization>
-   export HZN_FSS_CSSURL=https://<management-hub-ingress>/edge-css/
-   export HZN_EXCHANGE_URL=https://<management-hub-ingress>/edge-exchange/v1
+   export HZN_EXCHANGE_USER_AUTH=<authentication string>
+   export HZN_EXCHANGE_URL= # example http://open-horizon.lfedge.iol.unh.edu:3090/v1
+   export HZN_FSS_CSSURL= # example http://open-horizon.lfedge.iol.unh.edu:9443/
+   export HZN_AGBOT_URL= # example http://open-horizon.lfedge.iol.unh.edu:3111
+   export HZN_FDO_SVC_URL= # example http://open-horizon.lfedge.iol.unh.edu:9008/api
    ```
    {: codeblock}
 

docs/installing/edge_cluster_agent.md

@@ -2,7 +2,7 @@
 
 copyright:
 years: 2022 - 2024
-lastupdated: "2024-07-15"
+lastupdated: "2024-07-29"
 title: "Installing the edge cluster agent"
 
 parent: Edge clusters
@@ -56,9 +56,12 @@ This content describes how to install the {{site.data.keyword.ieam}} agent on yo
 2. If you have not completed the steps in [Creating your API key](../hub/prepare_for_edge_nodes.md), do that now. This process creates an API key, locates some files, and gathers environment variable values that are needed when you set up edge nodes. Set the same environment variables for this edge cluster.  Set the `HZN_NODE_ID` of the edge cluster.
 
    ```bash
-   export HZN_EXCHANGE_USER_AUTH=iamapikey:<api-key>
    export HZN_ORG_ID=<your-exchange-organization>
-   export HZN_FSS_CSSURL=https://<management-hub-ingress>/edge-css/
+   export HZN_EXCHANGE_USER_AUTH=<authentication string>
+   export HZN_EXCHANGE_URL= # example http://open-horizon.lfedge.iol.unh.edu:3090/v1
+   export HZN_FSS_CSSURL= # example http://open-horizon.lfedge.iol.unh.edu:9443/
+   export HZN_AGBOT_URL= # example http://open-horizon.lfedge.iol.unh.edu:3111
+   export HZN_FDO_SVC_URL= # example http://open-horizon.lfedge.iol.unh.edu:9008/api
    export HZN_NODE_ID=<edge-cluster-node-name>
    ```
    {: codeblock}
@@ -248,9 +251,12 @@ This content describes how to install the {{site.data.keyword.ieam}} agent on [K
 2. If you have not completed the steps in [Creating your API key](../hub/prepare_for_edge_nodes.md), do that now. This process creates an API key, locates some files, and gathers environment variable values that are needed when setting up edge nodes. Set the same environment variables on this edge cluster:
 
    ```bash
-   export HZN_EXCHANGE_USER_AUTH=iamapikey:<api-key>
    export HZN_ORG_ID=<your-exchange-organization>
-   export HZN_FSS_CSSURL=https://<ieam-management-hub-ingress>/edge-css/
+   export HZN_EXCHANGE_USER_AUTH=<authentication string>
+   export HZN_EXCHANGE_URL= # example http://open-horizon.lfedge.iol.unh.edu:3090/v1
+   export HZN_FSS_CSSURL= # example http://open-horizon.lfedge.iol.unh.edu:9443/
+   export HZN_AGBOT_URL= # example http://open-horizon.lfedge.iol.unh.edu:3111
+   export HZN_FDO_SVC_URL= # example http://open-horizon.lfedge.iol.unh.edu:9008/api
    ```
    {: codeblock}
 

docs/installing/fdo.md

@@ -1,7 +1,7 @@
 ---
 copyright:
-years: 2020 - 2023
-lastupdated: "2023-07-01"
+years: 2020 - 2024
+lastupdated: "2024-07-29"
 title: "FDO agent install"
 
 parent: Edge devices info
@@ -51,9 +51,12 @@ Before you purchase FDO-enabled edge devices, you can test FDO support in {{site
 2. Contact your {{site.data.keyword.ieam}} administrator to get the values of these environment variables. (You need them in the next step.)
 
    ```bash
-   export HZN_ORG_ID=<exchange-org>
-   export HZN_EXCHANGE_USER_AUTH=iamapikey:<api-key>
-   export HZN_FDO_SVC_URL=https://<mgmt-hub-ingress>/edge-fdo-ocs/api
+   export HZN_ORG_ID=<your-exchange-organization>
+   export HZN_EXCHANGE_USER_AUTH=<authentication string>
+   export HZN_EXCHANGE_URL= # example http://open-horizon.lfedge.iol.unh.edu:3090/v1
+   export HZN_FSS_CSSURL= # example http://open-horizon.lfedge.iol.unh.edu:9443/
+   export HZN_AGBOT_URL= # example http://open-horizon.lfedge.iol.unh.edu:3111
+   export HZN_FDO_SVC_URL= # example http://open-horizon.lfedge.iol.unh.edu:9008/api
    export HZN_MGMT_HUB_CERT_PATH=<path-to-mgmt-hub-self-signed-cert>
    export CURL_CA_BUNDLE=$HZN_MGMT_HUB_CERT_PATH
    ```
@@ -73,9 +76,12 @@ If you have purchased FDO-enabled devices and want to incorporate them into your
    2. Contact your {{site.data.keyword.ieam}} administrator to get the values of these environment variables. (You need them in the next step.)
 
       ```bash
-      export HZN_ORG_ID=<exchange-org>
-      export HZN_EXCHANGE_USER_AUTH=iamapikey:<api-key>
-      export HZN_FDO_SVC_URL=https://<mgmt-hub-ingress>/edge-fdo-ocs/api
+      export HZN_ORG_ID=<your-exchange-organization>
+      export HZN_EXCHANGE_USER_AUTH=<authentication string>
+      export HZN_EXCHANGE_URL= # example http://open-horizon.lfedge.iol.unh.edu:3090/v1
+      export HZN_FSS_CSSURL= # example http://open-horizon.lfedge.iol.unh.edu:9443/
+      export HZN_AGBOT_URL= # example http://open-horizon.lfedge.iol.unh.edu:3111
+      export HZN_FDO_SVC_URL= # example http://open-horizon.lfedge.iol.unh.edu:9008/api
       export HZN_MGMT_HUB_CERT_PATH=<path-to-mgmt-hub-self-signed-cert>
       export CURL_CA_BUNDLE=$HZN_MGMT_HUB_CERT_PATH
       ```

docs/installing/many_install.md

@@ -1,7 +1,7 @@
 ---
 copyright:
 years: 2020 - 2024
-lastupdated: "2024-03-01"
+lastupdated: "2024-07-29"
 title: "Bulk agent install"
 
 parent: Edge devices info
@@ -38,7 +38,12 @@ Use the bulk installation process to set up multiple edge devices of similar typ
 
    ```bash
    export AGENT_TAR_FILE=agentInstallFiles-<edge-device-type>.tar.gz
-   export HZN_EXCHANGE_USER_AUTH=iamapikey:<api-key>
+   export HZN_ORG_ID=<your-exchange-organization>
+   export HZN_EXCHANGE_USER_AUTH=<authentication string>
+   export HZN_EXCHANGE_URL= # example http://open-horizon.lfedge.iol.unh.edu:3090/v1
+   export HZN_FSS_CSSURL= # example http://open-horizon.lfedge.iol.unh.edu:9443/
+   export HZN_AGBOT_URL= # example http://open-horizon.lfedge.iol.unh.edu:3111
+   export HZN_FDO_SVC_URL= # example http://open-horizon.lfedge.iol.unh.edu:9008/api
    ```
   {: codeblock}
 

docs/using_edge_services/removing_agent_from_cluster.md

@@ -2,7 +2,7 @@
 
 copyright:
 years: 2022 - 2024
-lastupdated: "2024-06-07"
+lastupdated: "2024-07-29"
 title: "Removing the agent from an edge cluster"
 
 parent: Edge clusters
@@ -33,7 +33,12 @@ To unregister an edge cluster and remove the {{site.data.keyword.ieam}} agent fr
 2. Export your Horizon exchange user credentials:
 
    ```bash
-   export HZN_EXCHANGE_USER_AUTH=iamapikey:<api-key>
+   export HZN_ORG_ID=<your-exchange-organization>
+   export HZN_EXCHANGE_USER_AUTH=<authentication string>
+   export HZN_EXCHANGE_URL= # example http://open-horizon.lfedge.iol.unh.edu:3090/v1
+   export HZN_FSS_CSSURL= # example http://open-horizon.lfedge.iol.unh.edu:9443/
+   export HZN_AGBOT_URL= # example http://open-horizon.lfedge.iol.unh.edu:3111
+   export HZN_FDO_SVC_URL= # example http://open-horizon.lfedge.iol.unh.edu:9008/api
    ```
    {: codeblock}