From e5cb32b0f248014f5512879dd93851a101c72e61 Mon Sep 17 00:00:00 2001
From: Stefan Prodan <stefan.prodan@gmail.com>
Date: Wed, 24 Aug 2022 12:46:04 +0300
Subject: [PATCH] Add OCI layer selector to API docs

Signed-off-by: Stefan Prodan <stefan.prodan@gmail.com>
---
 api/v1beta2/ocirepository_types.go            |  3 ++-
 ...rce.toolkit.fluxcd.io_ocirepositories.yaml |  3 ++-
 docs/api/source.md                            |  3 ++-
 docs/spec/v1beta2/ocirepositories.md          | 24 +++++++++++++++++++
 4 files changed, 30 insertions(+), 3 deletions(-)

diff --git a/api/v1beta2/ocirepository_types.go b/api/v1beta2/ocirepository_types.go
index 24ea674c4..5c89a4ac0 100644
--- 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
index 39c7fbd2e..d5308a130 100644
--- 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
index b497c2688..ec0b1daf7 100644
--- 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
index d540d8131..6bb67650b 100644
--- 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`