From 804823453f154b6fb3afa602320443df4621779f Mon Sep 17 00:00:00 2001 From: gabriel-farache Date: Wed, 2 Aug 2023 14:50:49 +0200 Subject: [PATCH] Documentation: add more information on how to test and get started In `testing.md`, it was not explicitly stated that the protocol is needed when specifying the `src` and there was only a podman example shown for how to copy. In `getting_started.md` it was not mentioned that the config file has to be provided when running `clairctl report` and there was no advice on how to run directly on local image without having to start Quay. Signed-off-by: gabriel-farache Signed-off-by: Hank Donnay --- Documentation/howto/getting_started.md | 11 +++++++++-- Documentation/howto/testing.md | 25 ++++++++++++++++--------- 2 files changed, 25 insertions(+), 11 deletions(-) diff --git a/Documentation/howto/getting_started.md b/Documentation/howto/getting_started.md index 28354acd90..134761dee3 100644 --- a/Documentation/howto/getting_started.md +++ b/Documentation/howto/getting_started.md @@ -74,8 +74,11 @@ You can submit a manifest to ClairV4 via the following command. ```shell $ clairctl report --host ${net_address_of_clair} ${image_tag} ``` - -By default, `clairctl` will look for Clair at `localhost:6060`. +You will need to add the `config` flag if you are using a PSK authentication (as in the [local dev environment](./testing.md) setup, for example). +```shell +$ clairctl report --config local-dev/clair/config.yaml --host ${net_address_of_clair} ${image_tag} +``` +By default, `clairctl` will look for Clair at `localhost:6060` or the environment variable `CLAIR_API`, and for a configuration at `config.yaml` or the environment variable `CLAIR_CONF`. If everything is configured correctly, you should see some output like the following informing you of vulnerabilities affecting the supplied image. @@ -108,6 +111,10 @@ ubuntu:focal found libc6 2.31-0ubuntu9 CVE-2020-6096 ubuntu:focal found libgcrypt20 1.8.5-5ubuntu1 CVE-2019-12904 ``` +To test locally-built images, you'll need to push them to a registry that is accessible by the Clair service and the `clairctl` command. +A local registry can be used for this, but the specifics of configuration vary by registry and container runtime. +Consult the relevant documentation for more information. + ## What's Next Now that you see the basic usage of Clair, you can checkout our [deployment models](./deployment.md) to learn different ways of deploying. diff --git a/Documentation/howto/testing.md b/Documentation/howto/testing.md index 0c5b2a9762..81ec3a796e 100644 --- a/Documentation/howto/testing.md +++ b/Documentation/howto/testing.md @@ -11,7 +11,7 @@ Make is used to stand up the the local dev environment. Make is readily available in just about every package manager you can think of. It's very likely your workstation already has make on it. -### Docker and Docker Compose +### Podman/Docker and Docker Compose Currently our local dev tooling is supported by docker and docker-compose. Podman should work fine since v3.0. @@ -19,13 +19,13 @@ Podman should work fine since v3.0. Docker version 19.03.11 and docker-compose version 1.28.6 are confirmed working. Our assumption is most recent versions will not have an issue running the local dev tooling. -See [Install Docker](https://docs.docker.com/get-docker/) +See [Get Started with Podman](https://podman.io/get-started). ### Go Toolchain -Go v1.16 or higher is required. +Go 1.20 or higher is required. -See [Install Golang](https://golang.org/doc/install) +See [Install Golang](https://golang.org/doc/install). ## Starting a cluster @@ -41,16 +41,20 @@ docker-compose up -d After the local development environment successfully starts, the following infrastructure is available to you: - `localhost:8080` + Dashboards and debugging services -- See the traefik configs in `local-dev/traefik` for where the various services are served. - `localhost:6060` - Clair services + + Clair services. - Quay (if started) + Quay will be started in a single node, local storage configuration. A random port will be forwarded from localhost, see `podman port` for the mapping. - PostgreSQL + PostgreSQL will have a random port forwarded from localhost to the database server. See `local-dev/clair/init.sql` for credentials and permissions and `podman port` for the mapping. @@ -76,9 +80,12 @@ You'll also need to create a namespace. To push to Quay, you'll need to exec into the skopeo container: -```sh -podman exec -it quay-skopeo /usr/bin/skopeo copy --dst-creds ':' --dst-tls-verify=false clair-quay:8080//: +```shell +docker-compose exec -it skopeo /usr/bin/skopeo copy --dest-creds ':' --dest-tls-verify=false docker://clair-quay:8080//: ``` +Note that skopeo expects its image arguments in [`containers-transports(5)`] format. + +[`containers-transports(5)`]: https://github.com/containers/image/blob/main/docs/containers-transports.5.md ## Viewing Results @@ -105,11 +112,11 @@ will rip the entire environment down. The most common issue encountered when standing up the dev environment is port conflicts. Make sure that you do not have any other processes listening on any of the ports outlined above. -The second issue you may face is your Docker resource settings maybe too constrained to support the local dev stack. +The second issue you may face is your Docker resource settings being too constrained to support the local dev stack. This is typically seen on Docker4Mac since a VM is used with a specific set of resources configured. See [Docker For Mac Manual](https://docs.docker.com/docker-for-mac/) for instructions on how to change these resources. If `docker-compose` reports errors like `Unsupported config option for services.activemq: 'profiles'`, the `docker-compose` version is too old and you'll need to upgrade. Consult the relevant documentation for your environment for instructions. -Lastly, you can view traefik's ui at `localhost:8080/dashboard/`. +Lastly, you can view traefik's ui at [`localhost:8080/dashboard/`](http://localhost:8080/dashboard/).