Issue open-horizon#3467 - MultiNamespace: document edge cluster multi…

agent-install/README.md

@@ -140,6 +140,10 @@ Command line flags override the corresponding environment variables or config fi
 
 `--container` - Install the agent in a container
 
+`--namespace` - The namespace that the cluster agent will be installed to. The default is 'openhorizon-agent'
+
+`--namespace-scoped` - The cluster agent will only have namespace scope. The default is 'false'
+
 ### anax-in-container
 
 To install more than 1 agent in a container, the horizon-container command is used (which is included with the horizon-cli package). Instructions can be found below:

docs/agent_in_multi_namespace.md

@@ -0,0 +1,29 @@
+---
+copyright:
+years: 2022 - 2023
+lastupdated: "2023-10-19"
+
+title: "Multi-namespace for cluster agent"
+
+parent: Agent (anax)
+nav_order: 21
+---
+# Overview
+
+Open Horizon supports two types of Edge cluster agents: cluster scope and namespace scope. 
+
+- Cluster agent with **cluster scope** has permission to deploy and manage cluster service in all namespaces inside the Kubernetes cluster. Only one agent with cluster scope can be installed per Kubernetes cluster.
+
+- Cluster agent with **namespace scope** only has permission to deploy and manage cluster service within its own namespace. one or multiple namespce-scoped cluster agents can be installed per Kubernetes cluster. Each cluster agent will need to be installed into its own namespace. 
+
+**Note**: It is not supported to install both **cluster-scoped** agent and **namespace-scoped** agent into same Kubernetes cluster.
+
+## Install Namespace Scoped Agent
+
+After configured the edge cluster (see [here](./cluster_install.md)) run `agent-install.sh` with `--namespace <namespace-to-install-agent>` and `--namespace-scoped`
+
+**Note**: `--namespace` is equivilant to environment variable `AGENT_NAMESPACE`
+
+```bash
+./agent-install.sh -D cluster -i anax: -c css: -k css: --namespace <namespace-to-install-agent> --namespace-scoped
+```

docs/built_in_policy.md

@@ -1,7 +1,7 @@
 ---
 copyright:
 years: 2022 - 2023
-lastupdated: "2023-02-05"
+lastupdated: "2023-10-19"
 title: "Policy Properties"
 description: Built in Policy Properties
 
@@ -38,6 +38,8 @@ The user-defined policies (deployment policy, model policy, service policy) need
 | openhorizon.hardwareId| the device serial number if it can be found (from /proc/cpuinfo). A generated Id otherwise. | `string` |
 | openhorizon.allowPrivileged| a property set to determine if privileged services may be run on this device. Can be set by user, default is false. This is the only writable node property | `boolean` |
 | openhorizon.kubernetesVersion| Kubernetes version of the cluster the agent is running in | `string` for example 1.18 |
+| openhorizon.kubernetesNamespace| Kubernetes cluster namespace that the cluster agent is running in | `string` for example openhorizon-agent |
+| openhorizon.kubernetesNamespaceScoped| If the cluster agent is with namespace scope | `boolean` |
 | openhorizon.operatingSystem | the operating system the agent is running on. If the agent is containerized, this will be the host os | `string` for example ubuntu |
 | openhorizon.containerized | this indicates if the agent is running in a container or natively | `boolean` |
 {: caption="Table 1. {{site.data.keyword.edge_notm}} built-in node properties" caption-side="top"}

docs/cluster_install.md

@@ -1,7 +1,7 @@
 ---
 copyright:
 years: 2022 - 2023
-lastupdated: "2022-01-29"
+lastupdated: "2023-10-19"
 
 title: "All-in-One cluster agent"
 
@@ -305,58 +305,61 @@ This content describes how to install the Open Horizon agent on k3s or microk8s
     chmod +x agent-install.sh
     ```
 
-5. The agent-install.sh script will store the Open Horizon agent in the edge cluster image registry. Set the full image path (minus the tag) that should be used.
+5. Instruct agent-install.sh to use the default storage class:
 
     On k3s:
 
     ```bash
-    REGISTRY_ENDPOINT=$(kubectl get service docker-registry-service | grep docker-registry-service | awk '{print $3;}'):5000
-    export IMAGE_ON_EDGE_CLUSTER_REGISTRY=$REGISTRY_ENDPOINT/openhorizon-agent/amd64_anax_k8s
+    export EDGE_CLUSTER_STORAGE_CLASS=local-path
     ```
 
     On microk8s:
 
     ```bash
