Merge pull request #657 from snyk/feat/universal-broker-docs-refresh

feat: universal broker docs updates [ACC-2861] [DOCT-1712]

Author: VeronicaSnyk

docs/enterprise-setup/snyk-broker/universal-broker/README.md

@@ -5,21 +5,21 @@
 Universal Broker is in Early Access and is available only with Enterprise plans.
 {% endhint %}
 
-The Universal Broker improves the management of Broker deployments and connections, supporting many connections of any type through a single running client, preferably with multiple replicas, that is, entirely distinct clients. Credentials remain entirely local to your network and are never stored on the Snyk platform, which uses credentials references.
+The Universal Broker improves the management of Broker deployments and connections by supporting many connections of any type with a single running client (container) or with multiple client replicas. Credentials remain within your network and are never stored by or transmitted to Snyk. The Snyk platform uses credentials references to instruct the Universal Broker how to authenticate with your private resources.
 
-Each client or client with replicas is called a Broker deployment. The diagram shows two deployments, Universal Broker A and Universal Broker B.
+Each client or set of client replicas is called a Broker deployment. The diagram below shows two deployments, Universal Broker A and Universal Broker B.
 
-A deployment can support multiple connections of any type, as shown in the diagram examples: GitHub, GitLab, Artifactory, Jira, and Container Registry Agent. Connections are configured to communicate with specific private resources: SCMs, JIRA, and others.
+A deployment can support multiple connections of any type, as shown in the diagram examples: GitHub, GitLab, Artifactory, Jira, and Container Registry Agent. Connections are configured to communicate with specific private resources: SCMs, Jira, and others.
 
 <figure><img src="../../../.gitbook/assets/image 5 (6).png" alt=""><figcaption><p>Universal Broker deployment example</p></figcaption></figure>
 
 Connections are integrated with Organizations to provide access to your private resources for the appropriate Snyk Organization(s). These Organizations can be in the same or different Snyk Groups.
 
 In the diagram, Group 1 includes Organizations A through D, and Group 2 includes Organizations E and F.
 
-Organizations A, B, C, D, and E are integrated with the Universal Broker A deployment, and thus have access to all of the resources except the container registry agent.&#x20;
+Organizations A, B, C, D, and E are integrated with the Universal Broker A deployment, and thus have access to all of the resources except the Container Registry Agent.&#x20;
 
