From 761b50736baae41bb54ae0385cc342e4b0c6a407 Mon Sep 17 00:00:00 2001 From: Miguel Martinez Trivino Date: Thu, 9 Mar 2023 16:15:59 +0100 Subject: [PATCH 1/2] docs: add references from devel Signed-off-by: Miguel Martinez Trivino --- app/artifact-cas/README.md | 12 ++++++------ app/cli/README.md | 10 ++++++---- app/controlplane/README.md | 4 ++-- devel/README.md | 6 +++--- 4 files changed, 17 insertions(+), 15 deletions(-) diff --git a/app/artifact-cas/README.md b/app/artifact-cas/README.md index b18ae5801..c6e595913 100644 --- a/app/artifact-cas/README.md +++ b/app/artifact-cas/README.md @@ -1,8 +1,8 @@ # Artifact Content Addressable Storage (CAS) Proxy -The artifact proxy is a **Content Addressable Storage (CAS) Proxy** that sits in front of different storage backends. +The artifact proxy is a **Content-Addressable Storage (CAS) Proxy** that sits in front of different storage backends. -Clients such as the Chainloop Control Plane or the CLI can use this proxy to make sure that **immutable uploads are performed**. Files that later, on **can only be referenced by their content digest (sha256)**. +Clients such as the Chainloop Control Plane or the CLI will use this proxy to make sure that **uploaded artifacts are immutable and uniquely identifiable by their content digest (sha256sum)**. NOTE: At the moment of this writing, only an [OCI](https://opencontainers.org/) storage backend is supported. In the future you should potentially expect Object Storage Support (i.e AWS s3) as well. @@ -10,7 +10,7 @@ NOTE: At the moment of this writing, only an [OCI](https://opencontainers.org/) The project is a [Go](https://go.dev/) service that leverages [protocol buffers](https://github.com/protocolbuffers/protobuf) and [gRPC](https://grpc.io/) for its streaming API, [wire](https://github.com/google/wire/) for dependency injection and the [Kratos framework](https://github.com/go-kratos/kratos) for additional utilities such middlewares, configuration management or error handling. -The proxy API implements [a bytestream](https://pkg.go.dev/google.golang.org/api/transport/bytestream) gRPC service. This enables an efficient, and modern, streaming API for chunk based operations on top of HTTP/2. +The proxy API implements a [bytestream gRPC service](https://pkg.go.dev/google.golang.org/api/transport/bytestream). This enables an efficient, and modern, streaming API on top of HTTP/2. Its structure contains the following top to down layers. @@ -26,7 +26,7 @@ This secret backend is used to download OCI repository credentials (repository p ## AuthN/AuthZ -The Artifact CAS API expects each request to contain a [JSON Web Token](https://auth0.com/docs/secure/tokens/json-web-tokens) with references to a) what operation is this token allowed to do (Download, Upload) and b) a reference to where the CAS can find the OCI credentials. +The Artifact CAS API expects each request to contain a [JSON Web Token](https://auth0.com/docs/secure/tokens/json-web-tokens) with references to a) what operation is this token allowed to do (download or upload) and b) a reference to where the CAS can find the target OCI credentials. Currently, this token is generated by the Control Plane and used on demand. You can find the generator we use to craft those tokens [here](../../internal/robotaccount/cas/robotaccount.go). @@ -36,7 +36,7 @@ Note: there are plans to support [JWKS endpoints](https://auth0.com/docs/secure/ ## Runbook -We leverage `make` for most development tasks. Run `make -C app/artifact-cas` to see a list of the available tasks. +We use `make` for most development tasks. Run `make -C app/artifact-cas` to see a list of the available tasks. ### Run the project in development @@ -77,7 +77,7 @@ make build ### Generate API code from protocol buffer defintions (\*.proto) -We leverage buf.io to lint and generate proto files. Make sure you [install buf](https://docs.buf.build/installation) first. Once done, generating the API code is as easy as executing +We use buf.io to lint and generate proto files. Make sure you [install buf](https://docs.buf.build/installation) first. Once done, generating the API code is as easy as executing ``` make api diff --git a/app/cli/README.md b/app/cli/README.md index 550751ec9..10aa56c59 100644 --- a/app/cli/README.md +++ b/app/cli/README.md @@ -1,6 +1,6 @@ # Command Line Interface (CLI) -This Command Line Interface (CLI) is a local client that's used for two purposes +This Command Line Interface (CLI) is a local client that's used for two purposes: a) Operator [Management Tasks](https://docs.chainloop.dev/getting-started/workflow-definition) @@ -9,15 +9,15 @@ a) Operator [Management Tasks](https://docs.chainloop.dev/getting-started/workfl b) [Attestation Crafting Process](https://docs.chainloop.dev/getting-started/attestation-crafting) -- This CLI will be used in different CI/CD systems to perform the [attestation process](https://docs.chainloop.dev/getting-started/attestation-crafting) +- Perform the [attestation process](https://docs.chainloop.dev/getting-started/attestation-crafting) inside a CI/CD system. ![cas](../../docs/img/cli-overview.png) -The project is a [Go](https://go.dev/) CLI that leverages [Cobra](https://github.com/spf13/cobra) for CLI scaffolding, [Viper](https://github.com/spf13/viper) for configuration handling, [gRPC](https://grpc.io/) to communicate with both the control plane and the Artifact CAS APIs, and the [cosign](https://github.com/sigstore/cosign), [in-toto](https://github.com/in-toto/in-toto), [DSEE](https://github.com/secure-systems-lab/dsse/) and [SLSA](https://github.com/slsa-framework/slsa) projects to implement the attestation process. +The project is a [Go](https://go.dev/) CLI that leverages [Cobra](https://github.com/spf13/cobra) for CLI scaffolding, [Viper](https://github.com/spf13/viper) for configuration handling, [gRPC](https://grpc.io/) to communicate with both the control plane and the Artifact CAS APIs, and the [cosign](https://github.com/sigstore/cosign), [in-toto](https://github.com/in-toto/in-toto), [DSEE](https://github.com/secure-systems-lab/dsse/) and [SLSA](https://github.com/slsa-framework/slsa) projects for the attestation process. ## Runbook -We leverage `make` for most development tasks. Run `make -C app/cli` to see a list of the available tasks. +We use `make` for most development tasks. Run `make -C app/cli` to see a list of the available tasks. ### Run the project in development @@ -27,6 +27,8 @@ Refer to [development guide](../../devel/README.md) for more information but in go run app/cli/main.go --insecure ``` +> NOTE: In development a --insecure flag must be provided to talk to the local APIs + ### Configure the CLI to point to the local control plane and CAS services. If you want to use this CLI pointing to a local or custom instance of Chainloop, you need to perform a config override this way. diff --git a/app/controlplane/README.md b/app/controlplane/README.md index 368986a61..06a417f22 100644 --- a/app/controlplane/README.md +++ b/app/controlplane/README.md @@ -27,7 +27,7 @@ The control plane has 4 main dependencies ## Runbook -We leverage `make` for most development tasks. Run `make -C app/controlplane` to see a list of the available tasks. +We use `make` for most development tasks. Run `make -C app/controlplane` to see a list of the available tasks. ### Run the project in development @@ -58,7 +58,7 @@ make build ### Generate API code from protocol buffer defintions (\*.proto) -We leverage buf.io to lint and generate proto files. Make sure you [install buf](https://docs.buf.build/installation) first. +We use buf.io to lint and generate proto files. Make sure you [install buf](https://docs.buf.build/installation) first. Once done, generating the API code is as easy as executing diff --git a/devel/README.md b/devel/README.md index a1c3a612e..572b4fa00 100644 --- a/devel/README.md +++ b/devel/README.md @@ -33,8 +33,8 @@ docker compose up Once you have the pre-required services up and running, you should be able to run the different Chainloop server-side components, in our case we have: -- The Control Plane (`app/controlplane`) -- The Artifact Content Addressable Storage (CAS) Proxy (`app/artifact-cas`) +- The Control Plane [`app/controlplane`](../app/controlplane/) +- The Artifact Content Addressable Storage (CAS) Proxy [`app/artifact-cas`](../app/artifact-cas/) These components are built using [Go](https://go.dev/), have a `Makefile` and a `make run` target for convenience. @@ -43,7 +43,7 @@ These components are built using [Go](https://go.dev/), have a `Makefile` and a ### 4 - Using the CLI pointing to the local environment -The Command line interface (CLI) is used for both a) operate on the control plane and b) run the attestation process on your CI/CD. +The [Command line interface (CLI)](../app/cli/) is used for both a) operate on the control plane and b) run the attestation process on your CI/CD. You can run it by executing `go run app/cli/main.go` From bf65ca462e43f56612d0ef1debec7744e4afb64a Mon Sep 17 00:00:00 2001 From: Miguel Martinez Trivino Date: Thu, 9 Mar 2023 16:17:26 +0100 Subject: [PATCH 2/2] docs: add references from devel Signed-off-by: Miguel Martinez Trivino --- app/artifact-cas/README.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/app/artifact-cas/README.md b/app/artifact-cas/README.md index c6e595913..6c783d7cc 100644 --- a/app/artifact-cas/README.md +++ b/app/artifact-cas/README.md @@ -2,7 +2,7 @@ The artifact proxy is a **Content-Addressable Storage (CAS) Proxy** that sits in front of different storage backends. -Clients such as the Chainloop Control Plane or the CLI will use this proxy to make sure that **uploaded artifacts are immutable and uniquely identifiable by their content digest (sha256sum)**. +Clients such as the Chainloop Control Plane or the CLI use this proxy to make sure that **uploaded artifacts are immutable and uniquely identifiable by their content digest (sha256sum)**. NOTE: At the moment of this writing, only an [OCI](https://opencontainers.org/) storage backend is supported. In the future you should potentially expect Object Storage Support (i.e AWS s3) as well.