docs: Updating documentation structure and content in the tutorial section #2333

AnaisUrlichs · 2022-06-15T19:53:55Z

Description

Converting the Quick-start section into tutorials
Moving integrations into the tutorials section
adding three tutorials; Trivy Kubernetes, GitOps, and installing Trivy into ovh cloud
I made the installation section more visible by moving it to the main index.md

Checklist

I've read the guidelines for contributing to this repository.
I've followed the conventions in the PR title.
I've added tests that prove my fix is effective or that my feature works.
I've updated the documentation with the relevant information (if needed).
I've added usage information (if the PR introduces new options)
I've included a "before" and "after" example to the description (if the PR is a user interface change).

CLAassistant · 2022-06-15T19:55:01Z

Thank you for your submission! We really appreciate it. Like many open source projects, we ask that you all sign our Contributor License Agreement before we can accept your contribution.
2 out of 3 committers have signed the CLA.

✅ AnaisUrlichs
✅ knqyf263
❌ Anais Urlichs

Anais Urlichs seems not to be a GitHub user. You need a GitHub account to be able to sign the CLA. If you have already a GitHub account, please add the email address used for this commit to your account.
_{You have signed the CLA already but the status is still pending? Let us recheck it.}

AnaisUrlichs · 2022-07-04T09:41:02Z

@itaysk @knqyf263 could you please check the PR again?

docs/docs/index.md

docs/tutorials/other-resources/references.md

docs/tutorials/overview.md

AnaisUrlichs · 2022-07-26T14:47:00Z

@knqyf263 could you please review and merge the docs with the next release or similar?

knqyf263 · 2022-07-26T16:24:38Z

I don't have a strong opinion. I'm ok if Itay approves it. One thing to note is that we added some updates on our doc such as SBOM attestation. We need to make sure all the changes are reflected to this PR.

AnaisUrlichs · 2022-07-27T08:01:49Z

@knqyf263 I've merged the main branch into this one in one of my last commits

AnaisUrlichs · 2022-08-03T12:32:10Z

@knqyf263 just merged main into it

knqyf263 · 2022-08-03T13:39:36Z

@AnaisUrlichs Thanks.
@itaysk Would you review this PR?

mkdocs.yml

itaysk · 2022-08-14T05:52:14Z

docs/tutorials/kubernetes/ovhcloud.md

@@ -0,0 +1,452 @@
+# Scan for vulnerabilities and misconfigurations of your OVHcloud Managed Kubernetes with Trivy


Are we sure this is a "first party" tutorial and not "third party"? do we want to maintain it?

No, we can't. The first party tutorial should be

GitHub Actions

We have an official action

CircleCI

Travis CI

GitLab CI

GitLab folks maintain our tutorial

Bitbucket Pipelines

We have an official repo

(AWS CodePipeline)

It should be moved to third party as the blog is written by AWS, not us.

AWS Security Hub

as we maintain asff.tpl

Hmm in addition to those we need tutorials such as Deploy the Trivy Operator through GitOps Where do you see those?

itaysk · 2022-08-14T05:55:49Z

docs/tutorials/overview.md

+
+How to add a tutorial
+
+1. Simply create a new `.md` file in the tutorials folder of the docs


is there a specific place for "community tutorials" or just anywhere in tutorials? is this what the "tools" are for? if so, need to refine this instruction and also rename tools. otherwise lets clarify what tools are for

I would only accept tutorials here that we want to maintain e.g. installing Trivy Operator through Flux, Visualising Metrics in Grafana etc. or similar, re Trivy -- using Trivy in an air-gapped environment -- and similar -- otherwise, tutorials should be added in the additional resource section and just reference an external link. This is how I had it in mind

AnaisUrlichs · 2022-08-14T13:41:53Z

@itaysk @knqyf263 I made several changes based on your comments

removed the Kubernetes tutorial from the tutorials section and added it to the community tutorials
made it clearer what community tutorials are and where they go in the docs
clarified what CKS stands for with a link
merged in latest changes from main

knqyf263

I said I was ok, but after all I left some comments😄

mkdocs.yml

knqyf263 · 2022-08-15T08:16:27Z

docs/home/installation.md

@@ -248,6 +248,38 @@ podAnnotations: {}

 > **Tip**: List all releases using `helm list`.

+# Trivy Operator Installation


First of all, # is not shown in the navigator bar, so we should have a single # per a single page.

