From 43bd8a33b4b84c02d7b6e2472da0f173f7cfa24d Mon Sep 17 00:00:00 2001
From: Christopher O'Connell <coconnell@bridgephase.com>
Date: Wed, 31 Jan 2024 15:41:51 +0000
Subject: [PATCH] Update package integration docs + add steps
---
docs/developer/package-integration/README.md | 1 +
.../package-integration/bigbang-merge-request.md | 5 +++++
.../package-integration/helm-standards.md | 14 ++++++++++++++
docs/developer/package-integration/pipeline.md | 2 +-
.../package-integration/policy-enforcement.md | 2 +-
docs/developer/package-integration/storage.md | 4 ++--
docs/developer/package-integration/supported.md | 2 +-
docs/developer/package-integration/testing.md | 4 ++--
docs/developer/package-integration/upstream.md | 4 ++--
9 files changed, 29 insertions(+), 9 deletions(-)
create mode 100644 docs/developer/package-integration/bigbang-merge-request.md
diff --git a/docs/developer/package-integration/README.md b/docs/developer/package-integration/README.md
index 71153c4640..dcd73bb4a7 100644
--- a/docs/developer/package-integration/README.md
+++ b/docs/developer/package-integration/README.md
@@ -15,3 +15,4 @@ The following documents should be followed, in order, to fully integrate a new p
1. [Policy Enforcement](policy-enforcement.md): Update package to comply with default security and governance policies in Big Bang
2. [Supported Package](supported.md): Migrate package into the Big Bang repo as a supported package
3. [Final Documentation](documentation.md): Add additional Big Bang documentation for final release
+4. [Big Bang Merge Request](bigbang-merge-request.md): Create Big Bang Merge Request and run all packages pipeline.
diff --git a/docs/developer/package-integration/bigbang-merge-request.md b/docs/developer/package-integration/bigbang-merge-request.md
new file mode 100644
index 0000000000..54c2936857
--- /dev/null
+++ b/docs/developer/package-integration/bigbang-merge-request.md
@@ -0,0 +1,5 @@
+# Create a Big Bang Merge Request
+
+Following the steps in the [flux integration](flux.md), create a merge request into big bang for your package.
+When ready, add the all-packages label to the MR and run the pipeline. This will trigger a pipeline with all big bang packages installed to a k3d cluster.
+A passing all-packages pipeline is required prior to merging the new package. This validates that the additional package works with existing packages.
\ No newline at end of file
diff --git a/docs/developer/package-integration/helm-standards.md b/docs/developer/package-integration/helm-standards.md
index 0f81c445e2..70e8e3fda5 100644
--- a/docs/developer/package-integration/helm-standards.md
+++ b/docs/developer/package-integration/helm-standards.md
@@ -95,6 +95,20 @@ commonLabels:
app.kubernetes.io/bigbang-version: 1.6.0
```
+## Big Bang Package Readme Generation
+
+Follow [this guide](https://repo1.dso.mil/big-bang/product/packages/gluon/-/blob/master/docs/bb-package-readme.md?ref_type=heads) for package readme.md generation
+
+Note the Big Bang package README.md is separate from the README.md included as part of the upstream chart. See ArgoCD for an example, [Big Bang package README.md](https://repo1.dso.mil/big-bang/product/packages/argocd/-/blob/main/README.md?ref_type=heads) vs [upstream chart README.md](https://repo1.dso.mil/big-bang/product/packages/argocd/-/blob/main/chart/README.md?ref_type=heads)
+
+Each package value in values.yaml should have a comment descriptor above the value. We generate the package README.md using a script that expects this format. The README.md will contain a table with default configurations and descriptors pulled from the comments.
+
+# This is a comment for the value below
+enabled: false
+
+# This comment describes the purpose of the configurable value below
+strategy: scalable
+
## Kubernetes Objects
These requirements for the kubernetes components come from the Kubernetes STIG, Kubesec.io and other best practices
diff --git a/docs/developer/package-integration/pipeline.md b/docs/developer/package-integration/pipeline.md
index 569e9fb363..6b1e4682be 100644
--- a/docs/developer/package-integration/pipeline.md
+++ b/docs/developer/package-integration/pipeline.md
@@ -27,7 +27,7 @@ Pipelines provide rapid feedback to changes in our Helm chart as we develop and
The pipeline **requires** that all images are stored in either Iron Bank (`registry1.dso.mil`) or Repo1 (`registry.dso.mil`). In some cases, you may be able to substitute images already in Iron Bank for the ones in the Helm chart. For example, images for `curl`, `kubectl` or `jq` can use `registry1.dso.mil/ironbank/big-bang/base`. If you have not already submitted your containers to Iron Bank, [start the process](https://repo1.dso.mil/dsop/dccscr/-/blob/master/README.md). While you are working your way to Iron Bank approval, you can temporarily put the images in `registry.dso.mil` for development by doing the following:
-> Check if the Container Registry is on by navigating to `https://repo1.dso.mil/platform-one/big-bang/apps/sandbox/<your project>/container_registry`. If you get a 404 error, you need to request a Maintainer turn this feature on in your project via Settings > General > Visibility > Container Registry.
+> Check if the Container Registry is on by navigating to `https://repo1.dso.mil/big-bang/apps/sandbox/<your project>/container_registry`. If you get a 404 error, you need to request a Maintainer turn this feature on in your project via Settings > General > Visibility > Container Registry.
```shell
# Image Info
diff --git a/docs/developer/package-integration/policy-enforcement.md b/docs/developer/package-integration/policy-enforcement.md
index a7d288aabd..7412bb12ac 100644
--- a/docs/developer/package-integration/policy-enforcement.md
+++ b/docs/developer/package-integration/policy-enforcement.md
@@ -17,7 +17,7 @@ The policy enforcement tool is deployed as the first package in the default Big
### 2. Identifying Violations Found on Your Application
-In the following section, you will be shown how to identify violations found in your package. The app [PodInfo](https://repo1.dso.mil/big-bang/product/packages/podinfo) will be used for all of the examples. Gatekeeper has three enforcement actions `deny`, `dryrun`, and `warn`. Only `deny` will prohibit access to the cluster, but the `warn` and `dryrun` constraints should be fixed as well as they are generally best practice.
+In the following section, you will be shown how to identify violations found in your package. The app [PodInfo](https://repo1.dso.mil/big-bang/apps/sandbox/podinfo) will be used for all of the examples. Gatekeeper has three enforcement actions `deny`, `dryrun`, and `warn`. Only `deny` will prohibit access to the cluster, but the `warn` and `dryrun` constraints should be fixed as well as they are generally best practice.
In this example we will be attempting to install PodInfo onto our cluster:
diff --git a/docs/developer/package-integration/storage.md b/docs/developer/package-integration/storage.md
index d6f69cbb14..a92ad426a4 100644
--- a/docs/developer/package-integration/storage.md
+++ b/docs/developer/package-integration/storage.md
@@ -77,7 +77,7 @@ fileStore:
{{- end }}
```
-Example: [MatterMost](https://repo1.dso.mil/big-bang/bigbang/-/blob/master/chart/templates/mattermost/mattermost/values.yaml#L66-68) passes the endpoint and bucket via chart values.
+Example: [MatterMost](https://repo1.dso.mil/big-bang/bigbang/-/blob/master/chart/templates/mattermost/values.yaml#L101) passes the endpoint and bucket via chart values.
1. Package chart accepts a secret name where all the object storage connection info is defined. In these cases we make the secret in the BB chart.
@@ -90,7 +90,7 @@ objectStorage:
key: backups
```
-Example: [GitLab](https://repo1.dso.mil/big-bang/bigbang/-/blob/master/chart/templates/gitlab/values.yaml#L54-57)
+Example: [GitLab](https://repo1.dso.mil/big-bang/bigbang/-/blob/master/chart/templates/gitlab/values.yaml#L76)
- Create the secret in the Big Bang chart. (NOTE: Replace `<package>` with your package name in the example below)
diff --git a/docs/developer/package-integration/supported.md b/docs/developer/package-integration/supported.md
index 71ab5ba5b1..6cbb1ffc53 100644
--- a/docs/developer/package-integration/supported.md
+++ b/docs/developer/package-integration/supported.md
@@ -66,7 +66,7 @@ After [graduating your package](https://repo1.dso.mil/platform-one/bbtoc/-/tree/
1. Edit `tests/test-values.yaml`. These are the settings that the CI pipeline uses to run a deployment test. Set your Package to be enabled and add any other necessary values. Where possible reduce the number of replicas to a minimum to reduce strain on the CI infrastructure. When you commit your code the pipeline will run. You can view the pipeline in the Repo1 Gitlab console. Fix any errors in the pipeline output. The pipeline automatically runs a "smoke" test. It deploys bigbang on a k3d cluster using the test values file.
-1. You will also need to create an MR into the pipeline templates to update [02_wait_for_helmreleases.sh](https://repo1.dso.mil/big-bang/pipeline-templates/pipeline-templates/-/blob/master/scripts/deploy/02_wait_for_helmreleases.sh) and add your package's HR name to the core or addon lists.
+1. You will also need to create an MR into the pipeline templates to update [02_wait_for_helmreleases.sh](https://repo1.dso.mil/big-bang/pipeline-templates/pipeline-templates/-/blob/master/scripts/deploy/03_wait_for_helmreleases.sh) and add your package's HR name to the core or addon lists.
To test your pipeline changes you can make a draft MR pointing to your pipeline branch in `.gitlab-ci.yml`:
```yaml
diff --git a/docs/developer/package-integration/testing.md b/docs/developer/package-integration/testing.md
index c88b382500..5fa8b94640 100644
--- a/docs/developer/package-integration/testing.md
+++ b/docs/developer/package-integration/testing.md
@@ -15,7 +15,7 @@ Usually, Helm charts come with a set of Helm tests that can be run to test the d
## Integration
-Bigbang provides a library helm chart called [Gluon](https://repo1.dso.mil/big-bang/apps/library-charts/gluon) to help simplify the process of creating both cypress and script helm tests.
+Bigbang provides a library helm chart called [Gluon](https://repo1.dso.mil/big-bang/product/packages/gluon) to help simplify the process of creating both cypress and script helm tests.
To include this library as a subchart in your package repo follow the instructions provided in the pipeline repo [here](https://repo1.dso.mil/big-bang/pipeline-templates/pipeline-templates#including-the-gluon-helm-test-library-in-your-package).
@@ -90,7 +90,7 @@ echo "END podinfo jwt test"
echo "-----------------------------------------"
```
-More information on cypress tests and creating tests with scripts for testing non-UI portions of an app can be found [here](https://repo1.dso.mil/big-bang/apps/library-charts/gluon/-/blob/master/docs/bb-tests.md)
+More information on cypress tests and creating tests with scripts for testing non-UI portions of an app can be found [here](https://repo1.dso.mil/big-bang/product/packages/gluon/-/blob/master/docs/bb-tests.md)
## Validation
diff --git a/docs/developer/package-integration/upstream.md b/docs/developer/package-integration/upstream.md
index 9dab8644c8..d573c343f4 100644
--- a/docs/developer/package-integration/upstream.md
+++ b/docs/developer/package-integration/upstream.md
@@ -11,7 +11,7 @@ Before beginning the process of integrating a package into Big Bang, you will ne
## Project
-It is recommended that you create your project in [Big Bang's Sandbox](https://repo1.dso.mil/big-bang/product/packages). This allows you to leverage Big Bang's pipelines, collaborate with Big Bang developers, and easily migrate to a fully graduated project.
+It is recommended that you create your project in [Big Bang's Sandbox](https://repo1.dso.mil/big-bang/apps/sandbox). This allows you to leverage Big Bang's pipelines, collaborate with Big Bang developers, and easily migrate to a fully graduated project.
You will need to request a sandbox project and Developer access from a Big Bang team member.
@@ -143,7 +143,7 @@ To minimize maintenance, it is preferable to reuse existing Helm charts availabl
- Values: How to configure Helm chart values
- Contributing: Link to contributing guide
- There is a standard Big Bang template used for all packages. This can be created by following the [templating instructions](https://repo1.dso.mil/big-bang/apps/library-charts/gluon/-/blob/master/docs/bb-package-readme.md)
+ There is a standard Big Bang template used for all packages. This can be created by following the [templating instructions](https://repo1.dso.mil/big-bang/product/packages/gluon/-/blob/master/docs/bb-package-readme.md)
> This process produces a `README.md`, `README.md.gotpl`, and `.helmdocsignore`. The `gotpl` file is used as values to update the `README.md`.
> To avoid having the `flux` helm chart also added to the `README.md`, run `echo 'flux/*' >> .helmdocsignore`
--
GitLab