Big Bang Documentation Clean Up

docs/README.md

@@ -18,10 +18,16 @@
 * 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.)
+  * Ingress traffic protection
+    * Platform One's Cloud Native Access Point (CNAP) is one solution.
+    * CNAP can be swapped with an equivalent, or considered optional in an internet disconnected setup.
   * Hardened Host OS
-  * 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)
+  * Hardened Kubernetes Cluster
+    * Big Bang assumes Bring your own Cluster (BYOC)
+    * 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
+    * Iron Bank provides hardened containers that helps solve this component.
+    * Big Bang utilizes the hardened containers in Iron Bank.
 
 ## Benefits of using Big Bang
 

docs/understanding-bigbang/README.md

 # Useful Background Contextual Information
 
-## The purpose of this section is to help consumers of BigBang understand
+Start with the [Documentation README](../README.md), which includes the following sections:
 
-* BigBang's scope: what it is and isn't, goals and non-goals
-* The value add gained by using BigBang
-* What to expect in terms of prerequisites for those interested in using BigBang
-* Help those who want a deep drive concrete understanding of BigBang quickly come up to speed, via pre-reading materials, that can act as a self service new user orientation to point out features and nuances that new users wouldn't know to ask about.
-
-## BigBang's scope: what it is and isn't, goals and non-goals
-
-### What BigBang is
-
-* BigBang is a Helm Chart that is used to deploy a DevSecOps Platform composed of IronBank hardened container images on a Kubernetes Cluster.
-* See [/docs/README.md](../README.md#what-is-bigbang?) more details.
-
-### 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.
-* 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.)
-  * 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)
-
-## Value add gained by using BigBang
-
-* 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.
-  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.
-  * 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.
-  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.
+* [What is Big Bang](../README.md#what-is-big-bang)
+* [What Big Bang is not](../README.md#what-big-bang-isnt)
+* [Benefits of Big Bang](../README.md#benefits-of-using-big-bang)
 
 ## Acronyms
 
@@ -50,6 +13,7 @@
 * KMS: Key Management System / Encryption as a Service (AWS/GCP KMS, Azure Key Vault, HashiCorp Transient Secret Engine)
 * PGP: Pretty Good Privacy (Asymmetric Encryption Key Pair, where public key is used to encrypt, private key used to decrypt)
 * SOPS: "Secret Operations" CLI tool by Mozilla, leverages KMS or PGP to encrypt secrets in a Git Repo. (Flux and P1's modified ArgoCD can use SOPS to decrypt secrets stored in a Git Repo.)
+* ATO: Authority to Operate
 * cATO: continuous Authority to Operate
 * AO: Authorizing Official (Government Official who determines OS and Kubernetes Cluster hardening requirements, that result in a level of acceptable remaining risk that they're willing to sign off on for a Kubernetes Cluster to receive an ATO, and a BigBang Cluster to receive a cATO)
 * IaC: Infrastructure as Code
@@ -63,19 +27,21 @@
 
 ## Additional Useful Background Contextual Information
 
-* We are still migrating some docs from IL2 Confluence, and the BigBang Onboarding Engineering Cohort into to this repositories' /docs folder, the planned future state is for this to be a primary location for docs going forward. (Any docs hosted in other repositories, will at least have pointers hosted here.)
-* There are multiple implementations of Helm Charts (Helm repositories, .tgz, and files and folders in a git repo), whenever P1 refers to a helm chart we're always referring to the files and folders in a git repo implementation, which is stored in /chart folder in a git repo.
-* Additional pre-reading materials to develop a better understanding of BigBang before deploying can be found in this understanding_bigbang folder.
-* If you see an issue with docs or packages, please [open an issue against the main BigBang Repo](https://repo1.dso.mil/big-bang/bigbang/-/issues), instead of the individual package repo.
+* Big Bang utilizes Documents as Code stored in the main [Big Bang Repo](https://repo1.dso.mil/big-bang/bigbang/docs). For a better experience, the documentation can also be found on the [Big Bang Documentation Website](https://docs-bigbang.dso.mil).
+  * All locations use the same source code and will include pointers between them.
+* There are multiple implementations of Helm Charts (Helm repositories, `.tgz`, and files and folders in a git repo), whenever Platform One refers to a helm chart, it always referring to the files and folders in a git repo implementation, which is stored in the `/chart` folder within a git repo.
+* Additional pre-reading materials to develop a better understanding of Big Bang before deploying can be found in this `understanding_bigbang` section.
+* If you see an issue with docs or packages, please [open an issue against the main Big Bang Repo](https://repo1.dso.mil/big-bang/bigbang/-/issues), instead of the individual package repo.
 
 ## Note about Snippets of Architecture Diagrams in this folder
 
 * The intent of sharing Architecture Diagrams is to:
-  * Act as a starting point upon which further understanding can be built
-  * Improve a users understanding of how BigBang components fit together, so that if the user needs to modify components or workflows flows to fit their use case they'll have an idea of what the modification might look like
-  * Show potential use cases for some of BigBang's core components
+  * Act as a starting point upon which further understanding can be built.
+  * Improve a users understanding of how Big Bang components fit together.
+  * Provide insight on what it would take to modify components or workflows to fit specific use cases.
+  * Show potential use cases for some of BigBang's core components.
 * These Architecture Diagrams are NOT intended to:
-  * Reflect an accurate default configuration
-  * Prescriptively say you must do things this way
+  * Reflect an accurate default configuration.
+  * Prescriptively show the only possible solution of a Big Bang deployment
 * These Architecture Diagrams should be taken with a grain of salt:
-  It's difficult to make a generic diagram with high accuracy. BigBang's Helm Values are variables, some values can produce significantly different workflows. Nuances specific to the deployment environment and hardened configurations like SELinux & Istio CNI can slightly effect parts of implementation details.
+  It's difficult to make a generic diagram with high accuracy. Big Bang's Helm Values are variables, some values can produce significantly different workflows. Nuances specific to the deployment environment and hardened configurations like SELinux & Istio CNI can slightly effect parts of implementation details.

docs/understanding-bigbang/concepts/git-ops-engine.md

@@ -6,9 +6,9 @@ Big Bang will be deployed and managed with [Flux 2](https://github.com/fluxcd/fl
 
 ### Big Bang and Flux
 
-Big Bang is composed of several Open Source and licensed products.  [Helm](https://helm.sh/), as a member of the [CNCF](https://www.cncf.io/), is the de facto standard for packaging applications for Kubernetes.  As a result, several vendors support the release of their product **as helm charts** and have built their packaging and lifecycle management to expect to be the engine for driving that management.  As a result, Big Bang has adopted Helm as its internal deployment framework for Big Bang packages and requires Helm to be treated as a first class citizen.
+Big Bang is composed of Open Source and licensed products.  [Helm](https://helm.sh/), as a member of the [CNCF](https://www.cncf.io/), is the de facto standard for packaging applications for Kubernetes.  As a result, several vendors support the release of their product **as helm charts** and have built their packaging and lifecycle management to expect to be the engine for driving that management.  As a result, Big Bang has adopted Helm as its internal deployment framework for Big Bang packages and requires Helm to be treated as a first class citizen.
 
-The Flux2 Engine has native Helm support, meaning the controller deployed as part of "Flux 2" leverages the same Helm code as the CLI.
+The Flux 2 Engine has native Helm support, meaning the controller deployed as part of "Flux 2" leverages the same Helm code as the CLI.
 
 ### Limitations of Argo
 
@@ -28,4 +28,4 @@ Argo requires all configuration options to be embedded into the ApplicationCR.
 
 ## Argo Is Still A Package
 
-As defined in the list of [Big Bang Packages](../../packages.md), Big Bang comes deployed with Argo for use by Mission applications to continue to deploy and manage their applications.  Similarly, even though Big Bang uses Helm internally for management of Big Bang packages, Big Bang does not advocate for Helm for use by applications run on clusters with Big Bang.
+As defined in the list of [Big Bang Packages](../../packages.md), Big Bang comes deployed with Argo for use by mission applications to continue to deploy and manage their applications.  Similarly, even though Big Bang uses Helm internally for management of Big Bang packages, Big Bang does not advocate for Helm for use by applications run on clusters with Big Bang.

docs/understanding-bigbang/concepts/glossary.md

@@ -74,13 +74,13 @@ The diagram below shows a typical deployment of Big Bang into a Kubernetes clust
 1. With everything in Git, the user can [deploy BigBang](./deployment.md) using a Kubernetes manifest.
 1. The manifest holds two Flux resources, one pointing to the Git repository holding the custom environment, and one telling Flux to run Kustomize on a targeted folder within the repo.
    1. The repository is reconciled first, pulling the files from Git.
-   1. Next, Kustomize is run on the environment configuration
+   1. Next, Kustomize is run on the environment configuration.
       1. The Kustomize files use Big Bang's Git repo as a base before applying overlays and patches for the configuration.
-      1. Flux uses SOPS to decrypt any secrets before deploying the manifests
-      1. After completing the Kustomization process, Flux deploys two ConfigMaps, two Secrets, and flux resources for Big Bang
+      1. Flux uses SOPS to decrypt any secrets before deploying the manifests.
+      1. After completing the Kustomization process, Flux deploys two ConfigMaps, two Secrets, and flux resources for Big Bang.
 1. Big Bang's flux resources include a Git repository holding the Helm chart and a Helm Release resource that tells Flux how to deploy the Helm chart.
    1. The repository is reconciled first, pulling the Helm chart from Git.
-   1. The Helm Release will check for the Helm chart and the Secrets / ConfigMaps deployed before performing a Helm install
+   1. The Helm Release will check for the Helm chart and the Secrets / ConfigMaps deployed before performing a Helm install.
 1. Once the Helm release deploys the Helm chart for Big Bang, each package that is enabled will have a Flux Git Repository and Helm Release resource deployed.
 1. All of the package Git repositories containing Helm charts will be pulled so that Flux can reconcile dependencies.
 1. Each package's Helm Release has dependencies built in.  Flux will reconcile these dependencies and deploy the Helm chart for the package once all of the dependencies are ready.