Skip to content

Metadata Store

One of the defining features of the ocibuilder is it's ability to automatically push build and image metadata to a Grafeas metadata store.

To get started using Grafeas there is a getting started guide available here which goes through the definition and creation of Notes and Occurrences.

The ocibuilder supports the storing of three difference types of metadata (or three different note types), and automatically generates occurrences for these types that you have available in your store.

Metadata Types

Attestation

Image attestation helps to enable the binary authorization of container images.

An attestation is a statement by an attestor that a required process in your pipeline has been completed and that a container image is authorized for deployment.

The ocibuilder automatically signs the image with a given (GPG) ASCII armored private key and pushes the image signature to Grafeas when enabled.

NOTE: In order to sign an image you MUST provide a private and public key or environment variables which refer to a public and private key.

NOTE: The ocibuilder produces a signature using GPG from a GPG private and public key which are passed in. Ensure that your keys have been ASCII armored.

This then gives you a fine grain control on what images can be pushed to production registries. For example by integrating a policy manager like OPA to ensure only images signed by a specific authority can be pushed to a production image registry.

Below is an example attestation occurrence generated by ocibuilder:

{
    "name": "projects/image-build/occurrences/<UUID>",
    "resource": {
        "name": "",
        "uri": "docker.io/ocibuildere2e/go-test-service@sha256:imageID",
        "contentHash": null
    },
    "noteName": "projects/image-build/notes/oci-attest",
    "kind": "NOTE_KIND_UNSPECIFIED",
    "remediation": "",
    "createTime": "2020-01-29T11:23:05.407978900Z",
    "updateTime": "2020-01-29T11:23:05.407978900Z",
    "attestation": {
        "attestation": {
            "pgpSignedAttestation": {
                "signature": "-----BEGIN PGP SIGNATURE-----\n<MY_PGP_SIGNATURE>\n-----END PGP SIGNATURE-----",
                "contentType": "CONTENT_TYPE_UNSPECIFIED",
                "pgpKeyId": "4RANDOMCHARACTERS"
            }
        }
    }
}

Derived Image

The derived image metadata stores image related metadata for the image that has just been built by the ocibuilder.

This includes a number of useful auditable fields and includes metadata such as the image fingerprint (for both V1 and V2 docker registries), a breakdown of layer information, commands and arguments and finally the resource URI in the form <IMAGE_NAME>@<IMAGE_ID>.

Below is an example of a derived image occurrence generated by ocibuilder:

{
    "name": "projects/image-build/occurrences/<UUID>",
    "resource": {
        "name": "",
        "uri": "docker.io/ocibuildere2e/go-test-service@sha256:<IMAGE_ID>",
        "contentHash": null
    },
    "noteName": "projects/image-build/notes/oci-image",
    "kind": "NOTE_KIND_UNSPECIFIED",
    "remediation": "",
    "createTime": "2020-01-29T11:23:05.407903200Z",
    "updateTime": "2020-01-29T11:23:05.407903200Z",
    "derivedImage": {
        "derivedImage": {
            "fingerprint": {
                "v1Name": "sha256:<IMAGE_ID>",
                "v2Blob": [
                    "sha256:<LAYER_ID_SHA>",
                    "sha256:<LAYER_ID_SHA>",
                    "sha256:<LAYER_ID_SHA>",
                    "sha256:<LAYER_ID_SHA>",
                    "sha256:<LAYER_ID_SHA>",
                    "sha256:<LAYER_ID_SHA>",
                ],
                "v2Name": ""
            },
            "distance": 0,
            "layerInfo": [
                {
                    "directive": "LABEL",
                    "arguments": "type=build-1"
                },
                {
                    "directive": "LABEL",
                    "arguments": "overlay=first-step"
                },
                {
                    "directive": "ENTRYPOINT",
                    "arguments": "[\"/bin/sh\" \"-c\" \"./goapp\"]"
                },
                {
                    "directive": "WORKDIR",
                    "arguments": "/app"
                },
                {
                    "directive": "CMD",
                    "arguments": "[\"/bin/sh\"]"
                },
            ],
            "baseResourceUrl": ""
        }
    }
}

Build

The build metadata type stores build time related image metadata such as the creator, source code URI, ImageID, name as well as provenance and build timings.

This allows you to easily compare build times, diagnose issues as well as have an accurate record of what image was built and when.

Below is an example of a build occurrence generated by ocibuilder:

{
    "name": "projects/image-build/occurrences/<UUID>",
    "resource": {
        "name": "",
        "uri": "docker.io/ocibuildere2e/go-test-service@sha256:<IMAGE_ID>",
        "contentHash": null
    },
    "noteName": "projects/image-build/notes/oci-build",
    "kind": "NOTE_KIND_UNSPECIFIED",
    "remediation": "",
    "createTime": "2020-01-29T11:23:05.407951300Z",
    "updateTime": "2020-01-29T11:23:05.407951300Z",
    "build": {
        "provenance": {
            "id": "<UUID>",
            "projectId": "image-build",
            "commands": [],
            "builtArtifacts": [
                {
                    "checksum": "sha256:<IMAGE_ID>",
                    "id": "docker.io/ocibuildere2e/go-test-service@sha256:<IMAGE_ID>",
                    "names": [
                        "docker.io/ocibuildere2e/go-test-service:v0.1.0"
                    ]
                }
            ],
            "createTime": "2020-01-29T11:23:05.353335Z",
            "startTime": "2020-01-29T11:23:05.190303Z",
            "endTime": "2020-01-29T11:23:05.353335Z",
            "creator": "",
            "logsUri": "",
            "sourceProvenance": {
                "artifactStorageSourceUri": "",
                "fileHashes": {},
                "context": null,
                "additionalContexts": []
            },
            "triggerId": "",
            "buildOptions": {},
            "builderVersion": ""
        },
        "provenanceBytes": ""
}

Getting Started

To get started pushing metadata to Grafeas, you need to ensure the follow: * You have an instance of Grafeas running that is accessible * You have created and pushed any relevant Notes to Grafeas that you want to generate your occurrences for.

You can then update your ocibuilder.yaml configuration file to include the metadata field. Here you can list the metadata types that you'd like to push under the data array and also specify the note names that you had previously generated.

Below is an example metadata specification. Please view the specification doc for more details.

e.g.

metadata:
  hostname: "http://localhost:8080"
  signKey: 
    envPublicKey: OCI_PUB_KEY
    envPrivateKey: OCI_PRI_KEY
  storeConfig:
    grafeas:
      project: "image-build"
      notes:
        build: "projects/image-build/notes/oci-build"
        attestation: "projects/image-build/notes/oci-attest"
        image: "projects/image-build/notes/oci-image"
  data:
    - image
    - build
    - attestation