docs(borealis): DOC-517 update helm chart and parameters (#1136)

content/en/armory-enterprise/installation/aurora-install.md

@@ -12,6 +12,7 @@ aliases:
 {{% include "aurora-borealis/borealis-ea-banner.md" %}}
 {{< /alert >}}
 
+> If you installed an older version of the Remote Network Agent (RNA) using the Helm chart in `armory/aurora`, migrate to the new version by updating the Helm chart that is used. For more information, see [Migrate to the new RNA](#migrate-to-the-new-rna).
 
 ## Overview
 
@@ -78,14 +79,9 @@ Register your Armory Enterprise environment so that it can communicate with Armo
 3. In the left navigation menu, select **Access Management > Client Credentials**.
 4. In the upper right corner, select **New Credential**.
 5. Create a credential for your RNA. Use a descriptive name for the credential, such as `us-west RNA`
-6. Set the permission scope by selecting the preconfigured scope group **Custom Spinnaker**, which assigns the minimum required credentials for Aurora to work:
+6. Set the permission scope to `connect:agentHub`.
 
-   - `manage:deploy`
-   - `read:infra:data`
-   - `exec:infra:op`
-   - `read:artifacts:data`
-
-   > Note that removing a preconfigured scope group does not deselect the permissions that the group assigned. You must remove the permissions manually.
+   > Removing a preconfigured scope group does not deselect the permissions that the group assigned. You must remove the permissions manually.
 
 7. Note both the **Client ID** and **Client Secret**. You need these values when configuring the Remote Network Agent or other services that you want to use to interact with Aurora and Armory's hosted cloud services. Make sure to store the secret somewhere safe. You are not shown the value again.
 
@@ -95,46 +91,23 @@ This section walks you through installing the Remote Network Agent (RNA) using a
 
 {{< include "aurora-borealis/rna-install.md" >}}
 
+### Migrate to the new RNA 
 
+You do not need to do this migration if you are installing the RNA for the first time.
 
+{{< include "aurora-borealis/borealis-rna-wormhole-migrate.md" >}}
 
-If your Armory Enterprise (Spinnaker) environment is behind an HTTPS proxy, you need to configure HTTPS proxy settings.
-
-<details><summary>Learn more</summary>
-
-To set an HTTPS proxy, use the following config:
-
-```yaml
-env[0].name=”HTTPS_PROXY”,env[0].value="<hostname>:<port>"
-```
-
-You can include the following snippet in your `helm install` command:
-
-```yaml
---set env[0].name=”HTTPS_PROXY”,env[0].value="<hostname>:<port>"
-```
-
-Alternatively, you can create a `values.yaml` file to include the parameters:
-
-```yaml
-env:
-  - name: HTTPS_PROXY
-    value: <hostname>:<port>
-```
-With the file, you can configure multiple configs in addition to the `env` config in your `helm install` command. Instead of using `--set`, include the `--values` parameter as part of the Helm install command:
-
-```
---values=<path>/values.yaml
-```
+### Verify the Agent deployment
 
-</details>
+Go to the [Agents page in the Configuration UI](https://console.cloud.armory.io/configuration/agents) and verify the connection. If you do not see your cluster, verify that you are in the correct Armory Cloud environment.
 
+> Note that you may see a "No Data message" when first loading the Agent page.
 
+{{< figure src="/images/borealis/borealis-ui-rna-status.jpg" alt="The Connected Remote Network Agents page shows connected agents and the following information: Agent Identifier, Agent Version, Connection Time when the connection was established, Last Heartbeat time, Client ID, and IP Address." >}}
 
 
-### Verify the Agent deployment
 
-In the target deployment cluster, examine the Agent logs.
+If you do not see the RNA for your target deployment cluster, check the logs for the target deployment cluster to see if the RNA is up and running.
 
 You should see messages similar to the following that show your client ID and your account getting registered in the Armory Cloud Hub:
 

content/en/borealis/Reference/ref-deployment-file.md

@@ -73,9 +73,9 @@ targets:
 
 ### `targets.<targetName>.account`
 
-The account name that a target Kubernetes cluster got assigned when you installed the Remote Network Agent (RNA) on it. Specifically, it is the value for the `agent-k8s.accountName` parameter.
+The account name that a target Kubernetes cluster got assigned when you installed the Remote Network Agent (RNA) on it. Specifically, it is the value for the `agentIdentifier` parameter. Note that older versions of the RNA used the `agent-k8s.accountName` parameter.
 
-This name must match an existing cluster because Borealis uses the account name to determine which cluster to deploy to.
+This name must match an existing cluster because Borealis uses the identifier to determine which cluster to deploy to.
 
 For example, this snippet configures a deployment to an environment named `prod` that is hosted on a cluster named `prod-cluster-west`:
 

content/en/borealis/_index.md

@@ -9,11 +9,23 @@ Project Borealis uses Armory's hosted cloud services to deploy Kubernetes applic
 
 Borealis supports performing canary deployments. The canary deployment strategy deploys an app progressively to your cluster based on a set of steps that you configure. You set weights (percentage thresholds) for how the deployment should progress and a pause after each weight is met. Borealis works through these steps until your app is fully deployed. For example, you can deploy the new version of your app to 25% of your target cluster and then wait for a manual judgement or a configurable amount of time. This pause gives you time to assess the impact of your changes. From there, either continue the deployment to the next weight you set or roll back the deployment if you notice an issue.
 
-Using Borealis involves two parts:
+## Terminology
+
+To help you understand how Borealis works, familiarize yourself with the following terms:
+
+- **Environment**: environments are used in two ways for Borealis, depending on the context.
+  - **Cloud Console**: the Borealis backend and UI use environments to isolate users and secrets. Users and secrets for one environment do not have access to other environments. That means a user in environment A cannot access secrets or deployments in environment B.
+  - **Deployments**: for deployments, an environment is the collection of configs that you configure to tailor the deployment. It consists of characteristics that define how you deploy your app, including the  target Kubernetes cluster, namespace, deployment strategy, and constraints (dependencies). For example, if you create a `prod` environment for your deployment, you can make it dependent on a `dev` environment and add a deployment strategy that protects `prod` untested changes.
+- **Deployment/deploy file**: the deployment file is a YAML file that you use to define where you want to deploy to (the environments), what  you want to deploy (the manifests), and how you want to deploy (the strategy). You can generate a template for the file using the Borealis CLI. For more information, see the [Deployment File Reference]({{< ref "ref-deployment-file" >}}).
+
+## Using Borealis
+
+To start, review the [Requirements]({{< ref "borealis-requirements" >}}) and (optionally), the [Architecture]({{< ref "architecture-borealis" >}}).
+
+Once you're ready, using Borealis involves two parts:
 
 1. Preparing your deployment target as described in [Get Started with Project Borealis]({{< ref "borealis-org-get-started" >}}). This ony needs to be done once per deployment target.
-2. Using the Borealis CLI to deploy your app, either manually or programmatically.
+2. Using the Borealis CLI to deploy your app, either manually or programmatically. To learn more, see [Get Started with the CLI to Deploy Apps]({{< ref "borealis-cli-get-started" >}}).
 
 You can do the whole deployment process using the Borealis CLI directly while you are working on defining how you want to deploy apps. When you're ready to scale, integrate Borealis with your existing tools (such as GitHub or Jenkins) to deploy programmatically.
 
-To start, review the [Requirements]({{< ref "borealis-requirements" >}}).

content/en/borealis/borealis-automate/borealis-gh-action.md

@@ -81,95 +81,22 @@ Generate a deployment file with the following command:
 armory template kubernetes canary > deployment.yaml
 ```
 
-#### Manually create
+#### Manually create the file
 
-```yaml
-version: v1
-kind: kubernetes
-application: <appName>
-# Map of Deployment target
-targets:
- # A name for this deployment.
-  <deploymentName>: 
-    # The account name that a deployment target cluster got assigned when you installed the Remote Network Agent (RNA) on it.
-    account: <accountName>
-    # Optionally, override the namespaces that are in the manifests
-    namespace:
-    # This is the key that references a strategy you define under in the `strategies.<strategyName>` section of the file.
-    strategy: <strategyName>
-# The list of manifests sources
-manifests:
-  # A directory containing multiple manifests. Instructs Borealis to read all yaml|yml files in the directory and deploy all manifests to the target defined in    `targets`.
-  - path: /path/to/manifest/directory
-  # A specific manifest file
-  - path: /path/to/specific/manifest.yaml
-# The map of strategies that you can use to deploy your app.
-strategies:
-  # The name for a strategy. You select one to use with the `targets.strategy` key.
-  <strategyName>:
-    # The deployment strategy type. As part of the early access program, Borealis supports `canary`.
-    canary:
-      # List of canary steps
-      steps:
-        # The map key is the step type. First configure `setWeight` for the weight (how much of the cluster the app should deploy to for a step).
-        - setWeight:
-            weight: <integer> # Deploy the app to <integer> percent of the cluster as part of the first step. `setWeight` is followed by a `pause`.
-        - pause: # `pause` can be set to a be a specific amount of time or to a manual approval.
-            duration: <integer> # How long to wait before proceeding to the next step.
-            unit: seconds # Unit for duration. Can be seconds, minutes, or hours.
-        - setWeight:
-            weight: <integer> # Deploy the app to <integer> percent of the cluster as part of the second step
-        - pause:
-            untilApproved: true # Pause the deployment until a manual approval is given. You can approve the step through the CLI or Status UI.
+<details><summary>Show me the template file</summary>
+
+{{< include "aurora-borealis/borealis-yaml.md" >}}
+
+</details>
 
-```
 
 Note that you do not need to configure a `setWeight` step for `100`. Borealis automatically rolls out the deployment to the whole cluster after completing the final step you configure.
 
-#### Example deployment file
+### Example deployment file
 
 <details><summary>Show me an example deployment file</summary>
 
-```yaml
-version: v1
-kind: kubernetes
-application: ivan-nginx
-# Map of deployment target
-targets:
-  # A descriptive name for the deployment
-  dev-west: 
-    # The account name that a deployment target cluster got assigned when you installed the Remote Network Agent (RNA) on it.
-    account: cdf-dev
-    # Optionally, override the namespaces that are in the manifests
-    namespace: cdf-dev-agent
-    # This is the key that references a strategy you define under the strategies section of the file.
-    strategy: canary-wait-til-approved
-# The list of manifests sources
-manifests:
-  # A directory containing multiple manifests. Instructs Borealis to read all yaml|yml files in the directory and deploy all manifests to the target defined in    `targets`.
-  - path: /deployments/manifests/configmaps
-  # A specific manifest file that gets deployed to the target defined in `targets`.
-  - path: /deployments/manifests/deployment.yaml
-# The map of strategies that you can use to deploy your app.
-strategies:
-  # The name for a strategy, which you use for the `strategy` key to select one to use.
-  canary-wait-til-approved:
-    # The deployment strategy type. As part of the early access program, Borealis supports `canary`.
-    canary:
-      # List of canary steps
-      steps:
-      # The map key is the step type. First configure `setWeight` for the weight (how much of the cluster the app should deploy to for a step).
-      - setWeight:
-        - setWeight:
-            weight: 33 # Deploy the app to 33% of the cluster.
-        - pause: 
-            duration: 60 # Wait 60 seconds before starting the next step.
-            unit: seconds
-        - setWeight:
-            weight: 66 # Deploy the app to 66% of the cluster.
-        - pause:
-            untilApproved: true # Wait until approval is given through the Borealis CLI or Status UI.
-```
+{{< include "aurora-borealis/borealis-yaml-example.md" >}}
 
 </details>
 
@@ -229,6 +156,8 @@ To see the deployment ID and the Status UI link, perform the following steps:
 3. Select the GitHub Action. This is the `name` parameter you used in the `jobs` block.
 4. In the **Deployment** section, you can find the **Deployment ID** and a link to the **deployment status UI**.
 
+{{< figure src="/images/borealis/borealis-gha-statusUI.jpg" alt="" >}}
+
 ### Borealis CLI
 
 ```bash

content/en/borealis/borealis-requirements.md

@@ -29,6 +29,6 @@ You need a Kubernetes cluster to act as the deployment target for your app. The
 | Protocol                    | DNS                                                                    | Port | Used By           | Notes                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                     |
 |-----------------------------|------------------------------------------------------------------------|------|-------------------|---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
 | HTTPS                       | api.cloud.armory.io                      | 443  | Spinnaker         | **Armory Cloud REST API**<br><br>Used fetch information from the Kubernetes cache                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                         |
-| TLS enabled gRPC over HTTP2 | agents.cloud.armory.io                | 443  | Spinnaker, Agents | **Armory Cloud Agent-Hub**<br><br>Used to connect agents to the Agent Hub through encrypted long-lived gRPC HTTP2 connections. The connections are used for bi-directional communication between Armory Enterprise or Armory Cloud Services and any target Kubernetes clusters.<br><br>This is needed so that Armory Cloud Services can interact with a your private Kubernetes APIs, orchestrate deployments, and cache data for Armory Enterprise without direct network access to your Kubernetes APIs.<br><br>Agents send data about deployments, replica-sets, and related data to Armory Cloud's Agent Cache to power infrastructure management experiences, such as the Project Aurora Plugin. |
+| TLS enabled gRPC over HTTP2 | agent-hub.cloud.armory.io                | 443  | Agents | **Armory Cloud Agent-Hub**<br><br>Used to connect agents to the Agent Hub through encrypted long-lived gRPC HTTP2 connections. The connections are used for bi-directional communication between Armory Enterprise or Armory Cloud Services and any target Kubernetes clusters.<br><br>This is needed so that Armory Cloud Services can interact with a your private Kubernetes APIs, orchestrate deployments, and cache data for Armory Enterprise without direct network access to your Kubernetes APIs.<br><br>Agents send data about deployments, replica-sets, and related data to Armory Cloud's Agent Cache to power infrastructure management experiences, such as the Project Aurora Plugin. |
 | HTTPS                       | auth.cloud.armory.io                    | 443  | Spinnaker, Agents | **Armory’s OIDC authorization server**<br><br>Used to exchange the client ID and secret for a Java Web Token () to verify identity.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                     |
 | HTTPS                       | github.com                                        | 443  | Spinnaker         | **Github**<br><br>Used to download official Armory plugins at startup time.