OpenShift docs are moving and will soon only be available at docs.redhat.com, the home of all Red Hat product documentation. Explore the new docs experience today.
  1. Documentation
    2. history bug_report picture_as_pdf
×

Creating and using deployment collections

You can use collections in RHACS to define and name a group of resources by using matching patterns. You can then configure system processes to use these collections.

Currently, collections are available only under the following conditions:

  • Collections are available only for deployments.

  • You can only use collections with vulnerability reporting. See "Vulnerability reporting" in the Additional resources section for more information.

  • Deployment collections are only available to RHACS customers if they are using the PostgreSQL database.

    By default, RHACS Cloud Service uses the PostgreSQL database, and it is also used by default when installing RHACS release 4.0 and later. RHACS customers using an earlier release than 3.74 can migrate to the PostgreSQL database with help from Red Hat.

Prerequisites

A user account must have the following permissions to use the Collections feature:

  • WorkflowAdministration: You must have Read access to view collections and Write access to add, change, or delete collections.

  • Deployment: You need Read Access or Read and Write Access to understand how configured rules will match with deployments.

These permissions are included in the Admin system role. For more information about roles and permissions, see "Managing RBAC in RHACS" in "Additional resources".

Understanding deployment collections

Deployment collections are only available to RHACS customers using the PostgreSQL database. By default, RHACS Cloud Service uses the PostgreSQL database, and it is also used by default when installing RHACS release 4.0 and later. RHACS customers using an earlier release than 3.74 can migrate to the PostgreSQL database with help from Red Hat.

An RHACS collection is a user-defined, named reference. It defines a logical grouping by using selection rules. Those rules can match a deployment, namespace, or cluster name or label. You can specify rules by using exact matches or regular expressions. Collections are resolved at run time and can refer to objects that do not exist at the time of the collection definition. Collections can be constructed by using other collections to describe complex hierarchies.

Collections provide you with a language to describe how your dynamic infrastructure is organized, eliminating the need for cloning and repetitive editing of RHACS properties such as inclusion and exclusion scopes.

You can use collections to identify any group of deployments in your system, such as:

  • An infrastructure area that is owned by a specific development team

  • An application that requires different policy exceptions when running in a development or in a production cluster

  • A distributed application that spans multiple namespaces, defined with a common deployment label

  • An entire production or test environment

Collections can be created and managed by using the RHACS portal. The collection editor helps you apply selection rules at the deployment, namespace, and cluster level. You can use simple and complex rules, including regular expression.

You can define a collection by selecting one or more deployments, namespaces, or clusters, as shown in the following image. This image shows a collection that contains deployments with the name reporting or that contain db in the name. The collection includes deployments matching those names in the namespace with a specific label of kubernetes.io/metadata.name=medical, and in clusters named production.

Collection rules showing rules configured for deployments with names matching

The collection editor also helps you to describe complex hierarchies by attaching, or nesting, other collections. The editor provides a real-time preview side panel that helps you understand the rules you are applying by showing the resulting matches to the rules that you have configured. The following image provides an example of results from a collection named "Sensitive User Data" with a set of collection rules (not shown). The "Sensitive User Data" collection has two attached collections, "Credit card processors" and "Medical records" and each of those collections have their own collection rules. The results shown in the side panel include items that match the rules configured for all three collections.

Collection results from configuring a collection with two attached collections

Accessing deployment collections

To use collections, click Platform Configuration → Collections. The page displays a list of currently-configured collections. You can perform the following actions:

  • Search for collections by entering text in the Search by name field, and then press →.

  • Click on a collection in the collection list to view the collection in read-only mode.

  • Click on kebab for an existing collection to edit, clone, or delete it.

    You cannot delete a collection that is actively used in RHACS.

  • Click Create collection to create a new deployment collection.

Creating deployment collections

When creating a collection, you must name it and define the rules for the collection.

Procedure

  1. In the Collections page, click Create collection.

  2. Enter the name and description for the collection.

  3. In the Collection rules section, you must perform at least one of the following actions:

    • Define the rules for the collection: See the "Creating collection rules" section for more information.

    • Attach existing collections to the collection: See the "Adding attached collections" section for more information.

  4. The results of your rule configuration or choosing attached collections are available in the Collection results live preview panel. Click Hide results to remove this panel from display.

  5. Click Save.

Creating collection rules

When creating collections, you must configure at least one rule or attach another collection to the new collection that you are creating.

Currently, collections are available only for deployments.

Configure rules to select the resources to include in the collection. Use the preview panel to see the results of the collection rules as you configure them. You can configure rules in any order.