And do we want to put only Operator installation here though we have many related tools such as Docker Extension?

I would add the Docker Extension as a tutorial and then link here to it since it does not seem too straightforward and is more about the use rather than the installation. What do you think?

actually made the link to Trivy Operator part of the Helm installation. That makes more sense to me (didn't change much)

I would add the Docker Extension as a tutorial and then link here to it since it does not seem too straightforward and is more about the use rather than the installation. What do you think?

Hmm. I thought Trivy Operator, Docker Extensions, and other tools would move to Integrations or Tools. Do we have links in the Installation section to all the tools?

knqyf263 · 2022-08-15T09:00:11Z

docs/tutorials/integrations/gitops.md

@@ -0,0 +1,125 @@
+# Installing the Trivy-Operator through GitOps


"CI/CD" section details how to run Trivy in CI/CD, but this section is how to install Trivy Operator through GitOps. I feel like this section is different from others.
Also, do we want to Trivy Operator things in the Trivy doc?

This boils down to the question -- if Trivy is marketed as the all in one security scanner, do we want to send people do one docs where they can discover all features or to different docs -- or moreover, at what point do we send people to different docs?
When Itay and I spoke, we agreed to put the tutorials first into the trivy docs and then at some point move them over to the operator docs when there are too many -- but this might be counterintuitive since links might not work like expected.

Independently, I could add the GitOps tutorial to the Kubernetes tutorial section

When Itay and I spoke, we agreed to put the tutorials first into the trivy docs and then at some point move them over to the operator docs when there are too many -- but this might be counterintuitive since links might not work like expected.

Does it mean we will not have the same tutorial in the Trivy Operator doc? I just want to avoid duplication so that it could reduce the maintenance cost.

I think of this more as "installing Trivy in k8s through GitOps" rather than "installing Trivy Operator through GitOps". In my mind Trivy Operator is just another face of Trivy. Does that make sense?

I'm ok with "installing Trivy in k8s through GitOps". I just wondered if we want to include all Trivy-related tools in the tutorial. For example, Docker Extension is also another face of Trivy. In that case, don't we have the same tutorial in the Trivy Operator doc? Where is the single truth of source?

Last time we discussed documentation for integrations, we said that:

reference docs will live in the integration's own repo

we will link from the menu of trivy docs to the individual readmes/docs or other projects

tutorials will live in Trivy docs under dedicated tutorials sections covering different scenarios

Examples:

Trivy github actions document with all possible options is in the readme of the action's repo. It is linked to from the integrations section of trivy docs. the tutorial for using trivy in github actions is in trivy docs and linked in the triby tutorials section.

trivy semaphore document with all possible options is in the semaphore documentation. It is linked to from the integrations section of trivy docs. the tutorial for using trivy with semaphore is in the semaphore blog and linked in the trivy tutorials section.

does this still makes sense? @knqyf263 @AnaisUrlichs

We planned to put a link to Trivy Operator at the top header -- this turned now into Trivy Ecosystem linking to the external repos/docs -- so you are saying that you would like to keep it as Trivy Operator in the header and link to external tools in the integration section?
We could still have the Trivy Ecosystem overview somewhere -- maybe in an overview in integrations?

No I didn't mean to revert anything, just wanted to answer Teppei's comment. I think (?) this model I described still works with ecosystem page

OK, we can keep Operator tutorials then.

knqyf263 · 2022-08-15T09:06:11Z

mkdocs.yml

+  - Tutorials:
+      - Overview: tutorials/overview.md
+      - Trivy Kubernetes: 
+          - Trivy K8s: tutorials/kubernetes/trivy-kubernetes.md


Trivy K8s is not clear. I think we should mention what users can do with this tutorial, e.g. "Cluster scanning" or something like that.

maybe Kubernetes scanning

knqyf263 · 2022-08-15T09:11:50Z

docs/tutorials/other-resources/cks.md

+### Aqua Security Blog posts

 - Supply chain security best [practices][supply-chain-best-practices]
 - Supply chain [attacks][supply-chain-attacks]
- 
+


They are not CKS relevant, no?

yes but they are also not trivy-focused and teach people something

So, should we move these links to somewhere else? Otherwise, it looks like these links help users pass the CKS exam.

Well, it is study material, that's why I wanted to include it

mkdocs.yml

docs/tutorials/other-resources/references.md

knqyf263 · 2022-08-15T09:15:01Z

docs/tutorials/other-resources/references.md

@@ -0,0 +1,61 @@
+# Additional References
+Below is a list of additional resources from the community.


Most of them are our blogs, not from the community.

yes, will add more community ones -- you have a point tho hahah

We may want to have two sections:

Additional References

All of the contents are from Aqua (official)

Community Tutorials

All of the contents are from the community (unofficial)

I renamed it to additional resources -- the thing is that official vs unofficial is going to be a bit scarce, and people would have to look at multiple places that have the same goal

itaysk · 2022-08-15T11:22:21Z

consider adding tekton tutorial: https://www.redhat.com/architect/cicd-pipeline-openshift-tekton

knqyf263 · 2022-08-29T13:43:13Z

mkdocs.yml

+          - AWS CodePipeline: tutorials/integrations/aws-codepipeline.md
+          - AWS Security Hub: tutorials/integrations/aws-security-hub.md
+      - Additional Resources: 
+          - Tools: tutorials/other-resources/tools.md


We moved Tools to Ecosystem. We don't need it anymore, right?

knqyf263 · 2022-08-29T13:48:55Z

docs/getting-started/installation.md

+- Scan public and private images that are either locally or in the Docker Hub.
+- Generate an SBOM for your container images.
+
+Watch the [tutorial for further information.](https://youtu.be/99tiVZLMujs)


As for Trivy Operator Installation and Docker Desktop Extension, can we just put "Other tools" and say See the Ecosystem` tab?

knqyf263 · 2022-08-29T13:50:52Z

mkdocs.yml

+      - Installation: home/installation.md
+  - Tutorials:
+      - Overview: tutorials/overview.md
+      - Trivy Kubernetes: 


Not fixed yet?

knqyf263 · 2022-08-29T13:51:09Z

mkdocs.yml

+  - Tutorials:
+      - Overview: tutorials/overview.md
+      - Trivy Kubernetes: 
+          - Trivy K8s: tutorials/kubernetes/trivy-kubernetes.md


knqyf263 · 2022-08-29T13:52:36Z

mkdocs.yml

+      - Trivy Kubernetes: 
+          - Trivy K8s: tutorials/kubernetes/trivy-kubernetes.md
+          - GitOps: tutorials/kubernetes/gitops.md       
+      - CI/CD:


Can we put CI/CD on the Kubernetes section? CI/CD integration is the first citizen in Trivy.

What do you mean?

knqyf263 · 2022-08-29T13:53:39Z

mkdocs.yml

+  - Tutorials:
+      - Overview: tutorials/overview.md
+      - Trivy Kubernetes: 
+          - Trivy K8s: tutorials/kubernetes/trivy-kubernetes.md


knqyf263

I left some small comments. I believe this is the last review.

knqyf263 · 2022-08-29T13:56:50Z

docs/tutorials/other-resources/tools.md

+| [Trivy Vulnerability Explorer][explorer] | Explore trivy vulnerability reports in your browser and create .trivyignore files interactively. Can be integrated in your CI/CD tooling with deep links.   |
+
+
+## Official Trivy Tools


People might try unofficial tools first because community tools are listed first. Can we put official tools before community tools?

AnaisUrlichs · 2022-09-05T10:03:57Z

@knqyf263 could you please have another look 🙃

knqyf263 · 2022-09-13T11:44:15Z

@AnaisUrlichs Would you resolve conflicts and merge the main branch? Then I hope we can merge this PR🤞

AnaisUrlichs · 2022-09-14T10:19:35Z

@knqyf263 merged main and resolved conflicts

knqyf263 · 2022-09-15T06:24:58Z

I saw several rendering errors and fixed them. Also, I added some small changes.

knqyf263 · 2022-09-15T07:30:42Z

@AnaisUrlichs Do you have two accounts? Looks like one of them has not signed CLA yet.
#2333 (comment)

Anais Urlichs and others added 2 commits June 15, 2022 17:20

changing the tutorials section in the docs

5d6b80c

adding tutorials to the documentation

801c871

AnaisUrlichs requested a review from knqyf263 as a code owner June 15, 2022 19:53

AnaisUrlichs requested a review from itaysk June 15, 2022 19:54

knqyf263 marked this pull request as draft June 21, 2022 14:01

AnaisUrlichs added 4 commits June 22, 2022 10:04

changing the docs structure further

a8fb793

changing the docs structure further

a70c0ce

merging main

18b3f3d

documentation changes

5d1d53a

AnaisUrlichs changed the title ~~WIP: Docs tutorials~~ docs: Updating documentation structure and content in the tutorial section Jul 1, 2022

itaysk reviewed Jul 6, 2022

View reviewed changes

docs/docs/index.md Show resolved Hide resolved

docs/tutorials/other-resources/references.md Outdated Show resolved Hide resolved

docs/tutorials/overview.md Outdated Show resolved Hide resolved

AnaisUrlichs added 5 commits July 11, 2022 13:42

merging main branch

5316d46

changes to references and tutorials

1ae9cb4

merging incoming changes

589fe08

minor changes to docs

25504c2

minor changes to docs

c3604c4

merging main

79f33e2

AnaisUrlichs marked this pull request as ready for review August 3, 2022 12:31

AnaisUrlichs requested review from josedonizetti and chen-keinan as code owners August 3, 2022 12:31

itaysk reviewed Aug 14, 2022

View reviewed changes

AnaisUrlichs added 2 commits August 14, 2022 14:06

merging main

aee90d5

updates to docs based on comments in pr

825c036

itaysk approved these changes Aug 14, 2022

View reviewed changes

knqyf263 reviewed Aug 15, 2022

View reviewed changes

AnaisUrlichs added 5 commits August 15, 2022 13:11

responding to Teppei's comments in the PR

9460e20

adding tekton tutorial

23c71a0

adding tekton tutorial

fd0c0fd

adding tools to header

1538fa3

updating tool naming

9e0a57a

knqyf263 reviewed Aug 29, 2022

View reviewed changes

AnaisUrlichs added 2 commits September 1, 2022 14:01

-S

ae1000c

merging main & updating based on comments

90a7726

AnaisUrlichs requested a review from knqyf263 September 5, 2022 10:04

merging main & adding additional resources

561e793

knqyf263 added 3 commits September 15, 2022 08:45

Merge branch 'main' into docs-tutorials

06d3239

fix a render error

3642f05

some tweaks

0e49130

AnaisUrlichs added 3 commits September 15, 2022 11:33

attemtping to remove additional user

d570e55

merging main

51ab6e6

attemtping to remove additional user

fe5a3a5

knqyf263 approved these changes Sep 15, 2022

View reviewed changes

AnaisUrlichs closed this Sep 15, 2022

AnaisUrlichs mentioned this pull request Sep 15, 2022

docs: update documentation structure and content in the tutorial section #2883

Merged

		@@ -0,0 +1,452 @@
		# Scan for vulnerabilities and misconfigurations of your OVHcloud Managed Kubernetes with Trivy


		How to add a tutorial

		1. Simply create a new `.md` file in the tutorials folder of the docs

		@@ -248,6 +248,38 @@ podAnnotations: {}

		> Tip: List all releases using `helm list`.

		# Trivy Operator Installation

		@@ -0,0 +1,125 @@
		# Installing the Trivy-Operator through GitOps

		@@ -0,0 +1,61 @@
		# Additional References
		Below is a list of additional resources from the community.

		\| [Trivy Vulnerability Explorer][explorer] \| Explore trivy vulnerability reports in your browser and create .trivyignore files interactively. Can be integrated in your CI/CD tooling with deep links. \|


		## Official Trivy Tools

docs: Updating documentation structure and content in the tutorial section #2333

docs: Updating documentation structure and content in the tutorial section #2333

Conversation

AnaisUrlichs commented Jun 15, 2022

Description

Checklist

CLAassistant commented Jun 15, 2022 • edited

AnaisUrlichs commented Jul 4, 2022

AnaisUrlichs commented Jul 26, 2022

knqyf263 commented Jul 26, 2022

AnaisUrlichs commented Jul 27, 2022

AnaisUrlichs commented Aug 3, 2022

knqyf263 commented Aug 3, 2022

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

AnaisUrlichs commented Aug 14, 2022

knqyf263 left a comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

itaysk Aug 17, 2022 • edited

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

itaysk commented Aug 15, 2022

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

knqyf263 left a comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

AnaisUrlichs commented Sep 5, 2022

knqyf263 commented Sep 13, 2022

AnaisUrlichs commented Sep 14, 2022

knqyf263 commented Sep 15, 2022

knqyf263 commented Sep 15, 2022

CLAassistant commented Jun 15, 2022 •

edited

itaysk Aug 17, 2022 •

edited