|
| 1 | +--- |
| 2 | +sidebar_position: 2 |
| 3 | +title: Content Addressable Storage (CAS) backend |
| 4 | +--- |
| 5 | + |
| 6 | +import Image from "@theme/IdealImage"; |
| 7 | +import Tabs from "@theme/Tabs"; |
| 8 | +import TabItem from "@theme/TabItem"; |
| 9 | +import CodeBlock from "@theme/CodeBlock"; |
| 10 | + |
| 11 | +As part of an attestation process, you might want to collect different pieces of evidence such as Software Bill Of Materials (SBOMs), test results, runner logs, etc and then attach them to the final in-toto attestation. |
| 12 | + |
| 13 | +Chainloop helps with this process by providing a Content Addressable Storage API proxy that: |
| 14 | + |
| 15 | +- **Abstracts away the underlying storage backend**. Currently, we support OCI registries as storage backends but you can expect blob storage, Artifactory and other storage backends to be supported in the future. |
| 16 | +- Makes sure that the pieces of evidence are stored **in a tamper-proof manner**. This is achieved by storing the evidences named after their SHA256 content digest, which is calculated by the client, verified by the CAS server. |
| 17 | +- **Enables support of large pieces of evidence** since the content digest reference is what will be stored in the attestation. |
| 18 | + |
| 19 | +<Image img={require("./cas-backend.png")} className="light-mode-only" /> |
| 20 | +<Image img={require("./cas-backend-dark.png")} className="dark-mode-only" /> |
| 21 | + |
| 22 | + |
| 23 | +## Manage backends |
| 24 | + |
| 25 | +You can setup as many CAS backends as you want, but you can only have **one enabled as default at the time**. This **default backend will be used** during the attestation process **to store the pieces of evidence**. |
| 26 | + |
| 27 | +In Chainloop, CAS backends can be managed with the `chainloop cas-backend` command. |
| 28 | + |
| 29 | + |
| 30 | +```bash |
| 31 | +$ chainloop cas-backend ls |
| 32 | +┌─────────────────────────────────┬──────────┬─────────────────────────────────────┬───────────────┬─────────┐ |
| 33 | +│ LOCATION │ PROVIDER │ DESCRIPTION │ LIMITS │ DEFAULT │ |
| 34 | +├─────────────────────────────────┼──────────┼─────────────────────────────────────┼───────────────┼─────────┤ |
| 35 | +│ │ INLINE │ Embed artifacts content in the atte │ MaxSize: 500K │ false │ |
| 36 | +│ │ │ station (fallback) │ │ │ |
| 37 | +├─────────────────────────────────┼──────────┼─────────────────────────────────────┼───────────────┼─────────┤ |
| 38 | +│ ghcr.io/cyberdyne/chainloop-lab │ OCI │ │ MaxSize: 100M │ true │ |
| 39 | +└─────────────────────────────────┴──────────┴─────────────────────────────────────┴───────────────┴─────────┘ |
| 40 | +``` |
| 41 | + |
| 42 | +## Backend providers |
| 43 | + |
| 44 | +:::info |
| 45 | +New CAS Backends will be added over time. If yours is not implemented yet, please [let us know](https://chainloop.dev/contact) |
| 46 | +::: |
| 47 | + |
| 48 | +### Inline (fallback) |
| 49 | + |
| 50 | +Chainloop comes pre-configured with what we call an `inline` backend. |
| 51 | + |
| 52 | +The inline backend **embeds** the pieces of evidence in the resulting attestations. This is useful to get started quickly but since the metadata is embedded in the attestation, its max size is limited. |
| 53 | + |
| 54 | +We recommend that once you get closer to a production-ready setup, you switch to a more robust backend such as an OCI registry. |
| 55 | + |
| 56 | + |
| 57 | +### OCI registry |
| 58 | + |
| 59 | +#### Add a new OCI registry backend |
| 60 | + |
| 61 | +<Tabs> |
| 62 | + <TabItem value="gar" label="Google Artifact Registry" default> |
| 63 | + |
| 64 | +```bash |
| 65 | + # Using json-based service account |
| 66 | + # https://console.cloud.google.com/iam-admin/serviceaccounts |
| 67 | + |
| 68 | + $ chainloop cas-backend add oci \ |
| 69 | + # i.e us-east1-docker.pkg.dev/my-project/chainloop-cas-devel |
| 70 | + --repo [region]-docker.pkg.dev/[my-project]/[my-repository] \ |
| 71 | + --username _json_key \ |
| 72 | + --password "$(cat service-account.json)" \ |
| 73 | + --default |
| 74 | +``` |
| 75 | + |
| 76 | + </TabItem> |
| 77 | + |
| 78 | + <TabItem value="github" label="GitHub packages" default> |
| 79 | + |
| 80 | +```bash |
| 81 | + # Using personal access token with write:packages permissions |
| 82 | + # https://github.com/settings/tokens |
| 83 | + |
| 84 | + $ chainloop cas-backend add oci \ |
| 85 | + # i.e ghcr.io/chainloop-dev/chainloop-cas |
| 86 | + --repo ghcr.io/[username or org]/[my-repository] \ |
| 87 | + --username [username] \ |
| 88 | + --password [personal access token] \ |
| 89 | + --default |
| 90 | +``` |
| 91 | + |
| 92 | + </TabItem> |
| 93 | + <TabItem value="dockerhub" label="DockerHub" default> |
| 94 | + |
| 95 | +```bash |
| 96 | +# Create a personal access token at |
| 97 | +# https://hub.docker.com/settings/security |
| 98 | + |
| 99 | +$ chainloop cas-backend add oci \ |
| 100 | + --repo index.docker.io/[username] \ |
| 101 | + --username [username] \ |
| 102 | + --password [personal access token] \ |
| 103 | + --default |
| 104 | +``` |
| 105 | + |
| 106 | + </TabItem> |
| 107 | + <TabItem value="ecr" label="AWS Container Registry" default> |
| 108 | + |
| 109 | +:::caution |
| 110 | +**AWS Container Registry is not supported yet**. |
| 111 | +::: |
| 112 | + |
| 113 | + </TabItem> |
| 114 | +</Tabs> |
| 115 | + |
| 116 | +#### Rotate credentials |
| 117 | + |
| 118 | +```bash |
| 119 | +chainloop cas-backend update oci --id [BACKEND_ID] --username [NEW_USERNAME] --password [NEW_PASSWORD] |
| 120 | +``` |
| 121 | + |
| 122 | +#### Set as default |
| 123 | + |
| 124 | +```bash |
| 125 | +chainloop cas-backend update oci --id [BACKEND_ID] --default=true |
| 126 | +``` |
| 127 | + |
| 128 | +## Give it a try |
| 129 | + |
| 130 | +If everything went well, you should be able to upload and download artifact materials, let's give it a try |
| 131 | + |
| 132 | +```bash title="Upload a file to your OCI repository" |
| 133 | +$ chainloop artifact upload -f myfile |
| 134 | +myfile@sha256:c5cc0a2c712497c29f29c3ba11e7fcc0c3cc725ab591720db595e5d6469f3f37 ... done! [1.03KB in 0s; 5.48KB/s] |
| 135 | +``` |
| 136 | + |
| 137 | +```bash title="Download by content digest (sha256)" |
| 138 | +$ chainloop artifact download -d sha256:c5cc0a2c712497c29f29c3ba11e7fcc0c3cc725ab591720db595e5d6469f3f37 |
| 139 | +INF downloading file name=myfile to=/tmp/myfile |
| 140 | +INF file downloaded! path=/tmp/myfile |
| 141 | +``` |
0 commit comments