Procedure

  1. In the Deployments section, select one of the following options from the drop-down list:

    • All deployments: Includes all deployments in the collection. If you select this option, you must filter the collection by using namespaces or clusters or by attaching another collection.

    • Deployments with names matching Click this option to select by name and then click one of the following options:

      • Select An exact value of and enter the exact name of the deployment.

      • Select A regex value of to use regular expression to search for a deployment. This option is useful if you do not know the exact name of the deployment. A regular expression is a string of letters, numbers, and symbols that defines a pattern. RHACS uses this pattern to match characters or groups of characters and return results. For more information about regular expression, see "Regular-Expressions.info" in the "Additional resources" section.

    • Deployments with labels matching exactly: Click this option to select deployments with labels that match the exact text that you enter. The label must be a valid Kubernetes label in the format of key=value.

  2. Optional: To add more deployments with names or labels that match additional criteria for inclusion, click OR and configure another exact or regular expression value.

The following example provides the steps for configuring a collection for a medical application. In this example, you want your collection to include the reporting deployment, a database called patient-db, and you want to select namespaces with labels where key = kubernetes.io/metadata.name and value = medical. For this example, perform the following steps:

  1. In Collection rules, select Deployments with names matching.

  2. Click An exact value of and enter reporting.

  3. Click OR.

  4. Click A regex value of and enter .*-db to select all deployments with a name ending in db in your environment. The regex value option uses regular expression for pattern matching; for more information about regular expression, see "Regular-Expressions.info" in the Additional resources section. The panel on the right might display databases that you do not want to include. You can exclude those databases by using additional filters. For example:

    1. Filter by namespace labels by clicking Namespaces with labels matching exactly and entering kubernetes.io/metadata.name=medical to include only deployments in the namespace that is labeled medical.

    2. If you know the name of the namespace, click Namespaces with names matching and enter the name.

Adding attached collections

Grouping collections and adding them to other collections can be useful if you want to create small collections based on deployments. You can reuse and combine those smaller collections into larger, hierarchical collections. To add additional collections to a collection that you are creating:

  1. Perform one of the following actions:

    • Enter text in the Filter by name field and press → to view matching results.

    • Click the name of a collection from the Available collections list to view information about the collection, such as the name and rules for the collection and the deployments that match that collection.

  2. After viewing collection information, close the window to return to the Attached collections page.

  3. Click +Attach. The Attached collections section lists the collections that you attached.

    When you add an attached collection, the attached collection contains results based on the configured selection rules. For example, if an attached collection includes resources that would be filtered out by the rules used in the parent collection, then those items are still added to the parent collection because of the rules in the attached collection. Attached collections extend the original collection using an OR operator.

  4. Click Save.

Migration of access scopes to collections

Database changes in RHACS from rocksdb to PostgreSQL are provided as a Technology Preview beginning with release 3.74 and are generally available in release 4.0. When the database is migrated from rocksdb to PostgreSQL, existing access scopes used in vulnerability reporting are migrated to collections. You can verify that the migration resulted in the correct configuration for your existing reports by navigating to Vulnerability Management → Reporting and viewing the report information.

The migration process creates collection objects for access scopes that were used in report configurations. RHACS generates two or more collections for a single access scope, depending on the complexity of the access scope. The generated collections for a given access scope include the following types:

  • Embedded collections: To mimic the exact selection logic of the original access scope, RHACS generates one or more collections where matched deployments result in the same selection of clusters and namespaces as the original access scope. The collection name is in the format of System-generated embedded collection number for the scope where number is a number starting from 0.

    These embedded collections will not have any attached collections. They have cluster and namespace selection rules, but no deployment rules because the original access scopes did not filter on deployments.

  • Root collection for the access scope: This collection is added to the report configurations. The collection name is in the format of System-generated root collection for the scope. This collection does not define any rules, but attaches one or more embedded collections. The combination of these embedded collections results in the same selection of clusters and namespaces as the original access scope.

For access scopes that define cluster or namespace label selectors, RHACS can only migrate those scopes that have the 'IN' operator between the key and values. Access scopes with label selectors that were created by using the RHACS portal used the 'IN' operator by default. Migration of scopes that used the 'NOT_IN', 'EXISTS' and 'NOT_EXISTS' operators is not supported. If a collection cannot be created for an access scope, log messages are created during the migration. Log messages have the following format:

Failed to create collections for scope _scope-name_: Unsupported operator NOT_IN in scope's label selectors. Only operator 'IN' is supported.
The scope is attached to the following report configurations: [list of report configs]; Please manually create an equivalent collection and edit the listed report configurations to use this collection. Note that reports will not function correctly until a collection is attached.

You can also click the report in Vulnerability Management → Reporting to view the report information page. This page contains a message if a report needs a collection attached to it.

The original access scopes are not removed during the migration. If you created an access scope only for use in filtering vulnerability management reports, you can manually remove the access scope.

Managing collections by using the API

You can configure collections by using the CollectionService API object. For example, you can use CollectionService_DryRunCollection to return a list of results equivalent to the live preview panel in the RHACS portal. For more information, go to Help → API reference in the RHACS portal.

Additional resources