Skip to content

Commit 6e5b679

Browse files
ivanstanevivanstanev
authored
Merge pull request #1190 from snyk/docs/readme
docs: consolidate READMEs and use Helm chart README for installation
2 parents a822c23 + 7f5619b commit 6e5b679

File tree

2 files changed

+54
-191
lines changed

2 files changed

+54
-191
lines changed

‎README.md‎

Lines changed: 9 additions & 169 deletions
Original file line numberDiff line numberDiff line change
@@ -5,186 +5,26 @@
55

66
## Summary ##
77

8-
Container to monitor Kubernetes clusters' security
8+
A containerized application that is deployed with Helm. Monitors the security of a Kubernetes cluster by analyzing container images.
99

1010
## Prerequisites ##
1111

12-
* 50 GiB of storage in the form of [emptyDir](https://kubernetes.io/docs/concepts/storage/volumes/#emptydir).
13-
* External internet access from the Kubernetes cluster, specifically to `kubernetes-upstream.snyk.io`.
12+
* 50 GiB of storage in the form of [emptyDir](https://kubernetes.io/docs/concepts/storage/volumes/#emptydir) or a [PersistentVolumeClaim](https://kubernetes.io/docs/concepts/storage/persistent-volumes/).
13+
* External internet access from the Kubernetes cluster to `kubernetes-upstream.snyk.io`.
1414
* 1 CPU, 2 GiB RAM
1515
* 1 Kubernetes worker node of type `linux/amd64` - supported and tested only on the AMD64 CPU architecture
1616

1717
Supported Kubernetes distributions:
1818

19-
* Any Kubernetes Certified distribution, for example: GKE, AKS, EKS, OCP.
20-
* OCP 4.1+ if running on OpenShift - supported and tested on Generally Available versions
19+
* Any *Generally Available* Kubernetes Certified distribution, for example: GKE, AKS, EKS, OCP.
20+
* OCP 4.1+ if running on OpenShift - supported and tested on *Generally Available* versions
2121

2222
Tested with the following [Security Context Constraint](scc.txt) on OCP.
2323

24-
## Installing ##
24+
## Installation with Helm ##
2525

26-
The Snyk monitor (`kubernetes-monitor`) requires some minimal configuration items in order to work correctly.
26+
Please refer to the [Helm chart installation instructions](./snyk-monitor/README.md).
2727

28-
As with any Kubernetes deployment, the `kubernetes-monitor` runs within a single namespace.
29-
If you do not already have access to a namespace where you want to deploy the monitor, you can run the following command to create one:
30-
```shell
31-
kubectl create namespace snyk-monitor
32-
```
33-
Notice our namespace is called _snyk-monitor_ and it is used for the following commands in scoping the resources.
28+
## Documentation ##
3429

35-
36-
The Snyk monitor relies on using your Snyk Integration ID, which must be provided from a Kubernetes secret. The secret must be called _snyk-monitor_. The steps to create the secret are as such:
37-
38-
1. Locate your Snyk Integration ID from the Snyk Integrations page (navigate to https://app.snyk.io/org/YOUR-ORGANIZATION-NAME/manage/integrations/kubernetes) and copy it.
39-
The Snyk Integration ID is a UUID and looks similar to the following:
40-
```
41-
abcd1234-abcd-1234-abcd-1234abcd1234
42-
```
43-
The Snyk Integration ID is used in the `--from-literal=integrationId=` parameter in the next step.
44-
45-
2. If you are not using any private registries, create a Kubernetes secret called `snyk-monitor` containing the Snyk Integration ID from the previous step running the following command:
46-
```shell
47-
kubectl create secret generic snyk-monitor -n snyk-monitor --from-literal=dockercfg.json={} --from-literal=integrationId=abcd1234-abcd-1234-abcd-1234abcd1234
48-
```
49-
Continue to YAML files installation instructions below.
50-
51-
3. If you're using a private registry, you should create a `dockercfg.json` file. The `dockercfg.json` file is necessary to allow the monitor to look up images in private registries. Usually your credentials can be found in `$HOME/.docker/config.json`. These must also be added to the `dockercfg.json` file.
52-
53-
Create a file named `dockercfg.json`. Store your credentials in there; it should look like this:
54-
55-
```hjson
56-
{
57-
// If your cluster does not run on GKE or it runs on GKE and pulls images from other private registries, add the following:
58-
"auths": {
59-
"gcr.io": {
60-
"auth": "BASE64-ENCODED-AUTH-DETAILS"
61-
}
62-
// Add other registries as necessary
63-
},
64-
65-
// If your cluster runs on GKE and you are using GCR, add the following:
66-
"credHelpers": {
67-
"us.gcr.io": "gcloud",
68-
"asia.gcr.io": "gcloud",
69-
"marketplace.gcr.io": "gcloud",
70-
"gcr.io": "gcloud",
71-
"eu.gcr.io": "gcloud",
72-
"staging-k8s.gcr.io": "gcloud"
73-
}
74-
}
75-
```
76-
Finally, create the secret in Kubernetes by running the following command:
77-
```shell
78-
kubectl create secret generic snyk-monitor -n snyk-monitor --from-file=./dockercfg.json --from-literal=integrationId=abcd1234-abcd-1234-abcd-1234abcd1234
79-
```
80-
81-
4. If your private registry requires installing certificates (*.crt, *.cert, *.key only) please put them in a folder and create the following ConfigMap:
82-
```shell
83-
kubectl create configmap snyk-monitor-certs -n snyk-monitor --from-file=<path_to_certs_folder>
84-
```
85-
86-
5. If you are using an insecure registry or your registry is using unqualified images, you can provide a `registries.conf` file. See [the documentation](https://github.com/containers/image/blob/master/docs/containers-registries.conf.5.md) for information on the format and examples.
87-
88-
Create a file named `registries.conf`, see example adding an insecure registry:
89-
90-
```
91-
[[registry]]
92-
location = "internal-registry-for-example.net/bar"
93-
insecure = true
94-
```
95-
96-
Once you've created the file, you can use it to create the following ConfigMap:
97-
```shell
98-
kubectl create configmap snyk-monitor-registries-conf -n snyk-monitor --from-file=<path_to_registries_conf_file>
99-
```
100-
101-
## Installation from YAML files ##
102-
103-
The `kubernetes-monitor` can run in one of two modes: constrained to a single namespace, or with access to the whole cluster.
104-
In other words, the monitor can scan containers in one particular namespace, or it can scan all containers in your cluster.
105-
The choice of which deployment to use depends on the permissions you have on your cluster.
106-
107-
For _cluster_-scoped deployment you can create the necessary `ServiceAccount`, `ClusterRole`, and `ClusterRoleBinding` required for the monitor's deployment.
108-
These objects ensure the monitor has the right (limited) level of access to resources in the cluster. The command is as follows:
109-
```shell
110-
kubectl apply -f snyk-monitor-cluster-permissions.yaml
111-
```
112-
Note that even though the monitor operates in the whole cluster, the `ClusterRole` ensures it can only _read_ or _watch_ resources; the monitor can never modify your objects!
113-
114-
For a _namespaced_ deployment you can create the necessary `ServiceAccount`, `Role`, and `RoleBinding` required for the monitor's deployment:
115-
```shell
116-
kubectl apply -f snyk-monitor-namespaced-permissions.yaml
117-
```
118-
Similarly to the cluster-scoped deployment, this `Role` ensures the monitor can only _read_ or _watch_ resources, never to modify them!
119-
120-
By default, the Snyk monitor sends workload information to Snyk using a default cluster name.
121-
To _change the cluster name_, you can modify `snyk-monitor-namespaced-permissions.yaml` (for the Namespaced deployment) or `snyk-monitor-cluster-permissions.yaml` (for the Cluster-scoped deployment) and set the string value of `clusterName` to the name of your cluster. You will now see your workloads appearing in Snyk under the new cluster name.
122-
123-
124-
Finally, to launch the Snyk monitor in your cluster, run the following:
125-
```shell
126-
kubectl apply -f snyk-monitor-deployment.yaml
127-
```
128-
129-
## Upgrades ##
130-
131-
You can apply the latest version of the YAML installation files to upgrade.
132-
133-
If running with Operator Lifecycle Manager (OLM) then OLM will handle upgrades for you when you request to install the latest version. This applies to OpenShift (OCP) and regular installations of OLM.
134-
135-
## Setting up proxying ##
136-
137-
Proxying traffic through a forwarding proxy can be achieved by modifying the `snyk-monitor-cluster-permissions.yaml` or `snyk-monitor-namespaced-permissions.yaml` (depending on which one was applied) and setting the following variables in the `ConfigMap`:
138-
139-
* http_proxy
140-
* https_proxy
141-
* no_proxy
142-
143-
For example:
144-
145-
```yaml
146-
apiVersion: v1
147-
kind: ConfigMap
148-
metadata:
149-
...
150-
data:
151-
...
152-
https_proxy: "http://192.168.99.100:8080"
153-
```
154-
155-
The `snyk-monitor` currently works with HTTP proxies only.
156-
157-
Note that `snyk-monitor` does not proxy requests to the Kubernetes API server.
158-
159-
Note that `snyk-monitor` does not support wildcards or CIDR addresses in `no_proxy` -- it will only look for exact matches. For example:
160-
161-
```yaml
162-
# not OK:
163-
no_proxy: *.example.local,*.other.global,192.168.0.0/16
164-
165-
# OK:
166-
no_proxy: long.domain.name.local,example.local
167-
```
168-
169-
## Changing log level ##
170-
171-
To lower `snyk-monitor`'s logging verbosity `log_level` value could be set to one of these options:
172-
* `'WARN'`
173-
* `'ERROR'`
174-
175-
By default, `log_level` is `'INFO'`.
176-
177-
## Using a PVC ##
178-
179-
By default, `snyk-monitor` uses an emptyDir for temporary storage. If you prefer to have a PVC that uses a statically or
180-
dynamically provisioned PV that you have created, then set the following value
181-
* `pvc.enabled` `true`
182-
183-
The PVC's name defaults to `snyk-monitor-pvc`. If you prefer to override this, then use the following value:
184-
* `pvc.name`
185-
186-
## Terms and conditions ##
187-
188-
*The Snyk Container Kubernetes integration uses Red Hat UBI (Universal Base Image).*
189-
190-
*Before downloading or using this application, you must agree to the Red Hat subscription agreement located at redhat.com/licenses. If you do not agree with these terms, do not download or use the application. If you have an existing Red Hat Enterprise Agreement (or other negotiated agreement with Red Hat) with terms that govern subscription services associated with Containers, then your existing agreement will control.*
30+
For detailed documentation and support, please refer to the [Snyk Kubernetes integration documentation](https://docs.snyk.io/products/snyk-container/kubernetes-workload-and-image-scanning).

‎snyk-monitor/README.md‎

Lines changed: 45 additions & 22 deletions
Original file line numberDiff line numberDiff line change
@@ -36,16 +36,19 @@ The Snyk Integration ID is used in the `--from-literal=integrationId=` parameter
3636
Create a file named `dockercfg.json`. Store your credentials in there; it should look like this:
3737

3838
```hjson
39+
// If your cluster does not run on GKE or it runs on GKE and pulls images from other private registries, add the following:
3940
{
40-
// If your cluster does not run on GKE or it runs on GKE and pulls images from other private registries, add the following:
4141
"auths": {
4242
"gcr.io": {
4343
"auth": "BASE64-ENCODED-AUTH-DETAILS"
4444
}
4545
// Add other registries as necessary
46-
},
47-
48-
// If your cluster runs on GKE and you are using GCR, add the following:
46+
}
47+
}
48+
```
49+
```hjson
50+
// If your cluster runs on GKE and you are using GCR, add the following:
51+
{
4952
"credHelpers": {
5053
"us.gcr.io": "gcloud",
5154
"asia.gcr.io": "gcloud",
@@ -54,22 +57,23 @@ Create a file named `dockercfg.json`. Store your credentials in there; it should
5457
"eu.gcr.io": "gcloud",
5558
"staging-k8s.gcr.io": "gcloud"
5659
}
57-
58-
// If your cluster runs on EKS and you are using ECR, add the following:
59-
{
60-
"credsStore": "ecr-login"
61-
}
62-
63-
With Docker 1.13.0 or greater, you can configure Docker to use different credential helpers for different registries.
64-
To use this credential helper for a specific ECR registry, create a credHelpers section with the URI of your ECR registry:
65-
66-
{
67-
"credHelpers": {
68-
"public.ecr.aws": "ecr-login",
69-
"<aws_account_id>.dkr.ecr.<region>.amazonaws.com": "ecr-login"
70-
}
71-
}
60+
}
61+
```
62+
```hjson
63+
// If your cluster runs on EKS and you are using ECR, add the following:
64+
{
65+
"credsStore": "ecr-login"
66+
}
67+
```
7268

69+
```hjson
70+
// You can configure different credential helpers for different registries.
71+
// To use this credential helper for a specific ECR registry, create a credHelpers section with the URI of your ECR registry:
72+
{
73+
"credHelpers": {
74+
"public.ecr.aws": "ecr-login",
75+
"<aws_account_id>.dkr.ecr.<region>.amazonaws.com": "ecr-login"
76+
}
7377
}
7478
```
7579
Finally, create the secret in Kubernetes by running the following command:
@@ -86,7 +90,7 @@ kubectl create configmap snyk-monitor-certs -n snyk-monitor --from-file=<path_to
8690

8791
Create a file named `registries.conf`, see example adding an insecure registry:
8892

89-
```
93+
```conf
9094
[[registry]]
9195
location = "internal-registry-for-example.net/bar"
9296
insecure = true
@@ -105,20 +109,37 @@ Add the latest version of Snyk's Helm repo:
105109
helm repo add snyk-charts https://snyk.github.io/kubernetes-monitor/ --force-update
106110
```
107111

112+
Note that the Snyk monitor has **read-only** access to workloads in the cluster and will never interfere with other applications. The exact permissions requested by the monitor can be seen in the [ClusterRole](./templates/clusterrole.yaml) or [Role](./templates/role.yaml).
113+
114+
### Installation and monitoring of the whole cluster
115+
108116
Run the following command to launch the Snyk monitor in your cluster:
109117

110118
```shell
111-
helm upgrade --install snyk-monitor snyk-charts/snyk-monitor --namespace snyk-monitor --set clusterName="Production cluster"
119+
helm upgrade --install snyk-monitor snyk-charts/snyk-monitor \
120+
--namespace snyk-monitor \
121+
--set clusterName="Production cluster"
112122
```
113123

114124
To better organise the data scanned inside your cluster, the monitor requires a cluster name to be set.
115125
Replace the value of `clusterName` with the name of your cluster.
116126

117127
**Please note that `/` in cluster name is disallowed. Any `/` in cluster names will be removed.**
118128

129+
### Installation and monitoring of a single namespace
130+
131+
The Snyk monitor can be configured to monitor only the namespace in which it is installed instead of the whole cluster:
132+
133+
```shell
134+
helm upgrade --install snyk-monitor snyk-charts/snyk-monitor \
135+
--namespace some-ns-to-be-monitored \ # Note: ensure your snyk-monitor secret exists here
136+
--set scope=Namespaced \ # Monitor only the current namespace
137+
--set clusterName="Production cluster"
138+
```
139+
119140
## Upgrades ##
120141

121-
You can apply the latest version of the YAML installation files to upgrade.
142+
You can apply the latest version of the Helm chart to upgrade.
122143

123144
If you would like to reuse the last release's values and merge in any overrides from the command line via --set and -f, you can use the option `--reuse-values`. For example:
124145
```bash
@@ -312,6 +333,8 @@ extraInitContainers:
312333

313334
## Terms and conditions ##
314335

336+
Note that these terms and conditions apply when installing the Snyk Certified Red Hat Marketplace Operator, which uses Red Hat UBI.
337+
315338
*The Snyk Container Kubernetes integration uses Red Hat UBI (Universal Base Image).*
316339

317340
*Before downloading or using this application, you must agree to the Red Hat subscription agreement located at redhat.com/licenses. If you do not agree with these terms, do not download or use the application. If you have an existing Red Hat Enterprise Agreement (or other negotiated agreement with Red Hat) with terms that govern subscription services associated with Containers, then your existing agreement will control.*

0 commit comments

Comments
 (0)