Add OCI layer selector to API docs

Signed-off-by: Stefan Prodan <stefan.prodan@gmail.com>
fluxcd · Aug 24, 2022 · e5cb32b · e5cb32b
1 parent 49dc309
commit e5cb32b
Show file tree

Hide file tree

Showing 4 changed files with 30 additions and 3 deletions.
diff --git a/api/v1beta2/ocirepository_types.go b/api/v1beta2/ocirepository_types.go
@@ -138,7 +138,8 @@ type OCIRepositoryRef struct {
 // OCILayerSelector specifies which layer should be extracted from an OCI Artifact
 type OCILayerSelector struct {
 	// MediaType specifies the OCI media type of the layer
-	// which should be extracted from the OCI Artifact.
+	// which should be extracted from the OCI Artifact. The
+	// first layer matching this type is selected.
 	// +optional
 	MediaType string `json:"mediaType,omitempty"`
 }

diff --git a/config/crd/bases/source.toolkit.fluxcd.io_ocirepositories.yaml b/config/crd/bases/source.toolkit.fluxcd.io_ocirepositories.yaml
@@ -82,7 +82,8 @@ spec:
                 properties:
                   mediaType:
                     description: MediaType specifies the OCI media type of the layer
-                      which should be extracted from the OCI Artifact.
+                      which should be extracted from the OCI Artifact. The first layer
+                      matching this type is selected.
                     type: string
                 type: object
               provider:

diff --git a/docs/api/source.md b/docs/api/source.md
@@ -2571,7 +2571,8 @@ string
 <td>
 <em>(Optional)</em>
 <p>MediaType specifies the OCI media type of the layer
-which should be extracted from the OCI Artifact.</p>
+which should be extracted from the OCI Artifact. The
+first layer matching this type is selected.</p>
 </td>
 </tr>
 </tbody>

diff --git a/docs/spec/v1beta2/ocirepositories.md b/docs/spec/v1beta2/ocirepositories.md
@@ -368,6 +368,30 @@ spec:
 
 This field takes precedence over all other fields.
 
+### Layer selector
+
+`spec.layerSelector` is an optional field to specify which layer should be extracted from the OCI Artifact.
+If not specified, the controller will extract the first layer found in the artifact.
+
+To extract a layer matching a specific
+[OCI media type](https://github.com/opencontainers/image-spec/blob/v1.0.2/media-types.md):
+
+```yaml
+---
+apiVersion: source.toolkit.fluxcd.io/v1beta2
+kind: OCIRepository
+metadata:
+  name: <repository-name>
+spec:
+  layerSelector:
+    mediaType: "application/deployment.content.v1.tar+gzip"
+```
+
+If the layer selector matches more than one layer, the first layer matching the specified media type will be used.
+Note that the selected OCI layer must be
+[compressed](https://github.com/opencontainers/image-spec/blob/v1.0.2/layer.md#gzip-media-types)
+in the `tar+gzip` format.
+
 ### Ignore
 
 `.spec.ignore` is an optional field to specify rules in [the `.gitignore`