Update top level README files

README.md

@@ -2,9 +2,9 @@
 
 Big Bang is a declarative, continuous delivery tool for deploying DoD hardened and approved packages into a Kubernetes cluster.
 
-> _If viewing this from Github, note that this is a mirror of a government repo hosted on [Repo1](https://repo1.dso.mil/) by [DoD Platform One](http://p1.dso.mil/).  Please direct all code changes, issues and comments to [https://repo1.dso.mil/big-bang/bigbang](https://repo1.dso.mil/big-bang/bigbang)
+> If viewing this from Github, note that this is a mirror of a government repo hosted on [Repo1](https://repo1.dso.mil/) by [DoD Platform One](http://p1.dso.mil/).  Please direct all code changes, issues and comments to [https://repo1.dso.mil/big-bang/bigbang](https://repo1.dso.mil/big-bang/bigbang)
 
-## Usage & Scope 
+## Usage & Scope
 
 Big Bang's scope is to provide publicly available installation manifests for packages required to adhere to the DoD DevSecOps Reference Architecture and additional useful utilities. Big Bang packages are broken into three categories:
 
@@ -20,7 +20,7 @@ Big Bang also builds tooling around the testing and validation of Big Bang packa
 
 Big Bang is intended to be used for deploying and maintaining a DoD hardened and approved set of packages into a Kubernetes cluster.  Deployment and configuration of ingress/egress, load balancing, policy auditing, logging, monitoring, etc. are handled via Big Bang.  Additional packages (e.g. ArgoCD, GitLab) can also be enabled and customized to extend Big Bang's baseline.  Once deployed, the Kubernetes cluster can be used to add mission specific applications.
 
-Additional information can be found at [Big Bang Docs](https://docs-bigbang.dso.mil) and [here](./docs/README.md).
+Additional information can be found in the [Big Bang Docs](./docs/README.md).
 
 ## Getting Started
 
@@ -40,41 +40,31 @@ Additional information can be found in the [contributing guide](./CONTRIBUTING.m
 
 ## Release Schedule
 
-- Big Bang releases adopt a standardized versioning based on and loosely following the [Semantic Versioning 2.0.0 guidelines](https://semver.org/spec/v2.0.0.html) (major.minor.patch). These releases aren't based on a fixed schedule and instead the specifics in the scheme are as follows:
+- Big Bang releases adopt a standardized versioning based on and loosely following the [Semantic Versioning 2.0.0 guidelines](https://semver.org/spec/v2.0.0.html) (major.minor.patch). These releases are not based on a fixed schedule and instead the specifics in the following scheme.
 
 ### Patch Version
-A patch version increment is performed when there is a change in the tag (version number) of a Big Bang core package or a
-bug fix for a Big Bang template or values files.
-A change in the patch version number should be backwards compatible
-with previous patch changes within a minor version.  If there is a significant functionality change in the
-a core package that requires adjustments to Big Bang templates, this would require a change in the minor or major version
-depending on the impact to the values and secrets used to integrated the package with Big Bang.
 
-NOTE: Patch versions would not typically be created for addon package updates, rather customers would be expected to be 
-updating those packages via `git.tag`/`helmRepo.tag` changes directly, or "inheriting" those updates through another version.
+A patch version increment is performed when there is a change in the tag (version number) of a Big Bang core package or a bug fix for a Big Bang template or values files. A change in the patch version number should be backwards compatible with previous patch changes within a minor version.  If there is a significant functionality change in the a core package that requires adjustments to Big Bang templates, this would require a change in the minor or major version depending on the impact to the values and secrets used to integrated the package with Big Bang.
+
+NOTE: Patch versions would not typically be created for addon package updates, rather customers would be expected to be updating those packages via `git.tag`/`helmRepo.tag` changes directly, or "inheriting" those updates through another version.
 
 ### Minor Version
 
-A minor version increment is required when there is a change in the integration of Big Bang with core or addon packages.
-As examples the following changes warrant a Minor version change:
+A minor version increment is required when there is a change in the integration of Big Bang with core or addon packages. As examples the following changes warrant a Minor version change:
 
-  - Change in the umbrella values.yaml (except for changes to package version keys)
-  - Change in any Big Bang templates (non bug fix changes)
+- Change in the umbrella values.yaml (except for changes to package version keys)
+- Change in any Big Bang templates (non bug fix changes)
 
 Minor version changes should be backwards compatible.
 
 ### Major Version
 
-A major version increment indicates a release that has significant changes, which could potentially break
-compatibility with previous versions. A major change is required when there are changes to the architecture of Big Bang or
-critical values file keys.  For example removing a core package or changing significant values that propagate to all core
-and add-on packages are considered major version changes. As examples of major version changes:
-
-  - Removal or renaming of Big Bang values.yaml top level keys (e.g., istio, git repository values, etc.)
-  - Change to the structure of chart/templates files or key values.
-  - Additional integration between core/add-on packages that require change to the charts of all packages.
-  - Modification of Big Bang GitOps engine (i.e. switching from FluxCD -> ArgoCD)
+A major version increment indicates a release that has significant changes, which could potentially break compatibility with previous versions. A major change is required when there are changes to the architecture of Big Bang or critical values file keys. For example removing a core package or changing significant values that propagate to all core and add-on packages are considered major version changes. As examples of major version changes:
 
+- Removal or renaming of Big Bang values.yaml top level keys (e.g., istio, git repository values, etc.)
+- Change to the structure of chart/templates files or key values.
+- Additional integration between core/add-on packages that require change to the charts of all packages.
+- Modification of Big Bang GitOps engine (i.e. switching from FluxCD -> ArgoCD)
 
 To see what is on the roadmap or included in a given release you can still review our [project milestones](https://repo1.dso.mil/groups/big-bang/-/milestones)
 
@@ -82,9 +72,11 @@ To see what is on the roadmap or included in a given release you can still revie
 
 The Big Bang Universe Community Slack workspace is a great place to go to get involved, interact with the community, and ask for help. You can join the workspace with [this invite link](https://join.slack.com/t/bigbanguniver-ft39451/shared_invite/zt-1tnh3mq5u-a6u4BmxXBDiMwBKNiH25Bg).
 
-## Navigating our documentation
+## Navigating our Documentation
+
+> All Big Bang documentation is also provided at [https://docs-bigbang.dso.mil](https://docs-bigbang.dso.mil) offering a better experience and improved searchability.
 
-Big Bang Documentation is located in the following locations:
+The following list are useful starting points in the Big Bang documentation.
 
 - [Developer Contribution Documentation](./docs/developer/README.md)
 - [Key Big Bang Concept Overviews](./docs/understanding-bigbang/README.md)

docs/README.md

-# BigBang Docs
+# Big Bang Documentation README
 
-## What is BigBang?
+## What is Big Bang?
 
-* BigBang is a Helm Chart that is used to deploy a DevSecOps Platform on a Kubernetes Cluster. The DevSecOps Platform is composed of application packages which are bundled as helm charts that leverage IronBank hardened container images.
-* The BigBang Helm Chart deploys gitrepository and helmrelease Custom Resources to a Kubernetes Cluster that's running the Flux GitOps Operator, these can be seen using `kubectl get gitrepository,helmrelease -n=bigbang`. Flux then installs the helm charts defined by the Custom Resources into the cluster.
-* The BigBang Helm Chart has a values.yaml file that does 2 main things:
-  1. Defines which DevSecOps Platform packages/helm charts will be deployed
+* Big Bang is a Helm Chart that is used to deploy a DevSecOps Platform on a Kubernetes Cluster. The DevSecOps Platform is composed of application packages which are bundled as helm charts that leverage Iron Bank hardened container images.
+* The Big Bang Helm Chart deploys gitrepository and helmrelease Custom Resources to a Kubernetes Cluster running the Flux GitOps Operator, these can be seen using `kubectl get gitrepository,helmrelease -n=bigbang`. Flux then installs the helm charts defined by the Custom Resources into the cluster.
+* The Big Bang Helm Chart has a values.yaml file that does two main things:
+  1. Defines which DevSecOps Platform packages/helm charts will be deployed.
   1. Defines what input parameters will be passed through to the chosen helm charts.
 * You can see what applications are part of the platform by checking the following resources:
   * [packages.md](./packages.md) lists the packages and organizes them in categories.
   * [Release Notes](https://repo1.dso.mil/big-bang/bigbang/-/releases) lists the packages and their versions.
-  * For a code based source of truth, you can check [BigBang's default values.yaml](../chart/values.yaml), and `[CTRL] + [F]` "repo:", to quickly iterate through the list of applications supported by the BigBang team.
+  * For a code based source of truth, you can check [Big Bang's default values.yaml](../chart/values.yaml), and `[CTRL] + [F]`, `"repo:"`, to quickly iterate through the list of applications supported by the Big Bang team.
+  * [Big Bang Universe](https://universe.bigbang.dso.mil) provides an interactive visual of all packages in Core, Addons, and Community as described in [Big Bang README](../README.md#usage--scope)
 
+### What Big Bang isn't
 
-### What BigBang isn't
-
-* BigBang by itself is not intended to be an End to End Secure Kubernetes Cluster Solution, but rather a reusable secure component/piece of a full solution.
+* Big Bang by itself is not intended to be an End to End Secure Kubernetes Cluster Solution, but rather a reusable secure component/piece of a full solution.
 * A Secure Kubernetes Cluster Solution, will have multiple components, that can each be swappable and in some cases considered optional depending on use case and risk tolerance:
   Example of some potential components in a full End to End Solution:
-  * P1's Cloud Native Access Point to protect Ingress Traffic. (This can be swapped with an equivalent, or considered optional in an internet disconnected setup.)
+  * P1's Cloud Native Access Point to protect ingress traffic. (This can be swapped with an equivalent, or considered optional in an internet disconnected setup.)
   * Hardened Host OS
-  * Hardened Kubernetes Cluster (BigBang assumes ByoC, Bring your own Cluster) (The BigBang team recommends consumers who are interested in a full solution, partner with Vendors of Kubernetes Distributions to satisfy the prerequisite of a Hardened Kubernetes Cluster.)
-  * Hardened Applications running on the Cluster (BigBang helps solve this component)
-
+  * Hardened Kubernetes Distrobution and Cluster (Big Bang assumes ByoC, Bring your own Cluster) (The Big Bang team recommends consumers who are interested in a full solution, partner with vendors of Kubernetes Distributions to satisfy the prerequisite of a Hardened Kubernetes Cluster.)
+  * Hardened Applications running on the Cluster (Big Bang and Iron Bank helps solve this component)
 
-## Value add gained by using BigBang
+## Benefits of using Big Bang
 
 * Compliant with the [DoD DevSecOps Reference Architecture Design](https://dodcio.defense.gov/Portals/0/Documents/Library/DoD%20Enterprise%20DevSecOps%20Reference%20Design%20-%20CNCF%20Kubernetes%20w-DD1910_cleared_20211022.pdf)
-* Can be used to check some but not all of the boxes needed to achieve a cATO (Continuous Authority to Operate.)
-* Uses hardened IronBank Container Images. (left shifted security concern)
-* GitOps adds security benefits, and BigBang leverages GitOps, and can be further extended using GitOps.
+* Can be used to check some but not all of the boxes needed to achieve a Continuous Authority to Operate (cATO) or Authority to Operate (ATO).
+* Left shift supply chain security concerns using hardened Iron Bank container images.
+* GitOps adds security benefits, and Big Bang leverages GitOps, and can be further extended using GitOps.
   Security Benefits of GitOps:
-  * Prevents config drift between state of a live cluster and IaC/CaC source of truth: By avoiding giving any humans direct kubectl access, by only allowing humans to deploy via git commits, out of band changes are limited.
+  * Prevents configuration drift between state of a live cluster and IaC/CaC source of truth: By avoiding giving any humans direct `kubectl` access, by only allowing humans to deploy via git commits, out of band changes are limited.
   * Git Repo based deployments create an audit trail.
-  * Secure Configurations become reusable, which lowers the burden of implementing secure configurations.
-* Lowers maintainability overhead involved in keeping the images of the DevSecOps Platform's up to date and maintaining a secure posture over the long term. This is achieved by pairing the GitOps pattern with the Umbrella Helm Chart Pattern.
+  * Reusable secure configurations lowers the burden of implementing secure configurations.
+* Lowers maintainability overhead involved in keeping the images of a DevSecOps Platform up to date and maintaining a secure posture over the long term. This is achieved by pairing the GitOps pattern with the Umbrella Helm Chart Pattern.
   Let's walk through an example:
-  * Initially a kustomization.yaml file in a git repo will tell the Flux GitOps operator (software deployment bot running in the cluster), to deploy version 1.0.0 of BigBang. BigBang could deploy 10 helm charts. And each helm chart could deploy 10 images. (So BigBang is managing 100 container images in this example.)
-  * After a 2 week sprint version 1.1.0 of BigBang is released. A BigBang consumer updates the kustomization.yaml file in their git repo to point to version 1.1.0 of the BigBang Helm Chart. That triggers an update of 10 helm charts to a new version of the helm chart. Each updated helm chart will point to newer versions of the container images managed by the helm chart.
-  * So when the end user edits the version of 1 kustomization.yaml file, that triggers a chain reaction that updates 100 container images.
-  * These upgrades are pre-tested. The BigBang team "eats our own dogfood". Our CI jobs for developing the BigBang product, run against a BigBang dogfood Cluster, and as part of our release process we upgrade our dogfood cluster, before publishing each release. (Note: We don't test upgrades that skip multiple minor versions.)
-  * Auto updates are also possible by setting kustomization.yaml to 1.x.x, because BigBang follows semantic versioning, flux is smart enough to read x as the most recent version number.
-* DoD Software Developers get a Developer User Experience of "SSO for free". Instead of developers coding SSO support 10 times for 10 apps. The complexity of SSO support is baked into the platform, and after an Ops team correctly configures the Platform's SSO settings, SSO works for all apps hosted on the platform. The developer's user experience for enabling SSO for their app then becomes as simple as adding the label istio-injection=enabled (which transparently injects mTLS service mesh protection into their application's Kubernetes YAML manifest) and adding the label protect=keycloak to each pod, which leverages an EnvoyFilter CustomResource to auto inject an SSO Authentication Proxy in front of the data path to get to their application.
+  * Initially a `kustomization.yaml` file in a git repo will tell the Flux GitOps operator (software deployment bot running in the cluster), to deploy version 1.0.0 of Big Bang. Big Bang could deploy 10 helm charts. And each helm chart could deploy 10 images. (So Big Bang is managing 100 container images in this example.)
+  * After a 2 week sprint version 1.1.0 of Big Bang is released. A Big Bang consumer updates the `kustomization.yaml` file in their git repo to point to version 1.1.0 of the Big Bang Helm Chart. That triggers an update of 10 helm charts to a new version of the helm chart. Each updated helm chart will point to newer versions of the container images managed by the helm chart.
+  * So when the end user edits the version of one `kustomization.yaml` file, that triggers a chain reaction that updates 100 container images in the cluster.
+  * These upgrades are pre-tested. The Big Bang team "eats our own dogfood". Our CI jobs for developing the Big Bang product, run against a Big Bang Dogfood Cluster, and as part of our release process we upgrade our Big Bang Dogfood Cluster, before publishing each release.
+  > **Note:** We ONLY support and recommend successive upgrades. We do not test upgrades that skip multiple minor versions.
+  * Auto updates are also possible by setting kustomization.yaml to 1.x.x, because Big Bang follows semantic versioning per the [Big Bang README](../README.md#release-schedule), and flux is smart enough to read x as the most recent version number.
+* DoD Software Developers get a Developer User Experience of "Single Sign On (SSO) for free". Instead of developers coding SSO support 10 times for 10 apps. The complexity of SSO support is baked into the platform, and after an operations team correctly configures the Platform's SSO settings, SSO works for all apps hosted on the platform. The developer's user experience for enabling SSO for their app then becomes as simple as adding the label `istio-injection=enabled` (which transparently injects mTLS service mesh protection into their application's Kubernetes YAML manifest) and adding the label `protect=keycloak` to each pod, which leverages an EnvoyFilter CustomResource to auto inject an SSO Authentication Proxy in front of the data path to get to their application.
 
+## How do I deploy Big Bang?
 
-## How do I deploy BigBang?
-
-**Note:** The Deployment Process and Pre-Requisites will vary depending on the deployment scenario. The [Quick Start Demo Deployment](./guides/deployment-scenarios/quickstart.md) for example, allows some steps to be skipped due to a mixture of automation and generically reusable demo configuration that satisfies pre-requisites.
-The following is a general overview of the process, the [deployment guides](./guides/deployment-scenarios) go into more detail.
+**Note:** The Deployment Process and Pre-Requisites will vary depending on the deployment scenario. The [Quick Start Demo Deployment](./guides/deployment-scenarios/quickstart.md) for example, allows some steps to be skipped due to a mixture of automation and generically reusable demonstration configuration that satisfies pre-requisites. The following is a general overview of the process, reference the [deployment guides](./guides/deployment-scenarios) for more detail.
 
 1. Satisfy Pre-Requisites:
    * Provision a Kubernetes Cluster according to [best practices](./prerequisites/kubernetes-preconfiguration.md#best-practices).
-   * Ensure the Cluster has network connectivity to a Git Repo you control.
-   * Install Flux GitOps Operator on the Cluster.
-   * Configure Flux, the Cluster, and the Git Repo for GitOps Deployments that support deploying encrypted values.
-   * Commit to the Git Repo BigBang's values.yaml and encrypted secrets that have been configured to match the desired state of the cluster (including HTTPS Certs and DNS names).  
+   * Ensure the cluster has network connectivity to a Git Repo you control.
+   * Install Flux GitOps Operator on the cluster.
+   * Configure Flux, the cluster, and the Git Repo for GitOps Deployments that support deploying encrypted values.
+   * Commit to the Git Repo Big Bang's `values.yaml` and encrypted secrets that have been configured to match the desired state of the cluster (including HTTPS Certs and DNS names).  
 1. `kubectl apply --filename bigbang.yaml`
-   * [bigbang.yaml](https://repo1.dso.mil/big-bang/customers/template/-/blob/main/umbrella-strategy/bigbang.yaml) will trigger a chain reaction of GitOps Custom Resources' that will deploy other GitOps CR's that will eventually deploy an instance of a DevSecOps Platform that's declaratively defined in your Git Repo.
+   * [bigbang.yaml](https://repo1.dso.mil/big-bang/customers/template/-/blob/main/umbrella-strategy/bigbang.yaml) will trigger a chain reaction of GitOps Custom Resources that will deploy other GitOps Custom Resources that will eventually deploy an instance of a DevSecOps Platform that's declaratively defined in your Git Repo.
    * To be specific, the chain reaction pattern we consider best practice is to have:
-     * bigbang.yaml deploys a gitrepository and kustomization Custom Resource
-     * Flux reads the declarative configuration stored in the kustomization CR to do a GitOps equivalent of `kustomize build . | kubectl apply  --filename -`, to deploy a helmrelease CR of the BigBang Helm Chart, that references input values.yaml files defined in the Git Repo.
-     * Flux reads the declarative configuration stored in the helmrelease CR to do a GitOps equivalent of `helm upgrade --install bigbang /chart  --namespace=bigbang  --filename encrypted_values.yaml --filename values.yaml --create-namespace=true`, the BigBang Helm Chart, then deploys more CR's that flux uses to deploy packages specified in BigBang's values.yaml
+     * `bigbang.yaml` deploys a git repository and kustomization Custom Resource
+     * Flux reads the declarative configuration stored in the kustomization Custom Resource to do a GitOps equivalent of `kustomize build . | kubectl apply  --filename -`, to deploy a helmrelease Custom Resource of the Big Bang Helm Chart, that references input `values.yaml` files defined in the Git Repo.
+     * Flux reads the declarative configuration stored in the helmrelease Custom Resource to do a GitOps equivalent of `helm upgrade --install bigbang /chart  --namespace=bigbang  --filename encrypted_values.yaml --filename values.yaml --create-namespace=true`, the Big Bang Helm Chart, then deploys more Custom Resources that flux uses to deploy packages specified in Big Bang's `values.yaml`
   
 ## New User Orientation
 
-* New users are encouraged to read through the Useful Background Contextual Information present in the [Understanding Big Bang Section](./understanding-bigbang)
+New users are encouraged to read through the useful background information present in the [Understanding Big Bang Section](./understanding-bigbang).
 
 ## Frequently Asked Questions
 
-You can view answers to a number of frequently asked questions [here](FAQ.md).
+You can view answers to a number of [frequently asked questions](FAQ.md).
+
+ Please direct all code changes, issues and comments to [https://repo1.dso.mil/big-bang/bigbang](https://repo1.dso.mil/big-bang/bigbang).