|
| 1 | +[](https://circleci.com/gh/giantswarm/security-bundle) |
| 2 | + |
| 3 | +# Giant Swarm Security Bundle |
| 4 | + |
| 5 | +Giant Swarm offers a [managed security bundle][security-bundle] which provides an unintrusive baseline for security observability and enforcement in Kubernetes clusters. This App is a convenient wrapper containing multiple other Apps which make up the security bundle. See our full [App Bundle reference][app-bundle] to learn more. |
| 6 | + |
| 7 | +By default, installing the security bundle in a cluster includes: |
| 8 | + |
| 9 | +- Kyverno, from our [`kyverno-app`][kyverno-app] |
| 10 | + - our [`kyverno-policies`][kyverno-policies] app for Kubernetes Pod Security Standards (PSS) |
| 11 | + |
| 12 | +- components supporting our Policy API features |
| 13 | + - our [`kyverno-policy-operator`][kyverno-policy-operator] app, which orchestrates our managed Kyverno policies. |
| 14 | + - our [`exception-recommender`][exception-recommender] app, which recommends possible Giant Swarm PolicyExceptions for non-compliant workloads. |
| 15 | + |
| 16 | +Some optional components are also installable from this bundle, including: |
| 17 | + |
| 18 | +- Falco, from our [`falco-app`][falco-app] |
| 19 | +- Trivy, from our [`trivy-app`][trivy-app] |
| 20 | +- Trivy Operator, from our [`trivy-operator`][trivy-operator-app] app |
| 21 | + - our [`starboard-exporter`][starboard-exporter] for exposing metrics |
| 22 | +- Jiralert, from our [`jiralert-app`][jiralert-app], for automatically creating Jira issues from security findings |
| 23 | + |
| 24 | +Several additional components deployable from the bundle are under development for future platform features. These are platform-internal and not intended for direct customer use, but can be optionally enabled to test upcoming improvements to report storage. |
| 25 | + |
| 26 | +- CloudNative PG, from our [`cloudnative-pg-app`][cnpg-app] |
| 27 | +- EdgeDB, from our [`edgedb-app`][edgedb-app] |
| 28 | +- Kyverno Reports Server, from our [`reports-server-app`][reports-server-app] |
| 29 | + |
| 30 | +Previous versions of the pack included Starboard, from our [`starboard-app`][starboard-app]. Starboard has been deprecated in favor of Trivy Operator, and we have removed the Starboard app from this app bundle as of v0.13.0. |
| 31 | + |
| 32 | +Apps can be selectively enabled or disabled using the `enabled` setting for that app in the `security-bundle` Helm values. |
| 33 | + |
| 34 | +More information and configuration options can be found in each app repository. |
| 35 | + |
| 36 | +## Installing |
| 37 | + |
| 38 | +:warning: **In version `v1.0.0` PSPs are disabled by default. Clusters running versions older than `1.25.0` must enable the PSPs in the userconfig of the `values.yaml` file before installing the Security Bundle or use older `v0.x.x` versions.** |
| 39 | + |
| 40 | +### Compatibility Matrix |
| 41 | + |
| 42 | +| Bundle Version | K8s Version | GS Release | Branch | PSS Policy State | PSPs installed | |
| 43 | +|:---:|:---:|:---:|:---:|:---:|:---:| |
| 44 | +| v1.x.x | >= v1.25.0 | >= v20.0.0 | `main` | enforce | no | |
| 45 | +| v1.x.x | v1.24.x | >= v19.3.0, < v20.0.0 | `main` | enforce | no | |
| 46 | +| v0.x.x | < v1.25.0 | >= v19.1.0, < v19.3.0 | `legacy` | audit | yes | |
| 47 | + |
| 48 | +### Upgrading from a self-managed to a preinstalled `security-bundle` |
| 49 | + |
| 50 | +The `security-bundle` is now being installed by default in new Giant Swarm cluster versions. |
| 51 | + |
| 52 | +When upgrading from a cluster where the bundle was not preinstalled, it is possible that the installation of the bundle will fail if the bundle itself, or one of its apps (like Kyverno) was installed as an optional app prior to the upgrade. |
| 53 | + |
| 54 | +We are working on an automated way to resolve this condition, but due to technical limitations and variation between how customers manage Apps (e.g. gitops) we currently recommend uninstalling any customer-installed `security-bundle`, `kyverno-app`, and `kyverno-policies` Apps installed in a cluster when upgrading to a version containing the bundle by default. |
| 55 | + |
| 56 | +### Updating from `security-pack` |
| 57 | + |
| 58 | +To change an existing `security-pack` install to a `security-bundle`, the following changes must be made: |
| 59 | +- any overrides to the Apps `configMap` or `secret` inside the `userConfig` key must be switched from string to object. |
| 60 | +- any overrides to the `kyverno-policies` App in the `security-bundle` App values configuration must be replaced with equivalent overrides under the `kyvernoPolicies` key. The key `kyverno-policies` has been renamed to `kyvernoPolicies` only to simplify its usage in Helm. The name of the `kyverno-policies` App itself is unchanged. |
| 61 | +- if using the default installation namespace (`security-pack`), any logic which depends on that namespace must be updated to reference the new default namespaces (`security-bundle`). If setting a custom installation namespace, no change is required. |
| 62 | +- if the existing `security-pack` App CR is installing from the `playground` catalog, the catalog must be changed to `giantswarm`. The `security-bundle` will not be pushed to the `playground` catalog. |
| 63 | +- after the above changes have been made, the old `security-pack` CR must be deleted before the new `security-bundle` CR can then be created. |
| 64 | + |
| 65 | + |
| 66 | +This "App of Apps" method is rather new and our UX tooling is still catching up, so our normal App installation methods may or may not work for you depending on your management cluster and component versions. |
| 67 | + |
| 68 | +The currently recommended way to install the security bundle is: |
| 69 | + |
| 70 | +1. Create `user-values.yaml` containing the name of the cluster where the Apps should be installed, and the organization where that cluster is running: |
| 71 | + |
| 72 | + ```yaml |
| 73 | + clusterID: demo1 |
| 74 | + organization: demo-team |
| 75 | + ``` |
| 76 | +
|
| 77 | +2. Use `kubectl gs` to template the "outer" App CR: |
| 78 | + |
| 79 | + ```shell |
| 80 | + $ kubectl gs template app \ |
| 81 | + --catalog giantswarm \ |
| 82 | + --name security-bundle \ |
| 83 | + --app-name demo01-security-bundle \ |
| 84 | + --in-cluster \ |
| 85 | + --cluster-name demo01 \ |
| 86 | + --target-namespace demo01 \ |
| 87 | + --version 0.0.1 \ |
| 88 | + --user-configmap user-values.yaml > outerApp.yaml |
| 89 | + ``` |
| 90 | + |
| 91 | +3. Apply the generated App CR and ConfigMap to the management cluster: |
| 92 | + |
| 93 | + ```shell |
| 94 | + $ kubectl --context=<your-mc> apply -f outerApp.yaml |
| 95 | + configmap/security-bundle-userconfig created |
| 96 | + app.application.giantswarm.io/security-bundle created |
| 97 | + ``` |
| 98 | + |
| 99 | +Support for these methods are not yet officially supported, but may still work: |
| 100 | + |
| 101 | +1. [Using our web interface](https://docs.giantswarm.io/ui-api/web/app-platform/#installing-an-app) |
| 102 | +2. [Using our API](https://docs.giantswarm.io/api/#operation/createClusterAppV5) |
| 103 | + |
| 104 | +### **Important** |
| 105 | + |
| 106 | +If you are not using `kubectl gs` plugin, plese remember to ensure the correct label: `app-operator.giantswarm.io/version: 0.0.0` is set on the App CR. Missing this configuration will result with stuck deployment of an app. |
| 107 | + |
| 108 | +When naming the App CR, please make sure the name is unique within the Management Cluster, using just `security-bundle` |
| 109 | +name for two or more App CRs may lead to unexpected behavior. It is recommended to use cluster name as a prefix or suffix, |
| 110 | +for example `demo01-security-bundle` or `security-bundle-demo1`. |
| 111 | + |
| 112 | +## Configuring |
| 113 | + |
| 114 | +### values.yaml |
| 115 | + |
| 116 | +**This is an example of a values file you could upload using our web interface.** |
| 117 | + |
| 118 | +```yaml |
| 119 | +# values.yaml |
| 120 | +clusterID: demo1 |
| 121 | +organization: demo-team |
| 122 | +``` |
| 123 | + |
| 124 | +### Sample App CR and ConfigMap for the management cluster |
| 125 | + |
| 126 | +If you have access to the Kubernetes API on the management cluster, you could create |
| 127 | +the App CR and ConfigMap directly. |
| 128 | + |
| 129 | +Here is an example that would install the app to |
| 130 | +workload cluster `abc12`: |
| 131 | + |
| 132 | +```yaml |
| 133 | +# appCR.yaml |
| 134 | +apiVersion: application.giantswarm.io/v1alpha1 |
| 135 | +kind: App |
| 136 | +metadata: |
| 137 | + labels: |
| 138 | + app-operator.giantswarm.io/version: 0.0.0 |
| 139 | + giantswarm.io/cluster: demo1 |
| 140 | + name: security-bundle |
| 141 | + namespace: demo1 |
| 142 | +spec: |
| 143 | + catalog: giantswarm |
| 144 | + kubeConfig: |
| 145 | + inCluster: true |
| 146 | + name: security-bundle |
| 147 | + namespace: demo1 |
| 148 | + userConfig: |
| 149 | + configMap: |
| 150 | + name: security-bundle-userconfig |
| 151 | + namespace: demo1 |
| 152 | + version: 0.0.1 |
| 153 | +``` |
| 154 | + |
| 155 | +```yaml |
| 156 | +# user-values-configmap.yaml |
| 157 | +apiVersion: v1 |
| 158 | +data: |
| 159 | + values: | |
| 160 | + clusterID: demo1 |
| 161 | + organization: giantswarm |
| 162 | +kind: ConfigMap |
| 163 | +metadata: |
| 164 | + creationTimestamp: null |
| 165 | + name: security-bundle-userconfig |
| 166 | + namespace: demo1 |
| 167 | +``` |
| 168 | + |
| 169 | +See our [full reference page on how to configure applications](https://docs.giantswarm.io/app-platform/app-configuration/) for more details. |
| 170 | + |
| 171 | +[app-bundle]: https://docs.giantswarm.io/getting-started/app-platform/app-bundle/ |
| 172 | +[cnpg-app]: https://github.com/giantswarm/cloudnative-pg-app |
| 173 | +[edgedb-app]: https://github.com/giantswarm/edgedb-app |
| 174 | +[exception-recommender]: https://github.com/giantswarm/exception-recommender |
| 175 | +[falco-app]: https://github.com/giantswarm/falco-app |
| 176 | +[jiralert-app]: https://github.com/giantswarm/jiralert-app |
| 177 | +[kyverno-app]: https://github.com/giantswarm/kyverno-app |
| 178 | +[kyverno-policies]: https://github.com/giantswarm/kyverno-policies/ |
| 179 | +[kyverno-policy-operator]: https://github.com/giantswarm/kyverno-policy-operator |
| 180 | +[reports-server-app]: https://github.com/giantswarm/reports-server-app |
| 181 | +[security-bundle]: https://docs.giantswarm.io/app-platform/apps/security/ |
| 182 | +[starboard-app]: https://github.com/giantswarm/starboard-app |
| 183 | +[starboard-exporter]: https://github.com/giantswarm/starboard-exporter/ |
| 184 | +[trivy-app]: https://github.com/giantswarm/trivy-app/ |
| 185 | +[trivy-operator-app]: https://github.com/giantswarm/trivy-operator-app |
0 commit comments