From 3f171a8b650b3bacb00250a76478014f06420926 Mon Sep 17 00:00:00 2001 From: brian-armory <53799971+brian-armory@users.noreply.github.com> Date: Fri, 4 Feb 2022 13:22:45 -0800 Subject: [PATCH] docs(borealis): DOC-517 update helm chart and parameters (#1136) --- .hugo_build.lock | 0 .../installation/aurora-install.md | 49 +++------- .../borealis/Reference/ref-deployment-file.md | 4 +- content/en/borealis/_index.md | 18 +++- .../borealis-automate/borealis-gh-action.md | 91 ++---------------- content/en/borealis/borealis-requirements.md | 2 +- content/en/borealis/borealis-status-ui.md | 10 -- content/en/borealis/not-a-real-page.md | 91 ++++++++++++++++++ .../quick-start/borealis-cli-get-started.md | 2 +- .../quick-start/borealis-org-get-started.md | 53 +++++++--- content/en/borealis/ui/_index.md | 10 ++ .../borealis/ui/borealis-configuration-ui.md | 59 ++++++++++++ content/en/borealis/ui/borealis-status-ui.md | 41 ++++++++ .../aurora-borealis/borealis-client-creds.md | 2 +- .../borealis-rna-wormhole-migrate.md | 24 +++++ .../includes/aurora-borealis/rna-install.md | 53 ++++++---- .../images/borealis/borealis-gha-statusUI.jpg | Bin 0 -> 1947421 bytes .../borealis/borealis-multitarget-deploy.jpg | Bin 0 -> 361405 bytes .../borealis/borealis-ui-constraints.jpg | Bin 0 -> 354780 bytes .../borealis/borealis-ui-fulldetails.jpg | Bin 0 -> 268447 bytes .../borealis/borealis-ui-rna-status.jpg | Bin 0 -> 234861 bytes 21 files changed, 340 insertions(+), 169 deletions(-) create mode 100644 .hugo_build.lock delete mode 100644 content/en/borealis/borealis-status-ui.md create mode 100644 content/en/borealis/not-a-real-page.md create mode 100644 content/en/borealis/ui/_index.md create mode 100644 content/en/borealis/ui/borealis-configuration-ui.md create mode 100644 content/en/borealis/ui/borealis-status-ui.md create mode 100644 content/en/includes/aurora-borealis/borealis-rna-wormhole-migrate.md create mode 100644 static/images/borealis/borealis-gha-statusUI.jpg create mode 100644 static/images/borealis/borealis-multitarget-deploy.jpg create mode 100644 static/images/borealis/borealis-ui-constraints.jpg create mode 100644 static/images/borealis/borealis-ui-fulldetails.jpg create mode 100644 static/images/borealis/borealis-ui-rna-status.jpg diff --git a/.hugo_build.lock b/.hugo_build.lock new file mode 100644 index 00000000..e69de29b diff --git a/content/en/armory-enterprise/installation/aurora-install.md b/content/en/armory-enterprise/installation/aurora-install.md index 8f7cc66e..30bf568f 100644 --- a/content/en/armory-enterprise/installation/aurora-install.md +++ b/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. - -
Learn more - -To set an HTTPS proxy, use the following config: - -```yaml -env[0].name=”HTTPS_PROXY”,env[0].value=":" -``` - -You can include the following snippet in your `helm install` command: - -```yaml ---set env[0].name=”HTTPS_PROXY”,env[0].value=":" -``` - -Alternatively, you can create a `values.yaml` file to include the parameters: - -```yaml -env: - - name: HTTPS_PROXY - value: : -``` -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=/values.yaml -``` +### Verify the Agent deployment -
+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: diff --git a/content/en/borealis/Reference/ref-deployment-file.md b/content/en/borealis/Reference/ref-deployment-file.md index 6d8c30be..9e8c89b3 100644 --- a/content/en/borealis/Reference/ref-deployment-file.md +++ b/content/en/borealis/Reference/ref-deployment-file.md @@ -73,9 +73,9 @@ targets: ### `targets..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`: diff --git a/content/en/borealis/_index.md b/content/en/borealis/_index.md index 12f5ec5a..0caf17f9 100755 --- a/content/en/borealis/_index.md +++ b/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" >}}). \ No newline at end of file diff --git a/content/en/borealis/borealis-automate/borealis-gh-action.md b/content/en/borealis/borealis-automate/borealis-gh-action.md index 649de9c0..0c0131ed 100644 --- a/content/en/borealis/borealis-automate/borealis-gh-action.md +++ b/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: -# Map of Deployment target -targets: - # A name for this deployment. - : - # The account name that a deployment target cluster got assigned when you installed the Remote Network Agent (RNA) on it. - account: - # Optionally, override the namespaces that are in the manifests - namespace: - # This is the key that references a strategy you define under in the `strategies.` section of the file. - strategy: -# 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. - : - # 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: # Deploy the app to 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: # How long to wait before proceeding to the next step. - unit: seconds # Unit for duration. Can be seconds, minutes, or hours. - - setWeight: - weight: # Deploy the app to 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. +
Show me the template file + +{{< include "aurora-borealis/borealis-yaml.md" >}} + +
-``` 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
Show me an example deployment file -```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" >}}
@@ -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 diff --git a/content/en/borealis/borealis-requirements.md b/content/en/borealis/borealis-requirements.md index afb0f6a6..d7615894 100755 --- a/content/en/borealis/borealis-requirements.md +++ b/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**

Used fetch information from the Kubernetes cache | -| TLS enabled gRPC over HTTP2 | agents.cloud.armory.io | 443 | Spinnaker, Agents | **Armory Cloud Agent-Hub**

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.

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.

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**

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.

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.

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**

Used to exchange the client ID and secret for a Java Web Token () to verify identity. | | HTTPS | github.com | 443 | Spinnaker | **Github**

Used to download official Armory plugins at startup time. \ No newline at end of file diff --git a/content/en/borealis/borealis-status-ui.md b/content/en/borealis/borealis-status-ui.md deleted file mode 100644 index 1fe9e3fe..00000000 --- a/content/en/borealis/borealis-status-ui.md +++ /dev/null @@ -1,10 +0,0 @@ ---- -title: Borealis Status UI -linktitle: Status UI -description: > - Use the Borealis Status UI to interact with and monitor your app deployments, including approving next steps or performing rollbacks. -exclude_search: true -weight: 40 ---- - -Description coming soon! \ No newline at end of file diff --git a/content/en/borealis/not-a-real-page.md b/content/en/borealis/not-a-real-page.md new file mode 100644 index 00000000..b356fc7b --- /dev/null +++ b/content/en/borealis/not-a-real-page.md @@ -0,0 +1,91 @@ +--- +title: Fake page to watch changes +linkTitle: +weight: 99999 +summary: "This is not a real page. It's a draft file I use to update include files so that they render in builds dynamically." +draft: true +--- + +Each Kubernetes cluster that you install the RNA on should have a unique name that you set using the `agentIdentifier` parameter. This identifier is used to identify the cluster. Note that older versions of the RNA used the `agent-k8s.accountName` parameter for this. + +1. Verify that you are in the correct Kubernetes context. The RNA is installed in the target deployment cluster. + +2. Add the Armory Helm repo: + + ```bash + helm repo add armory https://armory.jfrog.io/artifactory/charts + ``` + + You only need to do this once. + +3. Refresh the repo cache: + + ```bash + helm repo update + ``` + +4. Create the namespace where the RNA gets installed: + + ```bash + kubectl create ns armory-rna + ``` + +5. Create secrets from your client ID and client secret: + + ```bash + kubectl --namespace armory-rna create secret generic rna-client-credentials --type=string --from-literal=client-secret= --from-literal=client-id= + ``` + + The examples use Kubernetes secrets to encrypt the value. You supply the encrypted values in the Helm command to install the RNA. + +6. Install the Helm chart. Keep the following in mind when you install the RNA: + + * The `agentIdentifier` option is the name that is used to refer to the deployment target cluster, so use a descriptive name. + + ```bash + helm upgrade --install armory-rna armory/remote-network-agent \ + --set agentIdentifier= \ + --set clientId=encrypted:k8s!n:rna-client-credentials!k:client-id \ + --set clientSecret=encrypted:k8s!n:rna-client-credentials!k:client-secret \ + --namespace armory-rna + ``` + + The encrypted values for `clientId` and `clientSecret` reference the Kubernetes secrets you generated in an earlier step. + + For advanced use cases such as proxy configurations, custom annotations, labels, or environment variables, see the [`values.yaml` for the RNA](https://github.com/armory-io/remote-network-agent-helm-chart/blob/master/values.yaml?rgh-link-date=2022-02-02T22%3A38%3A35Z). For information about using a `values file`, see the [Helm documentation](https://helm.sh/docs/chart_template_guide/values_files/). + +7. Verify the RNA connection. Go to the [Agents page](https://console.cloud.armory.io/configuration/agents) in the Configuration UI UI, and look for the Agent identifier you assigned to your target deployment cluster. You should see it along with some basic information: + + > 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." >}} + + 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. + + +## Migrate to the new RNA + +1. Check to see if you are running the old iteration of Agent. Run `helm list`. If the command returns `armory/aurora` for the Helm chart name, you need to update. +2. Navigate to the [Machine to Machine Client Credentials](https://console.cloud.armory.io/configuration/credentials) page in the Cloud Console. +3. Verify the permissions for the client credentials you are using for your deployment targets. They must have the `connect:agentHub` scope. This permission is used to connect the RNA endpoint. +4. Verify that you are in the correct Kubernetes context. The context should be for the deployment target cluster. +5. If you installed the RNA by providing your `clientID` and `clientSecret` in plaintext, now is a good time to update those values to use a secret engine. + + Run the following command to encrypt your client ID and client secret using Kubernetes secrets: + + ```bash + kubectl --namespace armory-rna create secret generic rna-client-credentials --type=string --from-literal=client-secret= --from-literal=client-id= + ``` +6. Change the Helm chart that is being used: + + ```bash + helm repo update + helm upgrade armory-rna armory/remote-network-agent \ + --set agent-k8s.clientId='encrypted:k8s!n:rna-client-credentials!k:client-id' \ + --set agent-k8s.clientSecret='encrypted:k8s!n:rna-client-credentials!k:client-secret' \ + --namespace armory-rna + ``` + + The encrypted values for `clientId` and `clientSecret` reference the Kubernetes secrets you generated in an earlier step. + + If you encounter the following error, make sure you specify the namespace in your Helm command: `Error: UPGRADE FAILED: "armory-rna" has no deployed releases.` \ No newline at end of file diff --git a/content/en/borealis/quick-start/borealis-cli-get-started.md b/content/en/borealis/quick-start/borealis-cli-get-started.md index 440e8e1c..7ff41df1 100644 --- a/content/en/borealis/quick-start/borealis-cli-get-started.md +++ b/content/en/borealis/quick-start/borealis-cli-get-started.md @@ -176,7 +176,7 @@ If this is the first deployment of your app, Borealis automatically deploys the - `application`: The name of your app. - `targets.`: A descriptive name for your deployment. Armory recommends using the environment name. - - `targets..account`: The name of the deployment target cluster. This is the name that was assigned to the cluster using the `agent-k8s.accountName` parameter when you installed the RNA. + - `targets..account`: The name of the deployment target cluster. This is the name that was assigned to the cluster using the `agentIdentifier` parameter when you installed the RNA. Note that older versions of the RNA used the `agent-k8s.accountName` parameter. - `targets..strategy`: the name of the deployment strategy you want to use. You define the strategy in `strategies.`. - `manifests`: a map of manifest locations. This can be a directory of `yaml (yml)` files or a specific manifest. Each entry must use the following convention: `- path: /path/to/directory-or-file` - `strategies.`: the list of your deployment strategies. Use one of these for `targets..strategy`. Each strategy in this section consists of a map of steps for your deployment strategy in the following format: diff --git a/content/en/borealis/quick-start/borealis-org-get-started.md b/content/en/borealis/quick-start/borealis-org-get-started.md index b73071c4..e2d4c971 100644 --- a/content/en/borealis/quick-start/borealis-org-get-started.md +++ b/content/en/borealis/quick-start/borealis-org-get-started.md @@ -6,6 +6,8 @@ description: > exclude_search: true --- +> 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). + ## {{% heading "prereq" %}} Review the requirements for using Borealis on the [Requirements]({{< ref "borealis-requirements.md" >}}) page. @@ -14,28 +16,54 @@ Review the requirements for using Borealis on the [Requirements]({{< ref "boreal {{< include "aurora-borealis/borealis-login-creds" >}} -Every user who wants to deploy to your clusters using Borealis must have an account. For information about inviting users, see [Invite users](#invite-users). +Every user who wants to deploy to your clusters using Borealis must have an account. For information about inviting users, see [Invite users]({{< ref "borealis-configuration-ui#invite-users" >}}). + +## Prepare your deployment target + + -## Create client credentials +You need to manually install the Remote Network Agent (RNA) to the target deployment cluster. Borealis uses the RNA on your deployment target to communicate with Armory's hosted cloud services and to initiate the deployment. -After you create an account, you can create machine-to-machine client credentials for the various service accounts that you will need. These credentials are machine credentials that are meant for authentication when using Borealis programmatically. The credentials consist of a client ID and a client secret. Make sure to keep the secret somewhere safe. You cannot retrieve secrets that you lose access to. You would need to create a new set of credentials and update any services that used the credentials that you are replacing. +### Create client credentials + + + +Create machine-to-machine client credentials for the various service accounts that you will need. These credentials are machine credentials that are meant for authentication when using Borealis programmatically. The credentials consist of a client ID and a client secret. Make sure to keep the secret somewhere safe. You cannot retrieve secrets that you lose access to. You would need to create a new set of credentials and update any services that used the credentials that you are replacing. > Armory recommends creating separate credentials for each cluster or service. -To get started, you need at least one service account to use for authentication between Borealis and your deployment target where a Remote Network Agent (RNA) is installed. For example, if you want to run the Borealis CLI in a Jenkins pipeline, create credentials for the deployment target and for the service account that you use with Jenkins. +To get started, you need at least one service account to use for authentication between Borealis and your deployment target where a Remote Network Agent (RNA) is installed. -To start, create the client credentials for the RNA on your deployment target: +Create the client credentials for the RNA on your deployment target: {{< include "aurora-borealis/borealis-client-creds.md" >}} -## Prepare your deployment target + -> Note that this step requires Helm. +### Install the RNA -Borealis uses the RNA on your deployment target to communicate with Armory's hosted cloud services and to initiate the deployment. Use the provided Helm command to install and configure the RNA. + {{< include "aurora-borealis/rna-install.md" >}} + + + ## Next steps Now that Borealis is configured for your deployment target, you can either try out deploying a sample app or invite more users. @@ -44,11 +72,8 @@ Now that Borealis is configured for your deployment target, you can either try o Use the [Borealis Quickstart CLI Guide]({{< ref "borealis-cli-get-started.md" >}}) to learn how to manually deploy an app using the Borealis CLI. -### Invite users +## Migrate to the new RNA -For your users to get access to Borealis, you must invite them to your organization. This grants them access to the Cloud Console and the Status UI. +You do not need to do this migration if you are installing the RNA for the first time. -1. Navigate to the Cloud Console: https://console.cloud.armory.io. -2. In the left navigation, go to **Users** and select **Invite User**. -3. Provide the name and email address for the user you want to invite. -4. Send the inviation. \ No newline at end of file +{{< include "aurora-borealis/borealis-rna-wormhole-migrate.md" >}} \ No newline at end of file diff --git a/content/en/borealis/ui/_index.md b/content/en/borealis/ui/_index.md new file mode 100644 index 00000000..707e241c --- /dev/null +++ b/content/en/borealis/ui/_index.md @@ -0,0 +1,10 @@ +--- +title: Borealis UI Overview +linkTitle: UI Overview +description: > + The Borealis UI has two main uses. You can monitor the status of your deployments and perform administrative tasks such as user and secrets management. +exclude_search: true +weight: 40 +aliases: + - /borealis/borealis-status-ui/ +--- diff --git a/content/en/borealis/ui/borealis-configuration-ui.md b/content/en/borealis/ui/borealis-configuration-ui.md new file mode 100644 index 00000000..332a3e77 --- /dev/null +++ b/content/en/borealis/ui/borealis-configuration-ui.md @@ -0,0 +1,59 @@ +--- +title: Configuration UI +description: > + Administer your Borealis instance, including inviting users, managing deployment targets, and generating secrets. +exclude_search: true +--- + + +## Access Management + +### Manage secrets + +[**Access Management > Client Credentials**](https://console.cloud.armory.io/configuration/credentials) + +Manage the secrets that you use for the Remote Network Agent (RNA) and to grant programmatic access to Borealis, such as when you configure the GitHub Action. + +Note that secrets are Armory Cloud environment specific. + +### Invite users + +[**Access Management > Users**](https://console.cloud.armory.io/configuration/users) + +For your users to get access to Borealis, you must invite them to your organization. This grants them access to the Borealis UI. Depending on their permissions, they may have access to the **Configuration UI** and the **Status UI**. + +You need their name and email. Note that the email domain must match your organization's format. For example, users that work for Acme (which uses `username@acme.com`) must have `@acme.com` email addresses. They are automatically added to your organization once they accept the invite and complete the sign up. + +1. Navigate to the Cloud Console: https://console.cloud.armory.io/configuration/users. +2. Provide the name and email address for the user you want to invite. +3. Send the invitation. + +They can access the UI after completing the signup process. + + +## Networking + +### Monitor connected agents + +[**Networking > Agents**](https://console.cloud.armory.io/configuration/agents) + +The **Agents** page shows you the list of agents that are connected if the credentials they use have the `connect:agentHub` scope. + +If you have not migrated from the old agent that uses the `armory/aurora` Helm chart, your RNA connections do not show up on this page. For information about how upgrading to the new RNA, see [Migrate to the new RNA]({{< ref "borealis-org-get-started#migrate-to-the-new-rna" >}}). + +> Note that you may see a "No Data" message when first loading the **Agents** page even if there are successfully connected RNAs. + +The Agent Hub (Armory's hosted cloud service) and the RNA on your clusters perform periodic healthchecks to ensure that the connection between the Agent Hub and your target deployment cluster is working. If the healthcheck fails, the RNA is removed from the list. When a subsequent check passes, the RNA and its cluster are added back to the list with the **Connected At** column showing when the connection was re-established. + +{{< 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." >}} diff --git a/content/en/borealis/ui/borealis-status-ui.md b/content/en/borealis/ui/borealis-status-ui.md new file mode 100644 index 00000000..69b3274e --- /dev/null +++ b/content/en/borealis/ui/borealis-status-ui.md @@ -0,0 +1,41 @@ +--- +title: Armory Deployments Status UI +linkTitle: Status UI +description: > + Monitor the status of your deployments and approve or rollback deployments. +exclude_search: true +--- + + +## Deployment Status UI + +When you navigate to the **Armory Deployments** tab of the UI, you land on the **All Deployments** page, which shows all the apps for a specific Armory Cloud environment. If you don't see a deployment that you're expecting to see, refresh the list or verify the Armory Cloud environment the app belongs to. You can switch environments in the top right menu by clicking on your username. + +On the **All Deployments** page, you can select a specific app to get more details on that app's deployments. This brings up a status pane with basic information that includes the following: + +- Who started the most recent deployment for an app +- When the deployment started +- Deployment health +- Progress and status for the deployment, such as if it is waiting for approval + +Select **See Full Details** from the status pane on the **All Deployments**, you arrive on the **All Environments** page, which shows all the environments that are part of that deploy file. If a deploy file only contains one environment, you'll only see one on this page. + +You can watch a [demo](https://s.armory.io/BludOJBo) of how the All Deployments page and the details page for a single environment work together to walk you through progressing your deployment. + +### All environments + +The **All Deployments** page shows you all environments that are being deployed to in a single deploy file. If you click the link that the CLI returns when you trigger the deployment, this is the page you are linked to. It can give you a general idea of the state of the deployment and what environment is currently being deployed to. + +{{< figure src="/images/borealis/borealis-multitarget-deploy.jpg" alt="The deployment starts in a dev environment. It then progresses to infosec and staging environments simultaneously. It finishes by deploying to a prod-west environment." >}} + +More specifically, this view shows you how deployments are supposed to progress through different environments based on the constraints that are defined in the deploy file. An environment that is waiting for one or more constraints to be satisfied is connected to the preceding deployment by a dotted line and is greyed out. + +{{< figure src="/images/borealis/borealis-ui-constraints.jpg" alt="The staging-west environment has constraints that prevent it from starting until they are satisfied." >}} + +Clicking on a specific environment brings up a status pane with basic information about that environment. From here, you can see the **Full Details** for that single environment where you can take additional action. + +### Single environment + +The **Full Details** page for a single environment is where you monitor the progress of the deployment to that environment. If the strategy you specified involves user input, such as a manual approval, this is the page where you can approve or rollback the deployment. + +{{< figure src="/images/borealis/borealis-ui-fulldetails.jpg" >}} diff --git a/content/en/includes/aurora-borealis/borealis-client-creds.md b/content/en/includes/aurora-borealis/borealis-client-creds.md index fa72f051..e5d9eada 100644 --- a/content/en/includes/aurora-borealis/borealis-client-creds.md +++ b/content/en/includes/aurora-borealis/borealis-client-creds.md @@ -15,4 +15,4 @@ > Removing a pre-configured scope group does not unassign the permissions that a pre-configured scope group assigns. You must remove the permissions manually. -7. Note both the `Client ID` and `Client Secret`. You need these values when configuring the RNA or any other service that you want to grant access to. Make sure to store the secret somewhere safe. You are not shown the value again. +8. Note both the `Client ID` and `Client Secret`. You need these values when configuring the RNA or any other service that you want to grant access to. Make sure to store the secret somewhere safe. You are not shown the value again. diff --git a/content/en/includes/aurora-borealis/borealis-rna-wormhole-migrate.md b/content/en/includes/aurora-borealis/borealis-rna-wormhole-migrate.md new file mode 100644 index 00000000..330c8296 --- /dev/null +++ b/content/en/includes/aurora-borealis/borealis-rna-wormhole-migrate.md @@ -0,0 +1,24 @@ +1. Check to see if you are running the old iteration of Agent. Run `helm list`. If the command returns `armory/aurora` for the Helm chart name, you need to update. +2. Navigate to the [Machine to Machine Client Credentials](https://console.cloud.armory.io/configuration/credentials) page in the Cloud Console. +3. Verify the permissions for the client credentials you are using for your deployment targets. They must have the `connect:agentHub` scope. This permission is used to connect the RNA endpoint. +4. Verify that you are in the correct Kubernetes context. The context should be for the deployment target cluster. +5. If you installed the RNA by providing your `clientID` and `clientSecret` in plaintext, now is a good time to update those values to use a secret engine. + + Run the following command to encrypt your client ID and client secret using Kubernetes secrets: + + ```bash + kubectl --namespace armory-rna create secret generic rna-client-credentials --type=string --from-literal=client-secret= --from-literal=client-id= + ``` +6. Change the Helm chart that is being used: + + ```bash + helm repo update + helm upgrade armory-rna armory/remote-network-agent \ + --set agent-k8s.clientId='encrypted:k8s!n:rna-client-credentials!k:client-id' \ + --set agent-k8s.clientSecret='encrypted:k8s!n:rna-client-credentials!k:client-secret' \ + --namespace armory-rna + ``` + + The encrypted values for `clientId` and `clientSecret` reference the Kubernetes secrets you generated in an earlier step. + + If you encounter the following error, make sure you specify the namespace in your Helm command: `Error: UPGRADE FAILED: "armory-rna" has no deployed releases.` \ No newline at end of file diff --git a/content/en/includes/aurora-borealis/rna-install.md b/content/en/includes/aurora-borealis/rna-install.md index 6d6c286c..58398b19 100644 --- a/content/en/includes/aurora-borealis/rna-install.md +++ b/content/en/includes/aurora-borealis/rna-install.md @@ -1,4 +1,4 @@ -Each Kubernetes cluster that you install the RNA on should have a unique account name that you set using the `agent-k8s.accountName` parameter. This account name is used in the Status UI and in other places to identify the cluster. +Each Kubernetes cluster that you install the RNA on should have a unique name that you set using the `agentIdentifier` parameter. This identifier is used to identify the cluster. Note that older versions of the RNA used the `agent-k8s.accountName` parameter for this. 1. Verify that you are in the correct Kubernetes context. The RNA is installed in the target deployment cluster. @@ -16,26 +16,43 @@ Each Kubernetes cluster that you install the RNA on should have a unique account helm repo update ``` -4. Install the Helm chart. Keep the following in mind when you install the RNA: +4. Create the namespace where the RNA gets installed: + + ```bash + kubectl create ns armory-rna + ``` + +5. Create secrets from your client ID and client secret: - * You can create the `armory-rna` namespace before running the `helm install` command or include the `--create-namespace` option. - * The `agent-k8s.accountName` option is the name that is used to refer to the deployment target cluster in the Status UI, your deployment file, and other places, so use a descriptive name. - - The following example includes the `--create-namespace` option: + ```bash + kubectl --namespace armory-rna create secret generic rna-client-credentials --type=string --from-literal=client-secret= --from-literal=client-id= + ``` - ```bash - helm install armory-rna armory/aurora \ - --set agent-k8s.accountName= \ - --set agent-k8s.clientId= \ - --set agent-k8s.clientSecret= \ - --namespace armory-rna \ - --create-namespace - ``` - The values for `agent-k8s.clientId` and `agent-k8s.clientSecret` can be passed as secrets by using environment variables. Instead of supplying the plaintext value, use an environment variable such as `${RNA_CLIENT_ID}` and `${RNA_CLIENT_SECRET}`. Then, attach environment variables with the same names to the pod. For more information, see the [Kubernetes documentation on using secrets as environment variables](https://kubernetes.io/docs/tasks/inject-data-application/define-environment-variable-container/). + The examples use Kubernetes secrets to encrypt the value. You supply the encrypted values in the Helm command to install the RNA. + +6. Install the Helm chart. Keep the following in mind when you install the RNA: - Optionally, you can also add labels and annotations to the RNA install: + * The `agentIdentifier` option is the name that is used to refer to the deployment target cluster, so use a descriptive name. ```bash - --set agent-k8s.podAnnotations.="" \ - --set agent-k8s.podLabels.="