Adds mirror API proc (#1195)

Co-authored-by: Steven Smith <stevsmit@stevsmit-thinkpadt14gen4.remote.csb>
quay · Jan 15, 2025 · 9be264b · 9be264b
1 parent 67244f2
commit 9be264b
Show file tree

Hide file tree

Showing 7 changed files with 166 additions and 0 deletions.
diff --git a/api/master.adoc b/api/master.adoc
@@ -66,6 +66,8 @@ include::modules/viewing-usage-logs-api.adoc[leveloffset=+2]
 include::modules/use-quay-export-logs-api.adoc[leveloffset=+2]
 //manifest label
 include::modules/adding-managing-labels-api.adoc[leveloffset=+2]
+//mirror 
+include::modules/mirror-quay-api.adoc[leveloffset=+2]
 
 //include::modules/proc_use-api.adoc[leveloffset=+1]
 
@@ -126,6 +128,7 @@ include::modules/api-manifest-addManifestLabel.adoc[leveloffset=+3]
 include::modules/api-manifest-listManifestLabels.adoc[leveloffset=+3]
 include::modules/api-manifest-getRepoManifest.adoc[leveloffset=+3]
 
+//example procedures provided
 include::modules/api-mirror.adoc[leveloffset=+2]
 include::modules/api-mirror-syncCancel.adoc[leveloffset=+3]
 include::modules/api-mirror-syncNow.adoc[leveloffset=+3]

diff --git a/modules/api-mirror-changeRepoMirrorConfig.adoc b/modules/api-mirror-changeRepoMirrorConfig.adoc
@@ -62,3 +62,27 @@ _optional_||object
 |403|Unauthorized access|&lt;&lt;_apierror,ApiError&gt;&gt;
 |404|Not found|&lt;&lt;_apierror,ApiError&gt;&gt;
 |===
+
+[discrete]
+== Example command
+
+[source,terminal]
+----
+$ curl -X PUT "https://<quay-server.example.com>/api/v1/repository/<namespace>/<repo>/mirror" \
+    -H "Authorization: Bearer <access_token>" \
+    -H "Content-Type: application/json" \
+    -d '{
+        "is_enabled": <false>, <1>
+        "external_reference": "<external_reference>",
+        "external_registry_username": "<external_registry_username>",
+        "external_registry_password": "<external_registry_password>",
+        "sync_start_date": "<sync_start_date>",
+        "sync_interval": <sync_interval>,
+        "robot_username": "<robot_username>",
+        "root_rule": {
+            "rule": "<rule>",
+            "rule_type": "<rule_type>"
+        }
+    }'
+----
+<1> Disables automatic synchronization.
diff --git a/modules/api-mirror-createRepoMirrorConfig.adoc b/modules/api-mirror-createRepoMirrorConfig.adoc
@@ -62,3 +62,26 @@ _optional_||object
 |403|Unauthorized access|&lt;&lt;_apierror,ApiError&gt;&gt;
 |404|Not found|&lt;&lt;_apierror,ApiError&gt;&gt;
 |===
+
+[discrete]
+== Example command
+
+[source,terminal]
+----
+$ curl -X POST "https://<quay-server.example.com>/api/v1/repository/<namespace>/<repo>/mirror" \
+    -H "Authorization: Bearer <access_token>" \
+    -H "Content-Type: application/json" \
+    -d '{
+        "is_enabled": <is_enabled>,
+        "external_reference": "<external_reference>",
+        "external_registry_username": "<external_registry_username>",
+        "external_registry_password": "<external_registry_password>",
+        "sync_start_date": "<sync_start_date>",
+        "sync_interval": <sync_interval>,
+        "robot_username": "<robot_username>",
+        "root_rule": {
+            "rule": "<rule>",
+            "rule_type": "<rule_type>"
+        }
+    }'
+----
diff --git a/modules/api-mirror-getRepoMirrorConfig.adoc b/modules/api-mirror-getRepoMirrorConfig.adoc
@@ -33,3 +33,12 @@ _required_|The full path of the repository. e.g. namespace/name|string
 |403|Unauthorized access|&lt;&lt;_apierror,ApiError&gt;&gt;
 |404|Not found|&lt;&lt;_apierror,ApiError&gt;&gt;
 |===
+
+[discrete]
+== Example command
+
+[source,terminal]
+----
+$ curl -X GET "https://<quay-server.example.com>/api/v1/repository/<namespace>/<repo>/mirror" \
+     -H "Authorization: Bearer <access_token>"
+----
diff --git a/modules/api-mirror-syncCancel.adoc b/modules/api-mirror-syncCancel.adoc
@@ -33,3 +33,11 @@ _required_|The full path of the repository. e.g. namespace/name|string
 |403|Unauthorized access|&lt;&lt;_apierror,ApiError&gt;&gt;
 |404|Not found|&lt;&lt;_apierror,ApiError&gt;&gt;
 |===
+
+[discrete]
+== Example command
+
+[source,terminal]
+----
+$ curl -X POST "https://<quay-server.example.com>/api/v1/repository/<namespace>/<repo>/mirror/sync-cancel" \
+----
diff --git a/modules/api-mirror-syncNow.adoc b/modules/api-mirror-syncNow.adoc
@@ -33,3 +33,12 @@ _required_|The full path of the repository. e.g. namespace/name|string
 |403|Unauthorized access|&lt;&lt;_apierror,ApiError&gt;&gt;
 |404|Not found|&lt;&lt;_apierror,ApiError&gt;&gt;
 |===
