Add support for "graph_update_mode" parameter in Add request

README.md

@@ -199,6 +199,13 @@ The custom configuration options for the REST API are listed below:
   to another dictionary mapping ocp_version label to a binary image pull specification.
   This is useful in setting up customized binary image for different index image images thus
   reducing complexity for the end user. This defaults to `{}`.
+* `IIB_GRAPH_MODE_INDEX_ALLOW_LIST` - the list of index image pull specs on which using the
+  `graph_update_mode` parameter while submitting an IIB request is permitted. This defaults to `[]`
+  . Please check out the [API Documentation](http://release-engineering.github.io/iib) for more
+  information on how to use "graph_update_mode" for Add requests.
+* `IIB_GRAPH_MODE_OPTIONS` - the list of valid options for the `graph_update_mode` parameter in
+  the Add API endpoint. It defaults to `['replaces', 'semver', 'semver-skippatch']` i.e. the list
+  of modes supported by OPM.
 * `IIB_GREENWAVE_CONFIG` - the mapping, `dict(<str>: dict(<str>:<str>))`, of celery task queues to
   another dictionary of [Greenwave](https://docs.pagure.org/greenwave/) query parameters to their
   values. This is useful in setting up customized gating for each queue. This defaults to `{}`. Use

iib/web/api_v1.py

@@ -127,6 +127,7 @@ def _get_add_args(
         flask.current_app.config['IIB_BINARY_IMAGE_CONFIG'],
         payload.get('deprecation_list', []),
         payload.get('build_tags', []),
+        payload.get('graph_update_mode'),
     ]
 
 

iib/web/config.py

@@ -20,6 +20,8 @@ class Config(object):
     IIB_ADDITIONAL_LOGGERS: List[str] = []
     IIB_AWS_S3_BUCKET_NAME: Optional[str] = None
     IIB_BINARY_IMAGE_CONFIG: Dict[str, Dict[str, str]] = {}
+    IIB_GRAPH_MODE_INDEX_ALLOW_LIST: List[str] = []
+    IIB_GRAPH_MODE_OPTIONS: List[str] = ['replaces', 'semver', 'semver-skippatch']
     IIB_GREENWAVE_CONFIG: Dict[str, str] = {}
     IIB_LOG_FORMAT: str = '%(asctime)s %(name)s %(levelname)s %(module)s.%(funcName)s %(message)s'
     # This sets the level of the "flask.app" logger, which is accessed from current_app.logger

iib/web/iib_static_types.py

@@ -65,6 +65,7 @@ class RelatedBundlesMetadata(TypedDict):
         'force_backport',
         'from_bundle_image',
         'from_index',
+        'graph_update_mode',
         'labels',
         'operators',
         'organization',
@@ -92,6 +93,7 @@ class AddRequestPayload(TypedDict):
     distribution_scope: NotRequired[str]
     force_backport: NotRequired[bool]
     from_index: NotRequired[str]
+    graph_update_mode: NotRequired[str]
     organization: NotRequired[str]
     overwrite_from_index: NotRequired[bool]
     overwrite_from_index_token: NotRequired[str]
@@ -344,6 +346,7 @@ class AddRmRequestResponseBase(CommonIndexImageResponseBase, APIPartImageBuildRe
 class AddRequestResponse(AddRmRequestResponseBase):
     """Datastructure of the response to request from /builds/add API point."""
 
+    graph_update_mode: str
     omps_operator_version: Dict[str, Any]
 
 

iib/web/migrations/versions/daf67ddcf4a1_add_support_for_graph_update_mode_in_.py

@@ -0,0 +1,25 @@
+"""Add support for graph_update_mode in Add endpoint.
+
+Revision ID: daf67ddcf4a1
+Revises: 8d50f82f0be9
+Create Date: 2023-07-27 15:37:59.568914
+
+"""
+from alembic import op
+import sqlalchemy as sa
+
+
+revision = 'daf67ddcf4a1'
+down_revision = '8d50f82f0be9'
+branch_labels = None
+depends_on = None
+
+
+def upgrade():
+    with op.batch_alter_table('request_add', schema=None) as batch_op:
+        batch_op.add_column(sa.Column('graph_update_mode', sa.String(), nullable=True))
+
+
+def downgrade():
+    with op.batch_alter_table('request_add', schema=None) as batch_op:
+        batch_op.drop_column('graph_update_mode')

iib/web/models.py

@@ -1038,6 +1038,7 @@ class RequestAdd(Request, RequestIndexImageMixin):
     deprecation_list: Mapped[List['Image']] = db.relationship(
         'Image', secondary=RequestAddBundleDeprecation.__table__
     )
+    graph_update_mode: Mapped[Optional[str]]
     organization: Mapped[Optional[str]]
 
     omps_operator_version: Mapped[Optional[str]]
@@ -1072,8 +1073,9 @@ def from_json(  # type: ignore[override] # noqa: F821
         if not (request_kwargs.get('bundles') or request_kwargs.get('from_index')):
             raise ValidationError('"from_index" must be specified if no bundles are specified')
 
-        ALLOWED_KEYS_1: Sequence[Literal['cnr_token', 'organization']] = (
+        ALLOWED_KEYS_1: Sequence[Literal['cnr_token', 'graph_update_mode', 'organization']] = (
             'cnr_token',
+            'graph_update_mode',
             'organization',
         )
         for param in ALLOWED_KEYS_1:
@@ -1083,6 +1085,21 @@ def from_json(  # type: ignore[override] # noqa: F821
             if not isinstance(request_kwargs[param], str):
                 raise ValidationError(f'"{param}" must be a string')
 
+            if param == 'graph_update_mode':
+                graph_mode_options = current_app.config['IIB_GRAPH_MODE_OPTIONS']
+                if request_kwargs[param] not in graph_mode_options:
+                    raise ValidationError(
+                        f'"{param}" must be set to one of these: {graph_mode_options}'
+                    )
+                allowed_from_indexes: List[str] = current_app.config[
+                    'IIB_GRAPH_MODE_INDEX_ALLOW_LIST'
+                ]
+                if request_kwargs.get('from_index') not in allowed_from_indexes:
+                    raise Forbidden(
+                        '"graph_update_mode" can only be used on the'
+                        f' following "from_index" pullspecs: {allowed_from_indexes}'
+                    )
+
         if not isinstance(request_kwargs.get('force_backport', False), bool):
             raise ValidationError('"force_backport" must be a boolean')
 
@@ -1099,6 +1116,7 @@ def from_json(  # type: ignore[override] # noqa: F821
                 'bundles',
                 'distribution_scope',
                 'deprecation_list',
+                'graph_update_mode',
                 'build_tags',
             ],
             batch=batch,
@@ -1137,6 +1155,7 @@ def to_json(self, verbose: Optional[bool] = True) -> AddRequestResponse:
         rv['omps_operator_version'] = {}
         if self.omps_operator_version:
             rv['omps_operator_version'] = json.loads(self.omps_operator_version)
+        rv['graph_update_mode'] = self.graph_update_mode
 
         for bundle in self.bundles:
             if bundle.operator:

iib/web/static/api_v1.yaml

@@ -1012,6 +1012,14 @@ components:
           description: >
             from_index is required when add_arches is not provided.
           example: 'quay.io/iib-stage/iib:4'
+        graph_update_mode:
+          type: string
+          description: >
+            Graph update mode that defines how channel graphs are updated in the index. It must be one
+            of "replaces", "semver" or "semver-skippatch". This attribute can only be used on index
+            image pull specs configured in IIB_GRAPH_MODE_INDEX_ALLOW_LIST in the IIB API Config. If not
+            specified, "--mode" will not be added to OPM commands to add the bundle(s) to the index.
+          default: None
         organization:
           type: string
           description: >
@@ -1055,6 +1063,9 @@ components:
               example: add
             omps_operator_version:
               $ref: '#/components/schemas/OMPSOperatorVersion'
+            graph_update_mode:
+              type: string
+              example: semver
     RmRequest:
       type: object
       properties:

iib/workers/tasks/build.py

@@ -453,6 +453,7 @@ def _opm_index_add(
     bundles: List[str],
     binary_image: str,
     from_index: Optional[str] = None,
+    graph_update_mode: Optional[str] = None,
     overwrite_from_index_token: Optional[str] = None,
     overwrite_csv: bool = False,
     container_tool: Optional[str] = None,
@@ -469,6 +470,8 @@ def _opm_index_add(
         gets copied from. This should point to a digest or stable tag.
     :param str from_index: the pull specification of the container image containing the index that
         the index image build will be based from.
+    :param str graph_update_mode: Graph update mode that defines how channel graphs are updated
+        in the index.
     :param str overwrite_from_index_token: the token used for overwriting the input
         ``from_index`` image. This is required to use ``overwrite_from_index``.
         The format of the token must be in the format "user:password".
@@ -497,6 +500,10 @@ def _opm_index_add(
         cmd.append('--container-tool')
         cmd.append(container_tool)
 
+    if graph_update_mode:
+        log.info('Using %s mode to update the channel graph in the index', graph_update_mode)
+        cmd.extend(['--mode', graph_update_mode])
+
     log.info('Generating the database file with the following bundle(s): %s', ', '.join(bundles))
     if from_index:
         log.info('Using the existing database from %s', from_index)
@@ -789,6 +796,7 @@ def handle_add_request(
     binary_image_config: Optional[Dict[str, Dict[str, str]]] = None,
     deprecation_list: Optional[List[str]] = None,
     build_tags: Optional[List[str]] = None,
+    graph_update_mode: Optional[str] = None,
     traceparent: Optional[str] = None,
 ) -> None:
     """
@@ -824,6 +832,8 @@ def handle_add_request(
     :param list deprecation_list: list of deprecated bundles for the target index image. Defaults
         to ``None``.
     :param list build_tags: List of tags which will be applied to intermediate index images.
+    :param str graph_update_mode: Graph update mode that defines how channel graphs are updated
+        in the index.
     :param str traceparent: the traceparent header value to be used for tracing the request.
     :raises IIBError: if the index image build fails.
     """
@@ -898,6 +908,7 @@ def handle_add_request(
                 bundles=resolved_bundles,
                 binary_image=prebuild_info['binary_image_resolved'],
                 from_index=from_index_resolved,
+                graph_update_mode=graph_update_mode,
                 overwrite_from_index_token=overwrite_from_index_token,
                 overwrite_csv=(prebuild_info['distribution_scope'] in ['dev', 'stage']),
             )
@@ -907,6 +918,7 @@ def handle_add_request(
                 bundles=resolved_bundles,
                 binary_image=prebuild_info['binary_image_resolved'],
                 from_index=from_index_resolved,
+                graph_update_mode=graph_update_mode,
                 overwrite_from_index_token=overwrite_from_index_token,
                 overwrite_csv=(prebuild_info['distribution_scope'] in ['dev', 'stage']),
             )

iib/workers/tasks/opm_operations.py

@@ -524,6 +524,7 @@ def _opm_registry_add(
     bundles: List[str],
     overwrite_csv: bool = False,
     container_tool: Optional[str] = None,
+    graph_update_mode: Optional[str] = None,
 ) -> None:
     """
     Add the input bundles to an operator index database.
@@ -537,6 +538,8 @@ def _opm_registry_add(
     :param bool overwrite_csv: a boolean determining if a bundle will be replaced if the CSV
         already exists.
     :param str container_tool: the container tool to be used to operate on the index image
+    :param str graph_update_mode: Graph update mode that defines how channel graphs are updated
+        in the index.
     """
     from iib.workers.tasks.utils import run_cmd
 
@@ -561,6 +564,10 @@ def _opm_registry_add(
         cmd.append('--container-tool')
         cmd.append(container_tool)
 
+    if graph_update_mode:
+        log.info('Using %s mode to update the channel graph in the index', graph_update_mode)
+        cmd.extend(['--mode', graph_update_mode])
+
     log.info('Generating the database file with the following bundle(s): %s', ', '.join(bundles))
 
     if overwrite_csv:
@@ -581,6 +588,7 @@ def opm_registry_add_fbc(
     bundles: List[str],
     binary_image: str,
     from_index: Optional[str] = None,
+    graph_update_mode: Optional[str] = None,
     overwrite_csv: bool = False,
     overwrite_from_index_token: Optional[str] = None,
     container_tool: Optional[str] = None,
@@ -597,6 +605,8 @@ def opm_registry_add_fbc(
         gets copied from. This should point to a digest or stable tag.
     :param str from_index: the pull specification of the container image containing the index that
         the index image build will be based from.
+    :param str graph_update_mode: Graph update mode that defines how channel graphs are updated
+        in the index.
     :param bool overwrite_csv: a boolean determining if a bundle will be replaced if the CSV
         already exists.
     :param str overwrite_from_index_token: the token used for overwriting the input
@@ -617,6 +627,7 @@ def opm_registry_add_fbc(
         bundles=bundles,
         overwrite_csv=overwrite_csv,
         container_tool=container_tool,
+        graph_update_mode=graph_update_mode,
     )
 
     fbc_dir, _ = opm_migrate(index_db=index_db_file, base_dir=base_dir)