From 2e20f397565b3f942e85856d8a1028aec27e0b01 Mon Sep 17 00:00:00 2001
From: Micah Nagel <micah.nagel@defenseunicorns.com>
Date: Mon, 27 Feb 2023 18:19:09 +0000
Subject: [PATCH] OCI-ify wrapper + packages, add docs around usage
---
chart/templates/package/gitrepository.yaml | 4 +-
chart/templates/package/helmrelease.yaml | 13 +-
chart/templates/wrapper/gitrepository.yaml | 2 +-
chart/templates/wrapper/helmrelease.yaml | 15 +-
chart/values2.0.yaml | 36 +++-
docs/guides/deployment-scenarios/.pages | 2 +
.../extra-package-deployment.md | 181 ++++++++++++++++++
7 files changed, 236 insertions(+), 17 deletions(-)
create mode 100644 docs/guides/deployment-scenarios/extra-package-deployment.md
diff --git a/chart/templates/package/gitrepository.yaml b/chart/templates/package/gitrepository.yaml
index dc3f10dac6..313de0b1a3 100644
--- a/chart/templates/package/gitrepository.yaml
+++ b/chart/templates/package/gitrepository.yaml
@@ -1,6 +1,6 @@
{{- /* Used for GitOps on a package's Helm chart */ -}}
{{- range $pkg, $vals := .Values.packages -}}
-{{- if (dig "enabled" true $vals) -}}
+{{- if and (dig "enabled" true $vals) (eq (include "checkGitRef" $vals) "true") -}}
{{- $pkg = include "resourceName" $pkg -}}
{{- $defaults := $.Files.Get (printf "defaults/%s.yaml" $pkg) -}}
{{- if $defaults -}}
@@ -22,5 +22,5 @@ spec:
{{- include "validRef" $vals.git | nindent 4 -}}
{{- include "gitCreds" $ | nindent 2 }}
---
-{{ end -}}
+{{- end -}}
{{- end -}}
\ No newline at end of file
diff --git a/chart/templates/package/helmrelease.yaml b/chart/templates/package/helmrelease.yaml
index d96a53162e..8c8e8a96ed 100644
--- a/chart/templates/package/helmrelease.yaml
+++ b/chart/templates/package/helmrelease.yaml
@@ -19,13 +19,22 @@ spec:
releaseName: {{ $pkg }}
chart:
spec:
+ {{- if eq (include "checkGitRef" $vals) "true" }}
chart: {{ dig "git" "path" "chart" $vals }}
- interval: {{ default "5m" $fluxSettings.interval }}
- reconcileStrategy: Revision
sourceRef:
kind: GitRepository
name: {{ $pkg }}
namespace: {{ dig "namespace" "name" $pkg $vals }}
+ {{- else }}
+ chart: {{ dig "oci" "name" $pkg $vals }}
+ version: {{ dig "oci" "tag" nil $vals }}
+ sourceRef:
+ kind: HelmRepository
+ name: {{ dig "oci" "repo" "registry1" $vals }}
+ namespace: {{ $.Release.Namespace }}
+ {{- end }}
+ interval: {{ default "5m" $fluxSettings.interval }}
+ reconcileStrategy: Revision
{{- toYaml $fluxSettings | nindent 2 }}
{{- if $vals.postRenderers }}
postRenderers:
diff --git a/chart/templates/wrapper/gitrepository.yaml b/chart/templates/wrapper/gitrepository.yaml
index 2475f87fc5..1640af34b7 100644
--- a/chart/templates/wrapper/gitrepository.yaml
+++ b/chart/templates/wrapper/gitrepository.yaml
@@ -1,5 +1,5 @@
{{- /* Used for GitOps of the BigBang package wrapper Helm chart. Shared by all packages */ -}}
-{{- if and .Values.wrapper (omit (default dict .Values.packages) "sample") -}}
+{{- if and .Values.wrapper (eq (include "checkGitRef" .Values.wrapper) "true") (omit (default dict .Values.packages) "sample") -}}
apiVersion: source.toolkit.fluxcd.io/v1beta1
kind: GitRepository
metadata:
diff --git a/chart/templates/wrapper/helmrelease.yaml b/chart/templates/wrapper/helmrelease.yaml
index 67d4ecfc8c..d8c98cbe64 100644
--- a/chart/templates/wrapper/helmrelease.yaml
+++ b/chart/templates/wrapper/helmrelease.yaml
@@ -15,13 +15,22 @@ spec:
releaseName: {{ $pkg }}-wrapper
chart:
spec:
- chart: {{ default "wrapper" $.Values.wrapper.git.path }}
- interval: {{ default "5m" $fluxSettings.interval }}
- reconcileStrategy: Revision
+ {{- if eq (include "checkGitRef" $.Values.wrapper) "true" }}
+ chart: {{ default "chart" $.Values.wrapper.git.path }}
sourceRef:
kind: GitRepository
name: {{ $.Release.Name }}-wrapper
namespace: {{ $.Release.Namespace }}
+ {{- else }}
+ chart: {{ $.Values.wrapper.oci.name }}
+ version: {{ $.Values.wrapper.oci.tag }}
+ sourceRef:
+ kind: HelmRepository
+ name: {{ $.Values.wrapper.oci.repo }}
+ namespace: {{ $.Release.Namespace }}
+ {{- end }}
+ interval: {{ default "5m" $fluxSettings.interval }}
+ reconcileStrategy: Revision
{{- toYaml $fluxSettings | nindent 2 }}
valuesFrom:
- name: {{ $pkg }}-wrapper-values
diff --git a/chart/values2.0.yaml b/chart/values2.0.yaml
index e6087e2e77..9cecc4d1ed 100644
--- a/chart/values2.0.yaml
+++ b/chart/values2.0.yaml
@@ -242,16 +242,22 @@ addons:
tag: "3.8.0-bb.6"
repo: "registry1"
-# -- Wrapper chart for integrating Big Bang into a package
+# -- Wrapper chart for integrating Big Bang into a package, default deployment with OCI HelmRepo
wrapper:
+ oci:
+ # -- Name of the OCI chart in `repo`
+ name: wrapper
+ # -- Tag of the OCI chart in `repo`
+ tag: "0.1.1"
+ # -- Repository holding OCI chart, corresponding to `ociRepositories` name
+ repo: "registry1"
git:
- # -- Git repo holding the wrapper helm chart
- repo: https://repo1.dso.mil/platform-one/big-bang/apps/wrapper
- # -- Path inside of the git repo to find the helm chart
- path: chart
- # -- Git tag to check out. Takes precedence over branch. [More info](https://fluxcd.io/flux/components/source/gitrepositories/#reference)
- tag:
- branch: main
+ # -- Git repo holding the wrapper helm chart, example: https://repo1.dso.mil/platform-one/big-bang/apps/wrapper
+ repo: ""
+ # -- Path inside of the git repo to find the helm chart, example: chart
+ path: ""
+ # -- Git tag to check out. Takes precedence over branch. [More info](https://fluxcd.io/flux/components/source/gitrepositories/#reference), example: 0.0.2
+ tag: ""
# -- Packages to deploy with Big Bang integration
# @default - '{}'
@@ -265,8 +271,20 @@ packages:
# -- Use a kustomize deployment rather than Helm
kustomize: false
+ # -- OCI source is supported and recommended for Helm deployments
+ oci:
+ # -- Name of the OCI chart in `repo`
+ # @default -- Uses package name/yaml key by default.
+ name:
+ # -- Tag of the OCI chart in `repo`, required if using OCI
+ tag:
+ # -- Repository holding OCI chart, corresponding to `ociRepositories` name
+ # @default -- Uses `registry1` Helm Repository if not specified
+ repo:
+
+ # -- Git source is supported for both Helm and Kustomize deployments
git:
- # -- (Required) Git repo URL holding the helm chart for this package
+ # -- Git repo URL holding the helm chart for this package, required if using git
repo:
# -- Git commit to check out. Takes precedence over semver, tag, and branch. [More info](https://fluxcd.io/flux/components/source/gitrepositories/#reference)
commit:
diff --git a/docs/guides/deployment-scenarios/.pages b/docs/guides/deployment-scenarios/.pages
index 4515e8761f..97fcaa89e9 100644
--- a/docs/guides/deployment-scenarios/.pages
+++ b/docs/guides/deployment-scenarios/.pages
@@ -1,4 +1,6 @@
nav:
- Quickstart: quickstart.md
- SSO Quickstart: sso-quickstart.md
+ - Extra Package Deployment: extra-package-deployment.md
- Multiple Ingress: multiple-ingress.md
+ - Appliance Mode: appliance-mode.md
diff --git a/docs/guides/deployment-scenarios/extra-package-deployment.md b/docs/guides/deployment-scenarios/extra-package-deployment.md
new file mode 100644
index 0000000000..e6a549525d
--- /dev/null
+++ b/docs/guides/deployment-scenarios/extra-package-deployment.md
@@ -0,0 +1,181 @@
+# Extra Package Deployment
+
+âš ï¸ **NOTE: This doc is a work in progress as this functionality is not standardized or fully tested yet. Changes may happen at any point, and this functionality should be considered as BETA until Big Bang 2.0.** âš ï¸
+
+When using Big Bang you often find that you need or want to deploy an additional package alongside your chosen core/addon packages. This might be a mission app or just an extra helm chart from the Big Bang community or broader helm/kubernetes community.
+
+In order to ease the burden on end users and increase integration with Big Bang components we have provided a way to deploy these additional packages with extra "wrapping" to provide additional alignment with Big Bang standards.
+
+## What is provided
+
+When utilizing the extra package values/logic there are two main pieces that are deployed: your package and a wrapper. Each of these pieces provides certain things necessary for deploying.
+
+### Package
+
+By deploying your package with the Big Bang values you will get the below all through Big Bang values control:
+- Flux `GitRepository` or `HelmRepository` depending on configuration
+- Flux `HelmRelease` or `Kustomization` depending on configuration
+- Control of flux settings for the above
+- Control of `postRenderers` is using Flux `HelmRelease`
+- Passthrough of values to configure your package chart
+
+The alternative is that customers would need to manage these things in a "sideloaded" fashion and not have these tied to the Big Bang deployment lifecycle/management.
+
+### Wrapper
+
+The wrapper provides additional integrations with key Big Bang components and standards, as well as extensibility features for common use cases. All of these can be tailored to a given package's needs witha simple interface. Currently included are:
+- Istio: injection/sidecars, `VirtualService` for ingress, and `PeerAuthentication` for mTLS
+- Monitoring: `ServiceMonitor` for metrics, alerts for alertmanager, dashboards for Grafana
+- NetworkPolicies: Default set of "best practice" network policies with opptions to extend
+- Secret creation (of arbitrary content)
+- Configmap creation (of arbitrary content)
+- SSO configuration with Authservice (not fully automated, requires additional configuration of chains)
+
+These pieces can typically be complicated to get setup correctly and connected to components that are provided in Big Bang core, so we provide a simplified interface to add them.
+
+## How to use it
+
+The first piece you need in order to make use of this extensibility is the addition of `wrapper` in your Big Bang values. As of this documentation revision that should look like the below:
+
+```yaml
+ociRepositories:
+ - name: "registry1"
+ repository: "oci://registry1.dso.mil/bigbang"
+ existingSecret: "private-registry"
+
+wrapper:
+ oci:
+ name: wrapper
+ tag: "0.1.0"
+ repo: "registry1"
+```
+
+In Big Bang 2.0 this will be included in the default values with an OCI source. The wrapper does not require any additional values (simply need to point to its "storage" location of git/helm repository as seen above).
+
+The wrapper does not add anything additional to your deployment, unless you also specify a `packages` value which configures what package to deploy and what wrapper configuration is desired. A basic example of a package deployment could look like this:
+
+```yaml
+packages:
+ podinfo:
+ git:
+ repo: https://github.com/stefanprodan/podinfo.git
+ tag: 6.3.4
+ path: charts/podinfo
+```
+
+The package also has OCI support for sourcing the artifacts; usage will be encouraged with the move to 2.0 and "first-class" support for `HelmRepository` resources.
+
+With these values added you should have a very basic deployment of `podinfo` added onto your Big Bang install with some basic default integrations. The rest of this guide will walk you through each section of Big Bang touchpoints and some example configurations you could use. Each of the configurations are compatible with each other (i.e. you can combine the examples below).
+
+### Basic Overrides
+
+There are some basic ovveride values provides to modify your Helm chart installation. An example of these values is included below:
+
+```yaml
+packages:
+ podinfo:
+ git:
+ repo: https://github.com/stefanprodan/podinfo.git
+ tag: 6.3.4
+ path: charts/podinfo
+ flux:
+ timeout: 5m
+ postRenderers: []
+ values:
+ replicaCount: 3
+```
+
+In this example we are doing two things:
+- Overriding the Flux timeout on our `HelmRelease` to be 5 minutes
+- Passing a value directly to the Podinfo chart to create 3 replicas
+
+We could also specify a `postRenderers` value here, which is documented well in [this document](../../understanding-bigbang/configuration/postrenderers.md).
+
+### Istio Configuration
+
+The wrapper chart provides a number of different ways to provide Istio configuration. The below is a basic example configuring some pieces for the `podinfo` application:
+
+```yaml
+packages:
+ podinfo:
+ git:
+ repo: https://github.com/stefanprodan/podinfo.git
+ tag: 6.3.4
+ path: charts/podinfo
+ istio:
+ hosts:
+ - names:
+ - podinfo
+ gateways:
+ - public
+ destination:
+ port: 9898
+```
+
+In this example we are primarily adding a virtual service for ingress to our application (leveraging defaults to select the proper service). By using the wrapper we are also getting several default options including istio sidecar injection and STRICT mTLS.
+
+There are more ways to modify the virtual service creation and mTLS config; additional values can be referenced in the [wrapper chart istio section](https://repo1.dso.mil/big-bang/product/packages/wrapper/-/blob/6536759fef016db8b5504ad6c237f2daffe22844/chart/values.yaml#L31-75).
+
+### Monitoring Configuration
+
+The wrapper chart also provides ways to integrate with the monitoring stack (Prometheus, Alertmanager, and Grafana). The example below is a basic way to configure monitoring for `podinfo`:
+
+```yaml
+packages:
+ podinfo:
+ git:
+ repo: https://github.com/stefanprodan/podinfo.git
+ tag: 6.3.4
+ path: charts/podinfo
+ monitor:
+ services:
+ - spec:
+ endpoints:
+ - port: http
+```
+
+In this example we are adding a service monitor that will target the port named `http`. We are leveraging a number of defaults here to select the proper service and metrics paths.
+
+There are other ways to further modify monitoring settings including more advanced service monitor config; additional values can be referenced in the [wrapper chart monitor section](https://repo1.dso.mil/big-bang/product/packages/wrapper/-/blob/6536759fef016db8b5504ad6c237f2daffe22844/chart/values.yaml#L77-91).
+
+### Network Policy Configuration
+
+The wrapper chart provides ways to configure network policies as needed for your application. The example below again provides a basic config for the `podinfo` application:
+
+```yaml
+packages:
+ podinfo:
+ git:
+ repo: https://github.com/stefanprodan/podinfo.git
+ tag: 6.3.4
+ path: charts/podinfo
+ network:
+ allowControlPlaneEgress: true
+```
+
+In this example we are allowing the package to have egress to the Kubernetes control plane (aka API). This particular setting can be beneficial for operators that may need to create Kubernetes resources.
+
+There are a number of additional configurations including allowing egress to https or more custom needs; additional values can be referenced in the [wrapper chart network section](https://repo1.dso.mil/big-bang/product/packages/wrapper/-/blob/6536759fef016db8b5504ad6c237f2daffe22844/chart/values.yaml#L93-113).
+
+### Configmap / Secret Creation
+
+Oftentimes when deploying a Helm chart you may be expected to point to an existing secret for credentials, a license, or external service configuration (S3/RDS). The below values can be helpful in creation of these items:
+
+```yaml
+packages:
+ podinfo:
+ git:
+ repo: https://github.com/stefanprodan/podinfo.git
+ tag: 6.3.4
+ path: charts/podinfo
+ configMaps:
+ - name: config
+ data:
+ foo: bar
+ secrets:
+ - name: secret
+ data:
+ foo: YmFyCg==
+```
+
+These secrets/configmaps are created prior to installation of your package, so that they can be referenced in any values you use to configure your package.
--
GitLab