+
+[discrete]
+== Example command
+
+[source,terminal]
+----
+$ curl -X POST "https://<quay-server.example.com>/api/v1/repository/<namespace>/<repo>/mirror/sync-now" \
+     -H "Authorization: Bearer <access_token>"
+----
diff --git a/modules/mirror-quay-api.adoc b/modules/mirror-quay-api.adoc
@@ -0,0 +1,90 @@
+:_content-type: CONCEPT
+[id="quay-mirror-api"]
+= Using the API to mirror a repository
+
+{productname} administrators can mirror external repositories by using the API.
+
+.Prerequisites
+
+* You have set `FEATURE_REPO_MIRROR: true` in your `config.yaml` file.
+
+.Procedure
+
+* Create a new repository mirror configuration by using the link:https://docs.redhat.com/en/documentation/red_hat_quay/3.13/html-single/red_hat_quay_api_guide/index#createrepomirrorconfig[`POST /api/v1/repository/{repository}/mirror`] endpoint:
++
+[source,terminal]
+----
+$ curl -X POST "https://<quay-server.example.com>/api/v1/repository/<namespace>/<repo>/mirror" \
+    -H "Authorization: Bearer <access_token>" \
+    -H "Content-Type: application/json" \
+    -d '{
+        "is_enabled": <is_enabled>,
+        "external_reference": "<external_reference>",
+        "external_registry_username": "<external_registry_username>",
+        "external_registry_password": "<external_registry_password>",
+        "sync_start_date": "<sync_start_date>",
+        "sync_interval": <sync_interval>,
+        "robot_username": "<robot_username>",
+        "root_rule": {
+            "rule": "<rule>",
+            "rule_type": "<rule_type>"
+        }
+    }'
+----
+
+* You can return information about the mirror configuration by using the link:https://docs.redhat.com/en/documentation/red_hat_quay/3.13/html-single/red_hat_quay_api_guide/index#getrepomirrorconfig[`GET /api/v1/repository/{repository}/mirror`] endpoint:
++
+[source,terminal]
+----
+$ curl -X GET "https://<quay-server.example.com>/api/v1/repository/<namespace>/<repo>/mirror" \
+     -H "Authorization: Bearer <access_token>"
+----
++
+.Example output
++
+[source,terminal]
+----
+{"is_enabled": true, "mirror_type": "PULL", "external_reference": "https://quay.io/repository/argoproj/argocd", "external_registry_username": null, "external_registry_config": {}, "sync_interval": 86400, "sync_start_date": "2025-01-15T12:00:00Z", "sync_expiration_date": null, "sync_retries_remaining": 3, "sync_status": "NEVER_RUN", "root_rule": {"rule_kind": "tag_glob_csv", "rule_value": ["*.latest*"]}, "robot_username": "quayadmin+mirror_robot"}
+----
+
+* You can use the link:https://docs.redhat.com/en/documentation/red_hat_quay/{producty}/html-single/red_hat_quay_api_guide/index#syncnow[`POST /api/v1/repository/{repository}/mirror/sync-now`] endpoint to sync the repositories. For example:
++
+[source,terminal]
+----
+$ curl -X POST "https://<quay-server.example.com>/api/v1/repository/<namespace>/<repo>/mirror/sync-now" \
+     -H "Authorization: Bearer <access_token>"
+----
++
+This command does not return output in the CLI.
+
+* Alternatively, you can cancel the sync with the link:https://docs.redhat.com/en/documentation/red_hat_quay/{producty}/html-single/red_hat_quay_api_guide/index#synccancel[`POST /api/v1/repository/{repository}/mirror/sync-cancel`] endpoint.For example:
++
+[source,terminal]
+----
+$ curl -X POST "https://<quay-server.example.com>/api/v1/repository/<namespace>/<repo>/mirror/sync-cancel" \
+----
++
+This command does not return output in the CLI.
+
+* After creating a mirror configuration, you can make changes with the link:https://docs.redhat.com/en/documentation/red_hat_quay/{producty}/html-single/red_hat_quay_api_guide/index#changerepomirrorconfig[`PUT /api/v1/repository/{repository}/mirror`] command. For example, you might choose to disable automatic synchronizations:
++
+[source,terminal]
+----
+$ curl -X PUT "https://<quay-server.example.com>/api/v1/repository/<namespace>/<repo>/mirror" \
+    -H "Authorization: Bearer <access_token>" \
+    -H "Content-Type: application/json" \
+    -d '{
+        "is_enabled": <false>, <1>
+        "external_reference": "<external_reference>",
+        "external_registry_username": "<external_registry_username>",
+        "external_registry_password": "<external_registry_password>",
+        "sync_start_date": "<sync_start_date>",
+        "sync_interval": <sync_interval>,
+        "robot_username": "<robot_username>",
+        "root_rule": {
+            "rule": "<rule>",
+            "rule_type": "<rule_type>"
+        }
+    }'
+----
+<1> Disables automatic synchronization.