-    export IMAGE_ON_EDGE_CLUSTER_REGISTRY=localhost:32000/openhorizon-agent/amd64_anax_k8s
+    export EDGE_CLUSTER_STORAGE_CLASS=microk8s-hostpath
     ```
 
-6. Instruct agent-install.sh to use the default storage class:
-
-    On k3s:
-
+6. Run agent-install.sh to get the necessary files from Github, install and configure the Horizon agent, and register your edge cluster with policy.
+
+    Set `AGENT_NAMESPACE` to the namespace that will install the cluster agent. If not set, the agent will be installed to `openhorizon-agent` default namespace
     ```bash
-    export EDGE_CLUSTER_STORAGE_CLASS=local-path
+    AGENT_NAMESPACE=<namespace-to-install-agent>
     ```
 
-    On microk8s:
-
+    To install a cluster-scoped agent: 
     ```bash
-    export EDGE_CLUSTER_STORAGE_CLASS=microk8s-hostpath
+    ./agent-install.sh -D cluster -i anax: -c css: -k css: --namespace $AGENT_NAMESPACE
     ```
 
-7. Run agent-install.sh to get the necessary files from Github, install and configure the Horizon agent, and register your edge cluster with policy.
-
+    To install a namespace-scoped agent:
     ```bash
-    ./agent-install.sh -D cluster -i anax: -c css: -k css:
+    ./agent-install.sh -D cluster -i anax: -c css: -k css: --namespace $AGENT_NAMESPACE --namespace-scoped
     ```
 
-8. Verify that the agent pod is running:
+7. Verify that the agent pod is running:
 
     ```bash
     kubectl get namespaces
+    kubectl -n $AGENT_NAMESPACE get pods
+    ```
+
+    If `AGENT_NAMESPACE` is not set in step 6, check agent pod in `openhorizon-agent`:
+    ```bash
     kubectl -n openhorizon-agent get pods
     ```
+    **Note**: See [here](./agent_in_multi_namespace.md) for more information about agent in multi-namespace.
+
 
-9. Use the following command to connect to a bash instance on the agent pod to execute hzn commands
+8. Use the following command to connect to a bash instance on the agent pod to execute hzn commands
 
     ```bash
-    kubectl exec -it $(kubectl get pod -l app=agent -n openhorizon-agent | grep "agent-" | cut -d " " -f1) -n openhorizon-agent -- bash
+    kubectl exec -it $(kubectl get pod -l app=agent -n openhorizon-agent | grep "agent-" | cut -d " " -f1) -n $AGENT_NAMESPACE -- bash
     ```
 
-10. As a test, execute the following hzn command on the agent pod:
+9. As a test, execute the following hzn command on the agent pod:
 
     ```bash
     hzn node ls
     ```
 
-11. The Open Horizon cluster agent is now successfully installed and ready to deploy services
+10. The Open Horizon cluster agent is now successfully installed and ready to deploy services

docs/deployment_policy.md

@@ -1,7 +1,7 @@
 ---
 copyright:
 years: 2022 - 2023
-lastupdated: "2023-02-05"
+lastupdated: "2023-10-19"
 title: "Deployment Policy"
 description: Description of Deployment policy json fields
 
@@ -36,6 +36,7 @@ Following are the fields in the JSON representation of a deployment policy:
   - `name`: The name (URL) of a service to be deployed. This is the same value as found in the `url` field [here](./service_def.md).
   - `org`: The organization in which the service in `name` is defined.
   - `arch`: The hardware architecture of the service in `name`, or `*` to indicate any compatible architecture. This is the same value as found in the `arch` field [here](./service_def.md).
+  - `clusterNamespace`: Namespace that this service will be deployed to. Only apply to cluster service.
   - `serviceVersions`: A list of versions of the service. At least one version must be specified.
     - `version`: One of the versions of the service in `name`. This is the same value as found in the `version` field [here](./service_def.md).
     - `priority`: The relative priority of deploying this version over another version in the list of service versions.

docs/secrets.md

@@ -1,7 +1,7 @@
 ---
 copyright:
 years: 2022 - 2023
-lastupdated: "2023-02-05"
+lastupdated: "2023-11-20"
 title: "Secrets"
 description: Secrets Management