Integration Guide¶
This guide is intended to showcase different ways bb-common can be integrated into applications. Although the recommended process is to simply add bb-common as a sub-chart, there may be some cases where that simply isn’t possible. In all scenarios it is recommended to pin to the most up-to-date version of bb-common which can be found here.
Fully Owned Applications¶
When the application chart is fully owned by the user, add bb-common directly
to the application’s Chart.yaml as shown below:
# Chart.yaml
dependencies:
- name: bb-common
version: "<version>" # Update with latest version
repository: oci://registry1.dso.mil/bigbang
Once the Chart.yaml file has been updated, run the following command from the chart directory:
helm dep update
The final step is to simply configure the settings in your values.yaml file as shown below:
# values.yaml
bb-common:
networkPolicies:
enabled: true
Applications Not Fully Owned by the User¶
It is possible to use bb-common directly as a sub-chart even when the application chart is not fully owned by the user by using a pass-through implementation. This is similar to how Big Bang leverages upstream applications like Grafana and Kiali.
The following command can be used to create a blank Helm application chart:
helm create <my-passthrough-application>
The only difference in this scenario is that the upstream chart will also be listed as a dependency inside the Chart.yaml along with bb-common. Once the dependencies have been updated the process is exactly the same as the previous scenario.
ArgoCD¶
It is possible to deploy bb-common alongside another application using ArgoCD even if the ability to add it as a sub-chart is not present. Although this is not the recommended approach, it may be necessary in some scenarios.
In this scenario, the bb-common chart can simply be provided as an additional source under the spec.sources key. The values for bb-common can then be specified under helm.valuesObject with all values inline.
[!NOTE] The application being deployed needs to be under both the
sourceandsourceskeys for this to work. This requirement comes from ArgoCD when using the GUI to deploy as it will not validate ifsourceis left blank; This is not necessary if installing via command line.
Below is a full example using the Nexus-IQ chart from the community site:
apiVersion: argoproj.io/v1alpha1
kind: Application
metadata:
name: podinfo
finalizers:
- resources-finalizer.argocd.argoproj.io
spec:
destination:
namespace: podinfo
server: https://kubernetes.default.svc
source:
repoURL: https://github.com/stefanprodan/podinfo.git
path: charts/podinfo
targetRevision: 6.12.0
sources:
- repoURL: https://github.com/stefanprodan/podinfo.git
path: charts/podinfo
targetRevision: 6.12.0
helm:
valuesObject:
cache: tcp://podinfo-redis:6379
image:
repository: registry1.dso.mil/ironbank/opensource/bigbang/podinfo
tag: 6.10.1
pullSecrets:
- name: private-registry
serviceMonitor:
enabled: true
redis:
enabled: true
repository: registry1.dso.mil/ironbank/opensource/redis/redis8-slim
tag: 8.6.1
imagePullSecrets:
- name: private-registry
- repoURL: https://repo1.dso.mil/big-bang/product/packages/bb-common.git
path: chart
targetRevision: 1.0.1 # Update with latest version
helm:
valuesObject:
istio:
enabled: true
authorizationPolicies:
enabled: true
generateFromNetpol: true
networkPolicies:
enabled: true
ingress:
to:
podinfo:9898:
from:
k8s:
monitoring-monitoring-kube-prometheus@monitoring/prometheus:
enabled: true
redis:6379:
podSelector:
matchLabels:
app: podinfo-redis
from:
k8s:
default@podinfo/podinfo: true
egress:
from:
podinfo:
to:
cidr:
0.0.0.0/0:443: true
routes:
inbound:
podinfo:
enabled: true
gateways:
- istio-gateway/public-ingressgateway
hosts:
- podinfo.dev.bigbang.mil
service: podinfo
port: 9898
selector:
app.kubernetes.io/name: podinfo
project: default
syncPolicy:
syncOptions:
- CreateNamespace=true
managedNamespaceMetadata:
labels:
istio-injection: enabled # This should be 'istio.io/dataplane-mode: ambient' when running in Ambient mode
sync-registry-secret: "true"
automated:
prune: true
selfHeal: true
Kustomize¶
Similar to the ArgoCD scenario, this approach can be used when bb-common cannot be added directly to the application chart and Kustomize is used to deploy the application. This requires the standalone Kustomize CLI because the version included with kubectl does not support Helm chart rendering. The following file tree shows an example of what this may look like:
bb-kustomize/
├── base/
│ └── podinfo/
│ ├── deployment.yaml
│ ├── kustomization.yaml
│ ├── namespace.yaml
│ └── service.yaml
└── overlays/
└── dev/
├── bb-common-global-values.yaml
├── kustomization.yaml
[!NOTE] It is highly recommended to use standard Kubernetes labels, such as
app.kubernetes.io/name, for applications deployed with Kustomize. These labels are assumed by bb-common, and they make custom configuration much easier. While bb-common can be configured to work without them, that approach is discouraged.
In this scenario there are no changes to anything under the base folder, all of the integration takes place in the kustomization.yaml file under the dev overlay folder with an optional reference to a global file:
# bb-common-global-values.yaml
istio:
enabled: true
authorizationPolicies:
enabled: true
networkPolicies:
enabled: true
egress:
definitions:
# -- Egress definition for Storage subnets (i.e. S3, Azure blob storage, etc.)
storage-subnets:
to:
- ipBlock:
cidr: "10.100.10.0/24"
- ipBlock:
cidr: "10.100.20.0/24"
ports:
- port: 443
protocol: TCP
# -- Egress definition for database subnets
database-subnets:
to:
- ipBlock:
cidr: "192.168.32.0/24"
- ipBlock:
cidr: "192.168.64.0/24"
ports:
- port: 5432
protocol: TCP
While it isn’t required to use a global file as shown above, it is highly recommended as it allows for reuse without repeating settings that are shared amongst one or more applications. This file can then be included with any needed overrides specified in the kustomization.yaml file:
# kustomization.yaml
apiVersion: kustomize.config.k8s.io/v1beta1
kind: Kustomization
resources:
- ../../base/podinfo
helmCharts:
- name: bb-common
repo: oci://registry1.dso.mil/bigbang
version: 1.0.1 # Update with latest version
releaseName: podinfo
namespace: podinfo
apiVersions:
- networking.istio.io/v1 # This is required for virtual service creation when using bb-common
valuesFile: bb-common-global-values.yaml # Reference to optional global values for bb-common
valuesInline: # All inline additive/overriding values for bb-common that apply to this application
networkPolicies:
egress:
from:
podinfo:
to:
definition:
storage-subnets: true # Usage of definition from global values
routes:
inbound:
podinfo: # Inbound route used to create virtual service and related resources
enabled: true
gateways:
- istio-gateway/public-ingressgateway
hosts:
- podinfo.dev.bigbang.mil
service: podinfo.podinfo.svc.cluster.local
port: 9898
The only other tweak required to get this to work is the use of the --enable-helm flag for Kustomize which will look like this:
kustomize build --enable-helm bb-kustomize/overlays/dev | kubectl apply -f -