-Organization F is integrated with Universal Broker B, and thus has access to Jira and the container registry agent.
+Organization F is integrated with Universal Broker B, and thus has access to Jira and the Container Registry Agent.
 
 {% hint style="info" %}
 You can learn more about Universal Broker in the dedicated Snyk Learn course. Explore the advantages, configuration, architecture, and much more with [Snyk Learn: Universal Broker](https://learn.snyk.io/lesson/universal-broker/?ecosystem=general).

docs/enterprise-setup/snyk-broker/universal-broker/add-a-new-connection-to-your-universal-broker.md

@@ -10,7 +10,7 @@ A Broker deployment supports numerous connections of any type, including the sam
 
 While the Universal Broker supports multiple connections of the same type, each Organization can be integrated with only one connection for a given type. For example, an Organization cannot be integrated with two GitLab connections.
 
-You can share credentials references across connections by selecting a credentials reference when you create a connection. However, you can share credentials references only  across connections of the same type AND running on the same Broker deployment
+You can share credentials references across connections by selecting a credentials reference when you create a connection. However, you can share credentials references only across connections of the same type and running on the same Broker deployment.
 
 After the connection is created, run `snyk-broker-config workflows connections integrate` and select the desired deployment and connection. Then enter the Organization ID for the Organization with which you want to integrate. For details, see [Integrate a connection with an Organization](setting-up-and-integrating-your-universal-broker-connections.md#integrate-a-connection-with-an-organization).
 

docs/enterprise-setup/snyk-broker/universal-broker/basic-steps-to-install-and-configure-universal-broker.md

@@ -14,12 +14,17 @@ To install the tool, use `npm i -g snyk-broker-config`.
 The `snyk-broker-config` CLI tool is your primary guide for setting up and managing Snyk Broker connections. It is designed to walk you step-by-step through the process, asking for the required information for each integration type. This adaptive method guarantees that you receive the latest parameter requirements directly from the tool.
 {% endhint %}
 
+The basic process for configuring a new Universal Broker deployment is as follows:
+1. Install the `snyk-broker-config` tool by running `npm i -g snyk-broker-config`
+2. Create a new Universal Broker connection by following the create workflow `snyk-broker-config workflows connections create`
+3. Integrate your new Universal Broker connection by following the integrate workflow `snyk-broker-config workflows connections integrate`
+
 ### How to use the CLI for parameter discovery
 
-Even if you are not running the full setup, the Snyk CLI can help you understand the required parameters. Use the interactive setup or the command line help.
+Even if you are not running the full setup, the `snyk-broker-config` CLI tool can help you understand the required parameters. Use the interactive setup or the command line help.
 
 * **Interactive setup:** Run `snyk-broker-config workflows connections create` and follow the prompts. The CLI asks for all required and optional parameters based on the integration type you select, such as GitLab, Artifactory, or Bitbucket Server.
-*   **Command line help:** Use the `--help` flag for any `snyk-broker-config` command to see available options and parameters. For instance, to see parameters specifically relevant for creating a GitLab connection type, use the following command:
+* **Command line help:** Use the `--help` flag for any `snyk-broker-config` command to see available options and parameters. For instance, to see parameters specifically relevant for creating a GitLab connection type, use the following command:
 
     ```bash
     snyk-broker-config workflows connections create --type gitlab --help
@@ -42,7 +47,7 @@ A typical workflow for adding a new Broker connection using the CLI involves the
 
     The CLI will then guide you through the process, prompting for:
 
-    * Your Snyk API Token, required for authentication.
+    * Your Snyk API Token, required for authentication if you did not already export it as an environment variable.
     * The Snyk Organization ID where the Broker connection is used.
     * The specific type of integration you want to connect, such as `gitlab`, `artifactory`, `bitbucket-server`.
     * All required and optional parameters, such as URLs, tokens, usernames, or passwords, are dynamically identified for your chosen integration type. Follow the on-screen instructions carefully.
@@ -100,9 +105,9 @@ Now using Tenant ID <current Tenant ID> and Install ID <current Install ID>.
 Do you want to create a new Deployment? (Y/N)
 ```
 
-Snyk recommends that you set the INSTALL\_ID as an environment variable now, to make the tool easier to use.:\
-`- export INSTALL_ID=zzzz (Linux/Mac)`\
-`- set INSTALL_ID=zzzz(Windows)`
+Snyk recommends that you set the INSTALL_ID as an environment variable to improve usability:\
+- `export INSTALL_ID=zzzz` (Linux/Mac)\
+- `set INSTALL_ID=zzzz` (Windows)
 
 ## Input connection parameters
 
@@ -180,7 +185,7 @@ Selected Connection ID <number>.
 Ready to configure integrations to use this connection.
 ```
 
-Details of the connection follow: `connection ID`; `connection type (broker_connection)`; `attributes:  deployment_id, identifier, name, and secrets-primary and secondary`, each with the `status`, `encrypted`, `expires_at`, and `nonce`; `configuration required: broker-client-url` and `github_token values`; `type: github.`
+Details of the connection follow: `connection ID`; `connection type (broker_connection)`; `attributes:  deployment_id, identifier, name, and secrets: primary and secondary`, each with the `status`, `encrypted`, `expires_at`, and `nonce`; `configuration required: broker-client-url` and `github_token values`; `type: github.`
 
 ```
 Connection Detail Workflow completed.
@@ -211,7 +216,6 @@ docker run -d --restart=always \
 -p 8000:8000 \
 -e DEPLOYMENT_ID=<DEPLOYMENT_ID_JUST_CREATED> \
 -e CLIENT_ID=<CLIENT_ID_SAVED_EARLIER> \
-
 -e CLIENT_SECRET=<CLIENT_SECRET_SAVED_EARLIER> \
 -e MY_GITHUB_TOKEN=<THE_ACTUAL_GITHUB_TOKEN_VALUE> \
 -e PORT=8000 \
@@ -224,7 +228,7 @@ When the Broker client has started, the connection is ready to use, in this case
 
 ## Integrate your connection with more Organizations
 
-To integrate your connection with another Organization so it will use the same connection, run the command again and enter the ID of the new Organization to integrate. You can repeat this step as often as needed to integrate with Organizations.
+To integrate your connection with another Organization, run the integrate command again and enter the new Organization ID. Repeat as needed to connect with multiple Organizations.
 
 ```
 > snyk-broker-config workflows connections integrate

docs/enterprise-setup/snyk-broker/universal-broker/broker-client-url.md

@@ -10,8 +10,8 @@ The same webhook mechanism is used to facilitate communication when Snyk creates
 
 When you set up a connection, the webhook target endpoint is defined by the value of the `broker_client_url` value. The webhook can point directly to Snyk or to the Broker client container, which will relay the webhook to Snyk. 
 
-Normally, and by default for SCM integrations, the regional Snyk API endpoint is used. For the list of URLs, see [Broker client URLs](../../../working-with-snyk/regional-hosting-and-data-residency.md#broker-client-urls). Sometimes, however, your environment may prohibit SCM webhooks from leaving the private cloud or data center. In that case, the webhook and thus the SCM must point to the Snyk Broker container running in your environment. In these cases, the`broker_client_url` has to reflect the hostname and port of the Broker client. 
+By default, SCM integrations use the regional Snyk API endpoint. For the list of URLs, see [Broker client URLs](../../../working-with-snyk/regional-hosting-and-data-residency.md#broker-client-urls). Sometimes, environments restrict SCM webhooks from leaving the private cloud or data center. In is scenario, the webhook and SCM must point to the Snyk Broker container in your environment, with `broker_client_url` reflecting the hostname and port of the Broker client.
 
 Non-SCM integrations, notably the container registries integrations, require the Broker client URL to be the Broker client address. Snyk recommends using the DNS hostname (`http://my.broker.client`), but you can also use IP addresses (`http://192.168.0.1`). Append the port, for example, `http://my.broker.client:8000`.
 
-Note that the `https` webhook calls requires additional setup in the Broker client to bring a TLS certificate and mount it into the container. For details, see [HTTPS for Broker client with Docker](../https-for-broker-client-with-docker.md).
+Note that the `https` webhook calls require additional setup in the Broker client to bring a TLS certificate and mount it into the container. For details, see [HTTPS for Broker client with Docker](../https-for-broker-client-with-docker.md).

docs/enterprise-setup/snyk-broker/universal-broker/deployment-tips-and-reference-architectures.md

@@ -6,16 +6,24 @@ You can learn more about deployment and architecture, and more, with the [Univer
 
 The Universal Broker allows you to run multiple connections of any type using a single container. Snyk recommends running in High Availability Mode (on by default), to run multiple replicas.
 
-On Kubernetes systems, the Helm chart creates a stateful set with numerous members, automatically creating multiple replicas.
+On Kubernetes, the Helm chart creates a stateful set with numerous members, automatically creating multiple replicas.
 
-In other orchestrators, you must create multiple replicas explicitly in your deployment configuration.
+In other orchestrators such as Docker Compose, you must create multiple replicas explicitly in your deployment configuration.
 
 Usage of resources varies based on a number of factors, making it difficult to model the actual use of resources (CPU and memory) for the container. Each deployment is limited to a maximum of 25 connections to avoid exhaustion of resources.
 
 If you find you need more resource segregation or allocation that does not fit well into a single container setup, you can create a new deployment with its set of connections to split the load across numerous Broker clients and containers.
 
-Note that moving connections from deployment A to deployment B is not supported.
+Note that moving connections from one deployment to another is not supported.
 
 Contact your Snyk account team or [Snyk support](https://support.snyk.io/s/) if you need more assistance designing a Universal Broker architecture for your needs.
 
+## High Availability Mode
+
+High Availability Mode for a Universal Broker deployment is enabled by default and can be disabled by setting the `BROKER_HA_MODE_ENABLED=false` environment variable inside the container. When HA mode is enabled the Universal Broker deployment will open a second backup websocket with the Snyk platform to provide redundancy in the event of a network failure. 
+
+Each Universal Broker deployment is limited to 4 total web sockets. They can be deployed in any configuration such as two Universal Broker Clients each with HA mode enabled, or four Universal Broker Clients with HA mode disabled. When deploying the Universal Broker using the [Snyk Universal Broker Helm chart](https://github.com/snyk/snyk-universal-broker-helm/blob/rc/snyk-universal-broker/values.yaml#L66) the default configuration is 2 replicas with HA mode enabled.
+
+Note that exceeding 4 web sockets per Universal Broker deployment will result in unpredictable and unstable behaviour for all broker clients in the deployment.
+
 \

docs/enterprise-setup/snyk-broker/universal-broker/disconnect-and-clean-up.md

@@ -1,14 +1,14 @@
 # Disconnect and clean up
 
-The `snyk-broker-config workflows <RESOURCE> delete` commands allow you to remove resources.&#x20;
+The `snyk-broker-config workflows <RESOURCE> delete` command allows you to remove resources.&#x20;
 
 Protections are in place to prevent invalid connection states, so you cannot delete connections that are integrated, and therefore relied upon, by Organizations. You must disconnect the integration before deleting the connection.
 
-`snyk-broker-config workflows connections delete` walks you through the disconnection steps.
+The `snyk-broker-config workflows connections disconnect` command walks you through the disconnection steps.
 
 For all resources, you must delete the child items before you can delete a parent, as illustrated in the diagram that follows. A deployment contains connections and credentials references. Connections use credentials references. Each connection may have an integration with one or more Organizations.
 
-`snyk-broker-config` commands walk you through this flow and indicate what needs to be done to achieve successful deletion. These commands implement and enforce the following rules:
+The `snyk-broker-config introduction` command walks you through this flow and indicates what needs to be done to achieve successful deletion. These commands implement and enforce the following rules:
 
 * Before you delete a connection, you must disconnect all integrations.
 * Before you delete a credentials reference, you must delete the connection(s) using it.
@@ -33,7 +33,7 @@ In response to the prompt, type Y and press Enter if you want to disconnect all
 ```
 Universal Broker - Delete Connection Workflow
 ✓ Valid Snyk Token.
-✓ Tenant Adnmim role confirms.
+✓ Tenant Admin role confirms.
 Now using Tenant ID of <returned number>.
 Now using Deployment <returned number>.
    Which Connection do you want to use? <number entered>
@@ -43,7 +43,7 @@ Do you want to disconnect them all? (Y/N)
 
 ## Disconnect integrations
 
-To delete multiple integrations, run s`nyk-broker-config workflows connections disconnect`.
+To delete multiple integrations, run `snyk-broker-config workflows connections disconnect`.
 
 Enter the connection from which to disconnect.
 
@@ -58,9 +58,8 @@ Now using Deployment <number returned>.
 Which Connection do you want to use <number entered>
 Selected Connection ID <number entered>. Ready to disconnect integrations using 
 this connection.
-Select (Press <backspace> to remove option) {Type: github] in <Organization ID returned>
-[✓ ] Type github in <Organization ID returned> integr <number returned>)
-[    ] Type github in <Organization ID returned>? integr <number returned>)
+Select (Press <backspace> to remove option) [Type: github] in <Organization ID returned>
+[✓ ] Type github in <Organization ID returned> (integration <Integration ID returned>)
 ```
 
 ## Delete credentials references

docs/enterprise-setup/snyk-broker/universal-broker/list-and-review-the-universal-broker-configuration-resources.md

@@ -7,21 +7,21 @@ The `snyk-broker-config` CLI tool provides resources to guide you in configuring
 * Deployments
 * Integrations
 
-To list the resources, run `snyk-broker-config-workflows`.
+To list the workflows available, run `snyk-broker-config workflows`.
 
 ```
-> snyk-broker-config-workflows
+> snyk-broker-config workflows
 Interactive workflows for Deployments, Credentials, Connections and 
 Integrations management
 
 USAGE
-     $ snyk-broker.config workflows COMMAND
+     $ snyk-broker-config workflows COMMAND
 
 TOPICS
       workflows connections    Universal Broker - Create Connection Workflow
-      workflows credentials.   Universal Broker - Create Credentials Workflow
+      workflows credentials   Universal Broker - Create Credentials Workflow
       workflows deployments    Universal Broker - Create Deployment Workflow
-      workflows integration.   Universal Broker - Get Connection Integration Workflow
+      workflows integration   Universal Broker - Get Connection Integration Workflow
 ```
 
 Run `snyk-broker-config workflows <RESOURCE>` to list the available resources to get, create, delete, disconnect, integrate, and migrate.