diff --git a/docs/developer/package-integration/network-policies.md b/docs/developer/package-integration/network-policies.md index b3a081dc48b366b5f683906d84a384a9415efb49..2ea5f263f2e398f1abdedf96a8a12144598addde 100644 --- a/docs/developer/package-integration/network-policies.md +++ b/docs/developer/package-integration/network-policies.md @@ -206,6 +206,39 @@ spec: - The networkPolicy template for kube-api egress will look like the above, so that communication to the [AWS Instance Metadata](https://docs.aws.amazon.com/AWSEC2/latest/UserGuide/ec2-instance-metadata.html) and [Azure Instance Metadata](https://docs.microsoft.com/en-us/azure/virtual-machines/windows/instance-metadata-service) can be limited unless required by the package. +### Supporting additional network policies through values.yaml + +All bigbang core and supported addon packages are expected to provide support for the deployment of additional network policies through the values yaml [as per the user guide](../../guides/using-bigbang/network-policies.md). There is a standard mechanism for the implementation of this pattern, with two use cases: + +- where a package will only be deployed into its own namespace (the majority of bigbang packages) +- where a package may be used in inside another package's namespace or deployed into its own namespace (such as the gitlab-runner) + +#### Single namespace + +For this use case, a simple iteration over the values is sufficient to create the needed functionality. The standard pattern is to place this into `<package>/chart/templates/bigbang/networkpolicies/additional-networkpolicies.yaml`: + +``` +{{- if .Values.networkPolicies.enabled }} +{{- range $policy := .Values.networkPolicies.additionalPolicies -}} +apiVersion: networking.k8s.io/v1 +kind: NetworkPolicy +metadata: + name: {{ $policy.name }} +spec: + {{ tpl ($policy.spec | toYaml) $ | nindent 2 }} +--- +{{- end }} +{{- end }} +``` + +#### Multiple namespaces + +For this use case, refer to [the gitlab runner implementation](https://repo1.dso.mil/big-bang/product/packages/gitlab-runner/-/blob/main/chart/templates/bigbang/networkpolicies/egress-runner-jobs.yaml?ref_type=heads). In this pattern, a given chart may be deployed into one or more namespaces. However, you may only want to enable to control of additional network policies in a certain subset of those namespaces. In these cases, it is sufficient to extend the conditional at the top that checks for the flag in the values: + +``` +{{- if and .Values.networkPolicies.enabled (ne .Release.Namespace "NAMESPACE-YOU-DONT-WANT-TO-DO-THIS-IN") }} +``` + ## Validation - Package functions as expected and is able to communicate with all BigBang touchpoints. diff --git a/docs/guides/using-bigbang/network-policies.md b/docs/guides/using-bigbang/network-policies.md new file mode 100644 index 0000000000000000000000000000000000000000..134347a0cb60dd6ece0a57efc1a618ab9d24fa84 --- /dev/null +++ b/docs/guides/using-bigbang/network-policies.md @@ -0,0 +1,116 @@ +# Using Network Policies in Big Bang + +## What are Network Policies + +Kubernetes allows Big Bang operators to utilize [Network Policies](https://kubernetes.io/docs/concepts/services-networking/network-policies/) to control the network traffic into or out of the various pods of a Kubernetes cluster. These network policies allow you to restrict incoming and outgoing traffic to or from a given set of pods using selectors. [Selectors](https://kubernetes.io/docs/concepts/overview/working-with-objects/labels/) allow you to select which pods a given networkPolicy will apply to. + +Network Policies are added as needed to supplement other good security practices; such as proper usage of TLS, only exposing necessary ports, and using other standard controls. However, Network Policies allow you to express additional control over what can connect to the pods in your cluster from outside; which pods in your kubernetes cluster can speak to each other internally; and which things those pods can initiate connections to outside of the cluster. + +## Package Types and Support Levels + +The mechanisms described in this document are natively available for: + +- all bigbang core packages (such as eck-operator, monitoring, istio, etc) +- all bigbang supported addon packages (such as minio, etc) +- select community supported addons (jira, confluence) + +For the purposes of this document, "customer defined package" and "community supported package" may be used interchangably and the techniques for one will apply equally to the other. However, customer defined packages will need to implement support for the networkpolicy control mechanism themselves if they want to make use of this functionality. See the [developer guide](../../developer/package-integration/network-policies.md) for how to implement this functionality in a customer defined package. + +## Enabling or Disabling Network Policies + +BigBang core and addon packages ship with various network policies already configured. You can turn these networking policies on and off by setting a global flag and a per-component flag. Community supported packages may or may not provide the same mechanism for managing networking policies - check the documentation for the given community supported package for confirmation or additional instructions. + +``` +# This will turn support on or off for network policies writ-large across the bigbang suite +networkPolicies: + enabled: [true|false] + +# For bigbang core packages, this will turn on or off support for network policies in a core component +COMPONENT_NAME: + values: + networkPolicies: + enabled: [true|false] + +# For bigbang supported addon packages, this will turn on or off support for network policies in a specific addon +addons: + ADDON_NAME: + values: + networkPolicies: + enabled: [true|false] + +# For community supported packages, this will turn on or off support for network policies in a specific package +package: + PACKAGE_NAME: + values: + networkPolicies: + enabled: [true|false] +``` + +## Crafting and Delivering Additional Network Policies + +Sometimes you will want to apply additional [Network Policies](https://kubernetes.io/docs/concepts/services-networking/network-policies/) to further isolate certain pods in your deployment. BigBang has adopted standardized mechanisms for crafting and deploying these Network Policies through the values provided to your BigBang core, supported addon or community addon packages. + +For BigBang core packages, you place these rules inside of the values for the given component: + +``` +COMPONENT_NAME: + values: + networkPolicies: + enabled: true + additionalPolicies: [] +``` + +For BigBang supported addon packages, you place these rules inside of the values for the given package: + +``` +addons: + ADDON_NAME: + values: + networkPolicies: + enabled: true + additionalPolicies: [] +``` + +For community supported packages, you add these rules inside of the values for the package: + +``` +packages: + PACKAGE_NAME: + values: + networkPolicies: + enabled: true + additionalPolicies: [] +``` + +In all cases, the `additionalPolicies` entry should be a list of YAML objects, each describing a single [Network Policy](https://kubernetes.io/docs/concepts/services-networking/network-policies/). You can add as many of these as you like. Consult [the upstream Kubernetes documentation](https://kubernetes.io/docs/concepts/services-networking/network-policies/) for more information on Network Policies, and what you can do with them. + +``` +additionalPolicies: + - name: example-egress-policy-all-pods + spec: + podSelector: {} + policyTypes: + - Egress + egress: + - to: + - ipBlock: + cidr: 172.20.0.0/12 + - name: example-ingress-policy-all-pods + spec: + podSelector: {} + policyTypes: + - Ingress + ingress: + - from: + - ipBlock: + cidr: 172.20.0.0/12 +``` + +## References + +* [Kubernetes Network Policies Documentation](https://kubernetes.io/docs/concepts/services-networking/network-policies/) +* [Kubernetes Labels and Selectors Documentation](https://kubernetes.io/docs/concepts/overview/working-with-objects/labels/) +* [Big Bang Developer Guide for Package Implementation](../../developer/develop-package.md) +* [Big Bang Developer Guide for Package Integration regarding Network Policies](../../developer/package-integration/network-policies.md) + +For more information regarding the behavior of a specific core, supported addon or community supported package, you should always reference the documentation for the specific package in question. Information specific to any given package is outside the scope of this documentation. \ No newline at end of file