UNCLASSIFIED - NO CUI

Skip to content
Snippets Groups Projects
Commit 204d7eec authored by Micah Nagel's avatar Micah Nagel
Browse files

Merge branch '851-docs-supported-integration' into 'master' 

Resolve "Update documentation for final integration product integration into Big Bang"

Closes #851

See merge request platform-one/big-bang/bigbang!981
parents a6b84572 81ab9627
No related branches found
No related tags found
No related merge requests found
Hide whitespace changes
Inline Side-by-side
docs/developer/package-integration.md
+ 1
− 1
View file @ 204d7eec
......@@ -13,5 +13,5 @@ The following documents should be followed, in order, to fully integrate a new p
1. [Additional Tests](./package-integration/package-integration-testing.md): Add testing to validate basic functionality
1. [Network Policies](./package-integration/package-integration-network-policies.md): Add ingress/egress policies to restrict network traffic for security
1. [Policy Enforcement](./package-integration/package-integration-policy-enforcement.md): Update package to comply with default security and governance policies in Big Bang
1. [Supported Package](./package-integration/package-integration-supported.md): Migrate package into the Big Bang repo as a supported package
1. [Supported Package](./package-integration/product-integration-supported.md): Migrate package into the Big Bang repo as a supported package
1. [Final Documentation](./package-integration/package-integration-documentation.md): Add additional Big Bang documentation for final release
docs/developer/package-integration/package-integration-supported.md → docs/developer/package-integration/product-integration-supported.md
+ 64
− 48
View file @ 204d7eec
# Integrate a Package with Bigbang Helm Chart
# Big Bang Package: Supported Package Integration
After [graduating your package](https://repo1.dso.mil/platform-one/bbtoc/-/tree/master/process) and getting approval to add it to Big Bang, the following instructions must be completed.
[[_TOC_]]
1. Make a branch from the BigBang chart repository master branch. You can automatically create a branch from the Repo1 Gitlab issue. Or, in some cases you might manually create the branch. You should name the branch with your issue number. If your issue number is 9999 then your branch name can be "9999-my-description". It is best practice to make branch names short and simple.
## Prerequisites
1. Create a directory for your package at `chart/templates/<your-package-name>`
- [Helm](https://helm.sh/docs/intro/install/)
- [Kubectl](https://kubernetes.io/docs/tasks/tools/#kubectl)
- [Git](https://git-scm.com/book/en/v2/Getting-Started-Installing-Git)
- A multi-node Kubernetes cluster to deploy Big Bang and your package
- Graduated package Helm chart in a Git repository
1. Inside this folder will be various helm template files. The rule is one document per yaml file. You can copy one of the other package folders and tweak the code for your package. Gitlab is a good example to reference because it is one of the more complicated Packages. Note that the Istio VirtualService comes from the Package and is not created in the BigBang chart. The purpose of these helm template files is to create an easy-to-use spec for deploying supported applications. Reasonable and safe defaults are provided and any needed secrets are auto-created. We accept the trade off of easy deployment for complicated template code. More details are in the following steps.
## Package Updates
```shell
gitrepository.yaml # Flux GitRepository. Is configured by BigBang chart values.
helmrelease.yaml # Flux HelmRelease. Is configured by BigBang chart values.
namespace.yaml # Contains the namespace and any needed secrets
secret-*.yaml # various template files that create any needed k8s secrets
values.yaml # Implements all the BigBang customizations of the package and passthrough for values.
```
1. Have a Big Bang owner move the package's GitLab project from sandbox to `https://repo1.dso.mil/platform-one/big-bang/apps/<category>`.
1. More details about values.yaml: Code reasonable and safe defaults but prioritize any user defined passthrough values wherever this makes sense. Avoid duplicating tags that are provided in the upstream chart values. Instead code reasonable defaults in the values.yaml template. The following is an example from Gitlab that handles SSO config. The code uses Package chart passthrough values if the user has entered them but otherwise defaults to the BigBang chart values or the Helm default values. Notice that the secret is not handled this way. The assumption is that if the user has enabled the BigBang SSO feature the secret will be auto created. In this case the user should not be overriding the secret. If the user wants to create their own secret they should not be enabling the BigBang SSO feature.
1. Have a Big Bang maintainer create a new tag and release for your project that matches your Helm chart `version` in `chart/Chart.yaml`.
Note that helm does not handle any missing parent tags in the yaml tree. The 'if' statement and 'default' method throw 'nil' errors when parent tags are missing. The work-around is to inspect each level of the tree and assign an empty 'dict' if the value does not exist. Then you will be able to use 'hasKey' in your 'if' statements as shown below in this example from Gitlab. Having described all this, you should understand that coding conditional values is optional. The passthrough values will take priority regardless. But the overridden values will not show up in the deployed flux HelmRelease object if you don't code the conditional values. The value overrides will be obscured in the Package values secret. The only way to confirm that the overrides have been applied is to use `helm get values <releasename> -n bigbang` command on the deployed helm release. When the passthrough values show up in the HelmRelease object the Package configuration is much easier to see and verify. Use your own judgement on when to code conditional values.
## Big Bang Updates
```yaml
global:
{{- if or .Values.addons.gitlab.sso.enabled .Values.addons.gitlab.objectStorage.endpoint }}
appConfig:
{{- end }}
{{- if .Values.addons.gitlab.sso.enabled }}
omniauth:
enabled: true
{{- $global := .Values.addons.gitlab.values.global | default dict }}
{{- $appConfig := $global.appConfig | default dict }}
{{- $omniauth := $appConfig.omniauth | default dict }}
{{- if hasKey $omniauth "allowSingleSignOn" }}
allowSingleSignOn: {{ .Values.addons.gitlab.values.global.appConfig.omniauth.allowSingleSignOn }}
{{- else }}
allowSingleSignOn: ['openid_connect']
{{- end }}
{{- if hasKey $omniauth "blockAutoCreatedUsers" }}
blockAutoCreatedUsers: {{ .Values.addons.gitlab.values.global.appConfig.omniauth.blockAutoCreatedUsers }}
{{- else }}
blockAutoCreatedUsers: false
{{- end }}
providers:
- secret: gitlab-sso-provider
key: gitlab-sso.json
{{- end }}
1. Open an issue under `https://repo1.dso.mil/platform-one/big-bang/bigbang/-/issues` to track your work for the new package.
```
1. Clone the [Big Bang Git repository](https://repo1.dso.mil/platform-one/big-bang/bigbang) to your machine using `git clone https://repo1.dso.mil/platform-one/big-bang/bigbang`
1. Make a branch from the BigBang chart repository `master` branch. You can automatically create a branch from the Repo1 Gitlab issue. Or, in some cases you might manually create the branch. Name the branch with your issue number. For example, if your issue number is `9999` then your branch name can be `9999-my-description`. It is best practice to make branch names short and simple.
1. Make sure the files described in this [document](https://repo1.dso.mil/platform-one/big-bang/bigbang/-/blob/master/docs/developer/package-integration/package-integration-flux.md) have been generated in `chart/templates/<your-package-name>` directory
1. More details about secret-*.yaml: The secret template is where the code for secrets go. Typically you will see secrets for imagePullSecret, sso, database, and possibly object storage. These secrets are a BigBang chart enhancement. They are created conditionally based on what the user enables in the config. For example if the app supports SSO and will need a Certificate Authority supplied to trust the connection to the IdP there should be a `secret-ca.yaml` template to populate a secret with the `sso.certificate_authority` value in the application namespace.
1. Edit the chart/templates/values.yaml. Add your Package to the list of Packages. Just copy one of the others and change the name. This supports adding chart values from a secret. Pay attention to whether this is a core Package or an add-on package, the toYaml values are different for add-ons. This template allows a Package to add chart values that need to be encrypted in a secret.
1. Merge your default package values from `<your-package-git-folder>/bigbang/values.yaml` into `chart/values.yaml`. Only the "standard" keys used across packages should be used. Keep in mind that values can be passed directly to the package using `.Values.<package>.values`
> If your package is an `addon`, it falls into a different location than core packages. In this case, you will need to update all your references from `.Values.<package>` to `.Values.addons.<package>`.
1. Edit the `chart/values.yaml`. Add your Package to the bottom of the core section if a core package or addons section if an add-on. You can copy from one of the other packages and modify appropriately. Some possible tags underneath your package are [enabled, git, sso, database, objectstorage]. Avoid duplicating value tags from the upstream chart in the BigBang chart. The goal is not to cover every edge case. Instead code reasonable defaults in the helmrelease template and allow customer to override values in addons.`<packageName>.values`
Example:
```yaml
addons:
......@@ -84,11 +64,22 @@
values: {}
```
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. 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. Add your packages name to the ORDERED_HELMRELEASES list in scripts/deploy/02_wait_for_helmreleases.sh.
1. You will also need to create an MR into the pipeline templates to update [02_wait_for_helmreleases.sh](https://repo1.dso.mil/platform-one/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.
To test your pipeline changes you can make a draft MR pointing to your pipeline branch in `.gitlab-ci.yml`:
```
include:
- project: 'platform-one/big-bang/pipeline-templates/pipeline-templates'
ref: your-branch
file: '/pipelines/bigbang.yaml'
variables:
PIPELINE_REPO_BRANCH: 'your-branch'
```
1. Create an overrrides directory as a sibling directory next to the bigbang code directory. Put your override yaml files in this directory. The reason we do this is to avoid modifying the bigbang values.yaml that is under source control. You could accidentally commit it with your secrets. Avoid that mistake and create a local overrides directory. One option is to copy the tests/ci/k3d/values.yaml to make the override-values.yaml and make modifications. The file structure is like this:
1. Create an overrrides directory as a sibling directory next to the bigbang code directory. Put your override yaml files in this directory. The reason we do this is to avoid modifying the bigbang values.yaml that is under source control. You could accidentally commit it with your secrets. Avoid that mistake and create a local overrides directory. One option is to copy the `./tests/test-values.yaml` to make the override-values.yaml and make modifications. The file structure is like this:
```text
├── bigbang/
└── overrides/
......@@ -96,7 +87,9 @@
├── registry-values.yaml
└── any-other-values.yaml
```
Make the registry-values yaml like this:
```yaml
registryCredentials:
- registry: registry1.dso.mil
......@@ -104,9 +97,11 @@
password: your-pull-token
email: xxx@xxx.xxx
```
You will use these files as arguments in your helm commands.
1. Verify your Package works when deployed through bigbang. See the instructions below in the ```BigBang Development and Testing Cycle``` for the manual ```imperative``` way to deploy with helm upgrade commands. While testing you should use your package git branch instead of a tag. If you don't null the tag your branch will not get deployed. example:
```yaml
addons:
app1:
......@@ -118,6 +113,7 @@
1. After you have tested BigBang integration complete a Package MR and contact the codeowners to create a release tag. Package release tags follow the naming convention of {UpstreamChartVersion}-bb.{BigBangVersion} – example 1.2.3-bb.0.
1. Make sure to change the chart/values.yaml file to point to the new release tag rather than your dev branch (i.e. tag: "1.2.3-bb.0" in place of branch: "999-your-dev-branch-name"). example:
```yaml
addons:
app1:
......@@ -151,13 +147,13 @@ helm delete bigbang -n bigbang
# Helm delete will not delete the bigbang namespace
kubectl delete ns bigbang
# Istio namespace will be stuck in "finalizing". So run the script to delete it.
./script/remove-ns-finalizer.sh istio-system
./scripts/remove-ns-finalizer.sh istio-system
```
### GitOps with Flux
Using GitOps for development is NOT recommended. Your development iteration cycle time will be slowed down waiting for flux reconciliation. This is not an efficient use of your time. These instructions are included here for informational purposes. You can deploy your development code the same way a customer would deploy using GitOps. You must commit any code changes to your development branches because this is how GitOps works. There is a [customer template repository](https://repo1.dso.mil/platform-one/big-bang/customers/template) that has an example template for how to deploy using BigBang. You must fork or copy this repo to your own private repo. Make the necessary modifications as explained in the README.md. The setup information is not repeated here. Before committing code it is a good idea to manually run `helm template` and a `helm install` with dry run. This will reveal many errors before you make a commit. Here are the steps you can iterate:
```shell
# Verify chart code before committing
helm template bigbang ./chart -n bigbang -f ../customers/template/dev/configmap.yaml --debug
......@@ -183,3 +179,23 @@ kubectl apply -f dev/bigbang.yaml
kubectl delete -f dev/bigbang.yaml
./scripts/remove-ns-finalizer.sh istio-system
```
### Validation
In order to validate that the new package is running as expected, we recommend to check the following things
1. Make sure that the steps from the other documentation in `package-integration` directory has been completed
1. Deploy the package following the Imperative step described [above](#imperative)
1. Make sure that a namespace has been created for the package deployed (`kubectl get ns`)
1. The HR (Helm Release) reconciled successfully for the package (`kubectl get hr -A`)
1. All the pods and services we expected are up and running (`kubectl get po -n <Package Namespace>`)
1. Make sure all the pods are in a healthy state and have the right specs
1. Utilize grafana to make sure the pods have the right resources if needed
1. Create an MR and make sure it passes all the automated tests
0% or .
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment

UNCLASSIFIED - NO CUI